@samitouri / QOSamiQemu / commits / 76c16b3c37

docs/spec: Add a specification document for vm-launch-update device

This change adds a specification document and expanation for the vm-launch-update device. CC: Alex Graf <graf@amazon.com> CC: Gerd Hoffman <kraxel@redhat.com> Reviewed-by: Alexander Graf <graf@amazon.com> Signed-off-by: Ani Sinha <anisinha@redhat.com> Message-ID: <20260817142010.80693-9-anisinha@redhat.com> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>

Ani Sinha committed Aug 17, 2026 at 19:50 UTC 76c16b3c37e705218844264e48b3657d14529d23
2 files changed +199
docs/specs/index.rst
+1
@@ -34,6 +34,7 @@ guest hardware that is specific to QEMU.
34 virt-ctlr
35 vmcoreinfo
36 vmgenid
37 + vmlaunchupdate
38 rapl-msr
39 rocker
40 riscv-iommu
docs/specs/vmlaunchupdate.rst new
+198
@@ -0,0 +1,198 @@
1 +.. SPDX-License-Identifier: GPL-2.0-or-later
2 +
3 +VMLAUNCHUPDATE Interface Specification
4 +######################################
5 +
6 +Introduction
7 +************
8 +
9 +``VmLaunchUpdate`` is an extension to ``fw-cfg`` that allows guests to replace
10 +boot state in their virtual machine using IGVM file container. Through a combination
11 +of this ``fw-cfg`` hypervisor interface, an IGVM file containing specific directives
12 +and with hypervisor stack knowledge, guests can deterministically replace the launch
13 +state for guests. This is useful for environments like SEV-SNP where the
14 +launch payload becomes the launch digest. Guests can use vm-launch-update device to
15 +provide a measured, full guest payload (BIOS image, kernel, initramfs, kernel
16 +command line) to the virtual machine which enables them to easily reason about
17 +integrity of the resulting system.
18 +It is also to be noted that this mechanism currently works only when the guest was
19 +already started with an IGVM file defining its initial launch state. Subsequent
20 +guest resets will use the launch state as defined in the guest provided IGVM file,
21 +not the file with which the guest was initially started. If the guest was not started
22 +with IGVM, writing a new bundle through the ``fw-cfg`` interface has no effect.
23 +
24 +For more information, please see the `KVM Forum 2024 presentation <KVMFORUM_>`__
25 +about this work.
26 +
27 +
28 +.. _KVMFORUM: https://www.youtube.com/watch?v=VCMBxU6tAto
29 +
30 +Base Requirements
31 +*****************
32 +
33 +#. **fw-cfg**:
34 + The target system must provide a ``fw-cfg`` interface. For x86 based
35 + environments, this ``fw-cfg`` interface must be accessible through PIO ports
36 + 0x510 and 0x511. The ``fw-cfg`` interface does not need to be announced as part
37 + of system device tables such as DSDT. The ``fw-cfg`` interface must support the
38 + DMA interface. It may only support the DMA interface for write operations.
39 +
40 +#. **IGVM support**:
41 + The hypervisor must provide support for parsing and executing the IGVM file bundle.
42 +
43 +#. **Confidential guests**:
44 + For confidential guests, the hypervisor must support guest reset. Otherwise, the new
45 + boot state provided through IGVM will not be applied.
46 +
47 +The Fw-cfg File
48 +***************
49 +
50 +Guests drive vmlaunchupdate through special ``fw-cfg`` files that control its flow
51 +followed by a standard system reset operation. When the ``vm-launch-update`` device
52 +is available, it provides the following ``fw-cfg`` file:
53 +
54 +* ``etc/vmlaunchupdate`` - It exposes a structure of the following type, all in
55 + little-endian format:
56 +
57 +.. code-block:: c
58 + :linenos:
59 +
60 + typedef struct {
61 + uint16_t version;
62 + uint16_t status;
63 +
64 + uint32_t _padding;
65 +
66 + uint64_t capabilities;
67 + uint64_t control;
68 +
69 + uint64_t fw_image_addr;
70 + uint64_t fw_image_size;
71 +
72 + uint64_t opaque_addr;
73 + uint64_t opaque_size;
74 +
75 + } VMLaunchUpdate;
76 +
77 +
78 +Currently, the ``version`` number (line 2 above) is initialized to the value ``1``.
79 +Only IGVM files are supported at present. The ``capabilities`` (line 7) and ``control`` (line 8) both support
80 +the following single value:
81 +
82 +* ``VM_LAUNCHUPDATE_FORMAT_IGVM``
83 +
84 + This value is used by the hypervisor to indicate that only IGVM container files are supported.
85 + This is set as a part of ``capabilities`` parameter (line 7) in the above structure. This same value
86 + is passed by the guest to the hypervisor in the ``control`` parameter (line 8) in the above structure
87 + to indicate that the guest passed IGVM file in memory to the hypervisor. The starting guest physical
88 + address of the IGVM file in memory is specified in ``fw_image_addr`` and it's length is specified in
89 + ``fw_image_size`` by the guest. If any other value is passed by the guest in the ``control`` parameter,
90 + the write is ignored by the hypervisor.
91 +
92 +Following ``control`` parameters are supported:
93 +
94 +* ``VM_LAUNCHUPDATE_CTL_DISABLE``
95 +
96 + This value is set in the ``control`` parameter by the guest in order to disable this ``fw-cfg``
97 + hypervisor interface from further updating the guest launch state with a new IGVM file.
98 +
99 +* ``VM_LAUNCHUPDATE_CTL_HOST_IGVM``
100 +
101 + This value is set in the ``control`` parameter by the guest in order to send request to the
102 + hypervisor to initialize the guest using the original host provided IGVM file.
103 + It is useful if the guest wanted to update the UKIs present in the ESP and upon
104 + reset, use one of the updated UKIs present there. If the guest passed addresses in memory
105 + where its own IGVM file is loaded (see below) while also setting this control value, the next
106 + reset will load the guest provided IGVM file and a subsequent second reset will restore the original
107 + host IGVM. If the guest did not provide any addresses of its own IGVM (the address values are
108 + cleared) while setting this control parameter, the immediate next guest reset will load the
109 + original host provided IGVM file.
110 +
111 + The combination of the above two ctl interfaces work as
112 + follows:
113 +
114 + A) ``CTL_HOST_IGVM`` = off ``CTL_DISABLE`` = off
115 +
116 + Supplied IGVM file replaces the firmware permanently. Updating the
117 + firmware again is possible.
118 +
119 + B) ``CTL_HOST_IGVM`` = off ``CTL_DISABLE`` = on
120 +
121 + Supplied IGVM file replaces the firmware permanently. Updating the
122 + firmware again is not possible.
123 +
124 + C) ``CTL_HOST_IGVM`` = on ``CTL_DISABLE`` = off
125 +
126 + Supplied IGVM file replaces the firmware for one reset. Resetting
127 + again will switch back to the original firmware. Updating the
128 + firmware again is possible.
129 +
130 + D) ``CTL_HOST_IGVM`` = on ``CTL_DISABLE`` = on
131 +
132 + Supplied IGVM file replaces the firmware for one reset. Resetting
133 + again will switch back to the original firmware. Updating the
134 + firmware again is NOT possible.
135 +
136 +``fw_image_addr`` (line 10) is the base guest physical address of the guest memory where the IGVM file of size
137 +``fw_image_size`` (line 11) is loaded. ``opaque_addr`` (line 13) and ``opaque_size`` (line 14) are used by
138 +the guest for passing data across resets. The contents of this guest memory are preserved across the
139 +reset. For confidential guests, this memory region must come from guest shared unencrypted memory.
140 +
141 +``status`` (line 3) is written by the hypervisor and it indicates the result of the IGVM loading operation.
142 +A success indicates status code 0. Otherwise a non-zero status code indicates failure. The nature of the
143 +failure is indicated by the value of the code.
144 +
145 +Triggering the Launch State Update using IGVM
146 +*********************************************
147 +
148 +To initiate the launch update process, the guest issues a standard system reset
149 +operation through any of the means implemented by the machine model.
150 +
151 +On a write to the ``etc/vmlaunchupdate`` interface, the hypervisor evaluates whether this
152 +hypervisor interface is disabled. If it is, it ignores any writes to this ``fw-cfg`` file
153 +by the guest. No updates to initial launch state is performed.
154 +
155 +If the hypervisor interface is enabled, upon write to the ``etc/vmlaunchupdate`` interface,
156 +the hypervisor parses the IGVM file bundle passed to it in memory, with starting guest physical
157 +address at ``fw_image_addr`` and length ``fw_image_size``. If parsing is successful, it creates
158 +a context handle to the IGVM file. If parsing and context loading is successful and there are no
159 +errors, ``fw_image_addr`` and ``fw_image_size`` are cleared. The guest can check this in order
160 +to determine if the IGVM was successfully parsed and the new context was loaded. If not, the
161 +guest can throw error and abort rebooting to new IGVM boot state. Alternatively, the guest can
162 +also check the ``status`` code from the ``fw-cfg`` file. A status code of 0 indicates success
163 +of the operation. Non-zero status code indicates failure. Exact nature of the failure is
164 +indicated by the value of the code. Currently, only two error values are supported:
165 +
166 +* ``VM_LAUNCHUPDATE_LOAD_FAIL`` - defined as value 1 and is set when loading of the IGVM file failed.
167 +* ``VM_LAUNCHUPDATE_NOT_IGVM_INIT`` - defined as value 2 and is set when the guest was not started with
168 + IGVM file.
169 +
170 +Upon guest reset, the hypervisor executes the IGVM bundle using
171 +the context handle, setting the initial launch state of the guest accordingly.
172 +If an invalid IGVM file is passed, parsing the file fails and the hypervisor ignores it
173 +when ``fw-cfg`` files are written. In this case, the initial launch state
174 +is not modified. If invalid addresses are passed, the hypervisor ignores them as well and no
175 +new launch state is set.
176 +
177 +The launch state update mechanism works both for confidential and non-confidential
178 +guests. In confidential guests, as a part of the reset operation, all existing
179 +guest shared memory (shared with the hypervisor) as well as the guest memory region
180 +starting with ``opaque_addr`` and length ``opaque_size`` are preserved.
181 +The reset causes recreation of the VM context which triggers a fresh
182 +measurement of the replaced BIOS region and reset CPU state.
183 +
184 +For non-confidential guests, there is no concept of guest private memory and all the existing
185 +guest memory is preserved (this is the default behaviour today - QEMU does not reset/clear
186 +guest memory upon reset).
187 +
188 +In both confidential and non-confidential cases, CPU and device state are reset to
189 +the reset states specified in IGVM. In confidential environments, the guest
190 +always resumes operation in the highest privileged mode available to it (VMPL0 in SEV-SNP).
191 +
192 +Closing Remarks
193 +***************
194 +The exact content of the memory region specified by starting address ``opaque_addr``
195 +and length ``opaque_size`` is guest specific and is hypervisor agnostic. The hypervisor does
196 +not care about the contents of this memory region. Therefore, it is not included in this
197 +specification. As of writing this document, TDX guests on QEMU does not support IGVM.
198 +Therefore, this mechanism cannot be used to change launch state of TDX guests.