conf: support stateless UEFI firmware

Normally when an UEFI firmware is marked as read-only, an associated
NVRAM file will be created. Some builds of UEFI firmware, however, wish
to remain stateless and so will be read-only, but never have any NVRAM
file. To represent this concept a 'stateless' tristate bool attribute
is introduced on the <loader/> element.

There are rather a large number of permutations to consider.

With default firmware selection

  *  <os/>

     => Historic default, no change

  *  <os>
       <loader stateless='yes'/>
     </os>

     => Explicit version of historic default, no change

  *  <os>
       <loader stateless='no'/>
     </os>

      => Invalid, bios is always stateless

With manual legacy BIOS selection

  *  <os>
       <loader>/path/to/seabios</loader>
       ...
     </os>

     => Historic default, no change

  *  <os>
       <loader stateless='yes'>/path/to/seabios</loader>
       ...
     </os>

     => Explicit version of historic default, no change

  *  <os>
       <loader stateless='no'>/path/to/seabios</loader>
       ...
     </os>

      => Invalid, bios is always stateless

With manual UEFI selection

  *  <os>
       <loader type='pflash'>/path/to/edk2</loader>
       ...
     </os>

     => Historic default, no change

  *  <os>
       <loader type='pflash' stateless='yes'>/path/to/edk2</loader>
       ...
     </os>

     => Skip auto-filling NVRAM / template

  *  <os>
       <loader type='pflash' stateless='no'>/path/to/edk2</loader>
       ...
     </os>

     => Explicit version of historic default, no change

With automatic firmware selection

  *  <os firmware='bios'/>

     => Historic default, no change

  *  <os firmware='bios'>
       <loader stateless='yes'/>
     </os>

     => Explicit version of historic default, no change

  *  <os firmware='bios'>
       <loader stateless='no'/>
     </os>

      => Invalid, bios is always stateless

  *  <os firmware='uefi'/>

     => Historic default, no change

  *  <os firmware='uefi'>
       <loader stateless='yes'/>
     </os>

     => Skip auto-filling NVRAM / template

  *  <os firmware='uefi'>
       <loader stateless='no'/>
     </os>

     => Explicit version of historic default, no change

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

1 files changed, 18 insertions, 1 deletions

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 3ea094e64c..1ed969ac3e 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -173,6 +173,15 @@ harddisk, cdrom, network) determining where to obtain/find the boot image.
    </os>
    ...
 
+   <!-- QEMU with automatic UEFI stateless firmware for AMD SEV -->
+   ...
+   <os firmware='efi'>
+     <type>hvm</type>
+     <loader stateless='yes'/>
+     <boot dev='hd'/>
+   </os>
+   ...
+
 ``firmware``
    The ``firmware`` attribute allows management applications to automatically
    fill ``<loader/>`` and ``<nvram/>`` elements and possibly enable some
@@ -242,7 +251,12 @@ harddisk, cdrom, network) determining where to obtain/find the boot image.
    firmwares may implement the Secure boot feature. Attribute ``secure`` can be
    used to tell the hypervisor that the firmware is capable of Secure Boot feature.
    It cannot be used to enable or disable the feature itself in the firmware.
-   :since:`Since 2.1.0`
+   :since:`Since 2.1.0`. If the loader is marked as read-only, then with UEFI it
+   is assumed that there will be a writable NVRAM available. In some cases,
+   however, it may be desirable for the loader to run without any NVRAM, discarding
+   any config changes on shutdown. The ``stateless`` flag (:since:`Since 8.6.0`)
+   can be used to control this behaviour, when set to ``no`` NVRAM will never
+   be created.
 ``nvram``
    Some UEFI firmwares may want to use a non-volatile memory to store some
    variables. In the host, this is represented as a file and the absolute path
@@ -262,6 +276,9 @@ harddisk, cdrom, network) determining where to obtain/find the boot image.
    **Note:** ``network`` backed NVRAM the variables are not instantiated from
    the ``template`` and it's user's responsibility to provide a valid NVRAM image.
 
+   It is not valid to provide this element if the loader is marked as
+   stateless.
+
 ``boot``
    The ``dev`` attribute takes one of the values "fd", "hd", "cdrom" or
    "network" and is used to specify the next boot device to consider. The