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