Only a small subset of all blockdev drivers make sense for firmware
images. Introduce and use a new enum to represent this.

This also reduces the dependency on firmware.json from the global qapi
definitions.

Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
---
 docs/interop/firmware.json | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index 54a1fc6c1041..a26fe81bf2fe 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -15,7 +15,6 @@
 ##
 
 { 'include' : 'machine.json' }
-{ 'include' : 'block-core.json' }
 
 ##
 # @FirmwareOSInterface:
@@ -200,6 +199,20 @@
              'enrolled-keys', 'requires-smm', 'secure-boot',
              'verbose-dynamic', 'verbose-static' ] }
 
+##
+# @FirmwareFormat:
+#
+# Formats that are supported for firmware images.
+#
+# @raw: Raw disk image format.
+#
+# @qcow2: QEMU image format.
+#
+# Since: 9.1
+##
+{ 'enum': 'FirmwareFormat',
+  'data': [ 'raw', 'qcow2' ] }
+
 ##
 # @FirmwareFlashFile:
 #
@@ -219,7 +232,7 @@
 ##
 { 'struct' : 'FirmwareFlashFile',
   'data'   : { 'filename' : 'str',
-               'format'   : 'BlockdevDriver' } }
+               'format'   : 'FirmwareFormat' } }
 
 
 ##

-- 
2.45.2

Thomas Weißschuh <thomas.weissschuh@linutronix.de> writes:

> Only a small subset of all blockdev drivers make sense for firmware
> images. Introduce and use a new enum to represent this.
>
> This also reduces the dependency on firmware.json from the global qapi
> definitions.
>
> Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
> ---
>  docs/interop/firmware.json | 17 +++++++++++++++--
>  1 file changed, 15 insertions(+), 2 deletions(-)
>
> diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
> index 54a1fc6c1041..a26fe81bf2fe 100644
> --- a/docs/interop/firmware.json
> +++ b/docs/interop/firmware.json
> @@ -15,7 +15,6 @@
>  ##
>  
>  { 'include' : 'machine.json' }
> -{ 'include' : 'block-core.json' }
>  
>  ##
>  # @FirmwareOSInterface:
> @@ -200,6 +199,20 @@
>               'enrolled-keys', 'requires-smm', 'secure-boot',
>               'verbose-dynamic', 'verbose-static' ] }
>  
> +##
> +# @FirmwareFormat:
> +#
> +# Formats that are supported for firmware images.
> +#
> +# @raw: Raw disk image format.
> +#
> +# @qcow2: QEMU image format.

It's not the only QEMU image format...  Maybe "The QCOW2 image format."
Almost tautological, but I don't have better ideas.

> +#
> +# Since: 9.1

The enum type is indeed since 9.1, but its two members are since 3.0,
and that's what matters.

> +##
> +{ 'enum': 'FirmwareFormat',
> +  'data': [ 'raw', 'qcow2' ] }
> +
>  ##
>  # @FirmwareFlashFile:
>  #
> @@ -219,7 +232,7 @@
>  ##
>  { 'struct' : 'FirmwareFlashFile',
>    'data'   : { 'filename' : 'str',
> -               'format'   : 'BlockdevDriver' } }
> +               'format'   : 'FirmwareFormat' } }
>  
>  
>  ##

On Thu, Jul 18, 2024 at 03:09:37PM +0200, Markus Armbruster wrote:
> Thomas Weißschuh <thomas.weissschuh@linutronix.de> writes:

[...]

> > +#
> > +# @raw: Raw disk image format.
> > +#
> > +# @qcow2: QEMU image format.
> 
> It's not the only QEMU image format...  Maybe "The QCOW2 image format."
> Almost tautological, but I don't have better ideas.

For slightly less tautology, not sure these are any better:

    @raw: Disk image format that's plain and unstructured.

    @qcow2: Disk image format with support for copy-on-write and more.

[...]

-- 
/kashyap

On Thu, Jul 18, 2024 at 03:09:37PM GMT, Markus Armbruster wrote:
> Thomas Weißschuh <thomas.weissschuh@linutronix.de> writes:
> 
> > Only a small subset of all blockdev drivers make sense for firmware
> > images. Introduce and use a new enum to represent this.
> >
> > This also reduces the dependency on firmware.json from the global qapi
> > definitions.
> >
> > Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
> > Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> > Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
> > ---
> >  docs/interop/firmware.json | 17 +++++++++++++++--
> >  1 file changed, 15 insertions(+), 2 deletions(-)
> >
> > diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
> > index 54a1fc6c1041..a26fe81bf2fe 100644
> > --- a/docs/interop/firmware.json
> > +++ b/docs/interop/firmware.json
> > @@ -15,7 +15,6 @@
> >  ##
> >  
> >  { 'include' : 'machine.json' }
> > -{ 'include' : 'block-core.json' }
> >  
> >  ##
> >  # @FirmwareOSInterface:
> > @@ -200,6 +199,20 @@
> >               'enrolled-keys', 'requires-smm', 'secure-boot',
> >               'verbose-dynamic', 'verbose-static' ] }
> >  
> > +##
> > +# @FirmwareFormat:
> > +#
> > +# Formats that are supported for firmware images.
> > +#
> > +# @raw: Raw disk image format.
> > +#
> > +# @qcow2: QEMU image format.
> 
> It's not the only QEMU image format...  Maybe "The QCOW2 image format."
> Almost tautological, but I don't have better ideas.

I used the wording from qemu-img(1).
If you prefer "The QCOW2 image format", I'll switch to that.

> > +#
> > +# Since: 9.1
> 
> The enum type is indeed since 9.1, but its two members are since 3.0,
> and that's what matters.

Ack.

So I change the Since: of the whole enum?
And not on the individual members?

> > +##
> > +{ 'enum': 'FirmwareFormat',
> > +  'data': [ 'raw', 'qcow2' ] }
> > +
> >  ##
> >  # @FirmwareFlashFile:
> >  #
> > @@ -219,7 +232,7 @@
> >  ##
> >  { 'struct' : 'FirmwareFlashFile',
> >    'data'   : { 'filename' : 'str',
> > -               'format'   : 'BlockdevDriver' } }
> > +               'format'   : 'FirmwareFormat' } }
> >  
> >  
> >  ##
> 

Thomas Weißschuh <t-8ch@linutronix.de> writes:

> On Thu, Jul 18, 2024 at 03:09:37PM GMT, Markus Armbruster wrote:
>> Thomas Weißschuh <thomas.weissschuh@linutronix.de> writes:
>> 
>> > Only a small subset of all blockdev drivers make sense for firmware
>> > images. Introduce and use a new enum to represent this.
>> >
>> > This also reduces the dependency on firmware.json from the global qapi
>> > definitions.
>> >
>> > Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
>> > Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
>> > Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
>> > ---
>> >  docs/interop/firmware.json | 17 +++++++++++++++--
>> >  1 file changed, 15 insertions(+), 2 deletions(-)
>> >
>> > diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
>> > index 54a1fc6c1041..a26fe81bf2fe 100644
>> > --- a/docs/interop/firmware.json
>> > +++ b/docs/interop/firmware.json
>> > @@ -15,7 +15,6 @@
>> >  ##
>> >  
>> >  { 'include' : 'machine.json' }
>> > -{ 'include' : 'block-core.json' }
>> >  
>> >  ##
>> >  # @FirmwareOSInterface:
>> > @@ -200,6 +199,20 @@
>> >               'enrolled-keys', 'requires-smm', 'secure-boot',
>> >               'verbose-dynamic', 'verbose-static' ] }
>> >  
>> > +##
>> > +# @FirmwareFormat:
>> > +#
>> > +# Formats that are supported for firmware images.
>> > +#
>> > +# @raw: Raw disk image format.
>> > +#
>> > +# @qcow2: QEMU image format.
>> 
>> It's not the only QEMU image format...  Maybe "The QCOW2 image format."
>> Almost tautological, but I don't have better ideas.
>
> I used the wording from qemu-img(1).

Interesting, wasn't aware.

> If you prefer "The QCOW2 image format", I'll switch to that.

Up to you, unless Kevin or Hanna have a preference.

>> > +#
>> > +# Since: 9.1
>> 
>> The enum type is indeed since 9.1, but its two members are since 3.0,
>> and that's what matters.
>
> Ack.
>
> So I change the Since: of the whole enum?
> And not on the individual members?

Whole enum is simpler, so that's what I'd do.  Perhaps with a brief
explanation in the commit message.  Here's my try:

    Claim "Since: 3.0" for the new enum, because that's correct for its
    members, and the members are what matters in the interface.

>> > +##
>> > +{ 'enum': 'FirmwareFormat',
>> > +  'data': [ 'raw', 'qcow2' ] }
>> > +
>> >  ##
>> >  # @FirmwareFlashFile:
>> >  #
>> > @@ -219,7 +232,7 @@
>> >  ##
>> >  { 'struct' : 'FirmwareFlashFile',
>> >    'data'   : { 'filename' : 'str',
>> > -               'format'   : 'BlockdevDriver' } }
>> > +               'format'   : 'FirmwareFormat' } }
>> >  
>> >  
>> >  ##
>>