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