MdeModulePkg/Universal/DebugSupportDxe/Ia32/DebugSupport.h

   1 /** @file
   2   Generic debug support macros, typedefs and prototypes for IA32/x64.
   3
   4 Copyright (c) 2006 - 2008, 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
  19 #include <Uefi.h>
  20
  21 #include <Protocol/DebugSupport.h>
  22 #include <Protocol/LoadedImage.h>
  23
  24 #include <Library/DebugLib.h>
  25 #include <Library/UefiDriverEntryPoint.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/MemoryAllocationLib.h>
  28 #include <Library/UefiBootServicesTableLib.h>
  29 #include <Library/BaseLib.h>
  30 #include <Library/PcdLib.h>
  31
  32 #define NUM_IDT_ENTRIES                 0x78
  33 #define SYSTEM_TIMER_VECTOR             0x68
  34 #define VECTOR_ENTRY_PAGES              1
  35
  36 #define FF_FXSR                         (1 << 24)
  37
  38 typedef
  39 VOID
  40 (*DEBUG_PROC) (
  41   VOID
  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   VOID (*RegisteredCallback) ();
  50 } IDT_ENTRY;
  51
  52 extern EFI_SYSTEM_CONTEXT SystemContext;
  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   Programs interrupt flag to the requested state and returns previous
  95   state.
  96
  97   @param  NewState    New interrupt status.
  98
  99   @retval TRUE     Old interrupt status is TRUE.
 100   @retval FALSE    Old interrupt status is FALSE
 101
 102 **/
 103 BOOLEAN
 104 WriteInterruptFlag (
 105   BOOLEAN NewState
 106   );
 107
 108 /**
 109   Initializes driver's handler registration databas.
 110
 111   This code executes in boot services context
 112   Must be public because it's referenced from DebugSupport.c
 113
 114   @retval  EFI_UNSUPPORTED      If IA32 processor does not support FXSTOR/FXRSTOR instructions,
 115                                 the context save will fail, so these processor's are not supported.
 116   @retval  EFI_OUT_OF_RESOURCES Fails to allocate memory.
 117   @retval  EFI_SUCCESS          Initializes successfully.
 118
 119 **/
 120 EFI_STATUS
 121 PlInitializeDebugSupportDriver (
 122   VOID
 123   );
 124
 125 /**
 126   This is the callback that is written to the LoadedImage protocol instance
 127   on the image handle. It uninstalls all registered handlers and frees all entry
 128   stub memory.
 129
 130   @param  ImageHandle    The firmware allocated handle for the EFI image.
 131
 132   @retval EFI_SUCCESS    Always.
 133
 134 **/
 135 EFI_STATUS
 136 EFIAPI
 137 PlUnloadDebugSupportDriver (
 138   IN EFI_HANDLE                       ImageHandle
 139   );
 140
 141 /**
 142   This is a DebugSupport protocol member function, hard
 143   coded to support only 1 processor for now.
 144
 145   @param  This                The DebugSupport instance
 146   @param  MaxProcessorIndex   The maximuim supported processor index
 147
 148   @retval EFI_SUCCESS         Always returned with **MaxProcessorIndex set to 0.
 149
 150 **/
 151 EFI_STATUS
 152 EFIAPI
 153 GetMaximumProcessorIndex (
 154   IN EFI_DEBUG_SUPPORT_PROTOCOL       *This,
 155   OUT UINTN                           *MaxProcessorIndex
 156   );
 157
 158 /**
 159   DebugSupport protocol member function.
 160
 161   @param  This               The DebugSupport instance
 162   @param  ProcessorIndex     Which processor the callback applies to.
 163   @param  PeriodicCallback   Callback function
 164
 165   @retval EFI_SUCCESS        Indicates the callback was registered.
 166   @retval others             Callback was not registered.
 167
 168 **/
 169 EFI_STATUS
 170 EFIAPI
 171 RegisterPeriodicCallback (
 172   IN EFI_DEBUG_SUPPORT_PROTOCOL       *This,
 173   IN UINTN                            ProcessorIndex,
 174   IN EFI_PERIODIC_CALLBACK            PeriodicCallback
 175   );
 176
 177 /**
 178   DebugSupport protocol member function.
 179
 180   This code executes in boot services context.
 181
 182   @param  This              The DebugSupport instance
 183   @param  ProcessorIndex    Which processor the callback applies to.
 184   @param  NewCallback       Callback function
 185   @param  ExceptionType     Which exception to hook
 186
 187   @retval EFI_SUCCESS        Indicates the callback was registered.
 188   @retval others             Callback was not registered.
 189
 190 **/
 191 EFI_STATUS
 192 EFIAPI
 193 RegisterExceptionCallback (
 194   IN EFI_DEBUG_SUPPORT_PROTOCOL       *This,
 195   IN UINTN                            ProcessorIndex,
 196   IN EFI_EXCEPTION_CALLBACK           NewCallback,
 197   IN EFI_EXCEPTION_TYPE               ExceptionType
 198   );
 199
 200 /**
 201   DebugSupport protocol member function.  Calls assembly routine to flush cache.
 202
 203   @param  This              The DebugSupport instance
 204   @param  ProcessorIndex    Which processor the callback applies to.
 205   @param  Start             Physical base of the memory range to be invalidated
 206   @param  Length            mininum number of bytes in instruction cache to invalidate
 207
 208   @retval EFI_SUCCESS       Always returned.
 209
 210 **/
 211 EFI_STATUS
 212 EFIAPI
 213 InvalidateInstructionCache (
 214   IN EFI_DEBUG_SUPPORT_PROTOCOL       *This,
 215   IN UINTN                            ProcessorIndex,
 216   IN VOID                             *Start,
 217   IN UINT64                           Length
 218   );
 219
 220 /**
 221   Allocate pool for a new IDT entry stub.
 222
 223   Copy the generic stub into the new buffer and fixup the vector number
 224   and jump target address.
 225
 226   @param  ExceptionType   This is the exception type that the new stub will be created
 227                           for.
 228   @param  Stub            On successful exit, *Stub contains the newly allocated entry stub.
 229
 230   @retval EFI_SUCCESS     Always.
 231
 232 **/
 233 EFI_STATUS
 234 CreateEntryStub (
 235   IN EFI_EXCEPTION_TYPE     ExceptionType,
 236   OUT VOID                  **Stub
 237   );
 238
 239 /**
 240   Get Procedure Entry Point from IDT Gate Descriptor.
 241
 242   @param  IdtGateDecriptor  IDT Gate Descriptor.
 243
 244   @return Procedure Entry Point located in IDT Gate Descriptor.
 245
 246 **/
 247 UINTN GetProcedureEntryPoint (
 248   IN IA32_IDT_GATE_DESCRIPTOR  *IdtGateDecriptor
 249   );
 250
 251 /**
 252   This is the main worker function that manages the state of the interrupt
 253   handlers.  It both installs and uninstalls interrupt handlers based on the
 254   value of NewCallback.  If NewCallback is NULL, then uninstall is indicated.
 255   If NewCallback is non-NULL, then install is indicated.
 256
 257   @param  NewCallback   If non-NULL, NewCallback specifies the new handler to register.
 258                         If NULL, specifies that the previously registered handler should
 259                         be uninstalled.
 260   @param  ExceptionType Indicates which entry to manage.
 261
 262   @retval EFI_SUCCESS            Process is ok.
 263   @retval EFI_INVALID_PARAMETER  Requested uninstalling a handler from a vector that has
 264                                  no handler registered for it
 265   @retval EFI_ALREADY_STARTED    Requested install to a vector that already has a handler registered.
 266   @retval others                 Possible return values are passed through from UnHookEntry and HookEntry.
 267
 268 **/
 269 EFI_STATUS
 270 ManageIdtEntryTable (
 271   VOID (*NewCallback)(),
 272   EFI_EXCEPTION_TYPE ExceptionType
 273   );
 274
 275 /**
 276   Creates a nes entry stub.  Then saves the current IDT entry and replaces it
 277   with an interrupt gate for the new entry point.  The IdtEntryTable is updated
 278   with the new registered function.
 279
 280   This code executes in boot services context.  The stub entry executes in interrupt
 281   context.
 282
 283   @param  ExceptionType      Specifies which vector to hook.
 284   @param  NewCallback        A pointer to the new function to be registered.
 285
 286   @retval EFI_SUCCESS        Always.
 287
 288 **/
 289 EFI_STATUS
 290 HookEntry (
 291   IN EFI_EXCEPTION_TYPE            ExceptionType,
 292   IN VOID                         (*NewCallback) ()
 293   );
 294
 295 /**
 296   Undoes HookEntry. This code executes in boot services context.
 297
 298   @param  ExceptionType   Specifies which entry to unhook
 299
 300   @retval EFI_SUCCESS     Always.
 301
 302 **/
 303 EFI_STATUS
 304 UnhookEntry (
 305   IN EFI_EXCEPTION_TYPE           ExceptionType
 306   );
 307
 308 #endif