1 /** @file 2 Generic debug support macros, typedefs and prototypes for IA32/x64. 3 4 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef _DEBUG_SUPPORT_H_ 16 #define _DEBUG_SUPPORT_H_ 17 18 #include <Uefi.h> 19 20 #include <Protocol/DebugSupport.h> 21 #include <Protocol/LoadedImage.h> 22 23 #include <Library/DebugLib.h> 24 #include <Library/UefiDriverEntryPoint.h> 25 #include <Library/BaseMemoryLib.h> 26 #include <Library/MemoryAllocationLib.h> 27 #include <Library/UefiBootServicesTableLib.h> 28 #include <Library/BaseLib.h> 29 30 #define NUM_IDT_ENTRIES 0x78 31 #define SYSTEM_TIMER_VECTOR 0x68 32 33 typedef 34 VOID 35 (*DEBUG_PROC) ( 36 VOID 37 ); 38 39 typedef 40 VOID 41 (EFIAPI *CALLBACK_FUNC) ( 42 ); 43 44 typedef struct { 45 IA32_IDT_GATE_DESCRIPTOR OrigDesc; 46 DEBUG_PROC OrigVector; 47 IA32_IDT_GATE_DESCRIPTOR NewDesc; 48 DEBUG_PROC StubEntry; 49 CALLBACK_FUNC RegisteredCallback; 50 } IDT_ENTRY; 51 52 extern UINT8 InterruptEntryStub[]; 53 extern UINT32 StubSize; 54 extern VOID (*OrigVector) (VOID); 55 extern IDT_ENTRY *IdtEntryTable; 56 extern IA32_IDT_GATE_DESCRIPTOR NullDesc; 57 58 /** 59 Generic IDT entry. 60 61 **/ 62 VOID 63 CommonIdtEntry ( 64 VOID 65 ); 66 67 /** 68 Check whether FXSTOR is supported 69 70 @retval TRUE FXSTOR is supported. 71 @retval FALSE FXSTOR is not supported. 72 73 **/ 74 BOOLEAN 75 FxStorSupport ( 76 VOID 77 ); 78 79 /** 80 Encodes an IDT descriptor with the given physical address. 81 82 @param DestDesc The IDT descriptor address. 83 @param Vecotr The interrupt vector entry. 84 85 **/ 86 VOID 87 Vect2Desc ( 88 IA32_IDT_GATE_DESCRIPTOR * DestDesc, 89 VOID (*Vector) (VOID) 90 ); 91 92 /** 93 Initializes driver's handler registration database. 94 95 This code executes in boot services context 96 Must be public because it's referenced from DebugSupport.c 97 98 @retval EFI_UNSUPPORTED If IA32 processor does not support FXSTOR/FXRSTOR instructions, 99 the context save will fail, so these processor's are not supported. 100 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory. 101 @retval EFI_SUCCESS Initializes successfully. 102 103 **/ 104 EFI_STATUS 105 PlInitializeDebugSupportDriver ( 106 VOID 107 ); 108 109 /** 110 This is the callback that is written to the LoadedImage protocol instance 111 on the image handle. It uninstalls all registered handlers and frees all entry 112 stub memory. 113 114 @param ImageHandle The firmware allocated handle for the EFI image. 115 116 @retval EFI_SUCCESS Always. 117 118 **/ 119 EFI_STATUS 120 EFIAPI 121 PlUnloadDebugSupportDriver ( 122 IN EFI_HANDLE ImageHandle 123 ); 124 125 /** 126 Returns the maximum value that may be used for the ProcessorIndex parameter in 127 RegisterPeriodicCallback() and RegisterExceptionCallback(). 128 129 Hard coded to support only 1 processor for now. 130 131 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 132 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported 133 processor index is returned. Always 0 returned. 134 135 @retval EFI_SUCCESS Always returned with **MaxProcessorIndex set to 0. 136 137 **/ 138 EFI_STATUS 139 EFIAPI 140 GetMaximumProcessorIndex ( 141 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 142 OUT UINTN *MaxProcessorIndex 143 ); 144 145 /** 146 Registers a function to be called back periodically in interrupt context. 147 148 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 149 @param ProcessorIndex Specifies which processor the callback function applies to. 150 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main 151 periodic entry point of the debug agent. 152 153 @retval EFI_SUCCESS The function completed successfully. 154 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback 155 function was previously registered. 156 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback 157 function. 158 **/ 159 EFI_STATUS 160 EFIAPI 161 RegisterPeriodicCallback ( 162 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 163 IN UINTN ProcessorIndex, 164 IN EFI_PERIODIC_CALLBACK PeriodicCallback 165 ); 166 167 /** 168 Registers a function to be called when a given processor exception occurs. 169 170 This code executes in boot services context. 171 172 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 173 @param ProcessorIndex Specifies which processor the callback function applies to. 174 @param ExceptionCallback A pointer to a function of type EXCEPTION_CALLBACK that is called 175 when the processor exception specified by ExceptionType occurs. 176 @param ExceptionType Specifies which processor exception to hook. 177 178 @retval EFI_SUCCESS The function completed successfully. 179 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback 180 function was previously registered. 181 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback 182 function. 183 **/ 184 EFI_STATUS 185 EFIAPI 186 RegisterExceptionCallback ( 187 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 188 IN UINTN ProcessorIndex, 189 IN EFI_EXCEPTION_CALLBACK ExceptionCallback, 190 IN EFI_EXCEPTION_TYPE ExceptionType 191 ); 192 193 /** 194 Invalidates processor instruction cache for a memory range. Subsequent execution in this range 195 causes a fresh memory fetch to retrieve code to be executed. 196 197 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 198 @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated. 199 @param Start Specifies the physical base of the memory range to be invalidated. 200 @param Length Specifies the minimum number of bytes in the processor's instruction 201 cache to invalidate. 202 203 @retval EFI_SUCCESS Always returned. 204 205 **/ 206 EFI_STATUS 207 EFIAPI 208 InvalidateInstructionCache ( 209 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 210 IN UINTN ProcessorIndex, 211 IN VOID *Start, 212 IN UINT64 Length 213 ); 214 215 /** 216 Allocate pool for a new IDT entry stub. 217 218 Copy the generic stub into the new buffer and fixup the vector number 219 and jump target address. 220 221 @param ExceptionType This is the exception type that the new stub will be created 222 for. 223 @param Stub On successful exit, *Stub contains the newly allocated entry stub. 224 225 **/ 226 VOID 227 CreateEntryStub ( 228 IN EFI_EXCEPTION_TYPE ExceptionType, 229 OUT VOID **Stub 230 ); 231 232 /** 233 Get Interrupt Handle from IDT Gate Descriptor. 234 235 @param IdtGateDecriptor IDT Gate Descriptor. 236 237 @return Interrupt Handle stored in IDT Gate Descriptor. 238 239 **/ 240 UINTN 241 GetInterruptHandleFromIdt ( 242 IN IA32_IDT_GATE_DESCRIPTOR *IdtGateDecriptor 243 ); 244 245 /** 246 This is the main worker function that manages the state of the interrupt 247 handlers. It both installs and uninstalls interrupt handlers based on the 248 value of NewCallback. If NewCallback is NULL, then uninstall is indicated. 249 If NewCallback is non-NULL, then install is indicated. 250 251 @param NewCallback If non-NULL, NewCallback specifies the new handler to register. 252 If NULL, specifies that the previously registered handler should 253 be uninstalled. 254 @param ExceptionType Indicates which entry to manage. 255 256 @retval EFI_SUCCESS Process is ok. 257 @retval EFI_INVALID_PARAMETER Requested uninstalling a handler from a vector that has 258 no handler registered for it 259 @retval EFI_ALREADY_STARTED Requested install to a vector that already has a handler registered. 260 @retval others Possible return values are passed through from UnHookEntry and HookEntry. 261 262 **/ 263 EFI_STATUS 264 ManageIdtEntryTable ( 265 CALLBACK_FUNC NewCallback, 266 EFI_EXCEPTION_TYPE ExceptionType 267 ); 268 269 /** 270 Creates a nes entry stub. Then saves the current IDT entry and replaces it 271 with an interrupt gate for the new entry point. The IdtEntryTable is updated 272 with the new registered function. 273 274 This code executes in boot services context. The stub entry executes in interrupt 275 context. 276 277 @param ExceptionType Specifies which vector to hook. 278 @param NewCallback A pointer to the new function to be registered. 279 280 **/ 281 VOID 282 HookEntry ( 283 IN EFI_EXCEPTION_TYPE ExceptionType, 284 IN CALLBACK_FUNC NewCallback 285 ); 286 287 /** 288 Undoes HookEntry. This code executes in boot services context. 289 290 @param ExceptionType Specifies which entry to unhook 291 292 **/ 293 VOID 294 UnhookEntry ( 295 IN EFI_EXCEPTION_TYPE ExceptionType 296 ); 297 298 #endif 299