| 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. |