1Independent Guest Virtual Machine (IGVM) support 2================================================ 3 4IGVM files are designed to encapsulate all the information required to launch a 5virtual machine on any given virtualization stack in a deterministic way. This 6allows the cryptographic measurement of initial guest state for Confidential 7Guests to be calculated when the IGVM file is built, allowing a relying party to 8verify the initial state of a guest via a remote attestation. 9 10Although IGVM files are designed with Confidential Computing in mind, they can 11also be used to configure non-confidential guests. Multiple platforms can be 12defined by a single IGVM file, allowing a single IGVM file to configure a 13virtual machine that can run on, for example, TDX, SEV and non-confidential 14hosts. 15 16QEMU supports IGVM files through the user-creatable ``igvm-cfg`` object. This 17object is used to define the filename of the IGVM file to process. A reference 18to the object is added to the ``-machine`` to configure the virtual machine 19to use the IGVM file for configuration. 20 21Confidential platform support is provided through the use of 22the ``ConfidentialGuestSupport`` object. If the virtual machine provides an 23instance of this object then this is used by the IGVM loader to configure the 24isolation properties of the directives within the file. 25 26Further Information on IGVM 27--------------------------- 28 29Information about the IGVM format, including links to the format specification 30and documentation for the Rust and C libraries can be found at the project 31repository: 32 33https://github.com/microsoft/igvm 34 35 36Supported Platforms 37------------------- 38 39Currently, IGVM files can be provided for Confidential Guests on host systems 40that support AMD SEV, SEV-ES and SEV-SNP with KVM. IGVM files can also be 41provided for non-confidential guests. 42 43 44Limitations when using IGVM with AMD SEV, SEV-ES and SEV-SNP 45------------------------------------------------------------ 46 47IGVM files configure the initial state of the guest using a set of directives. 48Not every directive is supported by every Confidential Guest type. For example, 49AMD SEV does not support encrypted save state regions, therefore setting the 50initial CPU state using IGVM for SEV is not possible. When an IGVM file contains 51directives that are not supported for the active platform, an error is generated 52and the guest launch is aborted. 53 54The table below describes the list of directives that are supported for SEV, 55SEV-ES, SEV-SNP and non-confidential platforms. 56 57.. list-table:: SEV, SEV-ES, SEV-SNP & non-confidential Supported Directives 58 :widths: 35 65 59 :header-rows: 1 60 61 * - IGVM directive 62 - Notes 63 * - IGVM_VHT_PAGE_DATA 64 - ``NORMAL`` zero, measured and unmeasured page types are supported. Other 65 page types result in an error. 66 * - IGVM_VHT_PARAMETER_AREA 67 - 68 * - IGVM_VHT_PARAMETER_INSERT 69 - 70 * - IGVM_VHT_VP_COUNT_PARAMETER 71 - The guest parameter page is populated with the CPU count. 72 * - IGVM_VHT_ENVIRONMENT_INFO_PARAMETER 73 - The ``memory_is_shared`` parameter is set to 1 in the guest parameter 74 page. 75 76.. list-table:: Additional SEV, SEV-ES & SEV_SNP Supported Directives 77 :widths: 25 75 78 :header-rows: 1 79 80 * - IGVM directive 81 - Notes 82 * - IGVM_VHT_MEMORY_MAP 83 - The memory map page is populated using entries from the E820 table. 84 * - IGVM_VHT_REQUIRED_MEMORY 85 - Ensures memory is available in the guest at the specified range. 86 87.. list-table:: Additional SEV-ES & SEV-SNP Supported Directives 88 :widths: 25 75 89 :header-rows: 1 90 91 * - IGVM directive 92 - Notes 93 * - IGVM_VHT_VP_CONTEXT 94 - Setting of the initial CPU state for the boot CPU and additional CPUs is 95 supported with limitations on the fields that can be provided in the 96 VMSA. See below for details on which fields are supported. 97 98Initial CPU state with VMSA 99--------------------------- 100 101The initial state of guest CPUs can be defined in the IGVM file for AMD SEV-ES 102and SEV-SNP. The state data is provided as a VMSA structure as defined in Table 103B-4 in the AMD64 Architecture Programmer's Manual, Volume 2 [1]. 104 105The IGVM VMSA is translated to CPU state in QEMU which is then synchronized 106by KVM to the guest VMSA during the launch process where it contributes to the 107launch measurement. See :ref:`amd-sev` for details on the launch process and 108guest launch measurement. 109 110It is important that no information is lost or changed when translating the 111VMSA provided by the IGVM file into the VSMA that is used to launch the guest. 112Therefore, QEMU restricts the VMSA fields that can be provided in the IGVM 113VMSA structure to the following registers: 114 115RAX, RCX, RDX, RBX, RBP, RSI, RDI, R8-R15, RSP, RIP, CS, DS, ES, FS, GS, SS, 116CR0, CR3, CR4, XCR0, EFER, PAT, GDT, IDT, LDTR, TR, DR6, DR7, RFLAGS, X87_FCW, 117MXCSR. 118 119When processing the IGVM file, QEMU will check if any fields other than the 120above are non-zero and generate an error if this is the case. 121 122KVM uses a hardcoded GPA of 0xFFFFFFFFF000 for the VMSA. When an IGVM file 123defines initial CPU state, the GPA for each VMSA must match this hardcoded 124value. 125 126Firmware Images with IGVM 127------------------------- 128 129When an IGVM filename is specified for a Confidential Guest Support object it 130overrides the default handling of system firmware: the firmware image, such as 131an OVMF binary should be contained as a payload of the IGVM file and not 132provided as a flash drive or via the ``-bios`` parameter. The default QEMU 133firmware is not automatically populated into the guest memory space. 134 135If an IGVM file is provided along with either the ``-bios`` parameter or pflash 136devices then an error is displayed and the guest startup is aborted. 137 138Running a guest configured using IGVM 139------------------------------------- 140 141To run a guest configured with IGVM you firstly need to generate an IGVM file 142that contains a guest configuration compatible with the platform you are 143targeting. 144 145The ``buildigvm`` tool [2] is an example of a tool that can be used to generate 146IGVM files for non-confidential X86 platforms as well as for SEV, SEV-ES and 147SEV-SNP confidential platforms. 148 149Example using this tool to generate an IGVM file for AMD SEV-SNP:: 150 151 buildigvm --firmware /path/to/OVMF.fd --output sev-snp.igvm \ 152 --cpucount 4 sev-snp 153 154To run a guest configured with the generated IGVM you need to add an 155``igvm-cfg`` object and refer to it from the ``-machine`` parameter: 156 157Example (for AMD SEV):: 158 159 qemu-system-x86_64 \ 160 <other parameters> \ 161 -machine ...,confidential-guest-support=sev0,igvm-cfg=igvm0 \ 162 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \ 163 -object igvm-cfg,id=igvm0,file=/path/to/sev-snp.igvm 164 165References 166---------- 167 168[1] AMD64 Architecture Programmer's Manual, Volume 2: System Programming 169 Rev 3.41 170 https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf 171 172[2] ``buildigvm`` - A tool to build example IGVM files containing OVMF firmware 173 https://github.com/roy-hopkins/buildigvm