2 DebugSupport protocol and supporting definitions as defined in the UEFI2.4
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 - 2010, Intel Corporation. All rights reserved.<BR>
9 Portions copyright (c) 2011 - 2013, ARM Ltd. All rights reserved.<BR>
11 This program and the accompanying materials are licensed and made available under
12 the terms and conditions of the BSD License that accompanies this distribution.
13 The full text of the license may be found at
14 http://opensource.org/licenses/bsd-license.php.
16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
17 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
21 #ifndef __DEBUG_SUPPORT_H__
22 #define __DEBUG_SUPPORT_H__
24 FILE_LICENCE ( BSD3 );
26 #include <ipxe/efi/IndustryStandard/PeImage.h>
28 typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL;
31 /// Debug Support protocol {2755590C-6F3C-42FA-9EA4-A3BA543CDA25}.
33 #define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \
35 0x2755590C, 0x6F3C, 0x42FA, {0x9E, 0xA4, 0xA3, 0xBA, 0x54, 0x3C, 0xDA, 0x25 } \
39 /// Processor exception to be hooked.
40 /// All exception types for IA32, X64, Itanium and EBC processors are defined.
42 typedef INTN EFI_EXCEPTION_TYPE;
45 /// IA-32 processor exception types.
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
67 /// FP / MMX / XMM registers (see fxrstor instruction definition).
80 UINT8 St0Mm0[10], Reserved3[6];
81 UINT8 St1Mm1[10], Reserved4[6];
82 UINT8 St2Mm2[10], Reserved5[6];
83 UINT8 St3Mm3[10], Reserved6[6];
84 UINT8 St4Mm4[10], Reserved7[6];
85 UINT8 St5Mm5[10], Reserved8[6];
86 UINT8 St6Mm6[10], Reserved9[6];
87 UINT8 St7Mm7[10], Reserved10[6];
96 UINT8 Reserved11[14 * 16];
97 } EFI_FX_SAVE_STATE_IA32;
100 /// IA-32 processor context definition.
103 UINT32 ExceptionData;
104 EFI_FX_SAVE_STATE_IA32 FxSaveState;
112 UINT32 Cr1; /* Reserved */
136 } EFI_SYSTEM_CONTEXT_IA32;
139 /// x64 processor exception types.
141 #define EXCEPT_X64_DIVIDE_ERROR 0
142 #define EXCEPT_X64_DEBUG 1
143 #define EXCEPT_X64_NMI 2
144 #define EXCEPT_X64_BREAKPOINT 3
145 #define EXCEPT_X64_OVERFLOW 4
146 #define EXCEPT_X64_BOUND 5
147 #define EXCEPT_X64_INVALID_OPCODE 6
148 #define EXCEPT_X64_DOUBLE_FAULT 8
149 #define EXCEPT_X64_INVALID_TSS 10
150 #define EXCEPT_X64_SEG_NOT_PRESENT 11
151 #define EXCEPT_X64_STACK_FAULT 12
152 #define EXCEPT_X64_GP_FAULT 13
153 #define EXCEPT_X64_PAGE_FAULT 14
154 #define EXCEPT_X64_FP_ERROR 16
155 #define EXCEPT_X64_ALIGNMENT_CHECK 17
156 #define EXCEPT_X64_MACHINE_CHECK 18
157 #define EXCEPT_X64_SIMD 19
161 /// FP / MMX / XMM registers (see fxrstor instruction definition).
171 UINT8 St0Mm0[10], Reserved2[6];
172 UINT8 St1Mm1[10], Reserved3[6];
173 UINT8 St2Mm2[10], Reserved4[6];
174 UINT8 St3Mm3[10], Reserved5[6];
175 UINT8 St4Mm4[10], Reserved6[6];
176 UINT8 St5Mm5[10], Reserved7[6];
177 UINT8 St6Mm6[10], Reserved8[6];
178 UINT8 St7Mm7[10], Reserved9[6];
188 // NOTE: UEFI 2.0 spec definition as follows.
190 UINT8 Reserved11[14 * 16];
191 } EFI_FX_SAVE_STATE_X64;
194 /// x64 processor context definition.
197 UINT64 ExceptionData;
198 EFI_FX_SAVE_STATE_X64 FxSaveState;
206 UINT64 Cr1; /* Reserved */
239 } EFI_SYSTEM_CONTEXT_X64;
242 /// Itanium Processor Family Exception types.
244 #define EXCEPT_IPF_VHTP_TRANSLATION 0
245 #define EXCEPT_IPF_INSTRUCTION_TLB 1
246 #define EXCEPT_IPF_DATA_TLB 2
247 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB 3
248 #define EXCEPT_IPF_ALT_DATA_TLB 4
249 #define EXCEPT_IPF_DATA_NESTED_TLB 5
250 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6
251 #define EXCEPT_IPF_DATA_KEY_MISSED 7
252 #define EXCEPT_IPF_DIRTY_BIT 8
253 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9
254 #define EXCEPT_IPF_DATA_ACCESS_BIT 10
255 #define EXCEPT_IPF_BREAKPOINT 11
256 #define EXCEPT_IPF_EXTERNAL_INTERRUPT 12
260 #define EXCEPT_IPF_PAGE_NOT_PRESENT 20
261 #define EXCEPT_IPF_KEY_PERMISSION 21
262 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS 22
263 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS 23
264 #define EXCEPT_IPF_GENERAL_EXCEPTION 24
265 #define EXCEPT_IPF_DISABLED_FP_REGISTER 25
266 #define EXCEPT_IPF_NAT_CONSUMPTION 26
267 #define EXCEPT_IPF_SPECULATION 27
271 #define EXCEPT_IPF_DEBUG 29
272 #define EXCEPT_IPF_UNALIGNED_REFERENCE 30
273 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE 31
274 #define EXCEPT_IPF_FP_FAULT 32
275 #define EXCEPT_IPF_FP_TRAP 33
276 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP 34
277 #define EXCEPT_IPF_TAKEN_BRANCH 35
278 #define EXCEPT_IPF_SINGLE_STEP 36
282 #define EXCEPT_IPF_IA32_EXCEPTION 45
283 #define EXCEPT_IPF_IA32_INTERCEPT 46
284 #define EXCEPT_IPF_IA32_INTERRUPT 47
287 /// IPF processor context definition.
291 // The first reserved field is necessary to preserve alignment for the correct
292 // bits in UNAT and to insure F2 is 16 byte aligned.
370 // application registers
436 // virtual registers - nat bits for R1-R31
440 } EFI_SYSTEM_CONTEXT_IPF;
443 /// EBC processor exception types.
445 #define EXCEPT_EBC_UNDEFINED 0
446 #define EXCEPT_EBC_DIVIDE_ERROR 1
447 #define EXCEPT_EBC_DEBUG 2
448 #define EXCEPT_EBC_BREAKPOINT 3
449 #define EXCEPT_EBC_OVERFLOW 4
450 #define EXCEPT_EBC_INVALID_OPCODE 5 ///< Opcode out of range.
451 #define EXCEPT_EBC_STACK_FAULT 6
452 #define EXCEPT_EBC_ALIGNMENT_CHECK 7
453 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8 ///< Malformed instruction.
454 #define EXCEPT_EBC_BAD_BREAK 9 ///< BREAK 0 or undefined BREAK.
455 #define EXCEPT_EBC_STEP 10 ///< To support debug stepping.
457 /// For coding convenience, define the maximum valid EBC exception.
459 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP
462 /// EBC processor context definition.
476 } EFI_SYSTEM_CONTEXT_EBC;
481 /// ARM processor exception types.
483 #define EXCEPT_ARM_RESET 0
484 #define EXCEPT_ARM_UNDEFINED_INSTRUCTION 1
485 #define EXCEPT_ARM_SOFTWARE_INTERRUPT 2
486 #define EXCEPT_ARM_PREFETCH_ABORT 3
487 #define EXCEPT_ARM_DATA_ABORT 4
488 #define EXCEPT_ARM_RESERVED 5
489 #define EXCEPT_ARM_IRQ 6
490 #define EXCEPT_ARM_FIQ 7
493 /// For coding convenience, define the maximum valid ARM exception.
495 #define MAX_ARM_EXCEPTION EXCEPT_ARM_FIQ
498 /// ARM processor context definition.
522 } EFI_SYSTEM_CONTEXT_ARM;
526 /// AARCH64 processor exception types.
528 #define EXCEPT_AARCH64_SYNCHRONOUS_EXCEPTIONS 0
529 #define EXCEPT_AARCH64_IRQ 1
530 #define EXCEPT_AARCH64_FIQ 2
531 #define EXCEPT_AARCH64_SERROR 3
534 /// For coding convenience, define the maximum valid ARM exception.
536 #define MAX_AARCH64_EXCEPTION EXCEPT_AARCH64_SERROR
539 // General Purpose Registers
569 UINT64 FP; // x29 - Frame pointer
570 UINT64 LR; // x30 - Link Register
571 UINT64 SP; // x31 - Stack pointer
607 UINT64 ELR; // Exception Link Register
608 UINT64 SPSR; // Saved Processor Status Register
609 UINT64 FPSR; // Floating Point Status Register
610 UINT64 ESR; // Exception syndrome register
611 UINT64 FAR; // Fault Address Register
612 } EFI_SYSTEM_CONTEXT_AARCH64;
616 /// Universal EFI_SYSTEM_CONTEXT definition.
619 EFI_SYSTEM_CONTEXT_EBC *SystemContextEbc;
620 EFI_SYSTEM_CONTEXT_IA32 *SystemContextIa32;
621 EFI_SYSTEM_CONTEXT_X64 *SystemContextX64;
622 EFI_SYSTEM_CONTEXT_IPF *SystemContextIpf;
623 EFI_SYSTEM_CONTEXT_ARM *SystemContextArm;
624 EFI_SYSTEM_CONTEXT_AARCH64 *SystemContextAArch64;
625 } EFI_SYSTEM_CONTEXT;
628 // DebugSupport callback function prototypes
632 Registers and enables an exception callback function for the specified exception.
634 @param ExceptionType Exception types in EBC, IA-32, x64, or IPF.
635 @param SystemContext Exception content.
640 (EFIAPI *EFI_EXCEPTION_CALLBACK)(
641 IN EFI_EXCEPTION_TYPE ExceptionType,
642 IN OUT EFI_SYSTEM_CONTEXT SystemContext
646 Registers and enables the on-target debug agent's periodic entry point.
648 @param SystemContext Exception content.
653 (EFIAPI *EFI_PERIODIC_CALLBACK)(
654 IN OUT EFI_SYSTEM_CONTEXT SystemContext
658 /// Machine type definition
661 IsaIa32 = IMAGE_FILE_MACHINE_I386, ///< 0x014C
662 IsaX64 = IMAGE_FILE_MACHINE_X64, ///< 0x8664
663 IsaIpf = IMAGE_FILE_MACHINE_IA64, ///< 0x0200
664 IsaEbc = IMAGE_FILE_MACHINE_EBC, ///< 0x0EBC
665 IsaArm = IMAGE_FILE_MACHINE_ARMTHUMB_MIXED, ///< 0x01c2
666 IsaAArch64 = IMAGE_FILE_MACHINE_ARM64 ///< 0xAA64
667 } EFI_INSTRUCTION_SET_ARCHITECTURE;
671 // DebugSupport member function definitions
675 Returns the maximum value that may be used for the ProcessorIndex parameter in
676 RegisterPeriodicCallback() and RegisterExceptionCallback().
678 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
679 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported
680 processor index is returned.
682 @retval EFI_SUCCESS The function completed successfully.
687 (EFIAPI *EFI_GET_MAXIMUM_PROCESSOR_INDEX)(
688 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
689 OUT UINTN *MaxProcessorIndex
693 Registers a function to be called back periodically in interrupt context.
695 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
696 @param ProcessorIndex Specifies which processor the callback function applies to.
697 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main
698 periodic entry point of the debug agent.
700 @retval EFI_SUCCESS The function completed successfully.
701 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
702 function was previously registered.
703 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
709 (EFIAPI *EFI_REGISTER_PERIODIC_CALLBACK)(
710 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
711 IN UINTN ProcessorIndex,
712 IN EFI_PERIODIC_CALLBACK PeriodicCallback
716 Registers a function to be called when a given processor exception occurs.
718 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
719 @param ProcessorIndex Specifies which processor the callback function applies to.
720 @param ExceptionCallback A pointer to a function of type EXCEPTION_CALLBACK that is called
721 when the processor exception specified by ExceptionType occurs.
722 @param ExceptionType Specifies which processor exception to hook.
724 @retval EFI_SUCCESS The function completed successfully.
725 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
726 function was previously registered.
727 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
733 (EFIAPI *EFI_REGISTER_EXCEPTION_CALLBACK)(
734 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
735 IN UINTN ProcessorIndex,
736 IN EFI_EXCEPTION_CALLBACK ExceptionCallback,
737 IN EFI_EXCEPTION_TYPE ExceptionType
741 Invalidates processor instruction cache for a memory range. Subsequent execution in this range
742 causes a fresh memory fetch to retrieve code to be executed.
744 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
745 @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated.
746 @param Start Specifies the physical base of the memory range to be invalidated.
747 @param Length Specifies the minimum number of bytes in the processor's instruction
750 @retval EFI_SUCCESS The function completed successfully.
755 (EFIAPI *EFI_INVALIDATE_INSTRUCTION_CACHE)(
756 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
757 IN UINTN ProcessorIndex,
763 /// This protocol provides the services to allow the debug agent to register
764 /// callback functions that are called either periodically or when specific
765 /// processor exceptions occur.
767 struct _EFI_DEBUG_SUPPORT_PROTOCOL {
769 /// Declares the processor architecture for this instance of the EFI Debug Support protocol.
771 EFI_INSTRUCTION_SET_ARCHITECTURE Isa;
772 EFI_GET_MAXIMUM_PROCESSOR_INDEX GetMaximumProcessorIndex;
773 EFI_REGISTER_PERIODIC_CALLBACK RegisterPeriodicCallback;
774 EFI_REGISTER_EXCEPTION_CALLBACK RegisterExceptionCallback;
775 EFI_INVALIDATE_INSTRUCTION_CACHE InvalidateInstructionCache;
778 extern EFI_GUID gEfiDebugSupportProtocolGuid;