Crate igvm_defs

source ·
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§

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

Structs§

Constants§