UefiCpuPkg/Include/Library/SmmCpuFeaturesLib.h

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