1 /** @file
2   DebugSupport protocol and supporting definitions as defined in the UEFI2.4
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 - 2010, Intel Corporation. All rights reserved.<BR>
9 Portions copyright (c) 2011 - 2013, ARM Ltd. All rights reserved.<BR>
10 
11 This program and the accompanying materials are licensed and made available under
12 the terms and conditions of the BSD License that accompanies this distribution.
13 The full text of the license may be found at
14 http://opensource.org/licenses/bsd-license.php.
15 
16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
17 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 
19 **/
20 
21 #ifndef __DEBUG_SUPPORT_H__
22 #define __DEBUG_SUPPORT_H__
23 
24 #include <IndustryStandard/PeImage.h>
25 
26 typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL;
27 
28 ///
29 /// Debug Support protocol {2755590C-6F3C-42FA-9EA4-A3BA543CDA25}.
30 ///
31 #define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \
32   { \
33     0x2755590C, 0x6F3C, 0x42FA, {0x9E, 0xA4, 0xA3, 0xBA, 0x54, 0x3C, 0xDA, 0x25 } \
34   }
35 
36 ///
37 /// Processor exception to be hooked.
38 /// All exception types for IA32, X64, Itanium and EBC processors are defined.
39 ///
40 typedef INTN  EFI_EXCEPTION_TYPE;
41 
42 ///
43 ///  IA-32 processor exception types.
44 ///
45 #define EXCEPT_IA32_DIVIDE_ERROR    0
46 #define EXCEPT_IA32_DEBUG           1
47 #define EXCEPT_IA32_NMI             2
48 #define EXCEPT_IA32_BREAKPOINT      3
49 #define EXCEPT_IA32_OVERFLOW        4
50 #define EXCEPT_IA32_BOUND           5
51 #define EXCEPT_IA32_INVALID_OPCODE  6
52 #define EXCEPT_IA32_DOUBLE_FAULT    8
53 #define EXCEPT_IA32_INVALID_TSS     10
54 #define EXCEPT_IA32_SEG_NOT_PRESENT 11
55 #define EXCEPT_IA32_STACK_FAULT     12
56 #define EXCEPT_IA32_GP_FAULT        13
57 #define EXCEPT_IA32_PAGE_FAULT      14
58 #define EXCEPT_IA32_FP_ERROR        16
59 #define EXCEPT_IA32_ALIGNMENT_CHECK 17
60 #define EXCEPT_IA32_MACHINE_CHECK   18
61 #define EXCEPT_IA32_SIMD            19
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   UINT8   St0Mm0[10], Reserved3[6];
79   UINT8   St1Mm1[10], Reserved4[6];
80   UINT8   St2Mm2[10], Reserved5[6];
81   UINT8   St3Mm3[10], Reserved6[6];
82   UINT8   St4Mm4[10], Reserved7[6];
83   UINT8   St5Mm5[10], Reserved8[6];
84   UINT8   St6Mm6[10], Reserved9[6];
85   UINT8   St7Mm7[10], Reserved10[6];
86   UINT8   Xmm0[16];
87   UINT8   Xmm1[16];
88   UINT8   Xmm2[16];
89   UINT8   Xmm3[16];
90   UINT8   Xmm4[16];
91   UINT8   Xmm5[16];
92   UINT8   Xmm6[16];
93   UINT8   Xmm7[16];
94   UINT8   Reserved11[14 * 16];
95 } EFI_FX_SAVE_STATE_IA32;
96 
97 ///
98 ///  IA-32 processor context definition.
99 ///
100 typedef struct {
101   UINT32                 ExceptionData;
102   EFI_FX_SAVE_STATE_IA32 FxSaveState;
103   UINT32                 Dr0;
104   UINT32                 Dr1;
105   UINT32                 Dr2;
106   UINT32                 Dr3;
107   UINT32                 Dr6;
108   UINT32                 Dr7;
109   UINT32                 Cr0;
110   UINT32                 Cr1;  /* Reserved */
111   UINT32                 Cr2;
112   UINT32                 Cr3;
113   UINT32                 Cr4;
114   UINT32                 Eflags;
115   UINT32                 Ldtr;
116   UINT32                 Tr;
117   UINT32                 Gdtr[2];
118   UINT32                 Idtr[2];
119   UINT32                 Eip;
120   UINT32                 Gs;
121   UINT32                 Fs;
122   UINT32                 Es;
123   UINT32                 Ds;
124   UINT32                 Cs;
125   UINT32                 Ss;
126   UINT32                 Edi;
127   UINT32                 Esi;
128   UINT32                 Ebp;
129   UINT32                 Esp;
130   UINT32                 Ebx;
131   UINT32                 Edx;
132   UINT32                 Ecx;
133   UINT32                 Eax;
134 } EFI_SYSTEM_CONTEXT_IA32;
135 
136 ///
137 ///  x64 processor exception types.
138 ///
139 #define EXCEPT_X64_DIVIDE_ERROR    0
140 #define EXCEPT_X64_DEBUG           1
141 #define EXCEPT_X64_NMI             2
142 #define EXCEPT_X64_BREAKPOINT      3
143 #define EXCEPT_X64_OVERFLOW        4
144 #define EXCEPT_X64_BOUND           5
145 #define EXCEPT_X64_INVALID_OPCODE  6
146 #define EXCEPT_X64_DOUBLE_FAULT    8
147 #define EXCEPT_X64_INVALID_TSS     10
148 #define EXCEPT_X64_SEG_NOT_PRESENT 11
149 #define EXCEPT_X64_STACK_FAULT     12
150 #define EXCEPT_X64_GP_FAULT        13
151 #define EXCEPT_X64_PAGE_FAULT      14
152 #define EXCEPT_X64_FP_ERROR        16
153 #define EXCEPT_X64_ALIGNMENT_CHECK 17
154 #define EXCEPT_X64_MACHINE_CHECK   18
155 #define EXCEPT_X64_SIMD            19
156 
157 ///
158 /// FXSAVE_STATE.
159 /// FP / MMX / XMM registers (see fxrstor instruction definition).
160 ///
161 typedef struct {
162   UINT16  Fcw;
163   UINT16  Fsw;
164   UINT16  Ftw;
165   UINT16  Opcode;
166   UINT64  Rip;
167   UINT64  DataOffset;
168   UINT8   Reserved1[8];
169   UINT8   St0Mm0[10], Reserved2[6];
170   UINT8   St1Mm1[10], Reserved3[6];
171   UINT8   St2Mm2[10], Reserved4[6];
172   UINT8   St3Mm3[10], Reserved5[6];
173   UINT8   St4Mm4[10], Reserved6[6];
174   UINT8   St5Mm5[10], Reserved7[6];
175   UINT8   St6Mm6[10], Reserved8[6];
176   UINT8   St7Mm7[10], Reserved9[6];
177   UINT8   Xmm0[16];
178   UINT8   Xmm1[16];
179   UINT8   Xmm2[16];
180   UINT8   Xmm3[16];
181   UINT8   Xmm4[16];
182   UINT8   Xmm5[16];
183   UINT8   Xmm6[16];
184   UINT8   Xmm7[16];
185   //
186   // NOTE: UEFI 2.0 spec definition as follows.
187   //
188   UINT8   Reserved11[14 * 16];
189 } EFI_FX_SAVE_STATE_X64;
190 
191 ///
192 ///  x64 processor context definition.
193 ///
194 typedef struct {
195   UINT64                ExceptionData;
196   EFI_FX_SAVE_STATE_X64 FxSaveState;
197   UINT64                Dr0;
198   UINT64                Dr1;
199   UINT64                Dr2;
200   UINT64                Dr3;
201   UINT64                Dr6;
202   UINT64                Dr7;
203   UINT64                Cr0;
204   UINT64                Cr1;  /* Reserved */
205   UINT64                Cr2;
206   UINT64                Cr3;
207   UINT64                Cr4;
208   UINT64                Cr8;
209   UINT64                Rflags;
210   UINT64                Ldtr;
211   UINT64                Tr;
212   UINT64                Gdtr[2];
213   UINT64                Idtr[2];
214   UINT64                Rip;
215   UINT64                Gs;
216   UINT64                Fs;
217   UINT64                Es;
218   UINT64                Ds;
219   UINT64                Cs;
220   UINT64                Ss;
221   UINT64                Rdi;
222   UINT64                Rsi;
223   UINT64                Rbp;
224   UINT64                Rsp;
225   UINT64                Rbx;
226   UINT64                Rdx;
227   UINT64                Rcx;
228   UINT64                Rax;
229   UINT64                R8;
230   UINT64                R9;
231   UINT64                R10;
232   UINT64                R11;
233   UINT64                R12;
234   UINT64                R13;
235   UINT64                R14;
236   UINT64                R15;
237 } EFI_SYSTEM_CONTEXT_X64;
238 
239 ///
240 ///  Itanium Processor Family Exception types.
241 ///
242 #define EXCEPT_IPF_VHTP_TRANSLATION       0
243 #define EXCEPT_IPF_INSTRUCTION_TLB        1
244 #define EXCEPT_IPF_DATA_TLB               2
245 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB    3
246 #define EXCEPT_IPF_ALT_DATA_TLB           4
247 #define EXCEPT_IPF_DATA_NESTED_TLB        5
248 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6
249 #define EXCEPT_IPF_DATA_KEY_MISSED        7
250 #define EXCEPT_IPF_DIRTY_BIT              8
251 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9
252 #define EXCEPT_IPF_DATA_ACCESS_BIT        10
253 #define EXCEPT_IPF_BREAKPOINT             11
254 #define EXCEPT_IPF_EXTERNAL_INTERRUPT     12
255 //
256 // 13 - 19 reserved
257 //
258 #define EXCEPT_IPF_PAGE_NOT_PRESENT           20
259 #define EXCEPT_IPF_KEY_PERMISSION             21
260 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS  22
261 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS         23
262 #define EXCEPT_IPF_GENERAL_EXCEPTION          24
263 #define EXCEPT_IPF_DISABLED_FP_REGISTER       25
264 #define EXCEPT_IPF_NAT_CONSUMPTION            26
265 #define EXCEPT_IPF_SPECULATION                27
266 //
267 // 28 reserved
268 //
269 #define EXCEPT_IPF_DEBUG                          29
270 #define EXCEPT_IPF_UNALIGNED_REFERENCE            30
271 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE     31
272 #define EXCEPT_IPF_FP_FAULT                       32
273 #define EXCEPT_IPF_FP_TRAP                        33
274 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP  34
275 #define EXCEPT_IPF_TAKEN_BRANCH                   35
276 #define EXCEPT_IPF_SINGLE_STEP                    36
277 //
278 // 37 - 44 reserved
279 //
280 #define EXCEPT_IPF_IA32_EXCEPTION 45
281 #define EXCEPT_IPF_IA32_INTERCEPT 46
282 #define EXCEPT_IPF_IA32_INTERRUPT 47
283 
284 ///
285 ///  IPF processor context definition.
286 ///
287 typedef struct {
288   //
289   // The first reserved field is necessary to preserve alignment for the correct
290   // bits in UNAT and to insure F2 is 16 byte aligned.
291   //
292   UINT64  Reserved;
293   UINT64  R1;
294   UINT64  R2;
295   UINT64  R3;
296   UINT64  R4;
297   UINT64  R5;
298   UINT64  R6;
299   UINT64  R7;
300   UINT64  R8;
301   UINT64  R9;
302   UINT64  R10;
303   UINT64  R11;
304   UINT64  R12;
305   UINT64  R13;
306   UINT64  R14;
307   UINT64  R15;
308   UINT64  R16;
309   UINT64  R17;
310   UINT64  R18;
311   UINT64  R19;
312   UINT64  R20;
313   UINT64  R21;
314   UINT64  R22;
315   UINT64  R23;
316   UINT64  R24;
317   UINT64  R25;
318   UINT64  R26;
319   UINT64  R27;
320   UINT64  R28;
321   UINT64  R29;
322   UINT64  R30;
323   UINT64  R31;
324 
325   UINT64  F2[2];
326   UINT64  F3[2];
327   UINT64  F4[2];
328   UINT64  F5[2];
329   UINT64  F6[2];
330   UINT64  F7[2];
331   UINT64  F8[2];
332   UINT64  F9[2];
333   UINT64  F10[2];
334   UINT64  F11[2];
335   UINT64  F12[2];
336   UINT64  F13[2];
337   UINT64  F14[2];
338   UINT64  F15[2];
339   UINT64  F16[2];
340   UINT64  F17[2];
341   UINT64  F18[2];
342   UINT64  F19[2];
343   UINT64  F20[2];
344   UINT64  F21[2];
345   UINT64  F22[2];
346   UINT64  F23[2];
347   UINT64  F24[2];
348   UINT64  F25[2];
349   UINT64  F26[2];
350   UINT64  F27[2];
351   UINT64  F28[2];
352   UINT64  F29[2];
353   UINT64  F30[2];
354   UINT64  F31[2];
355 
356   UINT64  Pr;
357 
358   UINT64  B0;
359   UINT64  B1;
360   UINT64  B2;
361   UINT64  B3;
362   UINT64  B4;
363   UINT64  B5;
364   UINT64  B6;
365   UINT64  B7;
366 
367   //
368   // application registers
369   //
370   UINT64  ArRsc;
371   UINT64  ArBsp;
372   UINT64  ArBspstore;
373   UINT64  ArRnat;
374 
375   UINT64  ArFcr;
376 
377   UINT64  ArEflag;
378   UINT64  ArCsd;
379   UINT64  ArSsd;
380   UINT64  ArCflg;
381   UINT64  ArFsr;
382   UINT64  ArFir;
383   UINT64  ArFdr;
384 
385   UINT64  ArCcv;
386 
387   UINT64  ArUnat;
388 
389   UINT64  ArFpsr;
390 
391   UINT64  ArPfs;
392   UINT64  ArLc;
393   UINT64  ArEc;
394 
395   //
396   // control registers
397   //
398   UINT64  CrDcr;
399   UINT64  CrItm;
400   UINT64  CrIva;
401   UINT64  CrPta;
402   UINT64  CrIpsr;
403   UINT64  CrIsr;
404   UINT64  CrIip;
405   UINT64  CrIfa;
406   UINT64  CrItir;
407   UINT64  CrIipa;
408   UINT64  CrIfs;
409   UINT64  CrIim;
410   UINT64  CrIha;
411 
412   //
413   // debug registers
414   //
415   UINT64  Dbr0;
416   UINT64  Dbr1;
417   UINT64  Dbr2;
418   UINT64  Dbr3;
419   UINT64  Dbr4;
420   UINT64  Dbr5;
421   UINT64  Dbr6;
422   UINT64  Dbr7;
423 
424   UINT64  Ibr0;
425   UINT64  Ibr1;
426   UINT64  Ibr2;
427   UINT64  Ibr3;
428   UINT64  Ibr4;
429   UINT64  Ibr5;
430   UINT64  Ibr6;
431   UINT64  Ibr7;
432 
433   //
434   // virtual registers - nat bits for R1-R31
435   //
436   UINT64  IntNat;
437 
438 } EFI_SYSTEM_CONTEXT_IPF;
439 
440 ///
441 ///  EBC processor exception types.
442 ///
443 #define EXCEPT_EBC_UNDEFINED            0
444 #define EXCEPT_EBC_DIVIDE_ERROR         1
445 #define EXCEPT_EBC_DEBUG                2
446 #define EXCEPT_EBC_BREAKPOINT           3
447 #define EXCEPT_EBC_OVERFLOW             4
448 #define EXCEPT_EBC_INVALID_OPCODE       5   ///< Opcode out of range.
449 #define EXCEPT_EBC_STACK_FAULT          6
450 #define EXCEPT_EBC_ALIGNMENT_CHECK      7
451 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8   ///< Malformed instruction.
452 #define EXCEPT_EBC_BAD_BREAK            9   ///< BREAK 0 or undefined BREAK.
453 #define EXCEPT_EBC_STEP                 10  ///< To support debug stepping.
454 ///
455 /// For coding convenience, define the maximum valid EBC exception.
456 ///
457 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP
458 
459 ///
460 ///  EBC processor context definition.
461 ///
462 typedef struct {
463   UINT64  R0;
464   UINT64  R1;
465   UINT64  R2;
466   UINT64  R3;
467   UINT64  R4;
468   UINT64  R5;
469   UINT64  R6;
470   UINT64  R7;
471   UINT64  Flags;
472   UINT64  ControlFlags;
473   UINT64  Ip;
474 } EFI_SYSTEM_CONTEXT_EBC;
475 
476 
477 
478 ///
479 ///  ARM processor exception types.
480 ///
481 #define EXCEPT_ARM_RESET                    0
482 #define EXCEPT_ARM_UNDEFINED_INSTRUCTION    1
483 #define EXCEPT_ARM_SOFTWARE_INTERRUPT       2
484 #define EXCEPT_ARM_PREFETCH_ABORT           3
485 #define EXCEPT_ARM_DATA_ABORT               4
486 #define EXCEPT_ARM_RESERVED                 5
487 #define EXCEPT_ARM_IRQ                      6
488 #define EXCEPT_ARM_FIQ                      7
489 
490 ///
491 /// For coding convenience, define the maximum valid ARM exception.
492 ///
493 #define MAX_ARM_EXCEPTION EXCEPT_ARM_FIQ
494 
495 ///
496 ///  ARM processor context definition.
497 ///
498 typedef struct {
499   UINT32  R0;
500   UINT32  R1;
501   UINT32  R2;
502   UINT32  R3;
503   UINT32  R4;
504   UINT32  R5;
505   UINT32  R6;
506   UINT32  R7;
507   UINT32  R8;
508   UINT32  R9;
509   UINT32  R10;
510   UINT32  R11;
511   UINT32  R12;
512   UINT32  SP;
513   UINT32  LR;
514   UINT32  PC;
515   UINT32  CPSR;
516   UINT32  DFSR;
517   UINT32  DFAR;
518   UINT32  IFSR;
519   UINT32  IFAR;
520 } EFI_SYSTEM_CONTEXT_ARM;
521 
522 
523 ///
524 ///  AARCH64 processor exception types.
525 ///
526 #define EXCEPT_AARCH64_SYNCHRONOUS_EXCEPTIONS    0
527 #define EXCEPT_AARCH64_IRQ                       1
528 #define EXCEPT_AARCH64_FIQ                       2
529 #define EXCEPT_AARCH64_SERROR                    3
530 
531 ///
532 /// For coding convenience, define the maximum valid ARM exception.
533 ///
534 #define MAX_AARCH64_EXCEPTION EXCEPT_AARCH64_SERROR
535 
536 typedef struct {
537   // General Purpose Registers
538   UINT64  X0;
539   UINT64  X1;
540   UINT64  X2;
541   UINT64  X3;
542   UINT64  X4;
543   UINT64  X5;
544   UINT64  X6;
545   UINT64  X7;
546   UINT64  X8;
547   UINT64  X9;
548   UINT64  X10;
549   UINT64  X11;
550   UINT64  X12;
551   UINT64  X13;
552   UINT64  X14;
553   UINT64  X15;
554   UINT64  X16;
555   UINT64  X17;
556   UINT64  X18;
557   UINT64  X19;
558   UINT64  X20;
559   UINT64  X21;
560   UINT64  X22;
561   UINT64  X23;
562   UINT64  X24;
563   UINT64  X25;
564   UINT64  X26;
565   UINT64  X27;
566   UINT64  X28;
567   UINT64  FP;   // x29 - Frame pointer
568   UINT64  LR;   // x30 - Link Register
569   UINT64  SP;   // x31 - Stack pointer
570 
571   // FP/SIMD Registers
572   UINT64  V0[2];
573   UINT64  V1[2];
574   UINT64  V2[2];
575   UINT64  V3[2];
576   UINT64  V4[2];
577   UINT64  V5[2];
578   UINT64  V6[2];
579   UINT64  V7[2];
580   UINT64  V8[2];
581   UINT64  V9[2];
582   UINT64  V10[2];
583   UINT64  V11[2];
584   UINT64  V12[2];
585   UINT64  V13[2];
586   UINT64  V14[2];
587   UINT64  V15[2];
588   UINT64  V16[2];
589   UINT64  V17[2];
590   UINT64  V18[2];
591   UINT64  V19[2];
592   UINT64  V20[2];
593   UINT64  V21[2];
594   UINT64  V22[2];
595   UINT64  V23[2];
596   UINT64  V24[2];
597   UINT64  V25[2];
598   UINT64  V26[2];
599   UINT64  V27[2];
600   UINT64  V28[2];
601   UINT64  V29[2];
602   UINT64  V30[2];
603   UINT64  V31[2];
604 
605   UINT64  ELR;  // Exception Link Register
606   UINT64  SPSR; // Saved Processor Status Register
607   UINT64  FPSR; // Floating Point Status Register
608   UINT64  ESR;  // Exception syndrome register
609   UINT64  FAR;  // Fault Address Register
610 } EFI_SYSTEM_CONTEXT_AARCH64;
611 
612 
613 ///
614 /// Universal EFI_SYSTEM_CONTEXT definition.
615 ///
616 typedef union {
617   EFI_SYSTEM_CONTEXT_EBC  *SystemContextEbc;
618   EFI_SYSTEM_CONTEXT_IA32 *SystemContextIa32;
619   EFI_SYSTEM_CONTEXT_X64  *SystemContextX64;
620   EFI_SYSTEM_CONTEXT_IPF  *SystemContextIpf;
621   EFI_SYSTEM_CONTEXT_ARM  *SystemContextArm;
622   EFI_SYSTEM_CONTEXT_AARCH64  *SystemContextAArch64;
623 } EFI_SYSTEM_CONTEXT;
624 
625 //
626 // DebugSupport callback function prototypes
627 //
628 
629 /**
630   Registers and enables an exception callback function for the specified exception.
631 
632   @param  ExceptionType         Exception types in EBC, IA-32, x64, or IPF.
633   @param  SystemContext         Exception content.
634 
635 **/
636 typedef
637 VOID
638 (EFIAPI *EFI_EXCEPTION_CALLBACK)(
639   IN     EFI_EXCEPTION_TYPE               ExceptionType,
640   IN OUT EFI_SYSTEM_CONTEXT               SystemContext
641   );
642 
643 /**
644   Registers and enables the on-target debug agent's periodic entry point.
645 
646   @param  SystemContext         Exception content.
647 
648 **/
649 typedef
650 VOID
651 (EFIAPI *EFI_PERIODIC_CALLBACK)(
652   IN OUT EFI_SYSTEM_CONTEXT               SystemContext
653   );
654 
655 ///
656 /// Machine type definition
657 ///
658 typedef enum {
659   IsaIa32 = IMAGE_FILE_MACHINE_I386,           ///< 0x014C
660   IsaX64  = IMAGE_FILE_MACHINE_X64,            ///< 0x8664
661   IsaIpf  = IMAGE_FILE_MACHINE_IA64,           ///< 0x0200
662   IsaEbc  = IMAGE_FILE_MACHINE_EBC,            ///< 0x0EBC
663   IsaArm  = IMAGE_FILE_MACHINE_ARMTHUMB_MIXED, ///< 0x01c2
664   IsaAArch64  = IMAGE_FILE_MACHINE_ARM64       ///< 0xAA64
665 } EFI_INSTRUCTION_SET_ARCHITECTURE;
666 
667 
668 //
669 // DebugSupport member function definitions
670 //
671 
672 /**
673   Returns the maximum value that may be used for the ProcessorIndex parameter in
674   RegisterPeriodicCallback() and RegisterExceptionCallback().
675 
676   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
677   @param  MaxProcessorIndex     Pointer to a caller-allocated UINTN in which the maximum supported
678                                 processor index is returned.
679 
680   @retval EFI_SUCCESS           The function completed successfully.
681 
682 **/
683 typedef
684 EFI_STATUS
685 (EFIAPI *EFI_GET_MAXIMUM_PROCESSOR_INDEX)(
686   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
687   OUT UINTN                              *MaxProcessorIndex
688   );
689 
690 /**
691   Registers a function to be called back periodically in interrupt context.
692 
693   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
694   @param  ProcessorIndex        Specifies which processor the callback function applies to.
695   @param  PeriodicCallback      A pointer to a function of type PERIODIC_CALLBACK that is the main
696                                 periodic entry point of the debug agent.
697 
698   @retval EFI_SUCCESS           The function completed successfully.
699   @retval EFI_ALREADY_STARTED   Non-NULL PeriodicCallback parameter when a callback
700                                 function was previously registered.
701   @retval EFI_OUT_OF_RESOURCES  System has insufficient memory resources to register new callback
702                                 function.
703 
704 **/
705 typedef
706 EFI_STATUS
707 (EFIAPI *EFI_REGISTER_PERIODIC_CALLBACK)(
708   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
709   IN UINTN                               ProcessorIndex,
710   IN EFI_PERIODIC_CALLBACK               PeriodicCallback
711   );
712 
713 /**
714   Registers a function to be called when a given processor exception occurs.
715 
716   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
717   @param  ProcessorIndex        Specifies which processor the callback function applies to.
718   @param  ExceptionCallback     A pointer to a function of type EXCEPTION_CALLBACK that is called
719                                 when the processor exception specified by ExceptionType occurs.
720   @param  ExceptionType         Specifies which processor exception to hook.
721 
722   @retval EFI_SUCCESS           The function completed successfully.
723   @retval EFI_ALREADY_STARTED   Non-NULL PeriodicCallback parameter when a callback
724                                 function was previously registered.
725   @retval EFI_OUT_OF_RESOURCES  System has insufficient memory resources to register new callback
726                                 function.
727 
728 **/
729 typedef
730 EFI_STATUS
731 (EFIAPI *EFI_REGISTER_EXCEPTION_CALLBACK)(
732   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
733   IN UINTN                               ProcessorIndex,
734   IN EFI_EXCEPTION_CALLBACK              ExceptionCallback,
735   IN EFI_EXCEPTION_TYPE                  ExceptionType
736   );
737 
738 /**
739   Invalidates processor instruction cache for a memory range. Subsequent execution in this range
740   causes a fresh memory fetch to retrieve code to be executed.
741 
742   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
743   @param  ProcessorIndex        Specifies which processor's instruction cache is to be invalidated.
744   @param  Start                 Specifies the physical base of the memory range to be invalidated.
745   @param  Length                Specifies the minimum number of bytes in the processor's instruction
746                                 cache to invalidate.
747 
748   @retval EFI_SUCCESS           The function completed successfully.
749 
750 **/
751 typedef
752 EFI_STATUS
753 (EFIAPI *EFI_INVALIDATE_INSTRUCTION_CACHE)(
754   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
755   IN UINTN                               ProcessorIndex,
756   IN VOID                                *Start,
757   IN UINT64                              Length
758   );
759 
760 ///
761 /// This protocol provides the services to allow the debug agent to register
762 /// callback functions that are called either periodically or when specific
763 /// processor exceptions occur.
764 ///
765 struct _EFI_DEBUG_SUPPORT_PROTOCOL {
766   ///
767   /// Declares the processor architecture for this instance of the EFI Debug Support protocol.
768   ///
769   EFI_INSTRUCTION_SET_ARCHITECTURE  Isa;
770   EFI_GET_MAXIMUM_PROCESSOR_INDEX   GetMaximumProcessorIndex;
771   EFI_REGISTER_PERIODIC_CALLBACK    RegisterPeriodicCallback;
772   EFI_REGISTER_EXCEPTION_CALLBACK   RegisterExceptionCallback;
773   EFI_INVALIDATE_INSTRUCTION_CACHE  InvalidateInstructionCache;
774 };
775 
776 extern EFI_GUID gEfiDebugSupportProtocolGuid;
777 
778 #endif
779