diff mbox series

[v3,09/15] docs/system: Add documentation on support for IGVM

Message ID b666f4e30e8785de3dc944ac8dbefd0a23f49f5d.1718979106.git.roy.hopkins@suse.com
State New
Headers show
Series Introduce support for IGVM files | expand

Commit Message

Roy Hopkins June 21, 2024, 2:29 p.m. UTC 
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                       | 157 +++++++++++++++++++++
 docs/system/index.rst                      |   1 +
 3 files changed, 160 insertions(+)
 create mode 100644 docs/system/igvm.rst

Comments

Daniel P. Berrangé June 24, 2024, 2:09 p.m. UTC | #1 
On Fri, Jun 21, 2024 at 03:29:12PM +0100, Roy Hopkins wrote:
> 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                       | 157 +++++++++++++++++++++
>  docs/system/index.rst                      |   1 +
>  3 files changed, 160 insertions(+)
>  create mode 100644 docs/system/igvm.rst

> diff --git a/docs/system/igvm.rst b/docs/system/igvm.rst
> new file mode 100644
> index 0000000000..b6e544a508
> --- /dev/null
> +++ b/docs/system/igvm.rst

> +Running a Confidential Guest configured using IGVM
> +--------------------------------------------------
> +
> +To run a confidential guest configured with IGVM you need to add an
> +``igvm-cfg`` object and refer to it from the ``-machine`` parameter:
> +
> +Example (for AMD SEV)::
> +
> +    qemu-system-x86_64 \
> +        <other parameters> \
> +        -machine ...,confidential-guest-support=sev0,igvm-cfg=igvm0 \
> +        -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \
> +        -object igvm-cfg,id=igvm0,file=/path/to/guest.igvm

Perhaps also illustrate use of your 'buildigvm' tool for creating
the igvm file first, assuming that's the tool users are most likely
to end up needing ?


With regards,
Daniel
Roy Hopkins July 1, 2024, 2:28 p.m. UTC | #2 
On Mon, 2024-06-24 at 15:09 +0100, Daniel P. Berrangé wrote:
> On Fri, Jun 21, 2024 at 03:29:12PM +0100, Roy Hopkins wrote:
> > 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                       | 157 +++++++++++++++++++++
> >  docs/system/index.rst                      |   1 +
> >  3 files changed, 160 insertions(+)
> >  create mode 100644 docs/system/igvm.rst
> 
> > diff --git a/docs/system/igvm.rst b/docs/system/igvm.rst
> > new file mode 100644
> > index 0000000000..b6e544a508
> > --- /dev/null
> > +++ b/docs/system/igvm.rst
> 
> > +Running a Confidential Guest configured using IGVM
> > +--------------------------------------------------
> > +
> > +To run a confidential guest configured with IGVM you need to add an
> > +``igvm-cfg`` object and refer to it from the ``-machine`` parameter:
> > +
> > +Example (for AMD SEV)::
> > +
> > +    qemu-system-x86_64 \
> > +        <other parameters> \
> > +        -machine ...,confidential-guest-support=sev0,igvm-cfg=igvm0 \
> > +        -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \
> > +        -object igvm-cfg,id=igvm0,file=/path/to/guest.igvm
> 
> Perhaps also illustrate use of your 'buildigvm' tool for creating
> the igvm file first, assuming that's the tool users are most likely
> to end up needing ?
> 
> 
> With regards,
> Daniel

I'm not sure it is the tool that _most_ people will end up using, but it is a
good example and I'm not aware of many other examples of IGVM build tools.

IGVM is likely to be used to package guests with custom configuration
requirements, such as the COCONUT-SVSM usage where the SVSM kernel is packaged
along with OVMF, configuration and other data required to launch a guest running
with a range of privilege levels in a confidential virtual machine.

But for the purposes of testing and examples it makes sense to update the
documentation to describe how to use the 'buildigvm' tool so I'll update the
docs.

Regards,
Roy
diff mbox series

Patch

diff --git a/docs/system/i386/amd-memory-encryption.rst b/docs/system/i386/amd-memory-encryption.rst
index 748f5094ba..6c23f3535f 100644
--- a/docs/system/i386/amd-memory-encryption.rst
+++ b/docs/system/i386/amd-memory-encryption.rst
@@ -1,3 +1,5 @@ 
+.. _amd-sev:
+
 AMD Secure Encrypted Virtualization (SEV)
 =========================================
 
diff --git a/docs/system/igvm.rst b/docs/system/igvm.rst
new file mode 100644
index 0000000000..b6e544a508
--- /dev/null
+++ b/docs/system/igvm.rst
@@ -0,0 +1,157 @@ 
+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.
+
+Although IGVM files are designed with Confidential Computing in mind, they can
+also be used to configure non-confidential guests. Multiple platforms can be
+defined by a single IGVM file, allowing a single IGVM file to configure a
+virtual machine that can run on, for example, TDX, SEV and non-confidential
+hosts.
+
+QEMU supports IGVM files through the user-creatable ``igvm-cfg`` object. This
+object is used to define the filename of the IGVM file to process. A reference
+to the object is added to the ``-machine`` to configure the virtual machine
+to use the IGVM file for configuration.
+
+Confidential platform support is provided through the use of
+the ``ConfidentialGuestSupport`` object. If the virtual machine provides an
+instance of this object then this is used by the IGVM loader to configure the
+isolation properties of the directives within the file.
+
+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, SEV-ES and SEV-SNP with KVM. IGVM files can also be
+provided for non-confidential guests.
+
+
+Limitations when using IGVM with AMD SEV, SEV-ES and SEV-SNP
+------------------------------------------------------------
+
+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 generated
+and the guest launch is aborted.
+
+The table below describes the list of directives that are supported for SEV,
+SEV-ES, SEV-SNP and non-confidential platforms.
+
+.. list-table:: SEV, SEV-ES, SEV-SNP & non-confidential 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_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, SEV-ES & SEV_SNP Supported Directives
+   :widths: 25 75
+   :header-rows: 1
+
+   * - IGVM directive
+     - Notes
+   * - IGVM_VHT_MEMORY_MAP
+     - The memory map page is populated using entries from the E820 table.
+   * - IGVM_VHT_REQUIRED_MEMORY
+     -
+
+.. list-table:: Additional SEV-ES & SEV-SNP 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 VMSA
+---------------------------
+
+The initial state of guest CPUs can be defined in the IGVM file for AMD SEV-ES
+and SEV-SNP. 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, PAT, GDT, IDT, LDTR, TR, DR6, DR7, RFLAGS, X87_FCW,
+MXCSR.
+
+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.
+
+KVM uses a hardcoded GPA of 0xFFFFFFFFF000 for the VMSA. When an IGVM file
+defines initial CPU state, the GPA for each VMSA must match this hardcoded
+value.
+
+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 an
+``igvm-cfg`` object and refer to it from the ``-machine`` parameter:
+
+Example (for AMD SEV)::
+
+    qemu-system-x86_64 \
+        <other parameters> \
+        -machine ...,confidential-guest-support=sev0,igvm-cfg=igvm0 \
+        -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \
+        -object igvm-cfg,id=igvm0,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
diff --git a/docs/system/index.rst b/docs/system/index.rst
index c21065e519..6235dfab87 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -38,4 +38,5 @@  or Hypervisor.Framework.
    security
    multi-process
    confidential-guest-support
+   igvm
    vm-templating