DebugSupport.h revision 4ca9b6c4e7dbbcf94f21b54f41f761cefc6b1086 
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
25typedef 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//
38typedef 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//
68typedef 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
98typedef 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//
161typedef 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
191typedef 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//
284typedef 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//
459typedef 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//
476typedef 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**/
494typedef
495VOID
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**/
507typedef
508VOID
509(*EFI_PERIODIC_CALLBACK)(
510  IN OUT EFI_SYSTEM_CONTEXT               SystemContext
511  );
512
513//
514// Machine type definition
515//
516typedef 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**/
539typedef
540EFI_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**/
561typedef
562EFI_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**/
585typedef
586EFI_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**/
607typedef
608EFI_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// DebugSupport protocol definition
618//
619/**
620  @par Protocol Description:
621  This protocol provides the services to allow the debug agent to register
622  callback functions that are called either periodically or when specific
623  processor exceptions occur.
624
625  @param Isa
626  Declares the processor architecture for this instance of the EFI
627  Debug Support protocol.
628
629  @param GetMaximumProcessorIndex
630  Returns the maximum processor index value that may be used.
631
632  @param RegisterPeriodicCallback
633  Registers a callback function that will be invoked periodically
634  and asynchronously to the execution of EFI.
635
636  @param RegisterExceptionCallback
637  Registers a callback function that will be called each time the
638  specified processor exception occurs.
639
640  @param InvalidateInstructionCache
641  Invalidate the instruction cache of the processor. This is required
642  by processor architectures where instruction and data caches are
643  not coherent when instructions in the code under debug has been
644  modified by the debug agent.
645**/
646struct _EFI_DEBUG_SUPPORT_PROTOCOL {
647  EFI_INSTRUCTION_SET_ARCHITECTURE  Isa;
648  EFI_GET_MAXIMUM_PROCESSOR_INDEX   GetMaximumProcessorIndex;
649  EFI_REGISTER_PERIODIC_CALLBACK    RegisterPeriodicCallback;
650  EFI_REGISTER_EXCEPTION_CALLBACK   RegisterExceptionCallback;
651  EFI_INVALIDATE_INSTRUCTION_CACHE  InvalidateInstructionCache;
652};
653
654extern EFI_GUID gEfiDebugSupportProtocolGuid;
655
656#endif
657