4 Copyright (c) 2015 - 2019, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
7 @par Specification Reference:
8 SMI Transfer Monitor (STM) User Guide Revision 1.00
12 #ifndef _INTEL_STM_API_H_
13 #define _INTEL_STM_API_H_
15 #include <Register/Intel/StmStatusCode.h>
16 #include <Register/Intel/StmResourceDescriptor.h>
17 #include <Register/Intel/ArchitecturalMsr.h>
26 UINT32 Intel64ModeSupported
:1; ///> bitfield
27 UINT32 EptSupported
:1; ///> bitfield
28 UINT32 Reserved
:30; ///> must be 0
31 #define STM_SPEC_VERSION_MAJOR 1
32 #define STM_SPEC_VERSION_MINOR 0
35 UINT8 StmSpecVerMajor
;
36 UINT8 StmSpecVerMinor
;
41 UINT32 StaticImageSize
;
42 UINT32 PerProcDynamicMemorySize
;
43 UINT32 AdditionalDynamicMemorySize
;
45 UINT32 NumberOfRevIDs
;
46 UINT32 StmSmmRevID
[1];
48 /// The total STM_HEADER should be 4K.
50 } SOFTWARE_STM_HEADER
;
54 SOFTWARE_STM_HEADER SwStmHdr
;
60 API number convention: BIOS facing VMCALL interfaces have bit 16 clear
64 StmMapAddressRange enables a SMM guest to create a non-1:1 virtual to
65 physical mapping of an address range into the SMM guest's virtual
68 @param EAX #STM_API_MAP_ADDRESS_RANGE (0x00000001)
69 @param EBX Low 32 bits of physical address of caller allocated
70 STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure.
71 @param ECX High 32 bits of physical address of caller allocated
72 STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is
73 clear (0), ECX must be 0.
75 @note All fields of STM_MAP_ADDRESS_RANGE_DESCRIPTOR are inputs only. They
76 are not modified by StmMapAddressRange.
79 No error, EAX set to STM_SUCCESS.
80 The memory range was mapped as requested.
82 An error occurred, EAX holds relevant error value.
83 @retval EAX #ERROR_STM_SECURITY_VIOLATION
84 The requested mapping contains a protected resource.
85 @retval EAX #ERROR_STM_CACHE_TYPE_NOT_SUPPORTED
86 The requested cache type could not be satisfied.
87 @retval EAX #ERROR_STM_PAGE_NOT_FOUND
88 Page count must not be zero.
89 @retval EAX #ERROR_STM_FUNCTION_NOT_SUPPORTED
90 STM supports EPT and has not implemented StmMapAddressRange().
91 @retval EAX #ERROR_STM_UNSPECIFIED
92 An unspecified error occurred.
94 @note All other registers unmodified.
96 #define STM_API_MAP_ADDRESS_RANGE 0x00000001
99 STM Map Address Range Descriptor for #STM_API_MAP_ADDRESS_RANGE VMCALL
102 UINT64 PhysicalAddress
;
103 UINT64 VirtualAddress
;
106 } STM_MAP_ADDRESS_RANGE_DESCRIPTOR
;
109 Define values for PatCacheType field of #STM_MAP_ADDRESS_RANGE_DESCRIPTOR
112 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_ST_UC 0x00
113 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WC 0x01
114 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WT 0x04
115 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WP 0x05
116 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WB 0x06
117 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_UC 0x07
118 #define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_FOLLOW_MTRR 0xFFFFFFFF
122 StmUnmapAddressRange enables a SMM guest to remove mappings from its page
125 If TXT_PROCESSOR_SMM_DESCRIPTOR.EptEnabled bit is set by the STM, BIOS can
126 control its own page tables. In this case, the STM implementation may
127 optionally return ERROR_STM_FUNCTION_NOT_SUPPORTED.
129 @param EAX #STM_API_UNMAP_ADDRESS_RANGE (0x00000002)
130 @param EBX Low 32 bits of virtual address of caller allocated
131 STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure.
132 @param ECX High 32 bits of virtual address of caller allocated
133 STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is
134 clear (0), ECX must be zero.
137 No error, EAX set to STM_SUCCESS. The memory range was unmapped
140 An error occurred, EAX holds relevant error value.
141 @retval EAX #ERROR_STM_FUNCTION_NOT_SUPPORTED
142 STM supports EPT and has not implemented StmUnmapAddressRange().
143 @retval EAX #ERROR_STM_UNSPECIFIED
144 An unspecified error occurred.
146 @note All other registers unmodified.
148 #define STM_API_UNMAP_ADDRESS_RANGE 0x00000002
151 STM Unmap Address Range Descriptor for #STM_API_UNMAP_ADDRESS_RANGE VMCALL
154 UINT64 VirtualAddress
;
156 } STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR
;
160 Since the normal OS environment runs with a different set of page tables than
161 the SMM guest, virtual mappings will certainly be different. In order to do a
162 guest virtual to host physical translation of an address from the normal OS
163 code (EIP for example), it is necessary to walk the page tables governing the
164 OS page mappings. Since the SMM guest has no direct access to the page tables,
165 it must ask the STM to do this page table walk. This is supported via the
166 StmAddressLookup VMCALL. All OS page table formats need to be supported,
167 (e.g. PAE, PSE, Intel64, EPT, etc.)
169 StmAddressLookup takes a CR3 value and a virtual address from the interrupted
170 code as input and returns the corresponding physical address. It also
171 optionally maps the physical address into the SMM guest's virtual address
172 space. This new mapping persists ONLY for the duration of the SMI and if
173 needed in subsequent SMIs it must be remapped. PAT cache types follow the
174 interrupted environment's page table.
176 If EPT is enabled, OS CR3 only provides guest physical address information,
177 but the SMM guest might also need to know the host physical address. Since
178 SMM does not have direct access rights to EPT (it is protected by the STM),
179 SMM can input InterruptedEptp to let STM help to walk through it, and output
180 the host physical address.
182 @param EAX #STM_API_ADDRESS_LOOKUP (0x00000003)
183 @param EBX Low 32 bits of virtual address of caller allocated
184 STM_ADDRESS_LOOKUP_DESCRIPTOR structure.
185 @param ECX High 32 bits of virtual address of caller allocated
186 STM_ADDRESS_LOOKUP_DESCRIPTOR structure. If Intel64Mode is
187 clear (0), ECX must be zero.
190 No error, EAX set to STM_SUCCESS. PhysicalAddress contains the
191 host physical address determined by walking the interrupted SMM
192 guest's page tables. SmmGuestVirtualAddress contains the SMM
193 guest's virtual mapping of the requested address.
195 An error occurred, EAX holds relevant error value.
196 @retval EAX #ERROR_STM_SECURITY_VIOLATION
197 The requested page was a protected page.
198 @retval EAX #ERROR_STM_PAGE_NOT_FOUND
199 The requested virtual address did not exist in the page given
201 @retval EAX #ERROR_STM_BAD_CR3
202 The CR3 input was invalid. CR3 values must be from one of the
203 interrupted guest, or from the interrupted guest of another
205 @retval EAX #ERROR_STM_PHYSICAL_OVER_4G
206 The resulting physical address is greater than 4G and no virtual
207 address was supplied. The STM could not determine what address
208 within the SMM guest's virtual address space to do the mapping.
209 STM_ADDRESS_LOOKUP_DESCRIPTOR field PhysicalAddress contains the
210 physical address determined by walking the interrupted
211 environment's page tables.
212 @retval EAX #ERROR_STM_VIRTUAL_SPACE_TOO_SMALL
213 A specific virtual mapping was requested, but
214 SmmGuestVirtualAddress + Length exceeds 4G and the SMI handler
215 is running in 32 bit mode.
216 @retval EAX #ERROR_STM_UNSPECIFIED
217 An unspecified error occurred.
219 @note All other registers unmodified.
221 #define STM_API_ADDRESS_LOOKUP 0x00000003
224 STM Lookup Address Range Descriptor for #STM_API_ADDRESS_LOOKUP VMCALL
227 UINT64 InterruptedGuestVirtualAddress
;
229 UINT64 InterruptedCr3
;
230 UINT64 InterruptedEptp
;
231 UINT32 MapToSmmGuest
:2;
232 UINT32 InterruptedCr4Pae
:1;
233 UINT32 InterruptedCr4Pse
:1;
234 UINT32 InterruptedIa32eMode
:1;
237 UINT64 PhysicalAddress
;
238 UINT64 SmmGuestVirtualAddress
;
239 } STM_ADDRESS_LOOKUP_DESCRIPTOR
;
242 Define values for the MapToSmmGuest field of #STM_ADDRESS_LOOKUP_DESCRIPTOR
245 #define STM_ADDRESS_LOOKUP_DESCRIPTOR_DO_NOT_MAP 0
246 #define STM_ADDRESS_LOOKUP_DESCRIPTOR_ONE_TO_ONE 1
247 #define STM_ADDRESS_LOOKUP_DESCRIPTOR_VIRTUAL_ADDRESS_SPECIFIED 3
252 When returning from a protection exception (see section 6.2), the SMM guest
253 can instruct the STM to take one of two paths. It can either request a value
254 be logged to the TXT.ERRORCODE register and subsequently reset the machine
255 (indicating it couldn't resolve the problem), or it can request that the STM
256 resume the SMM guest again with the specified register state.
258 Unlike other VMCALL interfaces, StmReturnFromProtectionException behaves more
259 like a jump or an IRET instruction than a "call". It does not return directly
260 to the caller, but indirectly to a different location specified on the
261 caller's stack (see section 6.2) or not at all.
263 If the SMM guest STM protection exception handler itself causes a protection
264 exception (e.g. a single nested exception), or more than 100 un-nested
265 exceptions occur within the scope of a single SMI event, the STM must write
266 STM_CRASH_PROTECTION_EXCEPTION_FAILURE to the TXT.ERRORCODE register and
267 assert TXT.CMD.SYS_RESET. The reason for these restrictions is to simplify
268 the code requirements while still enabling a reasonable debugging capability.
270 @param EAX #STM_API_RETURN_FROM_PROTECTION_EXCEPTION (0x00000004)
271 @param EBX If 0, resume SMM guest using register state found on exception
272 stack. If in range 0x01..0x0F, EBX contains a BIOS error code
273 which the STM must record in the TXT.ERRORCODE register and
274 subsequently reset the system via TXT.CMD.SYS_RESET. The value
275 of the TXT.ERRORCODE register is calculated as follows:
277 TXT.ERRORCODE = (EBX & 0x0F) | STM_CRASH_BIOS_PANIC
279 Values 0x10..0xFFFFFFFF are reserved, do not use.
282 #define STM_API_RETURN_FROM_PROTECTION_EXCEPTION 0x00000004
287 API number convention: MLE facing VMCALL interfaces have bit 16 set.
289 The STM configuration lifecycle is as follows:
290 1. SENTER->SINIT->MLE: MLE begins execution with SMI disabled (masked).
291 2. MLE invokes #STM_API_INITIALIZE_PROTECTION VMCALL to prepare STM for
292 setup of initial protection profile. This is done on a single CPU and
294 3. MLE invokes #STM_API_PROTECT_RESOURCE VMCALL to define the initial
295 protection profile. The protection profile is global across all CPUs.
296 4. MLE invokes #STM_API_START VMCALL to enable the STM to begin receiving
297 SMI events. This must be done on every logical CPU.
298 5. MLE may invoke #STM_API_PROTECT_RESOURCE VMCALL or
299 #STM_API_UNPROTECT_RESOURCE VMCALL during runtime as many times as
301 6. MLE invokes #STM_API_STOP VMCALL to disable the STM. SMI is again masked
302 following #STM_API_STOP VMCALL.
306 StartStmVmcall() is used to configure an STM that is present in MSEG. SMIs
307 should remain disabled from the invocation of GETSEC[SENTER] until they are
308 re-enabled by StartStmVMCALL(). When StartStmVMCALL() returns, SMI is
309 enabled and the STM has been started and is active. Prior to invoking
310 StartStmVMCALL(), the MLE root should first invoke
311 InitializeProtectionVMCALL() followed by as many iterations of
312 ProtectResourceVMCALL() as necessary to establish the initial protection
313 profile. StartStmVmcall() must be invoked on all processor threads.
315 @param EAX #STM_API_START (0x00010001)
316 @param EDX STM configuration options. These provide the MLE with the
317 ability to pass configuration parameters to the STM.
320 No error, EAX set to STM_SUCCESS. The STM has been configured
321 and is now active and the guarding all requested resources.
323 An error occurred, EAX holds relevant error value.
324 @retval EAX #ERROR_STM_ALREADY_STARTED
325 The STM is already configured and active. STM remains active and
326 guarding previously enabled resource list.
327 @retval EAX #ERROR_STM_WITHOUT_SMX_UNSUPPORTED
328 The StartStmVMCALL() was invoked from VMX root mode, but outside
329 of SMX. This error code indicates the STM or platform does not
330 support the STM outside of SMX. The SMI handler remains active
331 and operates in legacy mode. See Appendix C
332 @retval EAX #ERROR_STM_UNSUPPORTED_MSR_BIT
333 The CPU doesn't support the MSR bit. The STM is not active.
334 @retval EAX #ERROR_STM_UNSPECIFIED
335 An unspecified error occurred.
337 @note All other registers unmodified.
339 #define STM_API_START (BIT16 | 1)
342 Bit values for EDX input parameter to #STM_API_START VMCALL
345 #define STM_CONFIG_SMI_UNBLOCKING_BY_VMX_OFF BIT0
350 The StopStmVMCALL() is invoked by the MLE to teardown an active STM. This is
351 normally done as part of a full teardown of the SMX environment when the
352 system is being shut down. At the time the call is invoked, SMI is enabled
353 and the STM is active. When the call returns, the STM has been stopped and
354 all STM context is discarded and SMI is disabled.
356 @param EAX #STM_API_STOP (0x00010002)
359 No error, EAX set to STM_SUCCESS. The STM has been stopped and
360 is no longer processing SMI events. SMI is blocked.
362 An error occurred, EAX holds relevant error value.
363 @retval EAX #ERROR_STM_STOPPED
364 The STM was not active.
365 @retval EAX #ERROR_STM_UNSPECIFIED
366 An unspecified error occurred.
368 @note All other registers unmodified.
370 #define STM_API_STOP (BIT16 | 2)
374 The ProtectResourceVMCALL() is invoked by the MLE root to request protection
375 of specific resources. The request is defined by a STM_RESOURCE_LIST, which
376 may contain more than one resource descriptor. Each resource descriptor is
377 processed separately by the STM. Whether or not protection for any specific
378 resource is granted is returned by the STM via the ReturnStatus bit in the
379 associated STM_RSC_DESC_HEADER.
381 @param EAX #STM_API_PROTECT_RESOURCE (0x00010003)
382 @param EBX Low 32 bits of physical address of caller allocated
383 STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero,
384 making the buffer 4K aligned.
385 @param ECX High 32 bits of physical address of caller allocated
388 @note All fields of STM_RESOURCE_LIST are inputs only, except for the
389 ReturnStatus bit. On input, the ReturnStatus bit must be clear. On
390 return, the ReturnStatus bit is set for each resource request granted,
391 and clear for each resource request denied. There are no other fields
392 modified by ProtectResourceVMCALL(). The STM_RESOURCE_LIST must be
393 contained entirely within a single 4K page.
396 No error, EAX set to STM_SUCCESS. The STM has successfully
397 merged the entire protection request into the active protection
398 profile. There is therefore no need to check the ReturnStatus
399 bits in the STM_RESOURCE_LIST.
401 An error occurred, EAX holds relevant error value.
402 @retval EAX #ERROR_STM_UNPROTECTABLE_RESOURCE
403 At least one of the requested resource protections intersects a
404 BIOS required resource. Therefore, the caller must walk through
405 the STM_RESOURCE_LIST to determine which of the requested
406 resources was not granted protection. The entire list must be
407 traversed since there may be multiple failures.
408 @retval EAX #ERROR_STM_MALFORMED_RESOURCE_LIST
409 The resource list could not be parsed correctly, or did not
410 terminate before crossing a 4K page boundary. The caller must
411 walk through the STM_RESOURCE_LIST to determine which of the
412 requested resources was not granted protection. The entire list
413 must be traversed since there may be multiple failures.
414 @retval EAX #ERROR_STM_OUT_OF_RESOURCES
415 The STM has encountered an internal error and cannot complete
417 @retval EAX #ERROR_STM_UNSPECIFIED
418 An unspecified error occurred.
420 @note All other registers unmodified.
422 #define STM_API_PROTECT_RESOURCE (BIT16 | 3)
426 The UnProtectResourceVMCALL() is invoked by the MLE root to request that the
427 STM allow the SMI handler access to the specified resources.
429 @param EAX #STM_API_UNPROTECT_RESOURCE (0x00010004)
430 @param EBX Low 32 bits of physical address of caller allocated
431 STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero,
432 making the buffer 4K aligned.
433 @param ECX High 32 bits of physical address of caller allocated
436 @note All fields of STM_RESOURCE_LIST are inputs only, except for the
437 ReturnStatus bit. On input, the ReturnStatus bit must be clear. On
438 return, the ReturnStatus bit is set for each resource processed. For
439 a properly formed STM_RESOURCE_LIST, this should be all resources
440 listed. There are no other fields modified by
441 UnProtectResourceVMCALL(). The STM_RESOURCE_LIST must be contained
442 entirely within a single 4K page.
445 No error, EAX set to STM_SUCCESS. The requested resources are
446 not being guarded by the STM.
448 An error occurred, EAX holds relevant error value.
449 @retval EAX #ERROR_STM_MALFORMED_RESOURCE_LIST
450 The resource list could not be parsed correctly, or did not
451 terminate before crossing a 4K page boundary. The caller must
452 walk through the STM_RESOURCE_LIST to determine which of the
453 requested resources were not able to be unprotected. The entire
454 list must be traversed since there may be multiple failures.
455 @retval EAX #ERROR_STM_UNSPECIFIED
456 An unspecified error occurred.
458 @note All other registers unmodified.
460 #define STM_API_UNPROTECT_RESOURCE (BIT16 | 4)
464 The GetBiosResourcesVMCALL() is invoked by the MLE root to request the list
465 of BIOS required resources from the STM.
467 @param EAX #STM_API_GET_BIOS_RESOURCES (0x00010005)
468 @param EBX Low 32 bits of physical address of caller allocated destination
469 buffer. Bits 11:0 are ignored and assumed to be zero, making the
471 @param ECX High 32 bits of physical address of caller allocated destination
473 @param EDX Indicates which page of the BIOS resource list to copy into the
474 destination buffer. The first page is indicated by 0, the second
478 No error, EAX set to STM_SUCCESS. The destination buffer
479 contains the BIOS required resources. If the page retrieved is
480 the last page, EDX will be cleared to 0. If there are more pages
481 to retrieve, EDX is incremented to the next page index. Calling
482 software should iterate on GetBiosResourcesVMCALL() until EDX is
483 returned cleared to 0.
485 An error occurred, EAX holds relevant error value.
486 @retval EAX #ERROR_STM_PAGE_NOT_FOUND
487 The page index supplied in EDX input was out of range.
488 @retval EAX #ERROR_STM_UNSPECIFIED
489 An unspecified error occurred.
490 @retval EDX Page index of next page to read. A return of EDX=0 signifies
491 that the entire list has been read.
492 @note EDX is both an input and an output register.
494 @note All other registers unmodified.
496 #define STM_API_GET_BIOS_RESOURCES (BIT16 | 5)
500 The ManageVmcsDatabaseVMCALL() is invoked by the MLE root to add or remove an
501 MLE guest (including the MLE root) from the list of protected domains.
503 @param EAX #STM_API_MANAGE_VMCS_DATABASE (0x00010006)
504 @param EBX Low 32 bits of physical address of caller allocated
505 STM_VMCS_DATABASE_REQUEST. Bits 11:0 are ignored and assumed to
506 be zero, making the buffer 4K aligned.
507 @param ECX High 32 bits of physical address of caller allocated
508 STM_VMCS_DATABASE_REQUEST.
510 @note All fields of STM_VMCS_DATABASE_REQUEST are inputs only. They are not
511 modified by ManageVmcsDatabaseVMCALL().
514 No error, EAX set to STM_SUCCESS.
516 An error occurred, EAX holds relevant error value.
517 @retval EAX #ERROR_STM_INVALID_VMCS
518 Indicates a request to remove a VMCS from the database was made,
519 but the referenced VMCS was not found in the database.
520 @retval EAX #ERROR_STM_VMCS_PRESENT
521 Indicates a request to add a VMCS to the database was made, but
522 the referenced VMCS was already present in the database.
523 @retval EAX #ERROR_INVALID_PARAMETER
524 Indicates non-zero reserved field.
525 @retval EAX #ERROR_STM_UNSPECIFIED
526 An unspecified error occurred
528 @note All other registers unmodified.
530 #define STM_API_MANAGE_VMCS_DATABASE (BIT16 | 6)
533 STM VMCS Database Request for #STM_API_MANAGE_VMCS_DATABASE VMCALL
537 /// bits 11:0 are reserved and must be 0
539 UINT64 VmcsPhysPointer
;
540 UINT32 DomainType
:4;
541 UINT32 XStatePolicy
:2;
542 UINT32 DegradationPolicy
:4;
546 UINT32 Reserved1
:22;
548 } STM_VMCS_DATABASE_REQUEST
;
551 Values for the DomainType field of #STM_VMCS_DATABASE_REQUEST
554 #define DOMAIN_UNPROTECTED 0
555 #define DOMAIN_DISALLOWED_IO_OUT BIT0
556 #define DOMAIN_DISALLOWED_IO_IN BIT1
557 #define DOMAIN_INTEGRITY BIT2
558 #define DOMAIN_CONFIDENTIALITY BIT3
559 #define DOMAIN_INTEGRITY_PROT_OUT_IN (DOMAIN_INTEGRITY)
560 #define DOMAIN_FULLY_PROT_OUT_IN (DOMAIN_CONFIDENTIALITY | DOMAIN_INTEGRITY)
561 #define DOMAIN_FULLY_PROT (DOMAIN_FULLY_PROT_OUT_IN | DOMAIN_DISALLOWED_IO_IN | DOMAIN_DISALLOWED_IO_OUT)
565 Values for the XStatePolicy field of #STM_VMCS_DATABASE_REQUEST
568 #define XSTATE_READWRITE 0x00
569 #define XSTATE_READONLY 0x01
570 #define XSTATE_SCRUB 0x03
574 Values for the AddOrRemove field of #STM_VMCS_DATABASE_REQUEST
577 #define STM_VMCS_DATABASE_REQUEST_ADD 1
578 #define STM_VMCS_DATABASE_REQUEST_REMOVE 0
583 InitializeProtectionVMCALL() prepares the STM for setup of the initial
584 protection profile which is subsequently communicated via one or more
585 invocations of ProtectResourceVMCALL(), prior to invoking StartStmVMCALL().
586 It is only necessary to invoke InitializeProtectionVMCALL() on one processor
587 thread. InitializeProtectionVMCALL() does not alter whether SMIs are masked
588 or unmasked. The STM should return back to the MLE with "Blocking by SMI" set
589 to 1 in the GUEST_INTERRUPTIBILITY field for the VMCS the STM created for the
592 @param EAX #STM_API_INITIALIZE_PROTECTION (0x00010007)
595 No error, EAX set to STM_SUCCESS, EBX bits set to indicate STM
596 capabilities as defined below. The STM has set up an empty
597 protection profile, except for the resources that it sets up to
598 protect itself. The STM must not allow the SMI handler to map
599 any pages from the MSEG Base to the top of TSEG. The STM must
600 also not allow SMI handler access to those MSRs which the STM
601 requires for its own protection.
603 An error occurred, EAX holds relevant error value.
604 @retval EAX #ERROR_STM_ALREADY_STARTED
605 The STM is already configured and active. The STM remains active
606 and guarding the previously enabled resource list.
607 @retval EAX #ERROR_STM_UNPROTECTABLE
608 The STM determines that based on the platform configuration, the
609 STM is unable to protect itself. For example, the BIOS required
610 resource list contains memory pages in MSEG.
611 @retval EAX #ERROR_STM_UNSPECIFIED
612 An unspecified error occurred.
614 @note All other registers unmodified.
616 #define STM_API_INITIALIZE_PROTECTION (BIT16 | 7)
619 Byte granular support bits returned in EBX from #STM_API_INITIALIZE_PROTECTION
622 #define STM_RSC_BGI BIT1
623 #define STM_RSC_BGM BIT2
624 #define STM_RSC_MSR BIT3
629 The ManageEventLogVMCALL() is invoked by the MLE root to control the logging
630 feature. It consists of several sub-functions to facilitate establishment of
631 the log itself, configuring what events will be logged, and functions to
632 start, stop, and clear the log.
634 @param EAX #STM_API_MANAGE_EVENT_LOG (0x00010008)
635 @param EBX Low 32 bits of physical address of caller allocated
636 STM_EVENT_LOG_MANAGEMENT_REQUEST. Bits 11:0 are ignored and
637 assumed to be zero, making the buffer 4K aligned.
638 @param ECX High 32 bits of physical address of caller allocated
639 STM_EVENT_LOG_MANAGEMENT_REQUEST.
642 No error, EAX set to STM_SUCCESS.
644 An error occurred, EAX holds relevant error value. See subfunction
645 descriptions below for details.
647 @note All other registers unmodified.
649 #define STM_API_MANAGE_EVENT_LOG (BIT16 | 8)
652 /// STM Event Log Management Request for #STM_API_MANAGE_EVENT_LOG VMCALL
655 UINT32 SubFunctionIndex
;
660 // number of elements is PageCount
665 // bitmap of EVENT_TYPE
667 UINT32 EventEnableBitmap
;
669 } STM_EVENT_LOG_MANAGEMENT_REQUEST
;
672 Defines values for the SubFunctionIndex field of
673 #STM_EVENT_LOG_MANAGEMENT_REQUEST
676 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_NEW_LOG 1
677 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_CONFIGURE_LOG 2
678 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_START_LOG 3
679 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_STOP_LOG 4
680 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_CLEAR_LOG 5
681 #define STM_EVENT_LOG_MANAGEMENT_REQUEST_DELETE_LOG 6
688 UINT32 EventSerialNumber
;
698 Enum values for the Type field of #LOG_ENTRY_HEADER
703 EvtLogInvalidParameterDetected
,
704 EvtHandledProtectionException
,
706 /// unhandled protection exceptions result in reset & cannot be logged
708 EvtBiosAccessToUnclaimedResource
,
709 EvtMleResourceProtectionGranted
,
710 EvtMleResourceProtectionDenied
,
711 EvtMleResourceUnprotect
,
712 EvtMleResourceUnprotectError
,
713 EvtMleDomainTypeDegraded
,
721 EvtInvalid
= 0xFFFFFFFF,
726 } ENTRY_EVT_LOG_STARTED
;
730 } ENTRY_EVT_LOG_STOPPED
;
733 UINT32 VmcallApiNumber
;
734 } ENTRY_EVT_LOG_INVALID_PARAM
;
738 } ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION
;
742 } ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC
;
746 } ENTRY_EVT_MLE_RSC_PROT_GRANTED
;
750 } ENTRY_EVT_MLE_RSC_PROT_DENIED
;
754 } ENTRY_EVT_MLE_RSC_UNPROT
;
758 } ENTRY_EVT_MLE_RSC_UNPROT_ERROR
;
761 UINT64 VmcsPhysPointer
;
762 UINT8 ExpectedDomainType
;
763 UINT8 DegradedDomainType
;
764 } ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED
;
767 ENTRY_EVT_LOG_STARTED Started
;
768 ENTRY_EVT_LOG_STOPPED Stopped
;
769 ENTRY_EVT_LOG_INVALID_PARAM InvalidParam
;
770 ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION HandledProtectionException
;
771 ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC BiosUnclaimedRsc
;
772 ENTRY_EVT_MLE_RSC_PROT_GRANTED MleRscProtGranted
;
773 ENTRY_EVT_MLE_RSC_PROT_DENIED MleRscProtDenied
;
774 ENTRY_EVT_MLE_RSC_UNPROT MleRscUnprot
;
775 ENTRY_EVT_MLE_RSC_UNPROT_ERROR MleRscUnprotError
;
776 ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED MleDomainTypeDegraded
;
780 LOG_ENTRY_HEADER Hdr
;
785 Maximum STM Log Entry Size
787 #define STM_LOG_ENTRY_SIZE 256
791 STM Protection Exception Stack Frame Structures
805 UINT32 VmcsExitInstructionInfo
;
806 UINT32 VmcsExitInstructionLength
;
807 UINT64 VmcsExitQualification
;
809 /// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value
817 } STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32
;
839 UINT64 VmcsExitInstructionInfo
;
840 UINT64 VmcsExitInstructionLength
;
841 UINT64 VmcsExitQualification
;
843 /// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value
851 } STM_PROTECTION_EXCEPTION_STACK_FRAME_X64
;
854 STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32
*Ia32StackFrame
;
855 STM_PROTECTION_EXCEPTION_STACK_FRAME_X64
*X64StackFrame
;
856 } STM_PROTECTION_EXCEPTION_STACK_FRAME
;
859 Enum values for the ErrorCode field in
860 #STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32 and
861 #STM_PROTECTION_EXCEPTION_STACK_FRAME_X64
864 TxtSmmPageViolation
= 1,
866 TxtSmmRegisterViolation
,
869 } TXT_SMM_PROTECTION_EXCEPTION_TYPE
;
872 TXT Pocessor SMM Descriptor (PSD) structures
879 UINT16 PageViolationException
:1;
880 UINT16 MsrViolationException
:1;
881 UINT16 RegisterViolationException
:1;
882 UINT16 IoViolationException
:1;
883 UINT16 PciViolationException
:1;
886 } STM_PROTECTION_EXCEPTION_HANDLER
;
889 UINT8 ExecutionDisableOutsideSmrr
:1;
894 } STM_SMM_ENTRY_STATE
;
897 UINT8 SmramToVmcsRestoreRequired
: 1; ///> BIOS restore hint
898 UINT8 ReinitializeVmcsRequired
: 1; ///> BIOS request
900 } STM_SMM_RESUME_STATE
;
903 UINT8 DomainType
: 4; ///> STM input to BIOS on each SMI
904 UINT8 XStatePolicy
: 2; ///> STM input to BIOS on each SMI
905 UINT8 EptEnabled
: 1;
909 #define TXT_SMM_PSD_OFFSET 0xfb00
910 #define TXT_PROCESSOR_SMM_DESCRIPTOR_SIGNATURE SIGNATURE_64('T', 'X', 'T', 'P', 'S', 'S', 'I', 'G')
911 #define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MAJOR 1
912 #define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MINOR 0
917 UINT8 SmmDescriptorVerMajor
;
918 UINT8 SmmDescriptorVerMinor
;
920 STM_SMM_ENTRY_STATE SmmEntryState
;
921 STM_SMM_RESUME_STATE SmmResumeState
;
922 STM_SMM_STATE StmSmmState
;
927 UINT16 SmmOtherSegment
;
931 UINT64 SmmStmSetupRip
;
932 UINT64 SmmStmTeardownRip
;
933 UINT64 SmmSmiHandlerRip
;
934 UINT64 SmmSmiHandlerRsp
;
937 UINT32 RequiredStmSmmRevId
;
938 STM_PROTECTION_EXCEPTION_HANDLER StmProtectionExceptionHandler
;
940 UINT64 BiosHwResourceRequirementsPtr
;
943 UINT8 PhysicalAddressBits
;
944 } TXT_PROCESSOR_SMM_DESCRIPTOR
;