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 - 2018, Intel Corporation. All rights reserved.<BR>
9 Portions copyright (c) 2011 - 2013, ARM Ltd. All rights reserved.<BR>
10 Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR>
12 SPDX-License-Identifier: BSD-2-Clause-Patent
16 #ifndef __DEBUG_SUPPORT_H__
17 #define __DEBUG_SUPPORT_H__
19 #include <IndustryStandard/PeImage.h>
21 typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL
;
24 /// Debug Support protocol {2755590C-6F3C-42FA-9EA4-A3BA543CDA25}.
26 #define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \
28 0x2755590C, 0x6F3C, 0x42FA, {0x9E, 0xA4, 0xA3, 0xBA, 0x54, 0x3C, 0xDA, 0x25 } \
32 /// Processor exception to be hooked.
33 /// All exception types for IA32, X64, Itanium and EBC processors are defined.
35 typedef INTN EFI_EXCEPTION_TYPE
;
38 /// IA-32 processor exception types.
40 #define EXCEPT_IA32_DIVIDE_ERROR 0
41 #define EXCEPT_IA32_DEBUG 1
42 #define EXCEPT_IA32_NMI 2
43 #define EXCEPT_IA32_BREAKPOINT 3
44 #define EXCEPT_IA32_OVERFLOW 4
45 #define EXCEPT_IA32_BOUND 5
46 #define EXCEPT_IA32_INVALID_OPCODE 6
47 #define EXCEPT_IA32_DOUBLE_FAULT 8
48 #define EXCEPT_IA32_INVALID_TSS 10
49 #define EXCEPT_IA32_SEG_NOT_PRESENT 11
50 #define EXCEPT_IA32_STACK_FAULT 12
51 #define EXCEPT_IA32_GP_FAULT 13
52 #define EXCEPT_IA32_PAGE_FAULT 14
53 #define EXCEPT_IA32_FP_ERROR 16
54 #define EXCEPT_IA32_ALIGNMENT_CHECK 17
55 #define EXCEPT_IA32_MACHINE_CHECK 18
56 #define EXCEPT_IA32_SIMD 19
60 /// FP / MMX / XMM registers (see fxrstor instruction definition).
73 UINT8 St0Mm0
[10], Reserved3
[6];
74 UINT8 St1Mm1
[10], Reserved4
[6];
75 UINT8 St2Mm2
[10], Reserved5
[6];
76 UINT8 St3Mm3
[10], Reserved6
[6];
77 UINT8 St4Mm4
[10], Reserved7
[6];
78 UINT8 St5Mm5
[10], Reserved8
[6];
79 UINT8 St6Mm6
[10], Reserved9
[6];
80 UINT8 St7Mm7
[10], Reserved10
[6];
89 UINT8 Reserved11
[14 * 16];
90 } EFI_FX_SAVE_STATE_IA32
;
93 /// IA-32 processor context definition.
97 EFI_FX_SAVE_STATE_IA32 FxSaveState
;
105 UINT32 Cr1
; /* Reserved */
129 } EFI_SYSTEM_CONTEXT_IA32
;
132 /// x64 processor exception types.
134 #define EXCEPT_X64_DIVIDE_ERROR 0
135 #define EXCEPT_X64_DEBUG 1
136 #define EXCEPT_X64_NMI 2
137 #define EXCEPT_X64_BREAKPOINT 3
138 #define EXCEPT_X64_OVERFLOW 4
139 #define EXCEPT_X64_BOUND 5
140 #define EXCEPT_X64_INVALID_OPCODE 6
141 #define EXCEPT_X64_DOUBLE_FAULT 8
142 #define EXCEPT_X64_INVALID_TSS 10
143 #define EXCEPT_X64_SEG_NOT_PRESENT 11
144 #define EXCEPT_X64_STACK_FAULT 12
145 #define EXCEPT_X64_GP_FAULT 13
146 #define EXCEPT_X64_PAGE_FAULT 14
147 #define EXCEPT_X64_FP_ERROR 16
148 #define EXCEPT_X64_ALIGNMENT_CHECK 17
149 #define EXCEPT_X64_MACHINE_CHECK 18
150 #define EXCEPT_X64_SIMD 19
154 /// FP / MMX / XMM registers (see fxrstor instruction definition).
164 UINT8 St0Mm0
[10], Reserved2
[6];
165 UINT8 St1Mm1
[10], Reserved3
[6];
166 UINT8 St2Mm2
[10], Reserved4
[6];
167 UINT8 St3Mm3
[10], Reserved5
[6];
168 UINT8 St4Mm4
[10], Reserved6
[6];
169 UINT8 St5Mm5
[10], Reserved7
[6];
170 UINT8 St6Mm6
[10], Reserved8
[6];
171 UINT8 St7Mm7
[10], Reserved9
[6];
181 // NOTE: UEFI 2.0 spec definition as follows.
183 UINT8 Reserved11
[14 * 16];
184 } EFI_FX_SAVE_STATE_X64
;
187 /// x64 processor context definition.
190 UINT64 ExceptionData
;
191 EFI_FX_SAVE_STATE_X64 FxSaveState
;
199 UINT64 Cr1
; /* Reserved */
232 } EFI_SYSTEM_CONTEXT_X64
;
235 /// Itanium Processor Family Exception types.
237 #define EXCEPT_IPF_VHTP_TRANSLATION 0
238 #define EXCEPT_IPF_INSTRUCTION_TLB 1
239 #define EXCEPT_IPF_DATA_TLB 2
240 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB 3
241 #define EXCEPT_IPF_ALT_DATA_TLB 4
242 #define EXCEPT_IPF_DATA_NESTED_TLB 5
243 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6
244 #define EXCEPT_IPF_DATA_KEY_MISSED 7
245 #define EXCEPT_IPF_DIRTY_BIT 8
246 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9
247 #define EXCEPT_IPF_DATA_ACCESS_BIT 10
248 #define EXCEPT_IPF_BREAKPOINT 11
249 #define EXCEPT_IPF_EXTERNAL_INTERRUPT 12
253 #define EXCEPT_IPF_PAGE_NOT_PRESENT 20
254 #define EXCEPT_IPF_KEY_PERMISSION 21
255 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS 22
256 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS 23
257 #define EXCEPT_IPF_GENERAL_EXCEPTION 24
258 #define EXCEPT_IPF_DISABLED_FP_REGISTER 25
259 #define EXCEPT_IPF_NAT_CONSUMPTION 26
260 #define EXCEPT_IPF_SPECULATION 27
264 #define EXCEPT_IPF_DEBUG 29
265 #define EXCEPT_IPF_UNALIGNED_REFERENCE 30
266 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE 31
267 #define EXCEPT_IPF_FP_FAULT 32
268 #define EXCEPT_IPF_FP_TRAP 33
269 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP 34
270 #define EXCEPT_IPF_TAKEN_BRANCH 35
271 #define EXCEPT_IPF_SINGLE_STEP 36
275 #define EXCEPT_IPF_IA32_EXCEPTION 45
276 #define EXCEPT_IPF_IA32_INTERCEPT 46
277 #define EXCEPT_IPF_IA32_INTERRUPT 47
280 /// IPF processor context definition.
284 // The first reserved field is necessary to preserve alignment for the correct
285 // bits in UNAT and to insure F2 is 16 byte aligned.
363 // application registers
429 // virtual registers - nat bits for R1-R31
432 } EFI_SYSTEM_CONTEXT_IPF
;
435 /// EBC processor exception types.
437 #define EXCEPT_EBC_UNDEFINED 0
438 #define EXCEPT_EBC_DIVIDE_ERROR 1
439 #define EXCEPT_EBC_DEBUG 2
440 #define EXCEPT_EBC_BREAKPOINT 3
441 #define EXCEPT_EBC_OVERFLOW 4
442 #define EXCEPT_EBC_INVALID_OPCODE 5 ///< Opcode out of range.
443 #define EXCEPT_EBC_STACK_FAULT 6
444 #define EXCEPT_EBC_ALIGNMENT_CHECK 7
445 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8 ///< Malformed instruction.
446 #define EXCEPT_EBC_BAD_BREAK 9 ///< BREAK 0 or undefined BREAK.
447 #define EXCEPT_EBC_STEP 10 ///< To support debug stepping.
449 /// For coding convenience, define the maximum valid EBC exception.
451 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP
454 /// EBC processor context definition.
468 } EFI_SYSTEM_CONTEXT_EBC
;
471 /// ARM processor exception types.
473 #define EXCEPT_ARM_RESET 0
474 #define EXCEPT_ARM_UNDEFINED_INSTRUCTION 1
475 #define EXCEPT_ARM_SOFTWARE_INTERRUPT 2
476 #define EXCEPT_ARM_PREFETCH_ABORT 3
477 #define EXCEPT_ARM_DATA_ABORT 4
478 #define EXCEPT_ARM_RESERVED 5
479 #define EXCEPT_ARM_IRQ 6
480 #define EXCEPT_ARM_FIQ 7
483 /// For coding convenience, define the maximum valid ARM exception.
485 #define MAX_ARM_EXCEPTION EXCEPT_ARM_FIQ
488 /// ARM processor context definition.
512 } EFI_SYSTEM_CONTEXT_ARM
;
515 /// AARCH64 processor exception types.
517 #define EXCEPT_AARCH64_SYNCHRONOUS_EXCEPTIONS 0
518 #define EXCEPT_AARCH64_IRQ 1
519 #define EXCEPT_AARCH64_FIQ 2
520 #define EXCEPT_AARCH64_SERROR 3
523 /// For coding convenience, define the maximum valid ARM exception.
525 #define MAX_AARCH64_EXCEPTION EXCEPT_AARCH64_SERROR
528 // General Purpose Registers
558 UINT64 FP
; // x29 - Frame pointer
559 UINT64 LR
; // x30 - Link Register
560 UINT64 SP
; // x31 - Stack pointer
596 UINT64 ELR
; // Exception Link Register
597 UINT64 SPSR
; // Saved Processor Status Register
598 UINT64 FPSR
; // Floating Point Status Register
599 UINT64 ESR
; // Exception syndrome register
600 UINT64 FAR
; // Fault Address Register
601 } EFI_SYSTEM_CONTEXT_AARCH64
;
604 /// RISC-V processor exception types.
606 #define EXCEPT_RISCV_INST_MISALIGNED 0
607 #define EXCEPT_RISCV_INST_ACCESS_FAULT 1
608 #define EXCEPT_RISCV_ILLEGAL_INST 2
609 #define EXCEPT_RISCV_BREAKPOINT 3
610 #define EXCEPT_RISCV_LOAD_ADDRESS_MISALIGNED 4
611 #define EXCEPT_RISCV_LOAD_ACCESS_FAULT 5
612 #define EXCEPT_RISCV_STORE_AMO_ADDRESS_MISALIGNED 6
613 #define EXCEPT_RISCV_STORE_AMO_ACCESS_FAULT 7
614 #define EXCEPT_RISCV_ENV_CALL_FROM_UMODE 8
615 #define EXCEPT_RISCV_ENV_CALL_FROM_SMODE 9
616 #define EXCEPT_RISCV_ENV_CALL_FROM_HMODE 10
617 #define EXCEPT_RISCV_ENV_CALL_FROM_MMODE 11
619 #define EXCEPT_RISCV_SOFTWARE_INT 0x0
620 #define EXCEPT_RISCV_TIMER_INT 0x1
655 } EFI_SYSTEM_CONTEXT_RISCV64
;
658 // LoongArch processor exception types.
660 #define EXCEPT_LOONGARCH_INT 0
661 #define EXCEPT_LOONGARCH_PIL 1
662 #define EXCEPT_LOONGARCH_PIS 2
663 #define EXCEPT_LOONGARCH_PIF 3
664 #define EXCEPT_LOONGARCH_PME 4
665 #define EXCEPT_LOONGARCH_PNR 5
666 #define EXCEPT_LOONGARCH_PNX 6
667 #define EXCEPT_LOONGARCH_PPI 7
668 #define EXCEPT_LOONGARCH_ADE 8
669 #define EXCEPT_LOONGARCH_ALE 9
670 #define EXCEPT_LOONGARCH_BCE 10
671 #define EXCEPT_LOONGARCH_SYS 11
672 #define EXCEPT_LOONGARCH_BRK 12
673 #define EXCEPT_LOONGARCH_INE 13
674 #define EXCEPT_LOONGARCH_IPE 14
675 #define EXCEPT_LOONGARCH_FPD 15
676 #define EXCEPT_LOONGARCH_SXD 16
677 #define EXCEPT_LOONGARCH_ASXD 17
678 #define EXCEPT_LOONGARCH_FPE 18
679 #define EXCEPT_LOONGARCH_TBR 64 // For code only, there is no such type in the ISA spec, the TLB refill is defined for an independent exception.
682 // LoongArch processor Interrupt types.
684 #define EXCEPT_LOONGARCH_INT_SIP0 0
685 #define EXCEPT_LOONGARCH_INT_SIP1 1
686 #define EXCEPT_LOONGARCH_INT_IP0 2
687 #define EXCEPT_LOONGARCH_INT_IP1 3
688 #define EXCEPT_LOONGARCH_INT_IP2 4
689 #define EXCEPT_LOONGARCH_INT_IP3 5
690 #define EXCEPT_LOONGARCH_INT_IP4 6
691 #define EXCEPT_LOONGARCH_INT_IP5 7
692 #define EXCEPT_LOONGARCH_INT_IP6 8
693 #define EXCEPT_LOONGARCH_INT_IP7 9
694 #define EXCEPT_LOONGARCH_INT_PMC 10
695 #define EXCEPT_LOONGARCH_INT_TIMER 11
696 #define EXCEPT_LOONGARCH_INT_IPI 12
699 // For coding convenience, define the maximum valid
700 // LoongArch interrupt.
702 #define MAX_LOONGARCH_INTERRUPT 14
738 UINT64 CRMD
; // CuRrent MoDe information
739 UINT64 PRMD
; // PRe-exception MoDe information
740 UINT64 EUEN
; // Extended component Unit ENable
741 UINT64 MISC
; // MISCellaneous controller
742 UINT64 ECFG
; // Exception ConFiGuration
743 UINT64 ESTAT
; // Exception STATus
744 UINT64 ERA
; // Exception Return Address
745 UINT64 BADV
; // BAD Virtual address
746 UINT64 BADI
; // BAD Instruction
747 } EFI_SYSTEM_CONTEXT_LOONGARCH64
;
750 /// Universal EFI_SYSTEM_CONTEXT definition.
753 EFI_SYSTEM_CONTEXT_EBC
*SystemContextEbc
;
754 EFI_SYSTEM_CONTEXT_IA32
*SystemContextIa32
;
755 EFI_SYSTEM_CONTEXT_X64
*SystemContextX64
;
756 EFI_SYSTEM_CONTEXT_IPF
*SystemContextIpf
;
757 EFI_SYSTEM_CONTEXT_ARM
*SystemContextArm
;
758 EFI_SYSTEM_CONTEXT_AARCH64
*SystemContextAArch64
;
759 EFI_SYSTEM_CONTEXT_RISCV64
*SystemContextRiscV64
;
760 EFI_SYSTEM_CONTEXT_LOONGARCH64
*SystemContextLoongArch64
;
761 } EFI_SYSTEM_CONTEXT
;
764 // DebugSupport callback function prototypes
768 Registers and enables an exception callback function for the specified exception.
770 @param ExceptionType Exception types in EBC, IA-32, x64, or IPF.
771 @param SystemContext Exception content.
776 (EFIAPI
*EFI_EXCEPTION_CALLBACK
)(
777 IN EFI_EXCEPTION_TYPE ExceptionType
,
778 IN OUT EFI_SYSTEM_CONTEXT SystemContext
782 Registers and enables the on-target debug agent's periodic entry point.
784 @param SystemContext Exception content.
789 (EFIAPI
*EFI_PERIODIC_CALLBACK
)(
790 IN OUT EFI_SYSTEM_CONTEXT SystemContext
794 /// Machine type definition
797 IsaIa32
= IMAGE_FILE_MACHINE_I386
, ///< 0x014C
798 IsaX64
= IMAGE_FILE_MACHINE_X64
, ///< 0x8664
799 IsaIpf
= IMAGE_FILE_MACHINE_IA64
, ///< 0x0200
800 IsaEbc
= IMAGE_FILE_MACHINE_EBC
, ///< 0x0EBC
801 IsaArm
= IMAGE_FILE_MACHINE_ARMTHUMB_MIXED
, ///< 0x01c2
802 IsaAArch64
= IMAGE_FILE_MACHINE_ARM64
///< 0xAA64
803 } EFI_INSTRUCTION_SET_ARCHITECTURE
;
806 // DebugSupport member function definitions
810 Returns the maximum value that may be used for the ProcessorIndex parameter in
811 RegisterPeriodicCallback() and RegisterExceptionCallback().
813 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
814 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported
815 processor index is returned.
817 @retval EFI_SUCCESS The function completed successfully.
822 (EFIAPI
*EFI_GET_MAXIMUM_PROCESSOR_INDEX
)(
823 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
824 OUT UINTN
*MaxProcessorIndex
828 Registers a function to be called back periodically in interrupt context.
830 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
831 @param ProcessorIndex Specifies which processor the callback function applies to.
832 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main
833 periodic entry point of the debug agent.
835 @retval EFI_SUCCESS The function completed successfully.
836 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
837 function was previously registered.
838 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
844 (EFIAPI
*EFI_REGISTER_PERIODIC_CALLBACK
)(
845 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
846 IN UINTN ProcessorIndex
,
847 IN EFI_PERIODIC_CALLBACK PeriodicCallback
851 Registers a function to be called when a given processor exception occurs.
853 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
854 @param ProcessorIndex Specifies which processor the callback function applies to.
855 @param ExceptionCallback A pointer to a function of type EXCEPTION_CALLBACK that is called
856 when the processor exception specified by ExceptionType occurs.
857 @param ExceptionType Specifies which processor exception to hook.
859 @retval EFI_SUCCESS The function completed successfully.
860 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback
861 function was previously registered.
862 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback
868 (EFIAPI
*EFI_REGISTER_EXCEPTION_CALLBACK
)(
869 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
870 IN UINTN ProcessorIndex
,
871 IN EFI_EXCEPTION_CALLBACK ExceptionCallback
,
872 IN EFI_EXCEPTION_TYPE ExceptionType
876 Invalidates processor instruction cache for a memory range. Subsequent execution in this range
877 causes a fresh memory fetch to retrieve code to be executed.
879 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
880 @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated.
881 @param Start Specifies the physical base of the memory range to be invalidated.
882 @param Length Specifies the minimum number of bytes in the processor's instruction
885 @retval EFI_SUCCESS The function completed successfully.
890 (EFIAPI
*EFI_INVALIDATE_INSTRUCTION_CACHE
)(
891 IN EFI_DEBUG_SUPPORT_PROTOCOL
*This
,
892 IN UINTN ProcessorIndex
,
898 /// This protocol provides the services to allow the debug agent to register
899 /// callback functions that are called either periodically or when specific
900 /// processor exceptions occur.
902 struct _EFI_DEBUG_SUPPORT_PROTOCOL
{
904 /// Declares the processor architecture for this instance of the EFI Debug Support protocol.
906 EFI_INSTRUCTION_SET_ARCHITECTURE Isa
;
907 EFI_GET_MAXIMUM_PROCESSOR_INDEX GetMaximumProcessorIndex
;
908 EFI_REGISTER_PERIODIC_CALLBACK RegisterPeriodicCallback
;
909 EFI_REGISTER_EXCEPTION_CALLBACK RegisterExceptionCallback
;
910 EFI_INVALIDATE_INSTRUCTION_CACHE InvalidateInstructionCache
;
913 extern EFI_GUID gEfiDebugSupportProtocolGuid
;