# IGVM Image

The Independent Guest Virtual Machine (IGVM) format describes the initial state of an isolated virtual machine. OpenHCL is delivered as an IGVM image.

> **Note:** For more details on the IGVM specification, see the [IGVM repository](https://github.com/microsoft/igvm).

## Purpose

The IGVM file serves as the "firmware image" for the OpenHCL paravisor. It allows the host VMM to:

1. Load the OpenHCL components into VTL2 memory.
2. Place them at specific, required physical addresses in. (Components are loaded in a well-defined order to ensure that measurements are reproducable).
3. Pass initial configuration data to the paravisor.

## IGVM Image Contents

An OpenHCL IGVM image bundles the following artifacts:

- **Boot Shim (`openhcl_boot`):** The entry point for VTL2 execution.
- **Linux Kernel:** The operating system kernel.
- **Sidecar Kernel (x86_64):** The lightweight kernel for APs.
- **Initial Ramdisk (initrd):** The root filesystem containing userspace binaries (`underhill_init`, `openvmm_hcl`, etc.).
- **Memory Layout:** Directives specifying where each component should be loaded in memory.
- **Measurements:** Information that the underlying platform uses to confirm that the file was loaded correctly and signed by the appropriate authorities.
- **Configuration:** Boot-time parameters. This includes the data that is known at build time (and measured), and data that is not known until the VM is started (e.g. CPU topology, device settings, etc.). See [`ParavisorMeasuredVtl0Config`](https://openvmm.dev/rustdoc/linux/loader_defs/paravisor/struct.ParavisorMeasuredVtl0Config.html) and [`ParavisorMeasuredVtl2Config`](https://openvmm.dev/rustdoc/linux/loader_defs/paravisor/struct.ParavisorMeasuredVtl2Config.html) for examples of data known at build time.

## Build Process

The IGVM artifact is generated by the OpenHCL build system.
See [Building OpenHCL](../../../dev_guide/getting_started/build_openhcl.md) for instructions on how to build it.
