Re: [PATCH 2/2] docs/interop/firmware: Introduce extended syntax for FirmwareMappingMemory

["Daniel P. Berrangé" <berrange@redhat.com>]

On Mon, Dec 29, 2025 at 12:26:49AM +0100, Andrea Bolognani wrote:
> The new syntax allows describing firmwares that are loaded as
> ROMs but also support NVRAM storage. This is the case for edk2
> builds that are set up to use the uefi-vars QEMU device, and
> whose descriptors would advertise the 'host-uefi-vars' feature.

I find it a bit of a stretch to be referring to the host-uefi-vars
feature as being "NVRAM storage". IIUC, it is effectively a command
/ response RPC service over a paravirtualized device.

> The extended syntax intentionally mirrors FirmwareMappingFlash
> since it needs to cover the exact same scenarios, which are a
> strict superset of the ones FirmwareMappingMemory supports
> today.

IMHO this is a mistake as it isn't really the same as the
NVRAM for the flash mapping.


> +##
> +# @FirmwareMemoryExecutableFormat:
> +#
> +# Formats that are supported for firmware executables.
> +#
> +# @raw: Raw disk image format.
> +#
> +# Since: 11.0
> +##
> +{ 'enum': 'FirmwareMemoryExecutableFormat',
> +  'data': [ 'raw' ] }
> +
> +##
> +# @FirmwareMemoryNvramFormat:
> +#
> +# Formats that are supported for firmware NVRAM files.
> +#
> +# @json: JSON format.
> +#
> +# Since: 11.0
> +##
> +{ 'enum': 'FirmwareMemoryNvramFormat',
> +  'data': [ 'json' ] }

These two are both examples of where the analogy to the flash
mapping falls down.

The executable format in flash mapping was required because
the binaries are provided via the block backend config (-blockdev).
The list of formats conceptually would expand to anything that
is possible with -blockdev, but we artificially restricted the
schema to just raw & qcow2 since other options were somewhat
unplausible.

Similarly the flash mapping nvram again wanted a format because
it was again describing something to be used with -blockdev.

Neither of these two scenarios applies, and while we could squint
and say using "raw" is acceptable for FirmwareMemoryExecutableFormat,
using "json" is definitely not a fit as it has nothing todo with
-blockdev.


> +##
> +# @FirmwareMemoryMode:
> +#
> +# Describes how the firmware build handles variable persistence.
> +#
> +# @split: the executable file contains code while the NVRAM template
> +#     provides variable storage.  The executable can be shared
> +#     between multiple guests.  The NVRAM template must be cloned for
> +#     each new guest and configured read-write.
> +#
> +# @stateless: the executable file contains code and variable storage
> +#     is not persisted.  The executable can be shared between
> +#     multiple guests.  No NVRAM template will be specified.
> +#
> +# Since: 11.0
> +##
> +{ 'enum' : 'FirmwareMemoryMode',
> +  'data' : [ 'split', 'stateless' ] }

This feels very wierd talking about NVRAM again when no such concept
exists with -bios, even when the UEFI var service is present.

The 'split' concept doesn't really match what the UEFI var service
provides IMHO. 


> +# The two syntaxes are mutually exclusive. In particular:
> +#
> +# - only one of @filename and @executable can be specified;
> +#
> +# - if @filename is specified, @mode must be omitted and its value
> +#   is assumed to be @stateless.  If @executable is used instead,
> +#   the value for @mode must be provided explicitly;
> +#
> +# - @nvram-template can only be specified together with @executable,
> +#   and in this case the value of @mode must be @split.
> +#
> +# Based on these rules,
> +#
> +# ::
> +#
> +#     {
> +#         "mapping: {
> +#             "device": "memory",
> +#             "filename": "/path/to/firmware.bin"
> +#         }
> +#     }
> +#
> +# and
> +#
> +# ::
> +#
> +#     {
> +#         "mapping": {
> +#             "device": "memory",
> +#             "mode": "stateless",
> +#             "executable": {
> +#                 "filename": "/path/to/firmware.bin",
> +#                 "format": "raw"
> +#             }
> +#         }
> +#     }
> +#
> +# are completely equivalent, whereas
> +#
> +# ::
> +#
> +#     {
> +#         "mapping": {
> +#             "device": "memory",
> +#             "mode": "split",
> +#             "executable": {
> +#                 "filename": "/path/to/firmware.bin",
> +#                 "format": "raw"
> +#             },
> +#             "nvram-template": {
> +#                 "filename": "/path/to/variables.json",
> +#                 "format": "json"
> +#             }
> +#         }
> +#     }
> +#
> +# can only be described using the extended syntax.
> +#
> +# @mode: Describes how the firmware build handles variable storage.
> +#     Must be present when @executable is used and absent when
> +#     @filename is used; in the latter scenario, its value will be
> +#     assumed to be @stateless.  Since: 11.0
> +#
> +# @executable: Describes the firmware excutable.  The corresponding
> +#     QEMU command line option is "-bios @executable.@filename".
> +#     Since: 11.0
> +#
> +# @nvram-template: Describes the NVRAM template compatible with
> +#     @executable, when @mode is set to @split, otherwise it should
> +#     not be present.  Management software instantiates an individual
> +#     copy -- a specific NVRAM file -- from @nvram-template.@filename
> +#     for each new virtual machine definition created.
> +#     @nvram-template.@filename itself is never mapped into virtual
> +#     machines, only individual copies of it are.  An NVRAM file is
> +#     typically used for persistently storing the non-volatile UEFI
> +#     variables of a virtual machine definition.  The corresponding
> +#     QEMU command line option is
> +#
> +#     ::
> +#
> +#         -device uefi-vars-x64,jsonfile=FILENAME_OF_PRIVATE_NVRAM_FILE
> +#
> +#     on x86_64 and
> +#
> +#     ::
> +#
> +#         -device uefi-vars-sysbus,jsonfile=FILENAME_OF_PRIVATE_NVRAM_FILE
> +#
> +#     on other architectures (aarch64, riscv64, loongarch64).
> +#     Since: 11.0
> +#
> +# @filename: Legacy syntax that can only describe @stateless firmware
> +#     builds.  The corresponding QEMU command line option is "-bios
> +#     @filename".  If present, none of the other attributes (@mode,
> +#     @executable, @template) can be present.
>  #
>  # Since: 3.0
>  ##
>  { 'struct' : 'FirmwareMappingMemory',
> -  'data'   : { 'filename' : 'str' } }
> +  'data'   : { '*mode'           : 'FirmwareMemoryMode',
> +               '*executable'     : 'FirmwareMemoryExecutableFile',
> +               '*nvram-template' : 'FirmwareMemoryNvramTemplateFile',
> +               '*filename'       : 'str' } }

IMHO we could add merely a new "uefi-vars-service" such that it looks
like this:

     {
         "mapping: {
             "device": "memory",
             "filename": "/path/to/firmware.bin",
	     "uefi-vars-service": {
	       "template": "/path/to/firmware.json",
	     }
         }
     }

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|