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.
§Fixed Header
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§
- Device tree (DT) specific information related to IGVM.
Structs§
- The version 1 fixed header that is at the start of every IGVM file.
- IGVM_FIXED_HEADER_V2
unstable
The version 2 fixed header that is at the start of every IGVM file with format_version >= 2. - 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.
- This structure defines the guest policy that is isolation architecture dependent.
- The structure deposited by the loader for memory map entries for
IgvmVariableHeaderType::IGVM_VHT_MEMORY_MAP
that describe memory available to the guest. - A structure describing memory via a range of pages.
- The format used to describe the MMIO ranges of the guest for a
IgvmVariableHeaderType::IGVM_VHT_MMIO_RANGES
parameter. - This structure describes a page of data that should be loaded into the guest address space.
- 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. - 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
. - 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
. - This structure controls the insertion of a parameter area into the guest address space.
- 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.
- 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.
- This structure describes the AMD SEV-SNP ID block.
- Public key for SNP ID block. See the corresponding PSP definitions.
- Signature for SNP ID block. See the corresponding PSP definitions.
- 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. - The header describing each structure in the variable header section. Headers are aligned to 8 byte boundaries.
- This structure describes a VBS measurement to be used with Hyper-V’s VBS isolation architecture.
- This structure defines architecture specific that should be loaded into the guest address space to represent an initial VP context.
- IgvmArchitecture
unstable
The architecture described by the fixed header. - IgvmEnvironmentInfo
unstable
Default memory state described by the IGVM_VHT_MEMORY_STATE_PARAMETER parameter. - IgvmNativeVpContextX64
unstable
Format ofIGVM_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. - Flags for
IGVM_VHS_PAGE_DATA
structures. - Page data types that describe the type of import for
IGVM_VHS_PAGE_DATA
. cbindgen:prefix-with-name=true cbindgen:rename-all=ScreamingSnakeCase - Enum describing different isolation platforms for
IGVM_VHS_SUPPORTED_PLATFORM
structures. cbindgen:prefix-with-name=true cbindgen:rename-all=ScreamingSnakeCase - The type of each structure in the variable header section.
- The type of memory described by a memory map entry or device tree node. cbindgen:prefix-with-name=true cbindgen:rename-all=ScreamingSnakeCase
- Flags for
IGVM_VHS_REQUIRED_MEMORY
. - The AMD SEV-SNP Guest policy used in
IGVM_VHS_GUEST_POLICY::policy
. - The Intel TDX policy used in
IGVM_VHS_GUEST_POLICY::policy
. - The signature algorithm to use for VBS digest.
- The signature algorithm to use for VBS measurement.
- Format of VBS
IGVM_VHS_VP_CONTEXT
file data. - The registers associated with a VBS
IGVM_VHS_VP_CONTEXT
structure in the file data section.
Constants§
- IGVM format version 1.
- IGVM_FORMAT_VERSION_2
unstable
IGVM format version 2. This is work-in-progress and not stabilized. - The magic value of
0x4D564749
that must be present in theIGVM_FIXED_HEADER
. This is ASCIIIGVM
in little-endian. - Platform version for
IgvmPlatformType::NATIVE
. - IGVM_SEV_ES_PLATFORM_VERSION
unstable
Platform version forIgvmPlatformType::SEV_ES
. - IGVM_SEV_PLATFORM_VERSION
unstable
Platform version forIgvmPlatformType::SEV
. - Platform version for
IgvmPlatformType::SEV_SNP
. - Platform version for
IgvmPlatformType::TDX
. - GDTR for the specified VP and VTL should be adjusted by the amount this region was relocated. This is supported on X64 only.
- 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).
- Legacy name for [‘IGVM_VHF_RELOCATABLE_REGION_APPLY_PC’]
- This region describes VTL2.
- The range of header types for directive structures.
- The range of header types for initialization structures.
- The range of header types for platform structures.
- Platform version for
IgvmPlatformType::VSM_ISOLATION
. - A page size of 4K (4096) bytes.