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 /** 367 This function is hook point called after the gEfiSmmReadyToLockProtocolGuid 368 notification is completely processed. 369 **/ 370 VOID 371 EFIAPI 372 SmmCpuFeaturesCompleteSmmReadyToLock ( 373 VOID 374 ); 375 376 /** 377 This API provides a method for a CPU to allocate a specific region for storing page tables. 378 379 This API can be called more once to allocate memory for page tables. 380 381 Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the 382 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL 383 is returned. If there is not enough memory remaining to satisfy the request, then NULL is 384 returned. 385 386 This function can also return NULL if there is no preference on where the page tables are allocated in SMRAM. 387 388 @param Pages The number of 4 KB pages to allocate. 389 390 @return A pointer to the allocated buffer for page tables. 391 @retval NULL Fail to allocate a specific region for storing page tables, 392 Or there is no preference on where the page tables are allocated in SMRAM. 393 394 **/ 395 VOID * 396 EFIAPI 397 SmmCpuFeaturesAllocatePageTableMemory ( 398 IN UINTN Pages 399 ); 400 401 #endif 402