1 /** @file 2 STM API definition 3 4 Copyright (c) 2015 - 2016, 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 @par Specification Reference: 14 SMI Transfer Monitor (STM) User Guide Revision 1.00 15 16 **/ 17 18 #ifndef _STM_API_H_ 19 #define _STM_API_H_ 20 21 #include <Register/StmStatusCode.h> 22 #include <Register/StmResourceDescriptor.h> 23 #include <Register/ArchitecturalMsr.h> 24 25 #pragma pack (1) 26 27 /** 28 STM Header Structures 29 **/ 30 31 typedef struct { 32 UINT32 Intel64ModeSupported :1; ///> bitfield 33 UINT32 EptSupported :1; ///> bitfield 34 UINT32 Reserved :30; ///> must be 0 35 } STM_FEAT; 36 37 #define STM_SPEC_VERSION_MAJOR 1 38 #define STM_SPEC_VERSION_MINOR 0 39 40 typedef struct { 41 UINT8 StmSpecVerMajor; 42 UINT8 StmSpecVerMinor; 43 /// 44 /// Must be zero 45 /// 46 UINT16 Reserved; 47 UINT32 StaticImageSize; 48 UINT32 PerProcDynamicMemorySize; 49 UINT32 AdditionalDynamicMemorySize; 50 STM_FEAT StmFeatures; 51 UINT32 NumberOfRevIDs; 52 UINT32 StmSmmRevID[1]; 53 /// 54 /// The total STM_HEADER should be 4K. 55 /// 56 } SOFTWARE_STM_HEADER; 57 58 typedef struct { 59 MSEG_HEADER HwStmHdr; 60 SOFTWARE_STM_HEADER SwStmHdr; 61 } STM_HEADER; 62 63 64 /** 65 VMCALL API Numbers 66 API number convention: BIOS facing VMCALL interfaces have bit 16 clear 67 **/ 68 69 /** 70 StmMapAddressRange enables a SMM guest to create a non-1:1 virtual to 71 physical mapping of an address range into the SMM guest's virtual 72 memory space. 73 74 @param EAX #STM_API_MAP_ADDRESS_RANGE (0x00000001) 75 @param EBX Low 32 bits of physical address of caller allocated 76 STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure. 77 @param ECX High 32 bits of physical address of caller allocated 78 STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is 79 clear (0), ECX must be 0. 80 81 @note All fields of STM_MAP_ADDRESS_RANGE_DESCRIPTOR are inputs only. They 82 are not modified by StmMapAddressRange. 83 84 @retval CF 0 85 No error, EAX set to STM_SUCCESS. 86 The memory range was mapped as requested. 87 @retval CF 1 88 An error occurred, EAX holds relevant error value. 89 @retval EAX #ERROR_STM_SECURITY_VIOLATION 90 The requested mapping contains a protected resource. 91 @retval EAX #ERROR_STM_CACHE_TYPE_NOT_SUPPORTED 92 The requested cache type could not be satisfied. 93 @retval EAX #ERROR_STM_PAGE_NOT_FOUND 94 Page count must not be zero. 95 @retval EAX #ERROR_STM_FUNCTION_NOT_SUPPORTED 96 STM supports EPT and has not implemented StmMapAddressRange(). 97 @retval EAX #ERROR_STM_UNSPECIFIED 98 An unspecified error occurred. 99 100 @note All other registers unmodified. 101 **/ 102 #define STM_API_MAP_ADDRESS_RANGE 0x00000001 103 104 /** 105 STM Map Address Range Descriptor for #STM_API_MAP_ADDRESS_RANGE VMCALL 106 **/ 107 typedef struct { 108 UINT64 PhysicalAddress; 109 UINT64 VirtualAddress; 110 UINT32 PageCount; 111 UINT32 PatCacheType; 112 } STM_MAP_ADDRESS_RANGE_DESCRIPTOR; 113 114 /** 115 Define values for PatCacheType field of #STM_MAP_ADDRESS_RANGE_DESCRIPTOR 116 @{ 117 **/ 118 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_ST_UC 0x00 119 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WC 0x01 120 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WT 0x04 121 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WP 0x05 122 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WB 0x06 123 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_UC 0x07 124 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_FOLLOW_MTRR 0xFFFFFFFF 125 /// @} 126 127 /** 128 StmUnmapAddressRange enables a SMM guest to remove mappings from its page 129 table. 130 131 If TXT_PROCESSOR_SMM_DESCRIPTOR.EptEnabled bit is set by the STM, BIOS can 132 control its own page tables. In this case, the STM implementation may 133 optionally return ERROR_STM_FUNCTION_NOT_SUPPORTED. 134 135 @param EAX #STM_API_UNMAP_ADDRESS_RANGE (0x00000002) 136 @param EBX Low 32 bits of virtual address of caller allocated 137 STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure. 138 @param ECX High 32 bits of virtual address of caller allocated 139 STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is 140 clear (0), ECX must be zero. 141 142 @retval CF 0 143 No error, EAX set to STM_SUCCESS. The memory range was unmapped 144 as requested. 145 @retval CF 1 146 An error occurred, EAX holds relevant error value. 147 @retval EAX #ERROR_STM_FUNCTION_NOT_SUPPORTED 148 STM supports EPT and has not implemented StmUnmapAddressRange(). 149 @retval EAX #ERROR_STM_UNSPECIFIED 150 An unspecified error occurred. 151 152 @note All other registers unmodified. 153 **/ 154 #define STM_API_UNMAP_ADDRESS_RANGE 0x00000002 155 156 /** 157 STM Unmap Address Range Descriptor for #STM_API_UNMAP_ADDRESS_RANGE VMCALL 158 **/ 159 typedef struct { 160 UINT64 VirtualAddress; 161 UINT32 Length; 162 } STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR; 163 164 165 /** 166 Since the normal OS environment runs with a different set of page tables than 167 the SMM guest, virtual mappings will certainly be different. In order to do a 168 guest virtual to host physical translation of an address from the normal OS 169 code (EIP for example), it is necessary to walk the page tables governing the 170 OS page mappings. Since the SMM guest has no direct access to the page tables, 171 it must ask the STM to do this page table walk. This is supported via the 172 StmAddressLookup VMCALL. All OS page table formats need to be supported, 173 (e.g. PAE, PSE, Intel64, EPT, etc.) 174 175 StmAddressLookup takes a CR3 value and a virtual address from the interrupted 176 code as input and returns the corresponding physical address. It also 177 optionally maps the physical address into the SMM guest's virtual address 178 space. This new mapping persists ONLY for the duration of the SMI and if 179 needed in subsequent SMIs it must be remapped. PAT cache types follow the 180 interrupted environment's page table. 181 182 If EPT is enabled, OS CR3 only provides guest physical address information, 183 but the SMM guest might also need to know the host physical address. Since 184 SMM does not have direct access rights to EPT (it is protected by the STM), 185 SMM can input InterruptedEptp to let STM help to walk through it, and output 186 the host physical address. 187 188 @param EAX #STM_API_ADDRESS_LOOKUP (0x00000003) 189 @param EBX Low 32 bits of virtual address of caller allocated 190 STM_ADDRESS_LOOKUP_DESCRIPTOR structure. 191 @param ECX High 32 bits of virtual address of caller allocated 192 STM_ADDRESS_LOOKUP_DESCRIPTOR structure. If Intel64Mode is 193 clear (0), ECX must be zero. 194 195 @retval CF 0 196 No error, EAX set to STM_SUCCESS. PhysicalAddress contains the 197 host physical address determined by walking the interrupted SMM 198 guest's page tables. SmmGuestVirtualAddress contains the SMM 199 guest's virtual mapping of the requested address. 200 @retval CF 1 201 An error occurred, EAX holds relevant error value. 202 @retval EAX #ERROR_STM_SECURITY_VIOLATION 203 The requested page was a protected page. 204 @retval EAX #ERROR_STM_PAGE_NOT_FOUND 205 The requested virtual address did not exist in the page given 206 page table. 207 @retval EAX #ERROR_STM_BAD_CR3 208 The CR3 input was invalid. CR3 values must be from one of the 209 interrupted guest, or from the interrupted guest of another 210 processor. 211 @retval EAX #ERROR_STM_PHYSICAL_OVER_4G 212 The resulting physical address is greater than 4G and no virtual 213 address was supplied. The STM could not determine what address 214 within the SMM guest's virtual address space to do the mapping. 215 STM_ADDRESS_LOOKUP_DESCRIPTOR field PhysicalAddress contains the 216 physical address determined by walking the interrupted 217 environment's page tables. 218 @retval EAX #ERROR_STM_VIRTUAL_SPACE_TOO_SMALL 219 A specific virtual mapping was requested, but 220 SmmGuestVirtualAddress + Length exceeds 4G and the SMI handler 221 is running in 32 bit mode. 222 @retval EAX #ERROR_STM_UNSPECIFIED 223 An unspecified error occurred. 224 225 @note All other registers unmodified. 226 **/ 227 #define STM_API_ADDRESS_LOOKUP 0x00000003 228 229 /** 230 STM Lookup Address Range Descriptor for #STM_API_ADDRESS_LOOKUP VMCALL 231 **/ 232 typedef struct { 233 UINT64 InterruptedGuestVirtualAddress; 234 UINT32 Length; 235 UINT64 InterruptedCr3; 236 UINT64 InterruptedEptp; 237 UINT32 MapToSmmGuest:2; 238 UINT32 InterruptedCr4Pae:1; 239 UINT32 InterruptedCr4Pse:1; 240 UINT32 InterruptedIa32eMode:1; 241 UINT32 Reserved1:27; 242 UINT32 Reserved2; 243 UINT64 PhysicalAddress; 244 UINT64 SmmGuestVirtualAddress; 245 } STM_ADDRESS_LOOKUP_DESCRIPTOR; 246 247 /** 248 Define values for the MapToSmmGuest field of #STM_ADDRESS_LOOKUP_DESCRIPTOR 249 @{ 250 **/ 251 #define STM_ADDRESS_LOOKUP_DESCRIPTOR_DO_NOT_MAP 0 252 #define STM_ADDRESS_LOOKUP_DESCRIPTOR_ONE_TO_ONE 1 253 #define STM_ADDRESS_LOOKUP_DESCRIPTOR_VIRTUAL_ADDRESS_SPECIFIED 3 254 /// @} 255 256 257 /** 258 When returning from a protection exception (see section 6.2), the SMM guest 259 can instruct the STM to take one of two paths. It can either request a value 260 be logged to the TXT.ERRORCODE register and subsequently reset the machine 261 (indicating it couldn't resolve the problem), or it can request that the STM 262 resume the SMM guest again with the specified register state. 263 264 Unlike other VMCALL interfaces, StmReturnFromProtectionException behaves more 265 like a jump or an IRET instruction than a "call". It does not return directly 266 to the caller, but indirectly to a different location specified on the 267 caller's stack (see section 6.2) or not at all. 268 269 If the SMM guest STM protection exception handler itself causes a protection 270 exception (e.g. a single nested exception), or more than 100 un-nested 271 exceptions occur within the scope of a single SMI event, the STM must write 272 STM_CRASH_PROTECTION_EXCEPTION_FAILURE to the TXT.ERRORCODE register and 273 assert TXT.CMD.SYS_RESET. The reason for these restrictions is to simplify 274 the code requirements while still enabling a reasonable debugging capability. 275 276 @param EAX #STM_API_RETURN_FROM_PROTECTION_EXCEPTION (0x00000004) 277 @param EBX If 0, resume SMM guest using register state found on exception 278 stack. If in range 0x01..0x0F, EBX contains a BIOS error code 279 which the STM must record in the TXT.ERRORCODE register and 280 subsequently reset the system via TXT.CMD.SYS_RESET. The value 281 of the TXT.ERRORCODE register is calculated as follows: 282 283 TXT.ERRORCODE = (EBX & 0x0F) | STM_CRASH_BIOS_PANIC 284 285 Values 0x10..0xFFFFFFFF are reserved, do not use. 286 287 **/ 288 #define STM_API_RETURN_FROM_PROTECTION_EXCEPTION 0x00000004 289 290 291 /** 292 VMCALL API Numbers 293 API number convention: MLE facing VMCALL interfaces have bit 16 set. 294 295 The STM configuration lifecycle is as follows: 296 1. SENTER->SINIT->MLE: MLE begins execution with SMI disabled (masked). 297 2. MLE invokes #STM_API_INITIALIZE_PROTECTION VMCALL to prepare STM for 298 setup of initial protection profile. This is done on a single CPU and 299 has global effect. 300 3. MLE invokes #STM_API_PROTECT_RESOURCE VMCALL to define the initial 301 protection profile. The protection profile is global across all CPUs. 302 4. MLE invokes #STM_API_START VMCALL to enable the STM to begin receiving 303 SMI events. This must be done on every logical CPU. 304 5. MLE may invoke #STM_API_PROTECT_RESOURCE VMCALL or 305 #STM_API_UNPROTECT_RESOURCE VMCALL during runtime as many times as 306 necessary. 307 6. MLE invokes #STM_API_STOP VMCALL to disable the STM. SMI is again masked 308 following #STM_API_STOP VMCALL. 309 **/ 310 311 /** 312 StartStmVmcall() is used to configure an STM that is present in MSEG. SMIs 313 should remain disabled from the invocation of GETSEC[SENTER] until they are 314 re-enabled by StartStmVMCALL(). When StartStmVMCALL() returns, SMI is 315 enabled and the STM has been started and is active. Prior to invoking 316 StartStmVMCALL(), the MLE root should first invoke 317 InitializeProtectionVMCALL() followed by as many iterations of 318 ProtectResourceVMCALL() as necessary to establish the initial protection 319 profile. StartStmVmcall() must be invoked on all processor threads. 320 321 @param EAX #STM_API_START (0x00010001) 322 @param EDX STM configuration options. These provide the MLE with the 323 ability to pass configuration parameters to the STM. 324 325 @retval CF 0 326 No error, EAX set to STM_SUCCESS. The STM has been configured 327 and is now active and the guarding all requested resources. 328 @retval CF 1 329 An error occurred, EAX holds relevant error value. 330 @retval EAX #ERROR_STM_ALREADY_STARTED 331 The STM is already configured and active. STM remains active and 332 guarding previously enabled resource list. 333 @retval EAX #ERROR_STM_WITHOUT_SMX_UNSUPPORTED 334 The StartStmVMCALL() was invoked from VMX root mode, but outside 335 of SMX. This error code indicates the STM or platform does not 336 support the STM outside of SMX. The SMI handler remains active 337 and operates in legacy mode. See Appendix C 338 @retval EAX #ERROR_STM_UNSUPPORTED_MSR_BIT 339 The CPU doesn't support the MSR bit. The STM is not active. 340 @retval EAX #ERROR_STM_UNSPECIFIED 341 An unspecified error occurred. 342 343 @note All other registers unmodified. 344 **/ 345 #define STM_API_START (BIT16 | 1) 346 347 /** 348 Bit values for EDX input parameter to #STM_API_START VMCALL 349 @{ 350 **/ 351 #define STM_CONFIG_SMI_UNBLOCKING_BY_VMX_OFF BIT0 352 /// @} 353 354 355 /** 356 The StopStmVMCALL() is invoked by the MLE to teardown an active STM. This is 357 normally done as part of a full teardown of the SMX environment when the 358 system is being shut down. At the time the call is invoked, SMI is enabled 359 and the STM is active. When the call returns, the STM has been stopped and 360 all STM context is discarded and SMI is disabled. 361 362 @param EAX #STM_API_STOP (0x00010002) 363 364 @retval CF 0 365 No error, EAX set to STM_SUCCESS. The STM has been stopped and 366 is no longer processing SMI events. SMI is blocked. 367 @retval CF 1 368 An error occurred, EAX holds relevant error value. 369 @retval EAX #ERROR_STM_STOPPED 370 The STM was not active. 371 @retval EAX #ERROR_STM_UNSPECIFIED 372 An unspecified error occurred. 373 374 @note All other registers unmodified. 375 **/ 376 #define STM_API_STOP (BIT16 | 2) 377 378 379 /** 380 The ProtectResourceVMCALL() is invoked by the MLE root to request protection 381 of specific resources. The request is defined by a STM_RESOURCE_LIST, which 382 may contain more than one resource descriptor. Each resource descriptor is 383 processed separately by the STM. Whether or not protection for any specific 384 resource is granted is returned by the STM via the ReturnStatus bit in the 385 associated STM_RSC_DESC_HEADER. 386 387 @param EAX #STM_API_PROTECT_RESOURCE (0x00010003) 388 @param EBX Low 32 bits of physical address of caller allocated 389 STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero, 390 making the buffer 4K aligned. 391 @param ECX High 32 bits of physical address of caller allocated 392 STM_RESOURCE_LIST. 393 394 @note All fields of STM_RESOURCE_LIST are inputs only, except for the 395 ReturnStatus bit. On input, the ReturnStatus bit must be clear. On 396 return, the ReturnStatus bit is set for each resource request granted, 397 and clear for each resource request denied. There are no other fields 398 modified by ProtectResourceVMCALL(). The STM_RESOURCE_LIST must be 399 contained entirely within a single 4K page. 400 401 @retval CF 0 402 No error, EAX set to STM_SUCCESS. The STM has successfully 403 merged the entire protection request into the active protection 404 profile. There is therefore no need to check the ReturnStatus 405 bits in the STM_RESOURCE_LIST. 406 @retval CF 1 407 An error occurred, EAX holds relevant error value. 408 @retval EAX #ERROR_STM_UNPROTECTABLE_RESOURCE 409 At least one of the requested resource protections intersects a 410 BIOS required resource. Therefore, the caller must walk through 411 the STM_RESOURCE_LIST to determine which of the requested 412 resources was not granted protection. The entire list must be 413 traversed since there may be multiple failures. 414 @retval EAX #ERROR_STM_MALFORMED_RESOURCE_LIST 415 The resource list could not be parsed correctly, or did not 416 terminate before crossing a 4K page boundary. The caller must 417 walk through the STM_RESOURCE_LIST to determine which of the 418 requested resources was not granted protection. The entire list 419 must be traversed since there may be multiple failures. 420 @retval EAX #ERROR_STM_OUT_OF_RESOURCES 421 The STM has encountered an internal error and cannot complete 422 the request. 423 @retval EAX #ERROR_STM_UNSPECIFIED 424 An unspecified error occurred. 425 426 @note All other registers unmodified. 427 **/ 428 #define STM_API_PROTECT_RESOURCE (BIT16 | 3) 429 430 431 /** 432 The UnProtectResourceVMCALL() is invoked by the MLE root to request that the 433 STM allow the SMI handler access to the specified resources. 434 435 @param EAX #STM_API_UNPROTECT_RESOURCE (0x00010004) 436 @param EBX Low 32 bits of physical address of caller allocated 437 STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero, 438 making the buffer 4K aligned. 439 @param ECX High 32 bits of physical address of caller allocated 440 STM_RESOURCE_LIST. 441 442 @note All fields of STM_RESOURCE_LIST are inputs only, except for the 443 ReturnStatus bit. On input, the ReturnStatus bit must be clear. On 444 return, the ReturnStatus bit is set for each resource processed. For 445 a properly formed STM_RESOURCE_LIST, this should be all resources 446 listed. There are no other fields modified by 447 UnProtectResourceVMCALL(). The STM_RESOURCE_LIST must be contained 448 entirely within a single 4K page. 449 450 @retval CF 0 451 No error, EAX set to STM_SUCCESS. The requested resources are 452 not being guarded by the STM. 453 @retval CF 1 454 An error occurred, EAX holds relevant error value. 455 @retval EAX #ERROR_STM_MALFORMED_RESOURCE_LIST 456 The resource list could not be parsed correctly, or did not 457 terminate before crossing a 4K page boundary. The caller must 458 walk through the STM_RESOURCE_LIST to determine which of the 459 requested resources were not able to be unprotected. The entire 460 list must be traversed since there may be multiple failures. 461 @retval EAX #ERROR_STM_UNSPECIFIED 462 An unspecified error occurred. 463 464 @note All other registers unmodified. 465 **/ 466 #define STM_API_UNPROTECT_RESOURCE (BIT16 | 4) 467 468 469 /** 470 The GetBiosResourcesVMCALL() is invoked by the MLE root to request the list 471 of BIOS required resources from the STM. 472 473 @param EAX #STM_API_GET_BIOS_RESOURCES (0x00010005) 474 @param EBX Low 32 bits of physical address of caller allocated destination 475 buffer. Bits 11:0 are ignored and assumed to be zero, making the 476 buffer 4K aligned. 477 @param ECX High 32 bits of physical address of caller allocated destination 478 buffer. 479 @param EDX Indicates which page of the BIOS resource list to copy into the 480 destination buffer. The first page is indicated by 0, the second 481 page by 1, etc. 482 483 @retval CF 0 484 No error, EAX set to STM_SUCCESS. The destination buffer 485 contains the BIOS required resources. If the page retrieved is 486 the last page, EDX will be cleared to 0. If there are more pages 487 to retrieve, EDX is incremented to the next page index. Calling 488 software should iterate on GetBiosResourcesVMCALL() until EDX is 489 returned cleared to 0. 490 @retval CF 1 491 An error occurred, EAX holds relevant error value. 492 @retval EAX #ERROR_STM_PAGE_NOT_FOUND 493 The page index supplied in EDX input was out of range. 494 @retval EAX #ERROR_STM_UNSPECIFIED 495 An unspecified error occurred. 496 @retval EDX Page index of next page to read. A return of EDX=0 signifies 497 that the entire list has been read. 498 @note EDX is both an input and an output register. 499 500 @note All other registers unmodified. 501 **/ 502 #define STM_API_GET_BIOS_RESOURCES (BIT16 | 5) 503 504 505 /** 506 The ManageVmcsDatabaseVMCALL() is invoked by the MLE root to add or remove an 507 MLE guest (including the MLE root) from the list of protected domains. 508 509 @param EAX #STM_API_MANAGE_VMCS_DATABASE (0x00010006) 510 @param EBX Low 32 bits of physical address of caller allocated 511 STM_VMCS_DATABASE_REQUEST. Bits 11:0 are ignored and assumed to 512 be zero, making the buffer 4K aligned. 513 @param ECX High 32 bits of physical address of caller allocated 514 STM_VMCS_DATABASE_REQUEST. 515 516 @note All fields of STM_VMCS_DATABASE_REQUEST are inputs only. They are not 517 modified by ManageVmcsDatabaseVMCALL(). 518 519 @retval CF 0 520 No error, EAX set to STM_SUCCESS. 521 @retval CF 1 522 An error occurred, EAX holds relevant error value. 523 @retval EAX #ERROR_STM_INVALID_VMCS 524 Indicates a request to remove a VMCS from the database was made, 525 but the referenced VMCS was not found in the database. 526 @retval EAX #ERROR_STM_VMCS_PRESENT 527 Indicates a request to add a VMCS to the database was made, but 528 the referenced VMCS was already present in the database. 529 @retval EAX #ERROR_INVALID_PARAMETER 530 Indicates non-zero reserved field. 531 @retval EAX #ERROR_STM_UNSPECIFIED 532 An unspecified error occurred 533 534 @note All other registers unmodified. 535 **/ 536 #define STM_API_MANAGE_VMCS_DATABASE (BIT16 | 6) 537 538 /** 539 STM VMCS Database Request for #STM_API_MANAGE_VMCS_DATABASE VMCALL 540 **/ 541 typedef struct { 542 /// 543 /// bits 11:0 are reserved and must be 0 544 /// 545 UINT64 VmcsPhysPointer; 546 UINT32 DomainType :4; 547 UINT32 XStatePolicy :2; 548 UINT32 DegradationPolicy :4; 549 /// 550 /// Must be 0 551 /// 552 UINT32 Reserved1 :22; 553 UINT32 AddOrRemove; 554 } STM_VMCS_DATABASE_REQUEST; 555 556 /** 557 Values for the DomainType field of #STM_VMCS_DATABASE_REQUEST 558 @{ 559 **/ 560 #define DOMAIN_UNPROTECTED 0 561 #define DOMAIN_DISALLOWED_IO_OUT BIT0 562 #define DOMAIN_DISALLOWED_IO_IN BIT1 563 #define DOMAIN_INTEGRITY BIT2 564 #define DOMAIN_CONFIDENTIALITY BIT3 565 #define DOMAIN_INTEGRITY_PROT_OUT_IN (DOMAIN_INTEGRITY) 566 #define DOMAIN_FULLY_PROT_OUT_IN (DOMAIN_CONFIDENTIALITY | DOMAIN_INTEGRITY) 567 #define DOMAIN_FULLY_PROT (DOMAIN_FULLY_PROT_OUT_IN | DOMAIN_DISALLOWED_IO_IN | DOMAIN_DISALLOWED_IO_OUT) 568 /// @} 569 570 /** 571 Values for the XStatePolicy field of #STM_VMCS_DATABASE_REQUEST 572 @{ 573 **/ 574 #define XSTATE_READWRITE 0x00 575 #define XSTATE_READONLY 0x01 576 #define XSTATE_SCRUB 0x03 577 /// @} 578 579 /** 580 Values for the AddOrRemove field of #STM_VMCS_DATABASE_REQUEST 581 @{ 582 **/ 583 #define STM_VMCS_DATABASE_REQUEST_ADD 1 584 #define STM_VMCS_DATABASE_REQUEST_REMOVE 0 585 /// @} 586 587 588 /** 589 InitializeProtectionVMCALL() prepares the STM for setup of the initial 590 protection profile which is subsequently communicated via one or more 591 invocations of ProtectResourceVMCALL(), prior to invoking StartStmVMCALL(). 592 It is only necessary to invoke InitializeProtectionVMCALL() on one processor 593 thread. InitializeProtectionVMCALL() does not alter whether SMIs are masked 594 or unmasked. The STM should return back to the MLE with "Blocking by SMI" set 595 to 1 in the GUEST_INTERRUPTIBILITY field for the VMCS the STM created for the 596 MLE guest. 597 598 @param EAX #STM_API_INITIALIZE_PROTECTION (0x00010007) 599 600 @retval CF 0 601 No error, EAX set to STM_SUCCESS, EBX bits set to indicate STM 602 capabilities as defined below. The STM has set up an empty 603 protection profile, except for the resources that it sets up to 604 protect itself. The STM must not allow the SMI handler to map 605 any pages from the MSEG Base to the top of TSEG. The STM must 606 also not allow SMI handler access to those MSRs which the STM 607 requires for its own protection. 608 @retval CF 1 609 An error occurred, EAX holds relevant error value. 610 @retval EAX #ERROR_STM_ALREADY_STARTED 611 The STM is already configured and active. The STM remains active 612 and guarding the previously enabled resource list. 613 @retval EAX #ERROR_STM_UNPROTECTABLE 614 The STM determines that based on the platform configuration, the 615 STM is unable to protect itself. For example, the BIOS required 616 resource list contains memory pages in MSEG. 617 @retval EAX #ERROR_STM_UNSPECIFIED 618 An unspecified error occurred. 619 620 @note All other registers unmodified. 621 **/ 622 #define STM_API_INITIALIZE_PROTECTION (BIT16 | 7) 623 624 /** 625 Byte granular support bits returned in EBX from #STM_API_INITIALIZE_PROTECTION 626 @{ 627 **/ 628 #define STM_RSC_BGI BIT1 629 #define STM_RSC_BGM BIT2 630 #define STM_RSC_MSR BIT3 631 /// @} 632 633 634 /** 635 The ManageEventLogVMCALL() is invoked by the MLE root to control the logging 636 feature. It consists of several sub-functions to facilitate establishment of 637 the log itself, configuring what events will be logged, and functions to 638 start, stop, and clear the log. 639 640 @param EAX #STM_API_MANAGE_EVENT_LOG (0x00010008) 641 @param EBX Low 32 bits of physical address of caller allocated 642 STM_EVENT_LOG_MANAGEMENT_REQUEST. Bits 11:0 are ignored and 643 assumed to be zero, making the buffer 4K aligned. 644 @param ECX High 32 bits of physical address of caller allocated 645 STM_EVENT_LOG_MANAGEMENT_REQUEST. 646 647 @retval CF=0 648 No error, EAX set to STM_SUCCESS. 649 @retval CF=1 650 An error occurred, EAX holds relevant error value. See subfunction 651 descriptions below for details. 652 653 @note All other registers unmodified. 654 **/ 655 #define STM_API_MANAGE_EVENT_LOG (BIT16 | 8) 656 657 /// 658 /// STM Event Log Management Request for #STM_API_MANAGE_EVENT_LOG VMCALL 659 /// 660 typedef struct { 661 UINT32 SubFunctionIndex; 662 union { 663 struct { 664 UINT32 PageCount; 665 // 666 // number of elements is PageCount 667 // 668 UINT64 Pages[]; 669 } LogBuffer; 670 // 671 // bitmap of EVENT_TYPE 672 // 673 UINT32 EventEnableBitmap; 674 } Data; 675 } STM_EVENT_LOG_MANAGEMENT_REQUEST; 676 677 /** 678 Defines values for the SubFunctionIndex field of 679 #STM_EVENT_LOG_MANAGEMENT_REQUEST 680 @{ 681 **/ 682 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_NEW_LOG 1 683 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_CONFIGURE_LOG 2 684 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_START_LOG 3 685 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_STOP_LOG 4 686 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_CLEAR_LOG 5 687 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_DELETE_LOG 6 688 /// @} 689 690 /** 691 Log Entry Header 692 **/ 693 typedef struct { 694 UINT32 EventSerialNumber; 695 UINT16 Type; 696 UINT16 Lock :1; 697 UINT16 Valid :1; 698 UINT16 ReadByMle :1; 699 UINT16 Wrapped :1; 700 UINT16 Reserved :12; 701 } LOG_ENTRY_HEADER; 702 703 /** 704 Enum values for the Type field of #LOG_ENTRY_HEADER 705 **/ 706 typedef enum { 707 EvtLogStarted, 708 EvtLogStopped, 709 EvtLogInvalidParameterDetected, 710 EvtHandledProtectionException, 711 /// 712 /// unhandled protection exceptions result in reset & cannot be logged 713 /// 714 EvtBiosAccessToUnclaimedResource, 715 EvtMleResourceProtectionGranted, 716 EvtMleResourceProtectionDenied, 717 EvtMleResourceUnprotect, 718 EvtMleResourceUnprotectError, 719 EvtMleDomainTypeDegraded, 720 /// 721 /// add more here 722 /// 723 EvtMleMax, 724 /// 725 /// Not used 726 /// 727 EvtInvalid = 0xFFFFFFFF, 728 } EVENT_TYPE; 729 730 typedef struct { 731 UINT32 Reserved; 732 } ENTRY_EVT_LOG_STARTED; 733 734 typedef struct { 735 UINT32 Reserved; 736 } ENTRY_EVT_LOG_STOPPED; 737 738 typedef struct { 739 UINT32 VmcallApiNumber; 740 } ENTRY_EVT_LOG_INVALID_PARAM; 741 742 typedef struct { 743 STM_RSC Resource; 744 } ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION; 745 746 typedef struct { 747 STM_RSC Resource; 748 } ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC; 749 750 typedef struct { 751 STM_RSC Resource; 752 } ENTRY_EVT_MLE_RSC_PROT_GRANTED; 753 754 typedef struct { 755 STM_RSC Resource; 756 } ENTRY_EVT_MLE_RSC_PROT_DENIED; 757 758 typedef struct { 759 STM_RSC Resource; 760 } ENTRY_EVT_MLE_RSC_UNPROT; 761 762 typedef struct { 763 STM_RSC Resource; 764 } ENTRY_EVT_MLE_RSC_UNPROT_ERROR; 765 766 typedef struct { 767 UINT64 VmcsPhysPointer; 768 UINT8 ExpectedDomainType; 769 UINT8 DegradedDomainType; 770 } ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED; 771 772 typedef union { 773 ENTRY_EVT_LOG_STARTED Started; 774 ENTRY_EVT_LOG_STOPPED Stopped; 775 ENTRY_EVT_LOG_INVALID_PARAM InvalidParam; 776 ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION HandledProtectionException; 777 ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC BiosUnclaimedRsc; 778 ENTRY_EVT_MLE_RSC_PROT_GRANTED MleRscProtGranted; 779 ENTRY_EVT_MLE_RSC_PROT_DENIED MleRscProtDenied; 780 ENTRY_EVT_MLE_RSC_UNPROT MleRscUnprot; 781 ENTRY_EVT_MLE_RSC_UNPROT_ERROR MleRscUnprotError; 782 ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED MleDomainTypeDegraded; 783 } LOG_ENTRY_DATA; 784 785 typedef struct { 786 LOG_ENTRY_HEADER Hdr; 787 LOG_ENTRY_DATA Data; 788 } STM_LOG_ENTRY; 789 790 /** 791 Maximum STM Log Entry Size 792 **/ 793 #define STM_LOG_ENTRY_SIZE 256 794 795 796 /** 797 STM Protection Exception Stack Frame Structures 798 **/ 799 800 typedef struct { 801 UINT32 Rdi; 802 UINT32 Rsi; 803 UINT32 Rbp; 804 UINT32 Rdx; 805 UINT32 Rcx; 806 UINT32 Rbx; 807 UINT32 Rax; 808 UINT32 Cr3; 809 UINT32 Cr2; 810 UINT32 Cr0; 811 UINT32 VmcsExitInstructionInfo; 812 UINT32 VmcsExitInstructionLength; 813 UINT64 VmcsExitQualification; 814 /// 815 /// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value 816 /// 817 UINT32 ErrorCode; 818 UINT32 Rip; 819 UINT32 Cs; 820 UINT32 Rflags; 821 UINT32 Rsp; 822 UINT32 Ss; 823 } STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32; 824 825 typedef struct { 826 UINT64 R15; 827 UINT64 R14; 828 UINT64 R13; 829 UINT64 R12; 830 UINT64 R11; 831 UINT64 R10; 832 UINT64 R9; 833 UINT64 R8; 834 UINT64 Rdi; 835 UINT64 Rsi; 836 UINT64 Rbp; 837 UINT64 Rdx; 838 UINT64 Rcx; 839 UINT64 Rbx; 840 UINT64 Rax; 841 UINT64 Cr8; 842 UINT64 Cr3; 843 UINT64 Cr2; 844 UINT64 Cr0; 845 UINT64 VmcsExitInstructionInfo; 846 UINT64 VmcsExitInstructionLength; 847 UINT64 VmcsExitQualification; 848 /// 849 /// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value 850 /// 851 UINT64 ErrorCode; 852 UINT64 Rip; 853 UINT64 Cs; 854 UINT64 Rflags; 855 UINT64 Rsp; 856 UINT64 Ss; 857 } STM_PROTECTION_EXCEPTION_STACK_FRAME_X64; 858 859 typedef union { 860 STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32 *Ia32StackFrame; 861 STM_PROTECTION_EXCEPTION_STACK_FRAME_X64 *X64StackFrame; 862 } STM_PROTECTION_EXCEPTION_STACK_FRAME; 863 864 /** 865 Enum values for the ErrorCode field in 866 #STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32 and 867 #STM_PROTECTION_EXCEPTION_STACK_FRAME_X64 868 **/ 869 typedef enum { 870 TxtSmmPageViolation = 1, 871 TxtSmmMsrViolation, 872 TxtSmmRegisterViolation, 873 TxtSmmIoViolation, 874 TxtSmmPciViolation 875 } TXT_SMM_PROTECTION_EXCEPTION_TYPE; 876 877 /** 878 TXT Pocessor SMM Descriptor (PSD) structures 879 **/ 880 881 typedef struct { 882 UINT64 SpeRip; 883 UINT64 SpeRsp; 884 UINT16 SpeSs; 885 UINT16 PageViolationException:1; 886 UINT16 MsrViolationException:1; 887 UINT16 RegisterViolationException:1; 888 UINT16 IoViolationException:1; 889 UINT16 PciViolationException:1; 890 UINT16 Reserved1:11; 891 UINT32 Reserved2; 892 } STM_PROTECTION_EXCEPTION_HANDLER; 893 894 typedef struct { 895 UINT8 ExecutionDisableOutsideSmrr:1; 896 UINT8 Intel64Mode:1; 897 UINT8 Cr4Pae : 1; 898 UINT8 Cr4Pse : 1; 899 UINT8 Reserved1 : 4; 900 } STM_SMM_ENTRY_STATE; 901 902 typedef struct { 903 UINT8 SmramToVmcsRestoreRequired : 1; ///> BIOS restore hint 904 UINT8 ReinitializeVmcsRequired : 1; ///> BIOS request 905 UINT8 Reserved2 : 6; 906 } STM_SMM_RESUME_STATE; 907 908 typedef struct { 909 UINT8 DomainType : 4; ///> STM input to BIOS on each SMI 910 UINT8 XStatePolicy : 2; ///> STM input to BIOS on each SMI 911 UINT8 EptEnabled : 1; 912 UINT8 Reserved3 : 1; 913 } STM_SMM_STATE; 914 915 #define TXT_SMM_PSD_OFFSET 0xfb00 916 #define TXT_PROCESSOR_SMM_DESCRIPTOR_SIGNATURE SIGNATURE_64('T', 'X', 'T', 'P', 'S', 'S', 'I', 'G') 917 #define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MAJOR 1 918 #define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MINOR 0 919 920 typedef struct { 921 UINT64 Signature; 922 UINT16 Size; 923 UINT8 SmmDescriptorVerMajor; 924 UINT8 SmmDescriptorVerMinor; 925 UINT32 LocalApicId; 926 STM_SMM_ENTRY_STATE SmmEntryState; 927 STM_SMM_RESUME_STATE SmmResumeState; 928 STM_SMM_STATE StmSmmState; 929 UINT8 Reserved4; 930 UINT16 SmmCs; 931 UINT16 SmmDs; 932 UINT16 SmmSs; 933 UINT16 SmmOtherSegment; 934 UINT16 SmmTr; 935 UINT16 Reserved5; 936 UINT64 SmmCr3; 937 UINT64 SmmStmSetupRip; 938 UINT64 SmmStmTeardownRip; 939 UINT64 SmmSmiHandlerRip; 940 UINT64 SmmSmiHandlerRsp; 941 UINT64 SmmGdtPtr; 942 UINT32 SmmGdtSize; 943 UINT32 RequiredStmSmmRevId; 944 STM_PROTECTION_EXCEPTION_HANDLER StmProtectionExceptionHandler; 945 UINT64 Reserved6; 946 UINT64 BiosHwResourceRequirementsPtr; 947 // extend area 948 UINT64 AcpiRsdp; 949 UINT8 PhysicalAddressBits; 950 } TXT_PROCESSOR_SMM_DESCRIPTOR; 951 952 #pragma pack () 953 954 #endif 955
