MdeModulePkg/Universal/DebugSupportDxe/Ia32/DebugSupport.h

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