]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/DebugSupport.h
projects / mirror_edk2.git / blob
? search:


1b782cf6a50013978c8bd71a247f139d0e6780a6
[mirror_edk2.git] / MdePkg / Include / Protocol / DebugSupport.h
1 /** @file
2 DebugSupport protocol and supporting definitions as defined in the EFI 1.1
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 UINT8 St0Mm0[10], Reserved3[6];
79 UINT8 St0Mm1[10], Reserved4[6];
80 UINT8 St0Mm2[10], Reserved5[6];
81 UINT8 St0Mm3[10], Reserved6[6];
82 UINT8 St0Mm4[10], Reserved7[6];
83 UINT8 St0Mm5[10], Reserved8[6];
84 UINT8 St0Mm6[10], Reserved9[6];
85 UINT8 St0Mm7[10], Reserved10[6];
86 UINT8 Reserved11[22 * 16];
87 } EFI_FX_SAVE_STATE_IA32;
88
89 typedef struct {
90 UINT32 ExceptionData;
91 EFI_FX_SAVE_STATE_IA32 FxSaveState;
92 UINT32 Dr0;
93 UINT32 Dr1;
94 UINT32 Dr2;
95 UINT32 Dr3;
96 UINT32 Dr6;
97 UINT32 Dr7;
98 UINT32 Cr0;
99 UINT32 Cr1;
100 UINT32 Cr2;
101 UINT32 Cr3;
102 UINT32 Cr4;
103 UINT32 Eflags;
104 UINT32 Ldtr;
105 UINT32 Tr;
106 UINT32 Gdtr[2];
107 UINT32 Idtr[2];
108 UINT32 Eip;
109 UINT32 Gs;
110 UINT32 Fs;
111 UINT32 Es;
112 UINT32 Ds;
113 UINT32 Cs;
114 UINT32 Ss;
115 UINT32 Edi;
116 UINT32 Esi;
117 UINT32 Ebp;
118 UINT32 Esp;
119 UINT32 Ebx;
120 UINT32 Edx;
121 UINT32 Ecx;
122 UINT32 Eax;
123 } EFI_SYSTEM_CONTEXT_IA32;
124
125 //
126 // IPF processor exception types
127 //
128 #define EXCEPT_IPF_VHTP_TRANSLATION 0
129 #define EXCEPT_IPF_INSTRUCTION_TLB 1
130 #define EXCEPT_IPF_DATA_TLB 2
131 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB 3
132 #define EXCEPT_IPF_ALT_DATA_TLB 4
133 #define EXCEPT_IPF_DATA_NESTED_TLB 5
134 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6
135 #define EXCEPT_IPF_DATA_KEY_MISSED 7
136 #define EXCEPT_IPF_DIRTY_BIT 8
137 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9
138 #define EXCEPT_IPF_DATA_ACCESS_BIT 10
139 #define EXCEPT_IPF_BREAKPOINT 11
140 #define EXCEPT_IPF_EXTERNAL_INTERRUPT 12
141 //
142 // 13 - 19 reserved
143 //
144 #define EXCEPT_IPF_PAGE_NOT_PRESENT 20
145 #define EXCEPT_IPF_KEY_PERMISSION 21
146 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS 22
147 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS 23
148 #define EXCEPT_IPF_GENERAL_EXCEPTION 24
149 #define EXCEPT_IPF_DISABLED_FP_REGISTER 25
150 #define EXCEPT_IPF_NAT_CONSUMPTION 26
151 #define EXCEPT_IPF_SPECULATION 27
152 //
153 // 28 reserved
154 //
155 #define EXCEPT_IPF_DEBUG 29
156 #define EXCEPT_IPF_UNALIGNED_REFERENCE 30
157 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE 31
158 #define EXCEPT_IPF_FP_FAULT 32
159 #define EXCEPT_IPF_FP_TRAP 33
160 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP 34
161 #define EXCEPT_IPF_TAKEN_BRANCH 35
162 #define EXCEPT_IPF_SINGLE_STEP 36
163 //
164 // 37 - 44 reserved
165 //
166 #define EXCEPT_IPF_IA32_EXCEPTION 45
167 #define EXCEPT_IPF_IA32_INTERCEPT 46
168 #define EXCEPT_IPF_IA32_INTERRUPT 47
169
170 //
171 // IPF processor context definition
172 //
173 typedef struct {
174 //
175 // The first reserved field is necessary to preserve alignment for the correct
176 // bits in UNAT and to insure F2 is 16 byte aligned..
177 //
178 UINT64 Reserved;
179 UINT64 R1;
180 UINT64 R2;
181 UINT64 R3;
182 UINT64 R4;
183 UINT64 R5;
184 UINT64 R6;
185 UINT64 R7;
186 UINT64 R8;
187 UINT64 R9;
188 UINT64 R10;
189 UINT64 R11;
190 UINT64 R12;
191 UINT64 R13;
192 UINT64 R14;
193 UINT64 R15;
194 UINT64 R16;
195 UINT64 R17;
196 UINT64 R18;
197 UINT64 R19;
198 UINT64 R20;
199 UINT64 R21;
200 UINT64 R22;
201 UINT64 R23;
202 UINT64 R24;
203 UINT64 R25;
204 UINT64 R26;
205 UINT64 R27;
206 UINT64 R28;
207 UINT64 R29;
208 UINT64 R30;
209 UINT64 R31;
210
211 UINT64 F2[2];
212 UINT64 F3[2];
213 UINT64 F4[2];
214 UINT64 F5[2];
215 UINT64 F6[2];
216 UINT64 F7[2];
217 UINT64 F8[2];
218 UINT64 F9[2];
219 UINT64 F10[2];
220 UINT64 F11[2];
221 UINT64 F12[2];
222 UINT64 F13[2];
223 UINT64 F14[2];
224 UINT64 F15[2];
225 UINT64 F16[2];
226 UINT64 F17[2];
227 UINT64 F18[2];
228 UINT64 F19[2];
229 UINT64 F20[2];
230 UINT64 F21[2];
231 UINT64 F22[2];
232 UINT64 F23[2];
233 UINT64 F24[2];
234 UINT64 F25[2];
235 UINT64 F26[2];
236 UINT64 F27[2];
237 UINT64 F28[2];
238 UINT64 F29[2];
239 UINT64 F30[2];
240 UINT64 F31[2];
241
242 UINT64 Pr;
243
244 UINT64 B0;
245 UINT64 B1;
246 UINT64 B2;
247 UINT64 B3;
248 UINT64 B4;
249 UINT64 B5;
250 UINT64 B6;
251 UINT64 B7;
252
253 //
254 // application registers
255 //
256 UINT64 ArRsc;
257 UINT64 ArBsp;
258 UINT64 ArBspstore;
259 UINT64 ArRnat;
260
261 UINT64 ArFcr;
262
263 UINT64 ArEflag;
264 UINT64 ArCsd;
265 UINT64 ArSsd;
266 UINT64 ArCflg;
267 UINT64 ArFsr;
268 UINT64 ArFir;
269 UINT64 ArFdr;
270
271 UINT64 ArCcv;
272
273 UINT64 ArUnat;
274
275 UINT64 ArFpsr;
276
277 UINT64 ArPfs;
278 UINT64 ArLc;
279 UINT64 ArEc;
280
281 //
282 // control registers
283 //
284 UINT64 CrDcr;
285 UINT64 CrItm;
286 UINT64 CrIva;
287 UINT64 CrPta;
288 UINT64 CrIpsr;
289 UINT64 CrIsr;
290 UINT64 CrIip;
291 UINT64 CrIfa;
292 UINT64 CrItir;
293 UINT64 CrIipa;
294 UINT64 CrIfs;
295 UINT64 CrIim;
296 UINT64 CrIha;
297
298 //
299 // debug registers
300 //
301 UINT64 Dbr0;
302 UINT64 Dbr1;
303 UINT64 Dbr2;
304 UINT64 Dbr3;
305 UINT64 Dbr4;
306 UINT64 Dbr5;
307 UINT64 Dbr6;
308 UINT64 Dbr7;
309
310 UINT64 Ibr0;
311 UINT64 Ibr1;
312 UINT64 Ibr2;
313 UINT64 Ibr3;
314 UINT64 Ibr4;
315 UINT64 Ibr5;
316 UINT64 Ibr6;
317 UINT64 Ibr7;
318
319 //
320 // virtual registers - nat bits for R1-R31
321 //
322 UINT64 IntNat;
323
324 } EFI_SYSTEM_CONTEXT_IPF;
325
326 //
327 // EBC processor exception types
328 //
329 #define EXCEPT_EBC_UNDEFINED 0
330 #define EXCEPT_EBC_DIVIDE_ERROR 1
331 #define EXCEPT_EBC_DEBUG 2
332 #define EXCEPT_EBC_BREAKPOINT 3
333 #define EXCEPT_EBC_OVERFLOW 4
334 #define EXCEPT_EBC_INVALID_OPCODE 5 // opcode out of range
335 #define EXCEPT_EBC_STACK_FAULT 6
336 #define EXCEPT_EBC_ALIGNMENT_CHECK 7
337 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8 // malformed instruction
338 #define EXCEPT_EBC_BAD_BREAK 9 // BREAK 0 or undefined BREAK
339 #define EXCEPT_EBC_STEP 10 // to support debug stepping
340 //
341 // For coding convenience, define the maximum valid EBC exception.
342 //
343 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP
344
345 //
346 // EBC processor context definition
347 //
348 typedef struct {
349 UINT64 R0;
350 UINT64 R1;
351 UINT64 R2;
352 UINT64 R3;
353 UINT64 R4;
354 UINT64 R5;
355 UINT64 R6;
356 UINT64 R7;
357 UINT64 Flags;
358 UINT64 ControlFlags;
359 UINT64 Ip;
360 } EFI_SYSTEM_CONTEXT_EBC;
361
362 //
363 // Universal EFI_SYSTEM_CONTEXT definition
364 //
365 typedef union {
366 EFI_SYSTEM_CONTEXT_EBC *SystemContextEbc;
367 EFI_SYSTEM_CONTEXT_IA32 *SystemContextIa32;
368 EFI_SYSTEM_CONTEXT_IPF *SystemContextIpf;
369 } EFI_SYSTEM_CONTEXT;
370
371 //
372 // DebugSupport callback function prototypes
373 //
374
375 /**
376 Registers and enables an exception callback function for the specified exception.
377
378 @param ExceptionType Exception types in EBC, IA-32, X64, or IPF
379 @param SystemContext Exception content.
380
381 **/
382 typedef
383 VOID
384 (*EFI_EXCEPTION_CALLBACK) (
385 IN EFI_EXCEPTION_TYPE ExceptionType,
386 IN OUT EFI_SYSTEM_CONTEXT SystemContext
387 );
388
389 /**
390 Registers and enables the on-target debug agent¡¯s periodic entry point.
391
392 @param SystemContext Exception content.
393
394 **/
395 typedef
396 VOID
397 (*EFI_PERIODIC_CALLBACK) (
398 IN OUT EFI_SYSTEM_CONTEXT SystemContext
399 );
400
401 //
402 // Machine type definition
403 //
404 typedef enum {
405 IsaIa32 = IMAGE_FILE_MACHINE_I386, // 0x014C
406 IsaX64 = IMAGE_FILE_MACHINE_X64, // 0x8664
407 IsaIpf = IMAGE_FILE_MACHINE_IA64, // 0x0200
408 IsaEbc = IMAGE_FILE_MACHINE_EBC // 0x0EBC
409 } EFI_INSTRUCTION_SET_ARCHITECTURE;
410
411
412 //
413 // DebugSupport member function definitions
414 //
415
416 /**
417 Returns the maximum value that may be used for the ProcessorIndex parameter in
418 RegisterPeriodicCallback() and RegisterExceptionCallback().
419
420 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
421 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported
422 processor index is returned.
423
424 @retval EFI_SUCCESS The function completed successfully.
425
426 **/
427 typedef
428 EFI_STATUS
429 (EFIAPI *EFI_GET_MAXIMUM_PROCESSOR_INDEX) (
430 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
431 OUT UINTN *MaxProcessorIndex
432 );
433
434 /**
435 Registers a function to be called back periodically in interrupt context.
436
437 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
438 @param ProcessorIndex Specifies which processor the callback function applies to.
439 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main
440 periodic entry point of the debug agent.
441
442 @retval EFI_SUCCESS The function completed successfully.
443 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
444 function was previously registered.
445 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
446 function.
447
448 **/
449 typedef
450 EFI_STATUS
451 (EFIAPI *EFI_REGISTER_PERIODIC_CALLBACK) (
452 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
453 IN UINTN ProcessorIndex,
454 IN EFI_PERIODIC_CALLBACK PeriodicCallback
455 );
456
457 /**
458 Registers a function to be called when a given processor exception occurs.
459
460 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
461 @param ProcessorIndex Specifies which processor the callback function applies to.
462 @param PeriodicCallback A pointer to a function of type EXCEPTION_CALLBACK that is called
463 when the processor exception specified by ExceptionType occurs.
464 @param ExceptionType Specifies which processor exception to hook.
465
466 @retval EFI_SUCCESS The function completed successfully.
467 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
468 function was previously registered.
469 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
470 function.
471
472 **/
473 typedef
474 EFI_STATUS
475 (EFIAPI *EFI_REGISTER_EXCEPTION_CALLBACK) (
476 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
477 IN UINTN ProcessorIndex,
478 IN EFI_EXCEPTION_CALLBACK ExceptionCallback,
479 IN EFI_EXCEPTION_TYPE ExceptionType
480 );
481
482 /**
483 Invalidates processor instruction cache for a memory range. Subsequent execution in this range
484 causes a fresh memory fetch to retrieve code to be executed.
485
486 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
487 @param ProcessorIndex Specifies which processor¡¯s instruction cache is to be invalidated.
488 @param Start Specifies the physical base of the memory range to be invalidated.
489 @param Length Specifies the minimum number of bytes in the processor¡¯s instruction
490 cache to invalidate.
491
492 @retval EFI_SUCCESS The function completed successfully.
493
494 **/
495 typedef
496 EFI_STATUS
497 (EFIAPI *EFI_INVALIDATE_INSTRUCTION_CACHE) (
498 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
499 IN UINTN ProcessorIndex,
500 IN VOID *Start,
501 IN UINT64 Length
502 );
503
504 //
505 // DebugSupport protocol definition
506 //
507 struct _EFI_DEBUG_SUPPORT_PROTOCOL {
508 EFI_INSTRUCTION_SET_ARCHITECTURE Isa;
509 EFI_GET_MAXIMUM_PROCESSOR_INDEX GetMaximumProcessorIndex;
510 EFI_REGISTER_PERIODIC_CALLBACK RegisterPeriodicCallback;
511 EFI_REGISTER_EXCEPTION_CALLBACK RegisterExceptionCallback;
512 EFI_INVALIDATE_INSTRUCTION_CACHE InvalidateInstructionCache;
513 };
514
515 extern EFI_GUID gEfiDebugSupportProtocolGuid;
516
517 #endif
EFI Development Kit II mirror for PVE