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