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 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     //
 164     // Append Shadow Stack after normal stack
 165     //
 166     // |= SmiStack
 167     // +--------------------------------------------------+---------------------------------------------------------------+
 168     // | Known Good Stack | Guard Page |    SMM Stack     | Known Good Shadow Stack | Guard Page |    SMM Shadow Stack    |
 169     // +--------------------------------------------------+---------------------------------------------------------------+
 170     // |                               |PcdCpuSmmStackSize|                                      |PcdCpuSmmShadowStackSize|
 171     // |<-------------------- StackSize ----------------->|<------------------------- ShadowStackSize ------------------->|
 172     // |                                                                                                                  |
 173     // |<-------------------------------------------- Processor N ------------------------------------------------------->|
 174     // | low address (bottom)                                                                          high address (top) |
 175     //
 176
 177   @param[in] CpuIndex   The index of the CPU to install the custom SMI handler.
 178                         The value must be between 0 and the NumberOfCpus field
 179                         in the System Management System Table (SMST).
 180   @param[in] SmBase     The SMBASE address for the CPU specified by CpuIndex.
 181   @param[in] SmiStack   The bottom of stack to use when an SMI is processed by the
 182                         the CPU specified by CpuIndex.
 183   @param[in] StackSize  The size, in bytes, if the stack used when an SMI is
 184                         processed by the CPU specified by CpuIndex.
 185                         StackSize should be PcdCpuSmmStackSize, with 2 more pages
 186                         if PcdCpuSmmStackGuard is true.
 187                         If ShadowStack is enabled, the shadow stack is allocated
 188                         after the normal Stack. The size is PcdCpuSmmShadowStackSize.
 189                         with 2 more pages if PcdCpuSmmStackGuard is true.
 190   @param[in] GdtBase    The base address of the GDT to use when an SMI is
 191                         processed by the CPU specified by CpuIndex.
 192   @param[in] GdtSize    The size, in bytes, of the GDT used when an SMI is
 193                         processed by the CPU specified by CpuIndex.
 194   @param[in] IdtBase    The base address of the IDT to use when an SMI is
 195                         processed by the CPU specified by CpuIndex.
 196   @param[in] IdtSize    The size, in bytes, of the IDT used when an SMI is
 197                         processed by the CPU specified by CpuIndex.
 198   @param[in] Cr3        The base address of the page tables to use when an SMI
 199                         is processed by the CPU specified by CpuIndex.
 200 **/
 201 VOID
 202 EFIAPI
 203 SmmCpuFeaturesInstallSmiHandler (
 204   IN UINTN   CpuIndex,
 205   IN UINT32  SmBase,
 206   IN VOID    *SmiStack,
 207   IN UINTN   StackSize,
 208   IN UINTN   GdtBase,
 209   IN UINTN   GdtSize,
 210   IN UINTN   IdtBase,
 211   IN UINTN   IdtSize,
 212   IN UINT32  Cr3
 213   );
 214
 215 /**
 216   Determines if MTRR registers must be configured to set SMRAM cache-ability
 217   when executing in System Management Mode.
 218
 219   @retval TRUE   MTRR registers must be configured to set SMRAM cache-ability.
 220   @retval FALSE  MTRR registers do not need to be configured to set SMRAM
 221                  cache-ability.
 222 **/
 223 BOOLEAN
 224 EFIAPI
 225 SmmCpuFeaturesNeedConfigureMtrrs (
 226   VOID
 227   );
 228
 229 /**
 230   Disable SMRR register if SMRR is supported and SmmCpuFeaturesNeedConfigureMtrrs()
 231   returns TRUE.
 232 **/
 233 VOID
 234 EFIAPI
 235 SmmCpuFeaturesDisableSmrr (
 236   VOID
 237   );
 238
 239 /**
 240   Enable SMRR register if SMRR is supported and SmmCpuFeaturesNeedConfigureMtrrs()
 241   returns TRUE.
 242 **/
 243 VOID
 244 EFIAPI
 245 SmmCpuFeaturesReenableSmrr (
 246   VOID
 247   );
 248
 249 /**
 250   Processor specific hook point each time a CPU enters System Management Mode.
 251
 252   @param[in] CpuIndex  The index of the CPU that has entered SMM.  The value
 253                        must be between 0 and the NumberOfCpus field in the
 254                        System Management System Table (SMST).
 255 **/
 256 VOID
 257 EFIAPI
 258 SmmCpuFeaturesRendezvousEntry (
 259   IN UINTN  CpuIndex
 260   );
 261
 262 /**
 263   Processor specific hook point each time a CPU exits System Management Mode.
 264
 265   @param[in] CpuIndex  The index of the CPU that is exiting SMM.  The value must
 266                        be between 0 and the NumberOfCpus field in the System
 267                        Management System Table (SMST).
 268 **/
 269 VOID
 270 EFIAPI
 271 SmmCpuFeaturesRendezvousExit (
 272   IN UINTN  CpuIndex
 273   );
 274
 275 /**
 276   Check to see if an SMM register is supported by a specified CPU.
 277
 278   @param[in] CpuIndex  The index of the CPU to check for SMM register support.
 279                        The value must be between 0 and the NumberOfCpus field
 280                        in the System Management System Table (SMST).
 281   @param[in] RegName   Identifies the SMM register to check for support.
 282
 283   @retval TRUE   The SMM register specified by RegName is supported by the CPU
 284                  specified by CpuIndex.
 285   @retval FALSE  The SMM register specified by RegName is not supported by the
 286                  CPU specified by CpuIndex.
 287 **/
 288 BOOLEAN
 289 EFIAPI
 290 SmmCpuFeaturesIsSmmRegisterSupported (
 291   IN UINTN         CpuIndex,
 292   IN SMM_REG_NAME  RegName
 293   );
 294
 295 /**
 296   Returns the current value of the SMM register for the specified CPU.
 297   If the SMM register is not supported, then 0 is returned.
 298
 299   @param[in] CpuIndex  The index of the CPU to read 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 read.
 303
 304   @return  The value of the SMM register specified by RegName from the CPU
 305            specified by CpuIndex.
 306 **/
 307 UINT64
 308 EFIAPI
 309 SmmCpuFeaturesGetSmmRegister (
 310   IN UINTN         CpuIndex,
 311   IN SMM_REG_NAME  RegName
 312   );
 313
 314 /**
 315   Sets the value of an SMM register on a specified CPU.
 316   If the SMM register is not supported, then no action is performed.
 317
 318   @param[in] CpuIndex  The index of the CPU to write the SMM register.  The
 319                        value must be between 0 and the NumberOfCpus field in
 320                        the System Management System Table (SMST).
 321   @param[in] RegName   Identifies the SMM register to write.
 322                        registers are read-only.
 323   @param[in] Value     The value to write to the SMM register.
 324 **/
 325 VOID
 326 EFIAPI
 327 SmmCpuFeaturesSetSmmRegister (
 328   IN UINTN         CpuIndex,
 329   IN SMM_REG_NAME  RegName,
 330   IN UINT64        Value
 331   );
 332
 333 /**
 334   Read an SMM Save State register on the target processor.  If this function
 335   returns EFI_UNSUPPORTED, then the caller is responsible for reading the
 336   SMM Save Sate register.
 337
 338   @param[in]  CpuIndex  The index of the CPU to read the SMM Save State.  The
 339                         value must be between 0 and the NumberOfCpus field in
 340                         the System Management System Table (SMST).
 341   @param[in]  Register  The SMM Save State register to read.
 342   @param[in]  Width     The number of bytes to read from the CPU save state.
 343   @param[out] Buffer    Upon return, this holds the CPU register value read
 344                         from the save state.
 345
 346   @retval EFI_SUCCESS           The register was read from Save State.
 347   @retval EFI_INVALID_PARAMTER  Buffer is NULL.
 348   @retval EFI_UNSUPPORTED       This function does not support reading Register.
 349
 350 **/
 351 EFI_STATUS
 352 EFIAPI
 353 SmmCpuFeaturesReadSaveStateRegister (
 354   IN  UINTN                        CpuIndex,
 355   IN  EFI_SMM_SAVE_STATE_REGISTER  Register,
 356   IN  UINTN                        Width,
 357   OUT VOID                         *Buffer
 358   );
 359
 360 /**
 361   Writes an SMM Save State register on the target processor.  If this function
 362   returns EFI_UNSUPPORTED, then the caller is responsible for writing the
 363   SMM Save Sate register.
 364
 365   @param[in] CpuIndex  The index of the CPU to write the SMM Save State.  The
 366                        value must be between 0 and the NumberOfCpus field in
 367                        the System Management System Table (SMST).
 368   @param[in] Register  The SMM Save State register to write.
 369   @param[in] Width     The number of bytes to write to the CPU save state.
 370   @param[in] Buffer    Upon entry, this holds the new CPU register value.
 371
 372   @retval EFI_SUCCESS           The register was written to Save State.
 373   @retval EFI_INVALID_PARAMTER  Buffer is NULL.
 374   @retval EFI_UNSUPPORTED       This function does not support writing Register.
 375 **/
 376 EFI_STATUS
 377 EFIAPI
 378 SmmCpuFeaturesWriteSaveStateRegister (
 379   IN UINTN                        CpuIndex,
 380   IN EFI_SMM_SAVE_STATE_REGISTER  Register,
 381   IN UINTN                        Width,
 382   IN CONST VOID                   *Buffer
 383   );
 384
 385 /**
 386   This function is hook point called after the gEfiSmmReadyToLockProtocolGuid
 387   notification is completely processed.
 388 **/
 389 VOID
 390 EFIAPI
 391 SmmCpuFeaturesCompleteSmmReadyToLock (
 392   VOID
 393   );
 394
 395 /**
 396   This API provides a method for a CPU to allocate a specific region for storing page tables.
 397
 398   This API can be called more once to allocate memory for page tables.
 399
 400   Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
 401   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
 402   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
 403   returned.
 404
 405   This function can also return NULL if there is no preference on where the page tables are allocated in SMRAM.
 406
 407   @param  Pages                 The number of 4 KB pages to allocate.
 408
 409   @return A pointer to the allocated buffer for page tables.
 410   @retval NULL      Fail to allocate a specific region for storing page tables,
 411                     Or there is no preference on where the page tables are allocated in SMRAM.
 412
 413 **/
 414 VOID *
 415 EFIAPI
 416 SmmCpuFeaturesAllocatePageTableMemory (
 417   IN UINTN           Pages
 418   );
 419
 420 #endif