@@ -1,3 +1,5 @@
+.. _amd-sev:
+
AMD Secure Encrypted Virtualization (SEV)
=========================================
new file mode 100644
@@ -0,0 +1,129 @@
+Independent Guest Virtual Machine (IGVM) support
+================================================
+
+IGVM files are designed to encapsulate all the information required to launch a
+virtual machine on any given virtualization stack in a deterministic way. This
+allows the cryptographic measurement of initial guest state for Confidential
+Guests to be calculated when the IGVM file is built, allowing a relying party to
+verify the initial state of a guest via a remote attestation.
+
+QEMU supports IGVM files through the Confidential Guest Support object. An igvm
+filename can optionally be passed to the object which will subsequently be
+parsed and used to configure the guest state prior to launching the guest.
+
+Further Information on IGVM
+---------------------------
+
+Information about the IGVM format, including links to the format specification
+and documentation for the Rust and C libraries can be found at the project
+repository:
+
+https://github.com/microsoft/igvm
+
+
+Supported Platforms
+-------------------
+
+Currently, IGVM files can be provided for Confidential Guests on host systems
+that support AMD SEV and SEV-ES running under KVM.
+
+
+Limitations when using IGVM with AMD SEV and SEV-ES
+---------------------------------------------------
+
+IGVM files configure the initial state of the guest using a set of directives.
+Not every directive is supported by every Confidential Guest type. For example,
+AMD SEV does not support encrypted save state regions, therefore setting the
+initial CPU state using IGVM for SEV is not possible. When an IGVM file contains
+directives that are not supported for the active platform, an error is displayed
+and the guest launch is aborted.
+
+The table below describes the list of directives that are supported for SEV and
+SEV-ES.
+
+.. list-table:: SEV & SEV-ES Supported Directives
+ :widths: 35 65
+ :header-rows: 1
+
+ * - IGVM directive
+ - Notes
+ * - IGVM_VHT_PAGE_DATA
+ - ``NORMAL`` zero, measured and unmeasured page types are supported. Other
+ page types result in an error.
+ * - IGVM_VHT_PARAMETER_AREA
+ -
+ * - IGVM_VHT_PARAMETER_INSERT
+ -
+ * - IGVM_VHT_MEMORY_MAP
+ - The memory map page is populated using entries from the E820 table.
+ * - IGVM_VHT_VP_COUNT_PARAMETER
+ - The guest parameter page is populated with the CPU count.
+ * - IGVM_VHT_ENVIRONMENT_INFO_PARAMETER
+ - The ``memory_is_shared`` parameter is set to 1 in the guest parameter
+ page.
+
+.. list-table:: Additional SEV-ES Supported Directives
+ :widths: 25 75
+ :header-rows: 1
+
+ * - IGVM directive
+ - Notes
+ * - IGVM_VHT_VP_CONTEXT
+ - Setting of the initial CPU state for the boot CPU and additional CPUs is
+ supported with limitations on the fields that can be provided in the
+ VMSA. See below for details on which fields are supported.
+
+Initial CPU state with SEV-ES VMSA
+----------------------------------
+
+The initial state of guest CPUs can be defined in the IGVM file for AMD SEV-ES.
+The state data is provided as a VMSA structure as defined in Table B-4 in the
+AMD64 Architecture Programmer's Manual, Volume 2 [1].
+
+The IGVM VMSA is translated to CPU state in QEMU which is then synchronized
+by KVM to the guest VMSA during the launch process where it contributes to the
+launch measurement. See :ref:`amd-sev` for details on the launch process and
+guest launch measurement.
+
+It is important that no information is lost or changed when translating the
+VMSA provided by the IGVM file into the VSMA that is used to launch the guest.
+Therefore, QEMU restricts the VMSA fields that can be provided in the IGVM
+VMSA structure to the following registers:
+
+RAX, RCX, RDX, RBX, RBP, RSI, RDI, R8-R15, RSP, RIP, CS, DS, ES, FS, GS, SS,
+CR0, CR3, CR4, XCR0, EFER.
+
+When processing the IGVM file, QEMU will check if any fields other than the
+above are non-zero and generate an error if this is the case.
+
+Firmware Images with IGVM
+-------------------------
+
+When an IGVM filename is specified for a Confidential Guest Support object it
+overrides the default handling of system firmware: the firmware image, such as
+an OVMF binary should be contained as a payload of the IGVM file and not
+provided as a flash drive or via the ``-bios`` parameter. The default QEMU
+firmware is not automatically populated into the guest memory space.
+
+If an IGVM file is provided along with either the ``-bios`` parameter or pflash
+devices then an error is displayed and the guest startup is aborted.
+
+Running a Confidential Guest configured using IGVM
+--------------------------------------------------
+
+To run a confidential guest configured with IGVM you need to add the
+``igvm-file`` parameter to the "confidential guest support" object:
+
+Example (for AMD SEV)::
+
+ qemu-system-x86_64 \
+ <other parameters> \
+ -machine ...,confidential-guest-support=sev0 \
+ -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1,igvm-file=/path/to/guest.igvm
+
+References
+----------
+
+[1] AMD64 Architecture Programmer's Manual, Volume 2: System Programming
+ Rev 3.41
+ https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf
\ No newline at end of file
@@ -38,4 +38,5 @@ or Hypervisor.Framework.
security
multi-process
confidential-guest-support
+ igvm
vm-templating
IGVM support has been implemented for Confidential Guests that support AMD SEV and AMD SEV-ES. Add some documentation that gives some background on the IGVM format and how to use it to configure a confidential guest. Signed-off-by: Roy Hopkins <roy.hopkins@suse.com> --- docs/system/i386/amd-memory-encryption.rst | 2 + docs/system/igvm.rst | 129 +++++++++++++++++++++ docs/system/index.rst | 1 + 3 files changed, 132 insertions(+) create mode 100644 docs/system/igvm.rst