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 - 2022, 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   Setup separate stacks for certain exception handlers.
 107
 108   InitData is optional and processor arch dependent.
 109
 110   @param[in]  InitData      Pointer to data optional for information about how
 111                             to assign stacks for certain exception handlers.
 112
 113   @retval EFI_SUCCESS             The stacks are assigned successfully.
 114   @retval EFI_UNSUPPORTED         This function is not supported.
 115
 116 **/
 117 EFI_STATUS
 118 EFIAPI
 119 InitializeSeparateExceptionStacks (
 120   IN CPU_EXCEPTION_INIT_DATA  *InitData OPTIONAL
 121   );
 122
 123 /**
 124   Registers a function to be called from the processor interrupt handler.
 125
 126   This function registers and enables the handler specified by InterruptHandler for a processor
 127   interrupt or exception type specified by InterruptType. If InterruptHandler is NULL, then the
 128   handler for the processor interrupt or exception type specified by InterruptType is uninstalled.
 129   The installed handler is called once for each processor interrupt or exception.
 130   NOTE: This function should be invoked after InitializeCpuExceptionHandlers() is invoked,
 131   otherwise EFI_UNSUPPORTED returned.
 132
 133   @param[in]  InterruptType     Defines which interrupt or exception to hook.
 134   @param[in]  InterruptHandler  A pointer to a function of type EFI_CPU_INTERRUPT_HANDLER that is called
 135                                 when a processor interrupt occurs. If this parameter is NULL, then the handler
 136                                 will be uninstalled.
 137
 138   @retval EFI_SUCCESS           The handler for the processor interrupt was successfully installed or uninstalled.
 139   @retval EFI_ALREADY_STARTED   InterruptHandler is not NULL, and a handler for InterruptType was
 140                                 previously installed.
 141   @retval EFI_INVALID_PARAMETER InterruptHandler is NULL, and a handler for InterruptType was not
 142                                 previously installed.
 143   @retval EFI_UNSUPPORTED       The interrupt specified by InterruptType is not supported,
 144                                 or this function is not supported.
 145 **/
 146 EFI_STATUS
 147 EFIAPI
 148 RegisterCpuInterruptHandler (
 149   IN EFI_EXCEPTION_TYPE         InterruptType,
 150   IN EFI_CPU_INTERRUPT_HANDLER  InterruptHandler
 151   );
 152
 153 /**
 154   Display processor context.
 155
 156   @param[in] ExceptionType  Exception type.
 157   @param[in] SystemContext  Processor context to be display.
 158 **/
 159 VOID
 160 EFIAPI
 161 DumpCpuContext (
 162   IN EFI_EXCEPTION_TYPE  ExceptionType,
 163   IN EFI_SYSTEM_CONTEXT  SystemContext
 164   );
 165
 166 #endif