MdeModulePkg/Universal/DebugSupportDxe/Ia32/DebugSupport.h

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