Crate igvm_defs

Expand description

This crate provides the definitions for the Independent Guest Virtual Machine (IGVM) file format.

The IGVM file format is designed to encapsulate all information required to launch a virtual machine on any given virtualization stack, with support for different isolation technologies such as AMD SEV-SNP and Intel TDX.

At a conceptual level, this file format is a set of commands created by the tool that generated the file, used by the loader to construct the initial guest state. The file format also contains measurement information that the underlying platform will use to confirm that the file was loaded correctly and signed by the appropriate authorities.

This crate is available as no_std.

§Structure

An IGVM file consists of three regions: the fixed header, the variable header, and file data.

The endianness of the IGVM file and any byte contents is little endian.

FUTURE: Include sample valid file, expected behavior, and table images.

The fixed header is defined by the IGVM_FIXED_HEADER structure. This structure is always at the start of the file.

Note: Version 2 and future versions of the file format will use the IGVM_FIXED_HEADER_V2

§Version 2 work-in-progress

Version 2 supports specifying the architecture along with page size referred to by the file.

Version 2 definitions can be used via the unstable feature.

§Variable Header

The variable header is a list of different TLV (Type, Length, Value) data structures. Each structure is prefaced by a 32-bit type field and a 32-bit length field as described by the IGVM_VHS_VARIABLE_HEADER, and the content of each structure is determined by its type. The high bit of the type field indicates whether the structure can be ignored by a loader that does not support the structure type; if it is clear and the loader does not support the type, then the file cannot be loaded.

Each variable header structure must be fully contained within the size of the variable header described in the fixed header. The length field of each variable header structure describes only the content within the structure, and not the 8 bytes of type/length information. Each variable header structure must begin at a file offset that is a multiple of 8 bytes, so the length field of any structure must be rounded up to 8 bytes to find the type/length information of the following structure. The padding used to align each variable header to 8 byte alignments must be zero.

Variable headers can be divided into three different sections, platform, initialization, directives. Platform types define the compatibility masks and supported platforms for the file, initialization defines the early data needed by individual hardware platforms to prepare the guest partition to accept data, and directives are the actual commands for the loader to load data into the guest from the file and runtime parameters.

Variable headers must not appear in a later section after making a section transition. Loaders make a state transition from platform to initialization headers once the first initialization header type is read. The same applies for the transition from initialization to directives. For example, once the first initialization header is read, it is no longer valid for the file to specify any additional platform headers.

Types are defined by IgvmVariableHeaderType.

Except for a few specific structure types, each structure indicates to the loader that the data specified by the structure should be added to the guest immediately, in order to reach the same end measurement as specified by the file.

§File Data

The file data has no specific structure. Portions of the file data are consumed through references made from the header structures.

§Revisions

Version 2 of the specification is currently a work in progress. Those definitions can be enabled with the unstable feature.

Modules§

dt: Device tree (DT) specific information related to IGVM.

Structs§

IGVM_FIXED_HEADER: The version 1 fixed header that is at the start of every IGVM file.
IGVM_FIXED_HEADER_V2unstable: The version 2 fixed header that is at the start of every IGVM file with format_version >= 2.
IGVM_VHS_ERROR_RANGE: This structure describes a range in the GPA space of the guest that will be reserved for reporting errors to the host. Therefore, the memory described by this structure will also be marked as accessible by the host for the lifetime of the VM.
IGVM_VHS_GUEST_POLICY: This structure defines the guest policy that is isolation architecture dependent.
IGVM_VHS_MEMORY_MAP_ENTRY: The structure deposited by the loader for memory map entries for IgvmVariableHeaderType::IGVM_VHT_MEMORY_MAP that describe memory available to the guest.
IGVM_VHS_MEMORY_RANGE: A structure describing memory via a range of pages.
IGVM_VHS_MMIO_RANGES: The format used to describe the MMIO ranges of the guest for a IgvmVariableHeaderType::IGVM_VHT_MMIO_RANGES parameter.
IGVM_VHS_PAGE_DATA: This structure describes a page of data that should be loaded into the guest address space.
IGVM_VHS_PAGE_TABLE_RELOCATION: Indicate the region of memory containing the page table which can be relocated. This region must contain the root page table (CR3 on x64, TTBR0 on arm64). Page table pages that are described that lay outside of this region will not be walked nor fixed up. Page tables cannot lie within other relocatable regions. Similar to IGVM_VHS_RELOCATABLE_REGION, the loader must guarantee memory is present for the whole region described by this header.
IGVM_VHS_PARAMETER: The common parameter structure used by different parameter types to indicate to the loader which parameter area and what offset to deposit the specified runtime info. See corresponding parameter types in IgvmVariableHeaderType.
IGVM_VHS_PARAMETER_AREA: This structure defines a region of memory that can be used for holding parameters to be passed into the guest. Parameter areas are created with this structure, then parameters may be imported via parameter structures that define the byte offset to deposit the given parameter into a given parameter area by parameter_area_index.
IGVM_VHS_PARAMETER_INSERT: This structure controls the insertion of a parameter area into the guest address space.
IGVM_VHS_RELOCATABLE_REGION: Indicate a relocatable region. This region may be relocated according to the fields within the header. The region must be relocated as a whole, with each gpa within the region described being relocated by the same amount. Other directive headers that specify gpas must be relocated by the amount the region was relocated.
IGVM_VHS_REQUIRED_MEMORY: This structure describes memory the IGVM file expects to be present in the guest. This is a hint to the loader that the guest will not function without memory present at the specified range, and should terminate the load process if memory is not present.
IGVM_VHS_SNP_ID_BLOCK: This structure describes the AMD SEV-SNP ID block.
IGVM_VHS_SNP_ID_BLOCK_PUBLIC_KEY: Public key for SNP ID block. See the corresponding PSP definitions.
IGVM_VHS_SNP_ID_BLOCK_SIGNATURE: Signature for SNP ID block. See the corresponding PSP definitions.
IGVM_VHS_SUPPORTED_PLATFORM: This structure indicates which isolation platforms are compatible with this guest image. A separate IGVM_VHS_SUPPORTED_PLATFORM structure must be used for each compatible platform.
IGVM_VHS_VARIABLE_HEADER: The header describing each structure in the variable header section. Headers are aligned to 8 byte boundaries.
IGVM_VHS_VBS_MEASUREMENT: This structure describes a VBS measurement to be used with Hyper-V’s VBS isolation architecture.
IGVM_VHS_VP_CONTEXT: This structure defines architecture specific that should be loaded into the guest address space to represent an initial VP context.
IgvmArchitectureunstable: The architecture described by the fixed header.
IgvmEnvironmentInfounstable: Default memory state described by the IGVM_VHT_MEMORY_STATE_PARAMETER parameter.
IgvmNativeVpContextX64unstable: Format of IGVM_VHS_VP_CONTEXT file data for a native x86-64 image or for x86_64 isolation platforms that do not support measurement of the initial context, such as AMD SEV. Registers not specified here are initialized to their architectural reset values.
IgvmPageDataFlags: Flags for IGVM_VHS_PAGE_DATA structures.
IgvmPageDataType: Page data types that describe the type of import for IGVM_VHS_PAGE_DATA. cbindgen:prefix-with-name=true cbindgen:rename-all=ScreamingSnakeCase
IgvmPlatformType: Enum describing different isolation platforms for IGVM_VHS_SUPPORTED_PLATFORM structures. cbindgen:prefix-with-name=true cbindgen:rename-all=ScreamingSnakeCase
IgvmVariableHeaderType: The type of each structure in the variable header section.
MemoryMapEntryType: The type of memory described by a memory map entry or device tree node. cbindgen:prefix-with-name=true cbindgen:rename-all=ScreamingSnakeCase
RequiredMemoryFlags: Flags for IGVM_VHS_REQUIRED_MEMORY.
SnpPolicy: The AMD SEV-SNP Guest policy used in IGVM_VHS_GUEST_POLICY::policy.
TdxPolicy: The Intel TDX policy used in IGVM_VHS_GUEST_POLICY::policy.
VbsDigestAlgorithm: The signature algorithm to use for VBS digest.
VbsSigningAlgorithm: The signature algorithm to use for VBS measurement.
VbsVpContextHeader: Format of VBS IGVM_VHS_VP_CONTEXT file data.
VbsVpContextRegister: The registers associated with a VBS IGVM_VHS_VP_CONTEXT structure in the file data section.

Constants§

IGVM_FORMAT_VERSION_1: IGVM format version 1.
IGVM_FORMAT_VERSION_2unstable: IGVM format version 2. This is work-in-progress and not stabilized.
IGVM_MAGIC_VALUE: The magic value of 0x4D564749 that must be present in the IGVM_FIXED_HEADER. This is ASCII IGVM in little-endian.
IGVM_NATIVE_PLATFORM_VERSION: Platform version for IgvmPlatformType::NATIVE.
IGVM_SEV_ES_PLATFORM_VERSIONunstable: Platform version for IgvmPlatformType::SEV_ES.
IGVM_SEV_PLATFORM_VERSIONunstable: Platform version for IgvmPlatformType::SEV.
IGVM_SEV_SNP_PLATFORM_VERSION: Platform version for IgvmPlatformType::SEV_SNP.
IGVM_TDX_PLATFORM_VERSION: Platform version for IgvmPlatformType::TDX.
IGVM_VHF_RELOCATABLE_REGION_APPLY_GDTR: GDTR for the specified VP and VTL should be adjusted by the amount this region was relocated. This is supported on X64 only.
IGVM_VHF_RELOCATABLE_REGION_APPLY_PC: The starting executable address for the specified VP and VTL should be adjusted by the amount this region was relocated (RIP on x64, PC on arm64).
IGVM_VHF_RELOCATABLE_REGION_APPLY_RIP: Legacy name for [‘IGVM_VHF_RELOCATABLE_REGION_APPLY_PC’]
IGVM_VHF_RELOCATABLE_REGION_IS_VTL2: This region describes VTL2.
IGVM_VHT_RANGE_DIRECTIVE: The range of header types for directive structures.
IGVM_VHT_RANGE_INIT: The range of header types for initialization structures.
IGVM_VHT_RANGE_PLATFORM: The range of header types for platform structures.
IGVM_VSM_ISOLATION_PLATFORM_VERSION: Platform version for IgvmPlatformType::VSM_ISOLATION.
PAGE_SIZE_4K: A page size of 4K (4096) bytes.

Crate igvm_defsCopy item path