[PATCH v2 0/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[PATCH v2 0/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Andrea Bolognani]

This is part of the ongoing effort to make Secure Boot for aarch64
libvirt guests possible[1].

Changes from [v1]:

  * rewrite based on review feedback: the additional information is
    now recorded as a dedicated struct, which intentionally doesn't
    mirror the existing FirmwareMappingFlash.

[1] https://issues.redhat.com/browse/RHEL-82645
[v1] https://mail.gnu.org/archive/html/qemu-devel/2025-12/msg03462.html

Andrea Bolognani (1):
  docs/interop/firmware: Add 'uefi-vars' member for
    FirmwareMappingMemory

 docs/interop/firmware.json | 44 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

-- 
2.53.0

[PATCH v2 1/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Andrea Bolognani]

This allows describing firmwares that are loaded as ROMs but also
support a UEFI variable store. 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.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
---
 docs/interop/firmware.json | 44 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index da0362a2c0..e51fffa473 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -369,6 +369,39 @@
 { 'struct' : 'FirmwareMappingKernel',
   'data'   : { 'filename' : 'str' } }
 
+##
+# @FirmwareMemoryUefiVars:
+#
+# Contains information needed to set up the "uefi-vars" device
+# to provide UEFI variable store access to the firmware.
+#
+# @template: The path to the UEFI variable store template compatible
+#     with the firmware.  Management software instantiates an
+#     individual copy -- a specific UEFI variable store file -- from
+#     @template for each new virtual machine definition created.
+#     @template itself is never mapped into virtual machines, only
+#     individual copies of it are.  The file created by copying
+#     @template is used for persistently storing the non-volatile
+#     UEFI variables of a virtual machine definition.  The
+#     corresponding QEMU command line options are
+#
+#     ::
+#
+#         -device uefi-vars-x64,jsonfile=PATH_TO_PRIVATE_FILE
+#
+#     for x86_64 virtual machines, or
+#
+#     ::
+#
+#         -device uefi-vars-sysbus,jsonfile=PATH_TO_PRIVATE_FILE
+#
+#     for other UEFI architectures (aarch64, riscv64, loongarch64).
+#
+# Since: 11.0
+##
+{ 'struct' : 'FirmwareMemoryUefiVars',
+  'data'   : { 'template' : 'str' }}
+
 ##
 # @FirmwareMappingMemory:
 #
@@ -380,10 +413,19 @@
 #     definitions.  The corresponding QEMU command line option is
 #     "-bios @filename".
 #
+# @uefi-vars: Information specific to firmware builds that expect the
+#             "uefi-vars" device to be used to provide access to the
+#             UEFI variable store.  If the mapping contains this
+#             member, the firmware descriptor should advertise the
+#             @uefi interface from @FirmwareOSInterface as well as
+#             the @host-uefi-vars feature from @FirmwareFeature.
+#             Since 11.0
+#
 # Since: 3.0
 ##
 { 'struct' : 'FirmwareMappingMemory',
-  'data'   : { 'filename' : 'str' } }
+  'data'   : { 'filename' : 'str',
+               '*uefi-vars' : 'FirmwareMemoryUefiVars' } }
 
 ##
 # @FirmwareMappingIgvm:
-- 
2.53.0

Re: [PATCH v2 1/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Daniel P. Berrangé]

On Mon, Feb 09, 2026 at 02:39:06PM +0100, Andrea Bolognani wrote:
> This allows describing firmwares that are loaded as ROMs but also
> support a UEFI variable store. 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.
> 
> Signed-off-by: Andrea Bolognani <abologna@redhat.com>
> ---
>  docs/interop/firmware.json | 44 +++++++++++++++++++++++++++++++++++++-
>  1 file changed, 43 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
> index da0362a2c0..e51fffa473 100644
> --- a/docs/interop/firmware.json
> +++ b/docs/interop/firmware.json
> @@ -369,6 +369,39 @@
>  { 'struct' : 'FirmwareMappingKernel',
>    'data'   : { 'filename' : 'str' } }
>  
> +##
> +# @FirmwareMemoryUefiVars:
> +#
> +# Contains information needed to set up the "uefi-vars" device
> +# to provide UEFI variable store access to the firmware.
> +#
> +# @template: The path to the UEFI variable store template compatible

s/UEFI variable store/UEFI JSON variable store/

> +#     with the firmware.  Management software instantiates an
> +#     individual copy -- a specific UEFI variable store file -- from
> +#     @template for each new virtual machine definition created.
> +#     @template itself is never mapped into virtual machines, only
> +#     individual copies of it are.  The file created by copying
> +#     @template is used for persistently storing the non-volatile
> +#     UEFI variables of a virtual machine definition.  The
> +#     corresponding QEMU command line options are
> +#
> +#     ::
> +#
> +#         -device uefi-vars-x64,jsonfile=PATH_TO_PRIVATE_FILE
> +#
> +#     for x86_64 virtual machines, or
> +#
> +#     ::
> +#
> +#         -device uefi-vars-sysbus,jsonfile=PATH_TO_PRIVATE_FILE
> +#
> +#     for other UEFI architectures (aarch64, riscv64, loongarch64).
> +#
> +# Since: 11.0
> +##
> +{ 'struct' : 'FirmwareMemoryUefiVars',
> +  'data'   : { 'template' : 'str' }}
> +
>  ##
>  # @FirmwareMappingMemory:
>  #
> @@ -380,10 +413,19 @@
>  #     definitions.  The corresponding QEMU command line option is
>  #     "-bios @filename".
>  #
> +# @uefi-vars: Information specific to firmware builds that expect the
> +#             "uefi-vars" device to be used to provide access to the
> +#             UEFI variable store.  If the mapping contains this
> +#             member, the firmware descriptor should advertise the
> +#             @uefi interface from @FirmwareOSInterface as well as
> +#             the @host-uefi-vars feature from @FirmwareFeature.
> +#             Since 11.0

s/should advertize the/must advertize both the/

s/as well as/and/

With those changes:

  Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


> +#
>  # Since: 3.0
>  ##
>  { 'struct' : 'FirmwareMappingMemory',
> -  'data'   : { 'filename' : 'str' } }
> +  'data'   : { 'filename' : 'str',
> +               '*uefi-vars' : 'FirmwareMemoryUefiVars' } }
>  
>  ##
>  # @FirmwareMappingIgvm:
> -- 
> 2.53.0
> 

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

Re: [PATCH v2 1/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Markus Armbruster]

Andrea Bolognani <abologna@redhat.com> writes:

> This allows describing firmwares that are loaded as ROMs but also
> support a UEFI variable store. 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.
>
> Signed-off-by: Andrea Bolognani <abologna@redhat.com>
> ---
>  docs/interop/firmware.json | 44 +++++++++++++++++++++++++++++++++++++-
>  1 file changed, 43 insertions(+), 1 deletion(-)
>
> diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
> index da0362a2c0..e51fffa473 100644
> --- a/docs/interop/firmware.json
> +++ b/docs/interop/firmware.json
> @@ -369,6 +369,39 @@
>  { 'struct' : 'FirmwareMappingKernel',
>    'data'   : { 'filename' : 'str' } }
>  
> +##
> +# @FirmwareMemoryUefiVars:
> +#
> +# Contains information needed to set up the "uefi-vars" device
> +# to provide UEFI variable store access to the firmware.
> +#
> +# @template: The path to the UEFI variable store template compatible
> +#     with the firmware.  Management software instantiates an
> +#     individual copy -- a specific UEFI variable store file -- from
> +#     @template for each new virtual machine definition created.
> +#     @template itself is never mapped into virtual machines, only
> +#     individual copies of it are.  The file created by copying
> +#     @template is used for persistently storing the non-volatile
> +#     UEFI variables of a virtual machine definition.  The
> +#     corresponding QEMU command line options are
> +#
> +#     ::
> +#
> +#         -device uefi-vars-x64,jsonfile=PATH_TO_PRIVATE_FILE
> +#
> +#     for x86_64 virtual machines, or
> +#
> +#     ::
> +#
> +#         -device uefi-vars-sysbus,jsonfile=PATH_TO_PRIVATE_FILE
> +#
> +#     for other UEFI architectures (aarch64, riscv64, loongarch64).
> +#
> +# Since: 11.0
> +##
> +{ 'struct' : 'FirmwareMemoryUefiVars',
> +  'data'   : { 'template' : 'str' }}
> +
>  ##
>  # @FirmwareMappingMemory:
>  #
> @@ -380,10 +413,19 @@
>  #     definitions.  The corresponding QEMU command line option is
>  #     "-bios @filename".
>  #
> +# @uefi-vars: Information specific to firmware builds that expect the
> +#             "uefi-vars" device to be used to provide access to the
> +#             UEFI variable store.  If the mapping contains this
> +#             member, the firmware descriptor should advertise the
> +#             @uefi interface from @FirmwareOSInterface as well as
> +#             the @host-uefi-vars feature from @FirmwareFeature.
> +#             Since 11.0
> +#

(Since 11.0) and indent like this, please:

   # @uefi-vars: Information specific to firmware builds that expect the
   #     "uefi-vars" device to be used to provide access to the UEFI
   #     variable store.  If the mapping contains this member, the
   #     firmware descriptor should advertise the @uefi interface from
   #     @FirmwareOSInterface as well as the @host-uefi-vars feature
   #     from @FirmwareFeature.  (Since 11.0)

>  # Since: 3.0
>  ##
>  { 'struct' : 'FirmwareMappingMemory',
> -  'data'   : { 'filename' : 'str' } }
> +  'data'   : { 'filename' : 'str',
> +               '*uefi-vars' : 'FirmwareMemoryUefiVars' } }
>  
>  ##
>  # @FirmwareMappingIgvm:

Acked-by: Markus Armbruster <armbru@redhat.com>

Re: [PATCH v2 1/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Gerd Hoffmann]

On Tue, Feb 17, 2026 at 10:08:14AM +0100, Markus Armbruster wrote:
> 
> (Since 11.0) and indent like this, please:
> 
>    # @uefi-vars: Information specific to firmware builds that expect the
>    #     "uefi-vars" device to be used to provide access to the UEFI
>    #     variable store.  If the mapping contains this member, the
>    #     firmware descriptor should advertise the @uefi interface from
>    #     @FirmwareOSInterface as well as the @host-uefi-vars feature
>    #     from @FirmwareFeature.  (Since 11.0)

Fixed up and queued.

take care,
  Gerd
  

Re: [PATCH v2 1/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Andrea Bolognani]

On Tue, Feb 17, 2026 at 12:37:15PM +0100, Gerd Hoffmann wrote:
> On Tue, Feb 17, 2026 at 10:08:14AM +0100, Markus Armbruster wrote:
> > (Since 11.0) and indent like this, please:
> >
> >    # @uefi-vars: Information specific to firmware builds that expect the
> >    #     "uefi-vars" device to be used to provide access to the UEFI
> >    #     variable store.  If the mapping contains this member, the
> >    #     firmware descriptor should advertise the @uefi interface from
> >    #     @FirmwareOSInterface as well as the @host-uefi-vars feature
> >    #     from @FirmwareFeature.  (Since 11.0)
>
> Fixed up and queued.

I sent [v3] incorporating Daniel's comments too, maybe you've already
taken care of that but just in case please make sure they don't get
lost.

Thanks!


[v3] https://mail.gnu.org/archive/html/qemu-devel/2026-02/msg04422.html
-- 
Andrea Bolognani / Red Hat / Virtualization

Re: [PATCH v2 1/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Andrea Bolognani]

On Tue, Feb 17, 2026 at 10:08:14AM +0100, Markus Armbruster wrote:
> > +# @uefi-vars: Information specific to firmware builds that expect the
> > +#             "uefi-vars" device to be used to provide access to the
> > +#             UEFI variable store.  If the mapping contains this
> > +#             member, the firmware descriptor should advertise the
> > +#             @uefi interface from @FirmwareOSInterface as well as
> > +#             the @host-uefi-vars feature from @FirmwareFeature.
> > +#             Since 11.0
> > +#
>
> (Since 11.0) and indent like this, please:

Done, but note that the documentation for existing members
FirmwareDevice::igvm and FirmwareMappingFlash::mode doesn't follow
this convention.

-- 
Andrea Bolognani / Red Hat / Virtualization

Re: [PATCH v2 1/1] docs/interop/firmware: Add 'uefi-vars' member for FirmwareMappingMemory

[Markus Armbruster]

Andrea Bolognani <abologna@redhat.com> writes:

> On Tue, Feb 17, 2026 at 10:08:14AM +0100, Markus Armbruster wrote:
>> > +# @uefi-vars: Information specific to firmware builds that expect the
>> > +#             "uefi-vars" device to be used to provide access to the
>> > +#             UEFI variable store.  If the mapping contains this
>> > +#             member, the firmware descriptor should advertise the
>> > +#             @uefi interface from @FirmwareOSInterface as well as
>> > +#             the @host-uefi-vars feature from @FirmwareFeature.
>> > +#             Since 11.0
>> > +#
>>
>> (Since 11.0) and indent like this, please:
>
> Done, but note that the documentation for existing members
> FirmwareDevice::igvm and FirmwareMappingFlash::mode doesn't follow
> this convention.

... where "this convention" is about since.  You're right, and I wasn't
aware of it.  Thanks!