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
  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