]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/DebugSupport.h
projects / mirror_edk2.git / blob
? search:


b59ca4d52e600f75bb279e5e909edfe7b7ee329b
[mirror_edk2.git] / MdePkg / Include / Protocol / DebugSupport.h
1 /** @file
2 DebugSupport protocol and supporting definitions as defined in the UEFI2.0
3 specification.
4
5 The DebugSupport protocol is used by source level debuggers to abstract the
6 processor and handle context save and restore operations.
7
8 Copyright (c) 2006 - 2008, Intel Corporation
9 All rights reserved. This program and the accompanying materials
10 are licensed and made available under the terms and conditions of the BSD License
11 which accompanies this distribution. The full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php
13
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17 **/
18
19 #ifndef __DEBUG_SUPPORT_H__
20 #define __DEBUG_SUPPORT_H__
21
22 #include <ProcessorBind.h>
23 #include <IndustryStandard/PeImage.h>
24
25 typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL;
26
27 ///
28 /// Debug Support protocol {2755590C-6F3C-42FA-9EA4-A3BA543CDA25}
29 ///
30 #define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \
31 { \
32 0x2755590C, 0x6F3C, 0x42FA, {0x9E, 0xA4, 0xA3, 0xBA, 0x54, 0x3C, 0xDA, 0x25 } \
33 }
34
35 ///
36 /// Processor exception to be hooked.
37 /// All exception types for IA32, X64, Itanium and EBC processors are defined.
38 ///
39 typedef INTN EFI_EXCEPTION_TYPE;
40
41 ///
42 /// IA-32 processor exception types
43 ///
44 #define EXCEPT_IA32_DIVIDE_ERROR 0
45 #define EXCEPT_IA32_DEBUG 1
46 #define EXCEPT_IA32_NMI 2
47 #define EXCEPT_IA32_BREAKPOINT 3
48 #define EXCEPT_IA32_OVERFLOW 4
49 #define EXCEPT_IA32_BOUND 5
50 #define EXCEPT_IA32_INVALID_OPCODE 6
51 #define EXCEPT_IA32_DOUBLE_FAULT 8
52 #define EXCEPT_IA32_INVALID_TSS 10
53 #define EXCEPT_IA32_SEG_NOT_PRESENT 11
54 #define EXCEPT_IA32_STACK_FAULT 12
55 #define EXCEPT_IA32_GP_FAULT 13
56 #define EXCEPT_IA32_PAGE_FAULT 14
57 #define EXCEPT_IA32_FP_ERROR 16
58 #define EXCEPT_IA32_ALIGNMENT_CHECK 17
59 #define EXCEPT_IA32_MACHINE_CHECK 18
60 #define EXCEPT_IA32_SIMD 19
61
62 ///
63 /// FXSAVE_STATE
64 /// FP / MMX / XMM registers (see fxrstor instruction definition)
65 ///
66 typedef struct {
67 UINT16 Fcw;
68 UINT16 Fsw;
69 UINT16 Ftw;
70 UINT16 Opcode;
71 UINT32 Eip;
72 UINT16 Cs;
73 UINT16 Reserved1;
74 UINT32 DataOffset;
75 UINT16 Ds;
76 UINT8 Reserved2[10];
77 UINT8 St0Mm0[10], Reserved3[6];
78 UINT8 St1Mm1[10], Reserved4[6];
79 UINT8 St2Mm2[10], Reserved5[6];
80 UINT8 St3Mm3[10], Reserved6[6];
81 UINT8 St4Mm4[10], Reserved7[6];
82 UINT8 St5Mm5[10], Reserved8[6];
83 UINT8 St6Mm6[10], Reserved9[6];
84 UINT8 St7Mm7[10], Reserved10[6];
85 UINT8 Xmm0[16];
86 UINT8 Xmm1[16];
87 UINT8 Xmm2[16];
88 UINT8 Xmm3[16];
89 UINT8 Xmm4[16];
90 UINT8 Xmm5[16];
91 UINT8 Xmm6[16];
92 UINT8 Xmm7[16];
93 UINT8 Reserved11[14 * 16];
94 } EFI_FX_SAVE_STATE_IA32;
95
96 ///
97 /// IA-32 processor context definition
98 ///
99 typedef struct {
100 UINT32 ExceptionData;
101 EFI_FX_SAVE_STATE_IA32 FxSaveState;
102 UINT32 Dr0;
103 UINT32 Dr1;
104 UINT32 Dr2;
105 UINT32 Dr3;
106 UINT32 Dr6;
107 UINT32 Dr7;
108 UINT32 Cr0;
109 UINT32 Cr1; /* Reserved */
110 UINT32 Cr2;
111 UINT32 Cr3;
112 UINT32 Cr4;
113 UINT32 Eflags;
114 UINT32 Ldtr;
115 UINT32 Tr;
116 UINT32 Gdtr[2];
117 UINT32 Idtr[2];
118 UINT32 Eip;
119 UINT32 Gs;
120 UINT32 Fs;
121 UINT32 Es;
122 UINT32 Ds;
123 UINT32 Cs;
124 UINT32 Ss;
125 UINT32 Edi;
126 UINT32 Esi;
127 UINT32 Ebp;
128 UINT32 Esp;
129 UINT32 Ebx;
130 UINT32 Edx;
131 UINT32 Ecx;
132 UINT32 Eax;
133 } EFI_SYSTEM_CONTEXT_IA32;
134
135 ///
136 /// x64 processor exception types
137 ///
138 #define EXCEPT_X64_DIVIDE_ERROR 0
139 #define EXCEPT_X64_DEBUG 1
140 #define EXCEPT_X64_NMI 2
141 #define EXCEPT_X64_BREAKPOINT 3
142 #define EXCEPT_X64_OVERFLOW 4
143 #define EXCEPT_X64_BOUND 5
144 #define EXCEPT_X64_INVALID_OPCODE 6
145 #define EXCEPT_X64_DOUBLE_FAULT 8
146 #define EXCEPT_X64_INVALID_TSS 10
147 #define EXCEPT_X64_SEG_NOT_PRESENT 11
148 #define EXCEPT_X64_STACK_FAULT 12
149 #define EXCEPT_X64_GP_FAULT 13
150 #define EXCEPT_X64_PAGE_FAULT 14
151 #define EXCEPT_X64_FP_ERROR 16
152 #define EXCEPT_X64_ALIGNMENT_CHECK 17
153 #define EXCEPT_X64_MACHINE_CHECK 18
154 #define EXCEPT_X64_SIMD 19
155
156 ///
157 /// FXSAVE_STATE
158 /// FP / MMX / XMM registers (see fxrstor instruction definition)
159 ///
160 typedef struct {
161 UINT16 Fcw;
162 UINT16 Fsw;
163 UINT16 Ftw;
164 UINT16 Opcode;
165 UINT64 Rip;
166 UINT64 DataOffset;
167 UINT8 Reserved1[8];
168 UINT8 St0Mm0[10], Reserved2[6];
169 UINT8 St1Mm1[10], Reserved3[6];
170 UINT8 St2Mm2[10], Reserved4[6];
171 UINT8 St3Mm3[10], Reserved5[6];
172 UINT8 St4Mm4[10], Reserved6[6];
173 UINT8 St5Mm5[10], Reserved7[6];
174 UINT8 St6Mm6[10], Reserved8[6];
175 UINT8 St7Mm7[10], Reserved9[6];
176 UINT8 Xmm0[16];
177 UINT8 Xmm1[16];
178 UINT8 Xmm2[16];
179 UINT8 Xmm3[16];
180 UINT8 Xmm4[16];
181 UINT8 Xmm5[16];
182 UINT8 Xmm6[16];
183 UINT8 Xmm7[16];
184 //
185 // NOTE: UEFI 2.0 spec definition as follows.
186 //
187 UINT8 Reserved11[14 * 16];
188 } EFI_FX_SAVE_STATE_X64;
189
190 ///
191 /// x64 processor context definition
192 ///
193 typedef struct {
194 UINT64 ExceptionData;
195 EFI_FX_SAVE_STATE_X64 FxSaveState;
196 UINT64 Dr0;
197 UINT64 Dr1;
198 UINT64 Dr2;
199 UINT64 Dr3;
200 UINT64 Dr6;
201 UINT64 Dr7;
202 UINT64 Cr0;
203 UINT64 Cr1; /* Reserved */
204 UINT64 Cr2;
205 UINT64 Cr3;
206 UINT64 Cr4;
207 UINT64 Cr8;
208 UINT64 Rflags;
209 UINT64 Ldtr;
210 UINT64 Tr;
211 UINT64 Gdtr[2];
212 UINT64 Idtr[2];
213 UINT64 Rip;
214 UINT64 Gs;
215 UINT64 Fs;
216 UINT64 Es;
217 UINT64 Ds;
218 UINT64 Cs;
219 UINT64 Ss;
220 UINT64 Rdi;
221 UINT64 Rsi;
222 UINT64 Rbp;
223 UINT64 Rsp;
224 UINT64 Rbx;
225 UINT64 Rdx;
226 UINT64 Rcx;
227 UINT64 Rax;
228 UINT64 R8;
229 UINT64 R9;
230 UINT64 R10;
231 UINT64 R11;
232 UINT64 R12;
233 UINT64 R13;
234 UINT64 R14;
235 UINT64 R15;
236 } EFI_SYSTEM_CONTEXT_X64;
237
238 ///
239 /// Itanium Processor Family Exception types
240 ///
241 #define EXCEPT_IPF_VHTP_TRANSLATION 0
242 #define EXCEPT_IPF_INSTRUCTION_TLB 1
243 #define EXCEPT_IPF_DATA_TLB 2
244 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB 3
245 #define EXCEPT_IPF_ALT_DATA_TLB 4
246 #define EXCEPT_IPF_DATA_NESTED_TLB 5
247 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6
248 #define EXCEPT_IPF_DATA_KEY_MISSED 7
249 #define EXCEPT_IPF_DIRTY_BIT 8
250 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9
251 #define EXCEPT_IPF_DATA_ACCESS_BIT 10
252 #define EXCEPT_IPF_BREAKPOINT 11
253 #define EXCEPT_IPF_EXTERNAL_INTERRUPT 12
254 //
255 // 13 - 19 reserved
256 //
257 #define EXCEPT_IPF_PAGE_NOT_PRESENT 20
258 #define EXCEPT_IPF_KEY_PERMISSION 21
259 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS 22
260 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS 23
261 #define EXCEPT_IPF_GENERAL_EXCEPTION 24
262 #define EXCEPT_IPF_DISABLED_FP_REGISTER 25
263 #define EXCEPT_IPF_NAT_CONSUMPTION 26
264 #define EXCEPT_IPF_SPECULATION 27
265 //
266 // 28 reserved
267 //
268 #define EXCEPT_IPF_DEBUG 29
269 #define EXCEPT_IPF_UNALIGNED_REFERENCE 30
270 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE 31
271 #define EXCEPT_IPF_FP_FAULT 32
272 #define EXCEPT_IPF_FP_TRAP 33
273 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP 34
274 #define EXCEPT_IPF_TAKEN_BRANCH 35
275 #define EXCEPT_IPF_SINGLE_STEP 36
276 //
277 // 37 - 44 reserved
278 //
279 #define EXCEPT_IPF_IA32_EXCEPTION 45
280 #define EXCEPT_IPF_IA32_INTERCEPT 46
281 #define EXCEPT_IPF_IA32_INTERRUPT 47
282
283 ///
284 /// IPF processor context definition
285 ///
286 typedef struct {
287 //
288 // The first reserved field is necessary to preserve alignment for the correct
289 // bits in UNAT and to insure F2 is 16 byte aligned..
290 //
291 UINT64 Reserved;
292 UINT64 R1;
293 UINT64 R2;
294 UINT64 R3;
295 UINT64 R4;
296 UINT64 R5;
297 UINT64 R6;
298 UINT64 R7;
299 UINT64 R8;
300 UINT64 R9;
301 UINT64 R10;
302 UINT64 R11;
303 UINT64 R12;
304 UINT64 R13;
305 UINT64 R14;
306 UINT64 R15;
307 UINT64 R16;
308 UINT64 R17;
309 UINT64 R18;
310 UINT64 R19;
311 UINT64 R20;
312 UINT64 R21;
313 UINT64 R22;
314 UINT64 R23;
315 UINT64 R24;
316 UINT64 R25;
317 UINT64 R26;
318 UINT64 R27;
319 UINT64 R28;
320 UINT64 R29;
321 UINT64 R30;
322 UINT64 R31;
323
324 UINT64 F2[2];
325 UINT64 F3[2];
326 UINT64 F4[2];
327 UINT64 F5[2];
328 UINT64 F6[2];
329 UINT64 F7[2];
330 UINT64 F8[2];
331 UINT64 F9[2];
332 UINT64 F10[2];
333 UINT64 F11[2];
334 UINT64 F12[2];
335 UINT64 F13[2];
336 UINT64 F14[2];
337 UINT64 F15[2];
338 UINT64 F16[2];
339 UINT64 F17[2];
340 UINT64 F18[2];
341 UINT64 F19[2];
342 UINT64 F20[2];
343 UINT64 F21[2];
344 UINT64 F22[2];
345 UINT64 F23[2];
346 UINT64 F24[2];
347 UINT64 F25[2];
348 UINT64 F26[2];
349 UINT64 F27[2];
350 UINT64 F28[2];
351 UINT64 F29[2];
352 UINT64 F30[2];
353 UINT64 F31[2];
354
355 UINT64 Pr;
356
357 UINT64 B0;
358 UINT64 B1;
359 UINT64 B2;
360 UINT64 B3;
361 UINT64 B4;
362 UINT64 B5;
363 UINT64 B6;
364 UINT64 B7;
365
366 //
367 // application registers
368 //
369 UINT64 ArRsc;
370 UINT64 ArBsp;
371 UINT64 ArBspstore;
372 UINT64 ArRnat;
373
374 UINT64 ArFcr;
375
376 UINT64 ArEflag;
377 UINT64 ArCsd;
378 UINT64 ArSsd;
379 UINT64 ArCflg;
380 UINT64 ArFsr;
381 UINT64 ArFir;
382 UINT64 ArFdr;
383
384 UINT64 ArCcv;
385
386 UINT64 ArUnat;
387
388 UINT64 ArFpsr;
389
390 UINT64 ArPfs;
391 UINT64 ArLc;
392 UINT64 ArEc;
393
394 //
395 // control registers
396 //
397 UINT64 CrDcr;
398 UINT64 CrItm;
399 UINT64 CrIva;
400 UINT64 CrPta;
401 UINT64 CrIpsr;
402 UINT64 CrIsr;
403 UINT64 CrIip;
404 UINT64 CrIfa;
405 UINT64 CrItir;
406 UINT64 CrIipa;
407 UINT64 CrIfs;
408 UINT64 CrIim;
409 UINT64 CrIha;
410
411 //
412 // debug registers
413 //
414 UINT64 Dbr0;
415 UINT64 Dbr1;
416 UINT64 Dbr2;
417 UINT64 Dbr3;
418 UINT64 Dbr4;
419 UINT64 Dbr5;
420 UINT64 Dbr6;
421 UINT64 Dbr7;
422
423 UINT64 Ibr0;
424 UINT64 Ibr1;
425 UINT64 Ibr2;
426 UINT64 Ibr3;
427 UINT64 Ibr4;
428 UINT64 Ibr5;
429 UINT64 Ibr6;
430 UINT64 Ibr7;
431
432 //
433 // virtual registers - nat bits for R1-R31
434 //
435 UINT64 IntNat;
436
437 } EFI_SYSTEM_CONTEXT_IPF;
438
439 ///
440 /// EBC processor exception types
441 ///
442 #define EXCEPT_EBC_UNDEFINED 0
443 #define EXCEPT_EBC_DIVIDE_ERROR 1
444 #define EXCEPT_EBC_DEBUG 2
445 #define EXCEPT_EBC_BREAKPOINT 3
446 #define EXCEPT_EBC_OVERFLOW 4
447 #define EXCEPT_EBC_INVALID_OPCODE 5 /// opcode out of range
448 #define EXCEPT_EBC_STACK_FAULT 6
449 #define EXCEPT_EBC_ALIGNMENT_CHECK 7
450 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8 /// malformed instruction
451 #define EXCEPT_EBC_BAD_BREAK 9 /// BREAK 0 or undefined BREAK
452 #define EXCEPT_EBC_STEP 10 /// to support debug stepping
453 ///
454 /// For coding convenience, define the maximum valid EBC exception.
455 ///
456 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP
457
458 ///
459 /// EBC processor context definition
460 ///
461 typedef struct {
462 UINT64 R0;
463 UINT64 R1;
464 UINT64 R2;
465 UINT64 R3;
466 UINT64 R4;
467 UINT64 R5;
468 UINT64 R6;
469 UINT64 R7;
470 UINT64 Flags;
471 UINT64 ControlFlags;
472 UINT64 Ip;
473 } EFI_SYSTEM_CONTEXT_EBC;
474
475 ///
476 /// Universal EFI_SYSTEM_CONTEXT definition
477 ///
478 typedef union {
479 EFI_SYSTEM_CONTEXT_EBC *SystemContextEbc;
480 EFI_SYSTEM_CONTEXT_IA32 *SystemContextIa32;
481 EFI_SYSTEM_CONTEXT_X64 *SystemContextX64;
482 EFI_SYSTEM_CONTEXT_IPF *SystemContextIpf;
483 } EFI_SYSTEM_CONTEXT;
484
485 //
486 // DebugSupport callback function prototypes
487 //
488
489 /**
490 Registers and enables an exception callback function for the specified exception.
491
492 @param ExceptionType Exception types in EBC, IA-32, x64, or IPF
493 @param SystemContext Exception content.
494
495 **/
496 typedef
497 VOID
498 (*EFI_EXCEPTION_CALLBACK)(
499 IN EFI_EXCEPTION_TYPE ExceptionType,
500 IN OUT EFI_SYSTEM_CONTEXT SystemContext
501 );
502
503 /**
504 Registers and enables the on-target debug agent's periodic entry point.
505
506 @param SystemContext Exception content.
507
508 **/
509 typedef
510 VOID
511 (*EFI_PERIODIC_CALLBACK)(
512 IN OUT EFI_SYSTEM_CONTEXT SystemContext
513 );
514
515 ///
516 /// Machine type definition
517 ///
518 typedef enum {
519 IsaIa32 = IMAGE_FILE_MACHINE_I386, ///< 0x014C
520 IsaX64 = IMAGE_FILE_MACHINE_X64, ///< 0x8664
521 IsaIpf = IMAGE_FILE_MACHINE_IA64, ///< 0x0200
522 IsaEbc = IMAGE_FILE_MACHINE_EBC ///< 0x0EBC
523 } EFI_INSTRUCTION_SET_ARCHITECTURE;
524
525
526 //
527 // DebugSupport member function definitions
528 //
529
530 /**
531 Returns the maximum value that may be used for the ProcessorIndex parameter in
532 RegisterPeriodicCallback() and RegisterExceptionCallback().
533
534 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
535 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported
536 processor index is returned.
537
538 @retval EFI_SUCCESS The function completed successfully.
539
540 **/
541 typedef
542 EFI_STATUS
543 (EFIAPI *EFI_GET_MAXIMUM_PROCESSOR_INDEX)(
544 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
545 OUT UINTN *MaxProcessorIndex
546 );
547
548 /**
549 Registers a function to be called back periodically in interrupt context.
550
551 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
552 @param ProcessorIndex Specifies which processor the callback function applies to.
553 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main
554 periodic entry point of the debug agent.
555
556 @retval EFI_SUCCESS The function completed successfully.
557 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
558 function was previously registered.
559 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
560 function.
561
562 **/
563 typedef
564 EFI_STATUS
565 (EFIAPI *EFI_REGISTER_PERIODIC_CALLBACK)(
566 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
567 IN UINTN ProcessorIndex,
568 IN EFI_PERIODIC_CALLBACK PeriodicCallback
569 );
570
571 /**
572 Registers a function to be called when a given processor exception occurs.
573
574 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
575 @param ProcessorIndex Specifies which processor the callback function applies to.
576 @param PeriodicCallback A pointer to a function of type EXCEPTION_CALLBACK that is called
577 when the processor exception specified by ExceptionType occurs.
578 @param ExceptionType Specifies which processor exception to hook.
579
580 @retval EFI_SUCCESS The function completed successfully.
581 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
582 function was previously registered.
583 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
584 function.
585
586 **/
587 typedef
588 EFI_STATUS
589 (EFIAPI *EFI_REGISTER_EXCEPTION_CALLBACK)(
590 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
591 IN UINTN ProcessorIndex,
592 IN EFI_EXCEPTION_CALLBACK ExceptionCallback,
593 IN EFI_EXCEPTION_TYPE ExceptionType
594 );
595
596 /**
597 Invalidates processor instruction cache for a memory range. Subsequent execution in this range
598 causes a fresh memory fetch to retrieve code to be executed.
599
600 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
601 @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated.
602 @param Start Specifies the physical base of the memory range to be invalidated.
603 @param Length Specifies the minimum number of bytes in the processor's instruction
604 cache to invalidate.
605
606 @retval EFI_SUCCESS The function completed successfully.
607
608 **/
609 typedef
610 EFI_STATUS
611 (EFIAPI *EFI_INVALIDATE_INSTRUCTION_CACHE)(
612 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
613 IN UINTN ProcessorIndex,
614 IN VOID *Start,
615 IN UINT64 Length
616 );
617
618 ///
619 /// This protocol provides the services to allow the debug agent to register
620 /// callback functions that are called either periodically or when specific
621 /// processor exceptions occur.
622 ///
623 struct _EFI_DEBUG_SUPPORT_PROTOCOL {
624 ///
625 /// Declares the processor architecture for this instance of the EFI Debug Support protocol.
626 ///
627 EFI_INSTRUCTION_SET_ARCHITECTURE Isa;
628 EFI_GET_MAXIMUM_PROCESSOR_INDEX GetMaximumProcessorIndex;
629 EFI_REGISTER_PERIODIC_CALLBACK RegisterPeriodicCallback;
630 EFI_REGISTER_EXCEPTION_CALLBACK RegisterExceptionCallback;
631 EFI_INVALIDATE_INSTRUCTION_CACHE InvalidateInstructionCache;
632 };
633
634 extern EFI_GUID gEfiDebugSupportProtocolGuid;
635
636 #endif
EFI Development Kit II mirror for PVE