2 DebugSupport protocol and supporting definitions as defined in the UEFI2.0
5 The DebugSupport protocol is used by source level debuggers to abstract the
6 processor and handle context save and restore operations.
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
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.
17 Module Name: DebugSupport.h
21 #ifndef __DEBUG_SUPPORT_H__
22 #define __DEBUG_SUPPORT_H__
24 #include <IndustryStandard/PeImage.h>
26 typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL
;
29 // Debug Support protocol {2755590C-6F3C-42FA-9EA4-A3BA543CDA25}
31 #define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \
33 0x2755590C, 0x6F3C, 0x42FA, {0x9E, 0xA4, 0xA3, 0xBA, 0x54, 0x3C, 0xDA, 0x25 } \
37 // Debug Support definitions
39 typedef INTN EFI_EXCEPTION_TYPE
;
42 // IA-32 processor exception types
44 #define EXCEPT_IA32_DIVIDE_ERROR 0
45 #define EXCEPT_IA32_DEBUG 1
46 #define EXCEPT_IA32_NMI 2
47 #define EXCEPT_IA32_BREAKPOINT 3
48 #define EXCEPT_IA32_OVERFLOW 4
49 #define EXCEPT_IA32_BOUND 5
50 #define EXCEPT_IA32_INVALID_OPCODE 6
51 #define EXCEPT_IA32_DOUBLE_FAULT 8
52 #define EXCEPT_IA32_INVALID_TSS 10
53 #define EXCEPT_IA32_SEG_NOT_PRESENT 11
54 #define EXCEPT_IA32_STACK_FAULT 12
55 #define EXCEPT_IA32_GP_FAULT 13
56 #define EXCEPT_IA32_PAGE_FAULT 14
57 #define EXCEPT_IA32_FP_ERROR 16
58 #define EXCEPT_IA32_ALIGNMENT_CHECK 17
59 #define EXCEPT_IA32_MACHINE_CHECK 18
60 #define EXCEPT_IA32_SIMD 19
63 // IA-32 processor context definition
67 // FP / MMX / XMM registers (see fxrstor instruction definition)
80 #if (EFI_SPECIFICATION_VERSION >= 0x00020000)
81 UINT8 St0Mm0
[10], Reserved3
[6];
82 UINT8 St1Mm1
[10], Reserved4
[6];
83 UINT8 St2Mm2
[10], Reserved5
[6];
84 UINT8 St3Mm3
[10], Reserved6
[6];
85 UINT8 St4Mm4
[10], Reserved7
[6];
86 UINT8 St5Mm5
[10], Reserved8
[6];
87 UINT8 St6Mm6
[10], Reserved9
[6];
88 UINT8 St7Mm7
[10], Reserved10
[6];
97 UINT8 Reserved11
[14 * 16];
98 } EFI_FX_SAVE_STATE_IA32
;
100 UINT8 St0Mm0
[10], Reserved3
[6];
101 UINT8 St0Mm1
[10], Reserved4
[6];
102 UINT8 St0Mm2
[10], Reserved5
[6];
103 UINT8 St0Mm3
[10], Reserved6
[6];
104 UINT8 St0Mm4
[10], Reserved7
[6];
105 UINT8 St0Mm5
[10], Reserved8
[6];
106 UINT8 St0Mm6
[10], Reserved9
[6];
107 UINT8 St0Mm7
[10], Reserved10
[6];
108 UINT8 Reserved11
[22 * 16];
113 UINT32 ExceptionData
;
114 #if (EFI_SPECIFICATION_VERSION >= 0x00020000)
115 EFI_FX_SAVE_STATE_IA32 FxSaveState
;
117 EFI_FX_SAVE_STATE FxSaveState
;
126 UINT32 Cr1
; /* Reserved */
150 } EFI_SYSTEM_CONTEXT_IA32
;
153 // X64 processor exception types
155 #define EXCEPT_X64_DIVIDE_ERROR 0
156 #define EXCEPT_X64_DEBUG 1
157 #define EXCEPT_X64_NMI 2
158 #define EXCEPT_X64_BREAKPOINT 3
159 #define EXCEPT_X64_OVERFLOW 4
160 #define EXCEPT_X64_BOUND 5
161 #define EXCEPT_X64_INVALID_OPCODE 6
162 #define EXCEPT_X64_DOUBLE_FAULT 8
163 #define EXCEPT_X64_INVALID_TSS 10
164 #define EXCEPT_X64_SEG_NOT_PRESENT 11
165 #define EXCEPT_X64_STACK_FAULT 12
166 #define EXCEPT_X64_GP_FAULT 13
167 #define EXCEPT_X64_PAGE_FAULT 14
168 #define EXCEPT_X64_FP_ERROR 16
169 #define EXCEPT_X64_ALIGNMENT_CHECK 17
170 #define EXCEPT_X64_MACHINE_CHECK 18
171 #define EXCEPT_X64_SIMD 19
174 // X64 processor context definition
177 // FP / MMX / XMM registers (see fxrstor instruction definition)
187 UINT8 St0Mm0
[10], Reserved2
[6];
188 UINT8 St1Mm1
[10], Reserved3
[6];
189 UINT8 St2Mm2
[10], Reserved4
[6];
190 UINT8 St3Mm3
[10], Reserved5
[6];
191 UINT8 St4Mm4
[10], Reserved6
[6];
192 UINT8 St5Mm5
[10], Reserved7
[6];
193 UINT8 St6Mm6
[10], Reserved8
[6];
194 UINT8 St7Mm7
[10], Reserved9
[6];
203 #if (EFI_SPECIFICATION_VERSION >= 0x00020000)
205 // NOTE: UEFI 2.0 spec definition as follows. It should be updated
206 // after spec update.
208 UINT8 Reserved11
[14 * 16];
218 UINT8 Reserved10
[6 * 16];
220 } EFI_FX_SAVE_STATE_X64
;
223 UINT64 ExceptionData
;
224 EFI_FX_SAVE_STATE_X64 FxSaveState
;
232 UINT64 Cr1
; /* Reserved */
265 } EFI_SYSTEM_CONTEXT_X64
;
268 // IPF processor exception types
270 #define EXCEPT_IPF_VHTP_TRANSLATION 0
271 #define EXCEPT_IPF_INSTRUCTION_TLB 1
272 #define EXCEPT_IPF_DATA_TLB 2
273 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB 3
274 #define EXCEPT_IPF_ALT_DATA_TLB 4
275 #define EXCEPT_IPF_DATA_NESTED_TLB 5
276 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6
277 #define EXCEPT_IPF_DATA_KEY_MISSED 7
278 #define EXCEPT_IPF_DIRTY_BIT 8
279 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9
280 #define EXCEPT_IPF_DATA_ACCESS_BIT 10
281 #define EXCEPT_IPF_BREAKPOINT 11
282 #define EXCEPT_IPF_EXTERNAL_INTERRUPT 12
286 #define EXCEPT_IPF_PAGE_NOT_PRESENT 20
287 #define EXCEPT_IPF_KEY_PERMISSION 21
288 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS 22
289 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS 23
290 #define EXCEPT_IPF_GENERAL_EXCEPTION 24
291 #define EXCEPT_IPF_DISABLED_FP_REGISTER 25
292 #define EXCEPT_IPF_NAT_CONSUMPTION 26
293 #define EXCEPT_IPF_SPECULATION 27
297 #define EXCEPT_IPF_DEBUG 29
298 #define EXCEPT_IPF_UNALIGNED_REFERENCE 30
299 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE 31
300 #define EXCEPT_IPF_FP_FAULT 32
301 #define EXCEPT_IPF_FP_TRAP 33
302 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP 34
303 #define EXCEPT_IPF_TAKEN_BRANCH 35
304 #define EXCEPT_IPF_SINGLE_STEP 36
308 #define EXCEPT_IPF_IA32_EXCEPTION 45
309 #define EXCEPT_IPF_IA32_INTERCEPT 46
310 #define EXCEPT_IPF_IA32_INTERRUPT 47
313 // IPF processor context definition
317 // The first reserved field is necessary to preserve alignment for the correct
318 // bits in UNAT and to insure F2 is 16 byte aligned..
396 // application registers
462 // virtual registers - nat bits for R1-R31
466 } EFI_SYSTEM_CONTEXT_IPF
;
469 // EBC processor exception types
471 #define EXCEPT_EBC_UNDEFINED 0
472 #define EXCEPT_EBC_DIVIDE_ERROR 1
473 #define EXCEPT_EBC_DEBUG 2
474 #define EXCEPT_EBC_BREAKPOINT 3
475 #define EXCEPT_EBC_OVERFLOW 4
476 #define EXCEPT_EBC_INVALID_OPCODE 5 // opcode out of range
477 #define EXCEPT_EBC_STACK_FAULT 6
478 #define EXCEPT_EBC_ALIGNMENT_CHECK 7
479 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8 // malformed instruction
480 #define EXCEPT_EBC_BAD_BREAK 9 // BREAK 0 or undefined BREAK
481 #define EXCEPT_EBC_STEP 10 // to support debug stepping
483 // For coding convenience, define the maximum valid EBC exception.
485 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP
488 // EBC processor context definition
502 } EFI_SYSTEM_CONTEXT_EBC
;
505 // Universal EFI_SYSTEM_CONTEXT definition
508 EFI_SYSTEM_CONTEXT_EBC
*SystemContextEbc
;
509 EFI_SYSTEM_CONTEXT_IA32
*SystemContextIa32
;
510 EFI_SYSTEM_CONTEXT_X64
*SystemContextX64
;
511 EFI_SYSTEM_CONTEXT_IPF
*SystemContextIpf
;
512 } EFI_SYSTEM_CONTEXT
;
515 // DebugSupport callback function prototypes
519 Registers and enables an exception callback function for the specified exception.
521 @param ExceptionType Exception types in EBC, IA-32, X64, or IPF
522 @param SystemContext Exception content.
527 (*EFI_EXCEPTION_CALLBACK
) (
528 IN EFI_EXCEPTION_TYPE ExceptionType
,
529 IN OUT EFI_SYSTEM_CONTEXT SystemContext
533 Registers and enables the on-target debug agent's periodic entry point.
535 @param SystemContext Exception content.
540 (*EFI_PERIODIC_CALLBACK
) (
541 IN OUT EFI_SYSTEM_CONTEXT SystemContext
545 // Machine type definition
548 IsaIa32
= IMAGE_FILE_MACHINE_I386
, // 0x014C
549 IsaX64
= IMAGE_FILE_MACHINE_X64
, // 0x8664
550 IsaIpf
= IMAGE_FILE_MACHINE_IA64
, // 0x0200
551 IsaEbc
= IMAGE_FILE_MACHINE_EBC
// 0x0EBC
552 } EFI_INSTRUCTION_SET_ARCHITECTURE
;
556 // DebugSupport member function definitions
560 Returns the maximum value that may be used for the ProcessorIndex parameter in
561 RegisterPeriodicCallback() and RegisterExceptionCallback().
563 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
564 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported
565 processor index is returned.
567 @retval EFI_SUCCESS The function completed successfully.
572 (EFIAPI
*EFI_GET_MAXIMUM_PROCESSOR_INDEX
) (
573 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
574 OUT UINTN
*MaxProcessorIndex
578 Registers a function to be called back periodically in interrupt context.
580 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
581 @param ProcessorIndex Specifies which processor the callback function applies to.
582 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main
583 periodic entry point of the debug agent.
585 @retval EFI_SUCCESS The function completed successfully.
586 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
587 function was previously registered.
588 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
594 (EFIAPI
*EFI_REGISTER_PERIODIC_CALLBACK
) (
595 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
596 IN UINTN ProcessorIndex
,
597 IN EFI_PERIODIC_CALLBACK PeriodicCallback
601 Registers a function to be called when a given processor exception occurs.
603 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
604 @param ProcessorIndex Specifies which processor the callback function applies to.
605 @param PeriodicCallback A pointer to a function of type EXCEPTION_CALLBACK that is called
606 when the processor exception specified by ExceptionType occurs.
607 @param ExceptionType Specifies which processor exception to hook.
609 @retval EFI_SUCCESS The function completed successfully.
610 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
611 function was previously registered.
612 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
618 (EFIAPI
*EFI_REGISTER_EXCEPTION_CALLBACK
) (
619 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
620 IN UINTN ProcessorIndex
,
621 IN EFI_EXCEPTION_CALLBACK ExceptionCallback
,
622 IN EFI_EXCEPTION_TYPE ExceptionType
626 Invalidates processor instruction cache for a memory range. Subsequent execution in this range
627 causes a fresh memory fetch to retrieve code to be executed.
629 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
630 @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated.
631 @param Start Specifies the physical base of the memory range to be invalidated.
632 @param Length Specifies the minimum number of bytes in the processor's instruction
635 @retval EFI_SUCCESS The function completed successfully.
640 (EFIAPI
*EFI_INVALIDATE_INSTRUCTION_CACHE
) (
641 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
642 IN UINTN ProcessorIndex
,
648 // DebugSupport protocol definition
650 struct _EFI_DEBUG_SUPPORT_PROTOCOL
{
651 EFI_INSTRUCTION_SET_ARCHITECTURE Isa
;
652 EFI_GET_MAXIMUM_PROCESSOR_INDEX GetMaximumProcessorIndex
;
653 EFI_REGISTER_PERIODIC_CALLBACK RegisterPeriodicCallback
;
654 EFI_REGISTER_EXCEPTION_CALLBACK RegisterExceptionCallback
;
655 EFI_INVALIDATE_INSTRUCTION_CACHE InvalidateInstructionCache
;
658 extern EFI_GUID gEfiDebugSupportProtocolGuid
;