UefiCpuPkg/Include/Library/SmmCpuFeaturesLib.h

   1 /** @file
   2 Library that provides CPU specific functions to support the PiSmmCpuDxeSmm module.
   3
   4 Copyright (c) 2015, 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 __SMM_FEATURES_LIB_H__
  16 #define __SMM_FEATURES_LIB_H__
  17
  18 #include <Protocol/MpService.h>
  19 #include <Protocol/SmmCpu.h>
  20 #include <Register/SmramSaveStateMap.h>
  21 #include <CpuHotPlugData.h>
  22
  23 ///
  24 /// Enumeration of SMM registers that are accessed using the library functions
  25 /// SmmCpuFeaturesIsSmmRegisterSupported (), SmmCpuFeaturesGetSmmRegister (),
  26 /// and SmmCpuFeaturesSetSmmRegister ().
  27 ///
  28 typedef enum {
  29   ///
  30   /// Read-write register to provides access to MSR_SMM_FEATURE_CONTROL if the
  31   /// CPU supports this MSR.
  32   ///
  33   SmmRegFeatureControl,
  34   ///
  35   /// Read-only register that returns a non-zero value if the CPU is able to
  36   /// respond to SMIs.
  37   ///
  38   SmmRegSmmEnable,
  39   ///
  40   /// Read-only register that returns a non-zero value if the CPU is able to
  41   /// respond to SMIs, but is busy with other actions that are causing a delay
  42   /// in responding to an SMI.  This register abstracts access to MSR_SMM_DELAYED
  43   /// if the CPU supports this MSR.
  44   ///
  45   SmmRegSmmDelayed,
  46   ///
  47   /// Read-only register that returns a non-zero value if the CPU is able to
  48   /// respond to SMIs, but is busy with other actions that are blocking its
  49   /// ability to respond to an SMI.  This register abstracts access to
  50   /// MSR_SMM_BLOCKED if the CPU supports this MSR.
  51   ///
  52   SmmRegSmmBlocked
  53 } SMM_REG_NAME;
  54
  55 /**
  56   Called during the very first SMI into System Management Mode to initialize
  57   CPU features, including SMBASE, for the currently executing CPU.  Since this
  58   is the first SMI, the SMRAM Save State Map is at the default address of
  59   SMM_DEFAULT_SMBASE + SMRAM_SAVE_STATE_MAP_OFFSET.  The currently executing
  60   CPU is specified by CpuIndex and CpuIndex can be used to access information
  61   about the currently executing CPU in the ProcessorInfo array and the
  62   HotPlugCpuData data structure.
  63
  64   @param[in] CpuIndex        The index of the CPU to initialize.  The value
  65                              must be between 0 and the NumberOfCpus field in
  66                              the System Management System Table (SMST).
  67   @param[in] IsMonarch       TRUE if the CpuIndex is the index of the CPU that
  68                              was elected as monarch during System Management
  69                              Mode initialization.
  70                              FALSE if the CpuIndex is not the index of the CPU
  71                              that was elected as monarch during System
  72                              Management Mode initialization.
  73   @param[in] ProcessorInfo   Pointer to an array of EFI_PROCESSOR_INFORMATION
  74                              structures.  ProcessorInfo[CpuIndex] contains the
  75                              information for the currently executing CPU.
  76   @param[in] CpuHotPlugData  Pointer to the CPU_HOT_PLUG_DATA structure that
  77                              contains the ApidId and SmBase arrays.
  78 **/
  79 VOID
  80 EFIAPI
  81 SmmCpuFeaturesInitializeProcessor (
  82   IN UINTN                      CpuIndex,
  83   IN BOOLEAN                    IsMonarch,
  84   IN EFI_PROCESSOR_INFORMATION  *ProcessorInfo,
  85   IN CPU_HOT_PLUG_DATA          *CpuHotPlugData
  86   );
  87
  88 /**
  89   This function updates the SMRAM save state on the currently executing CPU
  90   to resume execution at a specific address after an RSM instruction.  This
  91   function must evaluate the SMRAM save state to determine the execution mode
  92   the RSM instruction resumes and update the resume execution address with
  93   either NewInstructionPointer32 or NewInstructionPoint.  The auto HALT restart
  94   flag in the SMRAM save state must always be cleared.  This function returns
  95   the value of the instruction pointer from the SMRAM save state that was
  96   replaced.  If this function returns 0, then the SMRAM save state was not
  97   modified.
  98
  99   This function is called during the very first SMI on each CPU after
 100   SmmCpuFeaturesInitializeProcessor() to set a flag in normal execution mode
 101   to signal that the SMBASE of each CPU has been updated before the default
 102   SMBASE address is used for the first SMI to the next CPU.
 103
 104   @param[in] CpuIndex                 The index of the CPU to hook.  The value
 105                                       must be between 0 and the NumberOfCpus
 106                                       field in the System Management System Table
 107                                       (SMST).
 108   @param[in] CpuState                 Pointer to SMRAM Save State Map for the
 109                                       currently executing CPU.
 110   @param[in] NewInstructionPointer32  Instruction pointer to use if resuming to
 111                                       32-bit execution mode from 64-bit SMM.
 112   @param[in] NewInstructionPointer    Instruction pointer to use if resuming to
 113                                       same execution mode as SMM.
 114
 115   @retval 0    This function did modify the SMRAM save state.
 116   @retval > 0  The original instruction pointer value from the SMRAM save state
 117                before it was replaced.
 118 **/
 119 UINT64
 120 EFIAPI
 121 SmmCpuFeaturesHookReturnFromSmm (
 122   IN UINTN                 CpuIndex,
 123   IN SMRAM_SAVE_STATE_MAP  *CpuState,
 124   IN UINT64                NewInstructionPointer32,
 125   IN UINT64                NewInstructionPointer
 126   );
 127
 128 /**
 129   Hook point in normal execution mode that allows the one CPU that was elected
 130   as monarch during System Management Mode initialization to perform additional
 131   initialization actions immediately after all of the CPUs have processed their
 132   first SMI and called SmmCpuFeaturesInitializeProcessor() relocating SMBASE
 133   into a buffer in SMRAM and called SmmCpuFeaturesHookReturnFromSmm().
 134 **/
 135 VOID
 136 EFIAPI
 137 SmmCpuFeaturesSmmRelocationComplete (
 138   VOID
 139   );
 140
 141 /**
 142   Return the size, in bytes, of a custom SMI Handler in bytes.  If 0 is
 143   returned, then a custom SMI handler is not provided by this library,
 144   and the default SMI handler must be used.
 145
 146   @retval 0    Use the default SMI handler.
 147   @retval > 0  Use the SMI handler installed by SmmCpuFeaturesInstallSmiHandler()
 148                The caller is required to allocate enough SMRAM for each CPU to
 149                support the size of the custom SMI handler.
 150 **/
 151 UINTN
 152 EFIAPI
 153 SmmCpuFeaturesGetSmiHandlerSize (
 154   VOID
 155   );
 156
 157 /**
 158   Install a custom SMI handler for the CPU specified by CpuIndex.  This function
 159   is only called if SmmCpuFeaturesGetSmiHandlerSize() returns a size is greater
 160   than zero and is called by the CPU that was elected as monarch during System
 161   Management Mode initialization.
 162
 163   @param[in] CpuIndex   The index of the CPU to install the custom SMI handler.
 164                         The value must be between 0 and the NumberOfCpus field
 165                         in the System Management System Table (SMST).
 166   @param[in] SmBase     The SMBASE address for the CPU specified by CpuIndex.
 167   @param[in] SmiStack   The stack to use when an SMI is processed by the
 168                         the CPU specified by CpuIndex.
 169   @param[in] StackSize  The size, in bytes, if the stack used when an SMI is
 170                         processed by the CPU specified by CpuIndex.
 171   @param[in] GdtBase    The base address of the GDT to use when an SMI is
 172                         processed by the CPU specified by CpuIndex.
 173   @param[in] GdtSize    The size, in bytes, of the GDT used when an SMI is
 174                         processed by the CPU specified by CpuIndex.
 175   @param[in] IdtBase    The base address of the IDT to use when an SMI is
 176                         processed by the CPU specified by CpuIndex.
 177   @param[in] IdtSize    The size, in bytes, of the IDT used when an SMI is
 178                         processed by the CPU specified by CpuIndex.
 179   @param[in] Cr3        The base address of the page tables to use when an SMI
 180                         is processed by the CPU specified by CpuIndex.
 181 **/
 182 VOID
 183 EFIAPI
 184 SmmCpuFeaturesInstallSmiHandler (
 185   IN UINTN   CpuIndex,
 186   IN UINT32  SmBase,
 187   IN VOID    *SmiStack,
 188   IN UINTN   StackSize,
 189   IN UINTN   GdtBase,
 190   IN UINTN   GdtSize,
 191   IN UINTN   IdtBase,
 192   IN UINTN   IdtSize,
 193   IN UINT32  Cr3
 194   );
 195
 196 /**
 197   Determines if MTRR registers must be configured to set SMRAM cache-ability
 198   when executing in System Management Mode.
 199
 200   @retval TRUE   MTRR registers must be configured to set SMRAM cache-ability.
 201   @retval FALSE  MTRR registers do not need to be configured to set SMRAM
 202                  cache-ability.
 203 **/
 204 BOOLEAN
 205 EFIAPI
 206 SmmCpuFeaturesNeedConfigureMtrrs (
 207   VOID
 208   );
 209
 210 /**
 211   Disable SMRR register if SMRR is supported and SmmCpuFeaturesNeedConfigureMtrrs()
 212   returns TRUE.
 213 **/
 214 VOID
 215 EFIAPI
 216 SmmCpuFeaturesDisableSmrr (
 217   VOID
 218   );
 219
 220 /**
 221   Enable SMRR register if SMRR is supported and SmmCpuFeaturesNeedConfigureMtrrs()
 222   returns TRUE.
 223 **/
 224 VOID
 225 EFIAPI
 226 SmmCpuFeaturesReenableSmrr (
 227   VOID
 228   );
 229
 230 /**
 231   Processor specific hook point each time a CPU enters System Management Mode.
 232
 233   @param[in] CpuIndex  The index of the CPU that has entered SMM.  The value
 234                        must be between 0 and the NumberOfCpus field in the
 235                        System Management System Table (SMST).
 236 **/
 237 VOID
 238 EFIAPI
 239 SmmCpuFeaturesRendezvousEntry (
 240   IN UINTN  CpuIndex
 241   );
 242
 243 /**
 244   Processor specific hook point each time a CPU exits System Management Mode.
 245
 246   @param[in] CpuIndex  The index of the CPU that is exiting SMM.  The value must
 247                        be between 0 and the NumberOfCpus field in the System
 248                        Management System Table (SMST).
 249 **/
 250 VOID
 251 EFIAPI
 252 SmmCpuFeaturesRendezvousExit (
 253   IN UINTN  CpuIndex
 254   );
 255
 256 /**
 257   Check to see if an SMM register is supported by a specified CPU.
 258
 259   @param[in] CpuIndex  The index of the CPU to check for SMM register support.
 260                        The value must be between 0 and the NumberOfCpus field
 261                        in the System Management System Table (SMST).
 262   @param[in] RegName   Identifies the SMM register to check for support.
 263
 264   @retval TRUE   The SMM register specified by RegName is supported by the CPU
 265                  specified by CpuIndex.
 266   @retval FALSE  The SMM register specified by RegName is not supported by the
 267                  CPU specified by CpuIndex.
 268 **/
 269 BOOLEAN
 270 EFIAPI
 271 SmmCpuFeaturesIsSmmRegisterSupported (
 272   IN UINTN         CpuIndex,
 273   IN SMM_REG_NAME  RegName
 274   );
 275
 276 /**
 277   Returns the current value of the SMM register for the specified CPU.
 278   If the SMM register is not supported, then 0 is returned.
 279
 280   @param[in] CpuIndex  The index of the CPU to read the SMM register.  The
 281                        value must be between 0 and the NumberOfCpus field in
 282                        the System Management System Table (SMST).
 283   @param[in] RegName   Identifies the SMM register to read.
 284
 285   @return  The value of the SMM register specified by RegName from the CPU
 286            specified by CpuIndex.
 287 **/
 288 UINT64
 289 EFIAPI
 290 SmmCpuFeaturesGetSmmRegister (
 291   IN UINTN         CpuIndex,
 292   IN SMM_REG_NAME  RegName
 293   );
 294
 295 /**
 296   Sets the value of an SMM register on a specified CPU.
 297   If the SMM register is not supported, then no action is performed.
 298
 299   @param[in] CpuIndex  The index of the CPU to write the SMM register.  The
 300                        value must be between 0 and the NumberOfCpus field in
 301                        the System Management System Table (SMST).
 302   @param[in] RegName   Identifies the SMM register to write.
 303                        registers are read-only.
 304   @param[in] Value     The value to write to the SMM register.
 305 **/
 306 VOID
 307 EFIAPI
 308 SmmCpuFeaturesSetSmmRegister (
 309   IN UINTN         CpuIndex,
 310   IN SMM_REG_NAME  RegName,
 311   IN UINT64        Value
 312   );
 313
 314 /**
 315   Read an SMM Save State register on the target processor.  If this function
 316   returns EFI_UNSUPPORTED, then the caller is responsible for reading the
 317   SMM Save Sate register.
 318
 319   @param[in]  CpuIndex  The index of the CPU to read the SMM Save State.  The
 320                         value must be between 0 and the NumberOfCpus field in
 321                         the System Management System Table (SMST).
 322   @param[in]  Register  The SMM Save State register to read.
 323   @param[in]  Width     The number of bytes to read from the CPU save state.
 324   @param[out] Buffer    Upon return, this holds the CPU register value read
 325                         from the save state.
 326
 327   @retval EFI_SUCCESS           The register was read from Save State.
 328   @retval EFI_INVALID_PARAMTER  Buffer is NULL.
 329   @retval EFI_UNSUPPORTED       This function does not support reading Register.
 330
 331 **/
 332 EFI_STATUS
 333 EFIAPI
 334 SmmCpuFeaturesReadSaveStateRegister (
 335   IN  UINTN                        CpuIndex,
 336   IN  EFI_SMM_SAVE_STATE_REGISTER  Register,
 337   IN  UINTN                        Width,
 338   OUT VOID                         *Buffer
 339   );
 340
 341 /**
 342   Writes an SMM Save State register on the target processor.  If this function
 343   returns EFI_UNSUPPORTED, then the caller is responsible for writing the
 344   SMM Save Sate register.
 345
 346   @param[in] CpuIndex  The index of the CPU to write the SMM Save State.  The
 347                        value must be between 0 and the NumberOfCpus field in
 348                        the System Management System Table (SMST).
 349   @param[in] Register  The SMM Save State register to write.
 350   @param[in] Width     The number of bytes to write to the CPU save state.
 351   @param[in] Buffer    Upon entry, this holds the new CPU register value.
 352
 353   @retval EFI_SUCCESS           The register was written to Save State.
 354   @retval EFI_INVALID_PARAMTER  Buffer is NULL.
 355   @retval EFI_UNSUPPORTED       This function does not support writing Register.
 356 **/
 357 EFI_STATUS
 358 EFIAPI
 359 SmmCpuFeaturesWriteSaveStateRegister (
 360   IN UINTN                        CpuIndex,
 361   IN EFI_SMM_SAVE_STATE_REGISTER  Register,
 362   IN UINTN                        Width,
 363   IN CONST VOID                   *Buffer
 364   );
 365
 366 #endif