path: root/src/vendorcode/intel/edk2/edk2-stable202005/MdePkg/Include/Register/Intel/StmApi.h

/** @file
  STM API definition

  Copyright (c) 2015 - 2019, Intel Corporation. All rights reserved.<BR>
  SPDX-License-Identifier: BSD-2-Clause-Patent

  @par Specification Reference:
  SMI Transfer Monitor (STM) User Guide Revision 1.00

**/

#ifndef _INTEL_STM_API_H_
#define _INTEL_STM_API_H_

#include <Register/Intel/StmStatusCode.h>
#include <Register/Intel/StmResourceDescriptor.h>
#include <Register/Intel/ArchitecturalMsr.h>

#pragma pack (1)

/**
  STM Header Structures
**/

typedef struct {
  UINT32  Intel64ModeSupported :1;  ///> bitfield
  UINT32  EptSupported         :1;  ///> bitfield
  UINT32  Reserved             :30; ///> must be 0
} STM_FEAT;

#define STM_SPEC_VERSION_MAJOR  1
#define STM_SPEC_VERSION_MINOR  0

typedef struct {
  UINT8     StmSpecVerMajor;
  UINT8     StmSpecVerMinor;
  ///
  /// Must be zero
  ///
  UINT16    Reserved;
  UINT32    StaticImageSize;
  UINT32    PerProcDynamicMemorySize;
  UINT32    AdditionalDynamicMemorySize;
  STM_FEAT  StmFeatures;
  UINT32    NumberOfRevIDs;
  UINT32    StmSmmRevID[1];
  ///
  /// The total STM_HEADER should be 4K.
  ///
} SOFTWARE_STM_HEADER;

typedef struct {
  MSEG_HEADER          HwStmHdr;
  SOFTWARE_STM_HEADER  SwStmHdr;
} STM_HEADER;


/**
  VMCALL API Numbers
  API number convention: BIOS facing VMCALL interfaces have bit 16 clear
**/

/**
  StmMapAddressRange enables a SMM guest to create a non-1:1 virtual to
  physical mapping of an address range into the SMM guest's virtual
  memory space.

  @param  EAX  #STM_API_MAP_ADDRESS_RANGE (0x00000001)
  @param  EBX  Low 32 bits of physical address of caller allocated
               STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure.
  @param  ECX  High 32 bits of physical address of caller allocated
               STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is
               clear (0), ECX must be 0.

  @note  All fields of STM_MAP_ADDRESS_RANGE_DESCRIPTOR are inputs only. They
         are not modified by StmMapAddressRange.

  @retval  CF   0
                No error, EAX set to STM_SUCCESS.
                The memory range was mapped as requested.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_SECURITY_VIOLATION
                The requested mapping contains a protected resource.
  @retval  EAX  #ERROR_STM_CACHE_TYPE_NOT_SUPPORTED
                The requested cache type could not be satisfied.
  @retval  EAX  #ERROR_STM_PAGE_NOT_FOUND
                Page count must not be zero.
  @retval  EAX  #ERROR_STM_FUNCTION_NOT_SUPPORTED
                STM supports EPT and has not implemented StmMapAddressRange().
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_MAP_ADDRESS_RANGE                  0x00000001

/**
  STM Map Address Range Descriptor for #STM_API_MAP_ADDRESS_RANGE VMCALL
**/
typedef struct {
  UINT64  PhysicalAddress;
  UINT64  VirtualAddress;
  UINT32  PageCount;
  UINT32  PatCacheType;
} STM_MAP_ADDRESS_RANGE_DESCRIPTOR;

/**
  Define values for PatCacheType field of #STM_MAP_ADDRESS_RANGE_DESCRIPTOR
  @{
**/
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_ST_UC        0x00
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WC           0x01
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WT           0x04
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WP           0x05
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WB           0x06
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_UC           0x07
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_FOLLOW_MTRR  0xFFFFFFFF
/// @}

/**
  StmUnmapAddressRange enables a SMM guest to remove mappings from its page
  table.

  If TXT_PROCESSOR_SMM_DESCRIPTOR.EptEnabled bit is set by the STM, BIOS can
  control its own page tables. In this case, the STM implementation may
  optionally return ERROR_STM_FUNCTION_NOT_SUPPORTED.

  @param  EAX  #STM_API_UNMAP_ADDRESS_RANGE (0x00000002)
  @param  EBX  Low 32 bits of virtual address of caller allocated
               STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure.
  @param  ECX  High 32 bits of virtual address of caller allocated
               STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is
               clear (0), ECX must be zero.

  @retval  CF   0
                No error, EAX set to STM_SUCCESS. The memory range was unmapped
                as requested.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_FUNCTION_NOT_SUPPORTED
                STM supports EPT and has not implemented StmUnmapAddressRange().
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_UNMAP_ADDRESS_RANGE                0x00000002

/**
  STM Unmap Address Range Descriptor for #STM_API_UNMAP_ADDRESS_RANGE VMCALL
**/
typedef struct {
  UINT64  VirtualAddress;
  UINT32  Length;
} STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR;


/**
  Since the normal OS environment runs with a different set of page tables than
  the SMM guest, virtual mappings will certainly be different. In order to do a
  guest virtual to host physical translation of an address from the normal OS
  code (EIP for example), it is necessary to walk the page tables governing the
  OS page mappings. Since the SMM guest has no direct access to the page tables,
  it must ask the STM to do this page table walk. This is supported via the
  StmAddressLookup VMCALL. All OS page table formats need to be supported,
  (e.g. PAE, PSE, Intel64, EPT, etc.)

  StmAddressLookup takes a CR3 value and a virtual address from the interrupted
  code as input and returns the corresponding physical address. It also
  optionally maps the physical address into the SMM guest's virtual address
  space. This new mapping persists ONLY for the duration of the SMI and if
  needed in subsequent SMIs it must be remapped. PAT cache types follow the
  interrupted environment's page table.

  If EPT is enabled, OS CR3 only provides guest physical address information,
  but the SMM guest might also need to know the host physical address. Since
  SMM does not have direct access rights to EPT (it is protected by the STM),
  SMM can input InterruptedEptp to let STM help to walk through it, and output
  the host physical address.

  @param  EAX  #STM_API_ADDRESS_LOOKUP (0x00000003)
  @param  EBX  Low 32 bits of virtual address of caller allocated
               STM_ADDRESS_LOOKUP_DESCRIPTOR structure.
  @param  ECX  High 32 bits of virtual address of caller allocated
               STM_ADDRESS_LOOKUP_DESCRIPTOR structure. If Intel64Mode is
               clear (0), ECX must be zero.

  @retval  CF   0
                No error, EAX set to STM_SUCCESS.  PhysicalAddress contains the
                host physical address determined by walking the interrupted SMM
                guest's page tables.  SmmGuestVirtualAddress contains the SMM
                guest's virtual mapping of the requested address.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_SECURITY_VIOLATION
                The requested page was a protected page.
  @retval  EAX  #ERROR_STM_PAGE_NOT_FOUND
                The requested virtual address did not exist in the page given
                page table.
  @retval  EAX  #ERROR_STM_BAD_CR3
                The CR3 input was invalid. CR3 values must be from one of the
                interrupted guest, or from the interrupted guest of another
                processor.
  @retval  EAX  #ERROR_STM_PHYSICAL_OVER_4G
                The resulting physical address is greater than 4G and no virtual
                address was supplied. The STM could not determine what address
                within the SMM guest's virtual address space to do the mapping.
                STM_ADDRESS_LOOKUP_DESCRIPTOR field PhysicalAddress contains the
                physical address determined by walking the interrupted
                environment's page tables.
  @retval  EAX  #ERROR_STM_VIRTUAL_SPACE_TOO_SMALL
                A specific virtual mapping was requested, but
                SmmGuestVirtualAddress + Length exceeds 4G and the SMI handler
                is running in 32 bit mode.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_ADDRESS_LOOKUP                     0x00000003

/**
  STM Lookup Address Range Descriptor for #STM_API_ADDRESS_LOOKUP VMCALL
**/
typedef struct {
  UINT64  InterruptedGuestVirtualAddress;
  UINT32  Length;
  UINT64  InterruptedCr3;
  UINT64  InterruptedEptp;
  UINT32  MapToSmmGuest:2;
  UINT32  InterruptedCr4Pae:1;
  UINT32  InterruptedCr4Pse:1;
  UINT32  InterruptedIa32eMode:1;
  UINT32  Reserved1:27;
  UINT32  Reserved2;
  UINT64  PhysicalAddress;
  UINT64  SmmGuestVirtualAddress;
} STM_ADDRESS_LOOKUP_DESCRIPTOR;

/**
  Define values for the MapToSmmGuest field of #STM_ADDRESS_LOOKUP_DESCRIPTOR
  @{
**/
#define STM_ADDRESS_LOOKUP_DESCRIPTOR_DO_NOT_MAP                 0
#define STM_ADDRESS_LOOKUP_DESCRIPTOR_ONE_TO_ONE                 1
#define STM_ADDRESS_LOOKUP_DESCRIPTOR_VIRTUAL_ADDRESS_SPECIFIED  3
/// @}


/**
  When returning from a protection exception (see section 6.2), the SMM guest
  can instruct the STM to take one of two paths. It can either request a value
  be logged to the TXT.ERRORCODE register and subsequently reset the machine
  (indicating it couldn't resolve the problem), or it can request that the STM
  resume the SMM guest again with the specified register state.

  Unlike other VMCALL interfaces, StmReturnFromProtectionException behaves more
  like a jump or an IRET instruction than a "call". It does not return directly
  to the caller, but indirectly to a different location specified on the
  caller's stack (see section 6.2) or not at all.

  If the SMM guest STM protection exception handler itself causes a protection
  exception (e.g. a single nested exception), or more than 100 un-nested
  exceptions occur within the scope of a single SMI event, the STM must write
  STM_CRASH_PROTECTION_EXCEPTION_FAILURE to the TXT.ERRORCODE register and
  assert TXT.CMD.SYS_RESET. The reason for these restrictions is to simplify
  the code requirements while still enabling a reasonable debugging capability.

  @param  EAX  #STM_API_RETURN_FROM_PROTECTION_EXCEPTION (0x00000004)
  @param  EBX  If 0, resume SMM guest using register state found on exception
               stack.  If in range 0x01..0x0F, EBX contains a BIOS error code
               which the STM must record in the TXT.ERRORCODE register and
               subsequently reset the system via TXT.CMD.SYS_RESET. The value
               of the TXT.ERRORCODE register is calculated as follows:

                 TXT.ERRORCODE = (EBX & 0x0F) | STM_CRASH_BIOS_PANIC

               Values 0x10..0xFFFFFFFF are reserved, do not use.

**/
#define STM_API_RETURN_FROM_PROTECTION_EXCEPTION   0x00000004


/**
  VMCALL API Numbers
  API number convention: MLE facing VMCALL interfaces have bit 16 set.

  The STM configuration lifecycle is as follows:
    1. SENTER->SINIT->MLE: MLE begins execution with SMI disabled (masked).
    2. MLE invokes #STM_API_INITIALIZE_PROTECTION VMCALL to prepare STM for
       setup of initial protection profile. This is done on a single CPU and
       has global effect.
    3. MLE invokes #STM_API_PROTECT_RESOURCE VMCALL to define the initial
       protection profile. The protection profile is global across all CPUs.
    4. MLE invokes #STM_API_START VMCALL to enable the STM to begin receiving
       SMI events. This must be done on every logical CPU.
    5. MLE may invoke #STM_API_PROTECT_RESOURCE VMCALL or
       #STM_API_UNPROTECT_RESOURCE VMCALL during runtime as many times as
       necessary.
    6. MLE invokes #STM_API_STOP VMCALL to disable the STM. SMI is again masked
       following #STM_API_STOP VMCALL.
**/

/**
  StartStmVmcall() is used to configure an STM that is present in MSEG. SMIs
  should remain disabled from the invocation of GETSEC[SENTER] until they are
  re-enabled by StartStmVMCALL(). When StartStmVMCALL() returns, SMI is
  enabled and the STM has been started and is active. Prior to invoking
  StartStmVMCALL(), the MLE root should first invoke
  InitializeProtectionVMCALL() followed by as many iterations of
  ProtectResourceVMCALL() as necessary to establish the initial protection
  profile.  StartStmVmcall() must be invoked on all processor threads.

  @param  EAX  #STM_API_START (0x00010001)
  @param  EDX  STM configuration options. These provide the MLE with the
               ability to pass configuration parameters to the STM.

  @retval  CF   0
                No error, EAX set to STM_SUCCESS. The STM has been configured
                and is now active and the guarding all requested resources.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_ALREADY_STARTED
                The STM is already configured and active. STM remains active and
                guarding previously enabled resource list.
  @retval  EAX  #ERROR_STM_WITHOUT_SMX_UNSUPPORTED
                The StartStmVMCALL() was invoked from VMX root mode, but outside
                of SMX. This error code indicates the STM or platform does not
                support the STM outside of SMX. The SMI handler remains active
                and operates in legacy mode. See Appendix C
  @retval  EAX  #ERROR_STM_UNSUPPORTED_MSR_BIT
                The CPU doesn't support the MSR bit. The STM is not active.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_START                              (BIT16 | 1)

/**
  Bit values for EDX input parameter to #STM_API_START VMCALL
  @{
**/
#define STM_CONFIG_SMI_UNBLOCKING_BY_VMX_OFF  BIT0
/// @}


/**
  The StopStmVMCALL() is invoked by the MLE to teardown an active STM. This is
  normally done as part of a full teardown of the SMX environment when the
  system is being shut down. At the time the call is invoked, SMI is enabled
  and the STM is active.  When the call returns, the STM has been stopped and
  all STM context is discarded and SMI is disabled.

  @param  EAX  #STM_API_STOP (0x00010002)

  @retval  CF   0
                No error, EAX set to STM_SUCCESS. The STM has been stopped and
                is no longer processing SMI events. SMI is blocked.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_STOPPED
                The STM was not active.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_STOP                               (BIT16 | 2)


/**
  The ProtectResourceVMCALL() is invoked by the MLE root to request protection
  of specific resources. The request is defined by a STM_RESOURCE_LIST, which
  may contain more than one resource descriptor. Each resource descriptor is
  processed separately by the STM. Whether or not protection for any specific
  resource is granted is returned by the STM via the ReturnStatus bit in the
  associated STM_RSC_DESC_HEADER.

  @param  EAX  #STM_API_PROTECT_RESOURCE (0x00010003)
  @param  EBX  Low 32 bits of physical address of caller allocated
               STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero,
               making the buffer 4K aligned.
  @param  ECX  High 32 bits of physical address of caller allocated
               STM_RESOURCE_LIST.

  @note  All fields of STM_RESOURCE_LIST are inputs only, except for the
         ReturnStatus bit. On input, the ReturnStatus bit must be clear. On
         return, the ReturnStatus bit is set for each resource request granted,
         and clear for each resource request denied. There are no other fields
         modified by ProtectResourceVMCALL(). The STM_RESOURCE_LIST must be
         contained entirely within a single 4K page.

  @retval  CF   0
                No error, EAX set to STM_SUCCESS. The STM has successfully
                merged the entire protection request into the active protection
                profile.  There is therefore no need to check the ReturnStatus
                bits in the STM_RESOURCE_LIST.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_UNPROTECTABLE_RESOURCE
                At least one of the requested resource protections intersects a
                BIOS required resource. Therefore, the caller must walk through
                the STM_RESOURCE_LIST to determine which of the requested
                resources was not granted protection. The entire list must be
                traversed since there may be multiple failures.
  @retval  EAX  #ERROR_STM_MALFORMED_RESOURCE_LIST
                The resource list could not be parsed correctly, or did not
                terminate before crossing a 4K page boundary. The caller must
                walk through the STM_RESOURCE_LIST to determine which of the
                requested resources was not granted protection. The entire list
                must be traversed since there may be multiple failures.
  @retval  EAX  #ERROR_STM_OUT_OF_RESOURCES
                The STM has encountered an internal error and cannot complete
                the request.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_PROTECT_RESOURCE                   (BIT16 | 3)


/**
  The UnProtectResourceVMCALL() is invoked by the MLE root to request that the
  STM allow the SMI handler access to the specified resources.

  @param  EAX  #STM_API_UNPROTECT_RESOURCE (0x00010004)
  @param  EBX  Low 32 bits of physical address of caller allocated
               STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero,
               making the buffer 4K aligned.
  @param  ECX  High 32 bits of physical address of caller allocated
               STM_RESOURCE_LIST.

  @note  All fields of STM_RESOURCE_LIST are inputs only, except for the
         ReturnStatus bit. On input, the ReturnStatus bit must be clear. On
         return, the ReturnStatus bit is set for each resource processed. For
         a properly formed STM_RESOURCE_LIST, this should be all resources
         listed. There are no other fields modified by
         UnProtectResourceVMCALL(). The STM_RESOURCE_LIST must be contained
         entirely within a single 4K page.

  @retval  CF   0
                No error, EAX set to STM_SUCCESS. The requested resources are
                not being guarded by the STM.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_MALFORMED_RESOURCE_LIST
                The resource list could not be parsed correctly, or did not
                terminate before crossing a 4K page boundary. The caller must
                walk through the STM_RESOURCE_LIST to determine which of the
                requested resources were not able to be unprotected. The entire
                list must be traversed since there may be multiple failures.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_UNPROTECT_RESOURCE                 (BIT16 | 4)


/**
  The GetBiosResourcesVMCALL() is invoked by the MLE root to request the list
  of BIOS required resources from the STM.

  @param  EAX  #STM_API_GET_BIOS_RESOURCES (0x00010005)
  @param  EBX  Low 32 bits of physical address of caller allocated destination
               buffer. Bits 11:0 are ignored and assumed to be zero, making the
               buffer 4K aligned.
  @param  ECX  High 32 bits of physical address of caller allocated destination
               buffer.
  @param  EDX  Indicates which page of the BIOS resource list to copy into the
               destination buffer. The first page is indicated by 0, the second
               page by 1, etc.

  @retval  CF   0
                No error, EAX set to STM_SUCCESS. The destination buffer
                contains the BIOS required resources. If the page retrieved is
                the last page, EDX will be cleared to 0. If there are more pages
                to retrieve, EDX is incremented to the next page index. Calling
                software should iterate on GetBiosResourcesVMCALL() until EDX is
                returned cleared to 0.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_PAGE_NOT_FOUND
                The page index supplied in EDX input was out of range.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.
  @retval  EDX  Page index of next page to read. A return of EDX=0 signifies
                that the entire list has been read.
                @note  EDX is both an input and an output register.

  @note  All other registers unmodified.
**/
#define STM_API_GET_BIOS_RESOURCES                 (BIT16 | 5)


/**
  The ManageVmcsDatabaseVMCALL() is invoked by the MLE root to add or remove an
  MLE guest (including the MLE root) from the list of protected domains.

  @param  EAX  #STM_API_MANAGE_VMCS_DATABASE (0x00010006)
  @param  EBX  Low 32 bits of physical address of caller allocated
               STM_VMCS_DATABASE_REQUEST. Bits 11:0 are ignored and assumed to
               be zero, making the buffer 4K aligned.
  @param  ECX  High 32 bits of physical address of caller allocated
               STM_VMCS_DATABASE_REQUEST.

  @note  All fields of STM_VMCS_DATABASE_REQUEST are inputs only.  They are not
         modified by ManageVmcsDatabaseVMCALL().

  @retval  CF   0
                No error, EAX set to STM_SUCCESS.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_INVALID_VMCS
                Indicates a request to remove a VMCS from the database was made,
                but the referenced VMCS was not found in the database.
  @retval  EAX  #ERROR_STM_VMCS_PRESENT
                Indicates a request to add a VMCS to the database was made, but
                the referenced VMCS was already present in the database.
  @retval  EAX  #ERROR_INVALID_PARAMETER
                Indicates non-zero reserved field.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred

  @note  All other registers unmodified.
**/
#define STM_API_MANAGE_VMCS_DATABASE               (BIT16 | 6)

/**
  STM VMCS Database Request for #STM_API_MANAGE_VMCS_DATABASE VMCALL
**/
typedef struct {
  ///
  /// bits 11:0 are reserved and must be 0
  ///
  UINT64  VmcsPhysPointer;
  UINT32  DomainType :4;
  UINT32  XStatePolicy :2;
  UINT32  DegradationPolicy :4;
  ///
  /// Must be 0
  ///
  UINT32  Reserved1 :22;
  UINT32  AddOrRemove;
} STM_VMCS_DATABASE_REQUEST;

/**
  Values for the DomainType field of #STM_VMCS_DATABASE_REQUEST
  @{
**/
#define DOMAIN_UNPROTECTED            0
#define DOMAIN_DISALLOWED_IO_OUT      BIT0
#define DOMAIN_DISALLOWED_IO_IN       BIT1
#define DOMAIN_INTEGRITY              BIT2
#define DOMAIN_CONFIDENTIALITY        BIT3
#define DOMAIN_INTEGRITY_PROT_OUT_IN  (DOMAIN_INTEGRITY)
#define DOMAIN_FULLY_PROT_OUT_IN      (DOMAIN_CONFIDENTIALITY | DOMAIN_INTEGRITY)
#define DOMAIN_FULLY_PROT             (DOMAIN_FULLY_PROT_OUT_IN | DOMAIN_DISALLOWED_IO_IN | DOMAIN_DISALLOWED_IO_OUT)
/// @}

/**
  Values for the XStatePolicy field of #STM_VMCS_DATABASE_REQUEST
  @{
**/
#define XSTATE_READWRITE  0x00
#define XSTATE_READONLY   0x01
#define XSTATE_SCRUB      0x03
/// @}

/**
  Values for the AddOrRemove field of #STM_VMCS_DATABASE_REQUEST
  @{
**/
#define STM_VMCS_DATABASE_REQUEST_ADD     1
#define STM_VMCS_DATABASE_REQUEST_REMOVE  0
/// @}


/**
  InitializeProtectionVMCALL() prepares the STM for setup of the initial
  protection profile which is subsequently communicated via one or more
  invocations of ProtectResourceVMCALL(), prior to invoking StartStmVMCALL().
  It is only necessary to invoke InitializeProtectionVMCALL() on one processor
  thread.  InitializeProtectionVMCALL() does not alter whether SMIs are masked
  or unmasked. The STM should return back to the MLE with "Blocking by SMI" set
  to 1 in the GUEST_INTERRUPTIBILITY field for the VMCS the STM created for the
  MLE guest.

  @param  EAX  #STM_API_INITIALIZE_PROTECTION (0x00010007)

  @retval  CF   0
                No error, EAX set to STM_SUCCESS, EBX bits set to indicate STM
                capabilities as defined below. The STM has set up an empty
                protection profile, except for the resources that it sets up to
                protect itself. The STM must not allow the SMI handler to map
                any pages from the MSEG Base to the top of TSEG. The STM must
                also not allow SMI handler access to those MSRs which the STM
                requires for its own protection.
  @retval  CF   1
                An error occurred, EAX holds relevant error value.
  @retval  EAX  #ERROR_STM_ALREADY_STARTED
                The STM is already configured and active. The STM remains active
                and guarding the previously enabled resource list.
  @retval  EAX  #ERROR_STM_UNPROTECTABLE
                The STM determines that based on the platform configuration, the
                STM is unable to protect itself. For example, the BIOS required
                resource list contains memory pages in MSEG.
  @retval  EAX  #ERROR_STM_UNSPECIFIED
                An unspecified error occurred.

  @note  All other registers unmodified.
**/
#define STM_API_INITIALIZE_PROTECTION              (BIT16 | 7)

/**
  Byte granular support bits returned in EBX from #STM_API_INITIALIZE_PROTECTION
  @{
**/
#define STM_RSC_BGI  BIT1
#define STM_RSC_BGM  BIT2
#define STM_RSC_MSR  BIT3
/// @}


/**
  The ManageEventLogVMCALL() is invoked by the MLE root to control the logging
  feature. It consists of several sub-functions to facilitate establishment of
  the log itself, configuring what events will be logged, and functions to
  start, stop, and clear the log.

  @param  EAX  #STM_API_MANAGE_EVENT_LOG (0x00010008)
  @param  EBX  Low 32 bits of physical address of caller allocated
               STM_EVENT_LOG_MANAGEMENT_REQUEST. Bits 11:0 are ignored and
               assumed to be zero, making the buffer 4K aligned.
  @param  ECX  High 32 bits of physical address of caller allocated
               STM_EVENT_LOG_MANAGEMENT_REQUEST.

  @retval  CF=0
           No error, EAX set to STM_SUCCESS.
  @retval  CF=1
           An error occurred, EAX holds relevant error value. See subfunction
           descriptions below for details.

  @note  All other registers unmodified.
**/
#define STM_API_MANAGE_EVENT_LOG                   (BIT16 | 8)

///
/// STM Event Log Management Request for #STM_API_MANAGE_EVENT_LOG VMCALL
///
typedef struct {
  UINT32      SubFunctionIndex;
  union {
    struct {
      UINT32  PageCount;
      //
      // number of elements is PageCount
      //
      UINT64  Pages[];
    } LogBuffer;
    //
    // bitmap of EVENT_TYPE
    //
    UINT32    EventEnableBitmap;
  } Data;
} STM_EVENT_LOG_MANAGEMENT_REQUEST;

/**
  Defines values for the SubFunctionIndex field of
  #STM_EVENT_LOG_MANAGEMENT_REQUEST
  @{
**/
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_NEW_LOG        1
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_CONFIGURE_LOG  2
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_START_LOG      3
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_STOP_LOG       4
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_CLEAR_LOG      5
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_DELETE_LOG     6
/// @}

/**
  Log Entry Header
**/
typedef struct {
  UINT32  EventSerialNumber;
  UINT16  Type;
  UINT16  Lock :1;
  UINT16  Valid :1;
  UINT16  ReadByMle :1;
  UINT16  Wrapped :1;
  UINT16  Reserved :12;
} LOG_ENTRY_HEADER;

/**
  Enum values for the Type field of #LOG_ENTRY_HEADER
**/
typedef enum {
  EvtLogStarted,
  EvtLogStopped,
  EvtLogInvalidParameterDetected,
  EvtHandledProtectionException,
  ///
  /// unhandled protection exceptions result in reset & cannot be logged
  ///
  EvtBiosAccessToUnclaimedResource,
  EvtMleResourceProtectionGranted,
  EvtMleResourceProtectionDenied,
  EvtMleResourceUnprotect,
  EvtMleResourceUnprotectError,
  EvtMleDomainTypeDegraded,
  ///
  /// add more here
  ///
  EvtMleMax,
  ///
  /// Not used
  ///
  EvtInvalid = 0xFFFFFFFF,
} EVENT_TYPE;

typedef struct {
  UINT32  Reserved;
} ENTRY_EVT_LOG_STARTED;

typedef struct {
  UINT32  Reserved;
} ENTRY_EVT_LOG_STOPPED;

typedef struct {
  UINT32  VmcallApiNumber;
} ENTRY_EVT_LOG_INVALID_PARAM;

typedef struct {
  STM_RSC  Resource;
} ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION;

typedef struct {
  STM_RSC  Resource;
} ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC;

typedef struct {
  STM_RSC  Resource;
} ENTRY_EVT_MLE_RSC_PROT_GRANTED;

typedef struct {
  STM_RSC  Resource;
} ENTRY_EVT_MLE_RSC_PROT_DENIED;

typedef struct {
  STM_RSC  Resource;
} ENTRY_EVT_MLE_RSC_UNPROT;

typedef struct {
  STM_RSC  Resource;
} ENTRY_EVT_MLE_RSC_UNPROT_ERROR;

typedef struct {
  UINT64  VmcsPhysPointer;
  UINT8   ExpectedDomainType;
  UINT8   DegradedDomainType;
} ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED;

typedef union {
  ENTRY_EVT_LOG_STARTED                       Started;
  ENTRY_EVT_LOG_STOPPED                       Stopped;
  ENTRY_EVT_LOG_INVALID_PARAM                 InvalidParam;
  ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION  HandledProtectionException;
  ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC         BiosUnclaimedRsc;
  ENTRY_EVT_MLE_RSC_PROT_GRANTED              MleRscProtGranted;
  ENTRY_EVT_MLE_RSC_PROT_DENIED               MleRscProtDenied;
  ENTRY_EVT_MLE_RSC_UNPROT                    MleRscUnprot;
  ENTRY_EVT_MLE_RSC_UNPROT_ERROR              MleRscUnprotError;
  ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED          MleDomainTypeDegraded;
} LOG_ENTRY_DATA;

typedef struct {
  LOG_ENTRY_HEADER  Hdr;
  LOG_ENTRY_DATA    Data;
} STM_LOG_ENTRY;

/**
  Maximum STM Log Entry Size
**/
#define STM_LOG_ENTRY_SIZE  256


/**
  STM Protection Exception Stack Frame Structures
**/

typedef struct {
  UINT32  Rdi;
  UINT32  Rsi;
  UINT32  Rbp;
  UINT32  Rdx;
  UINT32  Rcx;
  UINT32  Rbx;
  UINT32  Rax;
  UINT32  Cr3;
  UINT32  Cr2;
  UINT32  Cr0;
  UINT32  VmcsExitInstructionInfo;
  UINT32  VmcsExitInstructionLength;
  UINT64  VmcsExitQualification;
  ///
  /// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value
  ///
  UINT32  ErrorCode;
  UINT32  Rip;
  UINT32  Cs;
  UINT32  Rflags;
  UINT32  Rsp;
  UINT32  Ss;
} STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32;

typedef struct {
  UINT64  R15;
  UINT64  R14;
  UINT64  R13;
  UINT64  R12;
  UINT64  R11;
  UINT64  R10;
  UINT64  R9;
  UINT64  R8;
  UINT64  Rdi;
  UINT64  Rsi;
  UINT64  Rbp;
  UINT64  Rdx;
  UINT64  Rcx;
  UINT64  Rbx;
  UINT64  Rax;
  UINT64  Cr8;
  UINT64  Cr3;
  UINT64  Cr2;
  UINT64  Cr0;
  UINT64  VmcsExitInstructionInfo;
  UINT64  VmcsExitInstructionLength;
  UINT64  VmcsExitQualification;
  ///
  /// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value
  ///
  UINT64  ErrorCode;
  UINT64  Rip;
  UINT64  Cs;
  UINT64  Rflags;
  UINT64  Rsp;
  UINT64  Ss;
} STM_PROTECTION_EXCEPTION_STACK_FRAME_X64;

typedef union {
  STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32  *Ia32StackFrame;
  STM_PROTECTION_EXCEPTION_STACK_FRAME_X64   *X64StackFrame;
} STM_PROTECTION_EXCEPTION_STACK_FRAME;

/**
  Enum values for the ErrorCode field in
  #STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32 and
  #STM_PROTECTION_EXCEPTION_STACK_FRAME_X64
**/
typedef enum {
  TxtSmmPageViolation = 1,
  TxtSmmMsrViolation,
  TxtSmmRegisterViolation,
  TxtSmmIoViolation,
  TxtSmmPciViolation
} TXT_SMM_PROTECTION_EXCEPTION_TYPE;

/**
  TXT Pocessor SMM Descriptor (PSD) structures
**/

typedef struct {
  UINT64  SpeRip;
  UINT64  SpeRsp;
  UINT16  SpeSs;
  UINT16  PageViolationException:1;
  UINT16  MsrViolationException:1;
  UINT16  RegisterViolationException:1;
  UINT16  IoViolationException:1;
  UINT16  PciViolationException:1;
  UINT16  Reserved1:11;
  UINT32  Reserved2;
} STM_PROTECTION_EXCEPTION_HANDLER;

typedef struct {
  UINT8  ExecutionDisableOutsideSmrr:1;
  UINT8  Intel64Mode:1;
  UINT8  Cr4Pae : 1;
  UINT8  Cr4Pse : 1;
  UINT8  Reserved1 : 4;
} STM_SMM_ENTRY_STATE;

typedef struct {
  UINT8  SmramToVmcsRestoreRequired : 1; ///> BIOS restore hint
  UINT8  ReinitializeVmcsRequired : 1;   ///> BIOS request
  UINT8  Reserved2 : 6;
} STM_SMM_RESUME_STATE;

typedef struct {
  UINT8  DomainType : 4;   ///> STM input to BIOS on each SMI
  UINT8  XStatePolicy : 2; ///> STM input to BIOS on each SMI
  UINT8  EptEnabled : 1;
  UINT8  Reserved3 : 1;
} STM_SMM_STATE;

#define TXT_SMM_PSD_OFFSET                          0xfb00
#define TXT_PROCESSOR_SMM_DESCRIPTOR_SIGNATURE      SIGNATURE_64('T', 'X', 'T', 'P', 'S', 'S', 'I', 'G')
#define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MAJOR  1
#define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MINOR  0

typedef struct {
  UINT64                            Signature;
  UINT16                            Size;
  UINT8                             SmmDescriptorVerMajor;
  UINT8                             SmmDescriptorVerMinor;
  UINT32                            LocalApicId;
  STM_SMM_ENTRY_STATE               SmmEntryState;
  STM_SMM_RESUME_STATE              SmmResumeState;
  STM_SMM_STATE                     StmSmmState;
  UINT8                             Reserved4;
  UINT16                            SmmCs;
  UINT16                            SmmDs;
  UINT16                            SmmSs;
  UINT16                            SmmOtherSegment;
  UINT16                            SmmTr;
  UINT16                            Reserved5;
  UINT64                            SmmCr3;
  UINT64                            SmmStmSetupRip;
  UINT64                            SmmStmTeardownRip;
  UINT64                            SmmSmiHandlerRip;
  UINT64                            SmmSmiHandlerRsp;
  UINT64                            SmmGdtPtr;
  UINT32                            SmmGdtSize;
  UINT32                            RequiredStmSmmRevId;
  STM_PROTECTION_EXCEPTION_HANDLER  StmProtectionExceptionHandler;
  UINT64                            Reserved6;
  UINT64                            BiosHwResourceRequirementsPtr;
  // extend area
  UINT64                            AcpiRsdp;
  UINT8                             PhysicalAddressBits;
} TXT_PROCESSOR_SMM_DESCRIPTOR;

#pragma pack ()

#endif