MdeModulePkg/Include/Library/CpuExceptionHandlerLib.h

   1 /** @file
   2   CPU Exception library provides the default CPU interrupt/exception handler.
   3   It also provides capability to register user interrupt/exception handler.
   4
   5   Copyright (c) 2012 - 2018, Intel Corporation. All rights reserved.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __CPU_EXCEPTION_HANDLER_LIB_H__
  11 #define __CPU_EXCEPTION_HANDLER_LIB_H__
  12
  13 #include <Ppi/VectorHandoffInfo.h>
  14 #include <Protocol/Cpu.h>
  15
  16 #define CPU_EXCEPTION_INIT_DATA_REV     1
  17
  18 typedef union {
  19   struct {
  20     //
  21     // Revision number of this structure.
  22     //
  23     UINT32                    Revision;
  24     //
  25     // The address of top of known good stack reserved for *ALL* exceptions
  26     // listed in field StackSwitchExceptions.
  27     //
  28     UINTN                     KnownGoodStackTop;
  29     //
  30     // The size of known good stack for *ONE* exception only.
  31     //
  32     UINTN                     KnownGoodStackSize;
  33     //
  34     // Buffer of exception vector list for stack switch.
  35     //
  36     UINT8                     *StackSwitchExceptions;
  37     //
  38     // Number of exception vectors in StackSwitchExceptions.
  39     //
  40     UINTN                     StackSwitchExceptionNumber;
  41     //
  42     // Buffer of IDT table. It must be type of IA32_IDT_GATE_DESCRIPTOR.
  43     // Normally there's no need to change IDT table size.
  44     //
  45     VOID                      *IdtTable;
  46     //
  47     // Size of buffer for IdtTable.
  48     //
  49     UINTN                     IdtTableSize;
  50     //
  51     // Buffer of GDT table. It must be type of IA32_SEGMENT_DESCRIPTOR.
  52     //
  53     VOID                      *GdtTable;
  54     //
  55     // Size of buffer for GdtTable.
  56     //
  57     UINTN                     GdtTableSize;
  58     //
  59     // Pointer to start address of descriptor of exception task gate in the
  60     // GDT table. It must be type of IA32_TSS_DESCRIPTOR.
  61     //
  62     VOID                      *ExceptionTssDesc;
  63     //
  64     // Size of buffer for ExceptionTssDesc.
  65     //
  66     UINTN                     ExceptionTssDescSize;
  67     //
  68     // Buffer of task-state segment for exceptions. It must be type of
  69     // IA32_TASK_STATE_SEGMENT.
  70     //
  71     VOID                      *ExceptionTss;
  72     //
  73     // Size of buffer for ExceptionTss.
  74     //
  75     UINTN                     ExceptionTssSize;
  76     //
  77     // Flag to indicate if default handlers should be initialized or not.
  78     //
  79     BOOLEAN                   InitDefaultHandlers;
  80   } Ia32, X64;
  81 } CPU_EXCEPTION_INIT_DATA;
  82
  83 /**
  84   Initializes all CPU exceptions entries and provides the default exception handlers.
  85
  86   Caller should try to get an array of interrupt and/or exception vectors that are in use and need to
  87   persist by EFI_VECTOR_HANDOFF_INFO defined in PI 1.3 specification.
  88   If caller cannot get reserved vector list or it does not exists, set VectorInfo to NULL.
  89   If VectorInfo is not NULL, the exception vectors will be initialized per vector attribute accordingly.
  90
  91   @param[in]  VectorInfo    Pointer to reserved vector list.
  92
  93   @retval EFI_SUCCESS           CPU Exception Entries have been successfully initialized
  94                                 with default exception handlers.
  95   @retval EFI_INVALID_PARAMETER VectorInfo includes the invalid content if VectorInfo is not NULL.
  96   @retval EFI_UNSUPPORTED       This function is not supported.
  97
  98 **/
  99 EFI_STATUS
 100 EFIAPI
 101 InitializeCpuExceptionHandlers (
 102   IN EFI_VECTOR_HANDOFF_INFO       *VectorInfo OPTIONAL
 103   );
 104
 105 /**
 106   Initializes all CPU exceptions entries with optional extra initializations.
 107
 108   By default, this method should include all functionalities implemented by
 109   InitializeCpuExceptionHandlers(), plus extra initialization works, if any.
 110   This could be done by calling InitializeCpuExceptionHandlers() directly
 111   in this method besides the extra works.
 112
 113   InitData is optional and its use and content are processor arch dependent.
 114   The typical usage of it is to convey resources which have to be reserved
 115   elsewhere and are necessary for the extra initializations of exception.
 116
 117   @param[in]  VectorInfo    Pointer to reserved vector list.
 118   @param[in]  InitData      Pointer to data optional for extra initializations
 119                             of exception.
 120
 121   @retval EFI_SUCCESS             The exceptions have been successfully
 122                                   initialized.
 123   @retval EFI_INVALID_PARAMETER   VectorInfo or InitData contains invalid
 124                                   content.
 125   @retval EFI_UNSUPPORTED         This function is not supported.
 126
 127 **/
 128 EFI_STATUS
 129 EFIAPI
 130 InitializeCpuExceptionHandlersEx (
 131   IN EFI_VECTOR_HANDOFF_INFO            *VectorInfo OPTIONAL,
 132   IN CPU_EXCEPTION_INIT_DATA            *InitData OPTIONAL
 133   );
 134
 135 /**
 136   Initializes all CPU interrupt/exceptions entries and provides the default interrupt/exception handlers.
 137
 138   Caller should try to get an array of interrupt and/or exception vectors that are in use and need to
 139   persist by EFI_VECTOR_HANDOFF_INFO defined in PI 1.3 specification.
 140   If caller cannot get reserved vector list or it does not exists, set VectorInfo to NULL.
 141   If VectorInfo is not NULL, the exception vectors will be initialized per vector attribute accordingly.
 142
 143   @param[in]  VectorInfo    Pointer to reserved vector list.
 144
 145   @retval EFI_SUCCESS           All CPU interrupt/exception entries have been successfully initialized
 146                                 with default interrupt/exception handlers.
 147   @retval EFI_INVALID_PARAMETER VectorInfo includes the invalid content if VectorInfo is not NULL.
 148   @retval EFI_UNSUPPORTED       This function is not supported.
 149
 150 **/
 151 EFI_STATUS
 152 EFIAPI
 153 InitializeCpuInterruptHandlers (
 154   IN EFI_VECTOR_HANDOFF_INFO       *VectorInfo OPTIONAL
 155   );
 156
 157 /**
 158   Registers a function to be called from the processor interrupt handler.
 159
 160   This function registers and enables the handler specified by InterruptHandler for a processor
 161   interrupt or exception type specified by InterruptType. If InterruptHandler is NULL, then the
 162   handler for the processor interrupt or exception type specified by InterruptType is uninstalled.
 163   The installed handler is called once for each processor interrupt or exception.
 164   NOTE: This function should be invoked after InitializeCpuExceptionHandlers() or
 165   InitializeCpuInterruptHandlers() invoked, otherwise EFI_UNSUPPORTED returned.
 166
 167   @param[in]  InterruptType     Defines which interrupt or exception to hook.
 168   @param[in]  InterruptHandler  A pointer to a function of type EFI_CPU_INTERRUPT_HANDLER that is called
 169                                 when a processor interrupt occurs. If this parameter is NULL, then the handler
 170                                 will be uninstalled.
 171
 172   @retval EFI_SUCCESS           The handler for the processor interrupt was successfully installed or uninstalled.
 173   @retval EFI_ALREADY_STARTED   InterruptHandler is not NULL, and a handler for InterruptType was
 174                                 previously installed.
 175   @retval EFI_INVALID_PARAMETER InterruptHandler is NULL, and a handler for InterruptType was not
 176                                 previously installed.
 177   @retval EFI_UNSUPPORTED       The interrupt specified by InterruptType is not supported,
 178                                 or this function is not supported.
 179 **/
 180 EFI_STATUS
 181 EFIAPI
 182 RegisterCpuInterruptHandler (
 183   IN EFI_EXCEPTION_TYPE            InterruptType,
 184   IN EFI_CPU_INTERRUPT_HANDLER     InterruptHandler
 185   );
 186
 187 /**
 188   Display processor context.
 189
 190   @param[in] ExceptionType  Exception type.
 191   @param[in] SystemContext  Processor context to be display.
 192 **/
 193 VOID
 194 EFIAPI
 195 DumpCpuContext (
 196   IN EFI_EXCEPTION_TYPE   ExceptionType,
 197   IN EFI_SYSTEM_CONTEXT   SystemContext
 198   );
 199
 200 #endif