Markus Armbruster <armbru@xxxxxxxxxx> writes:
> The next commit will add feature flags to enum members. There's a
> problem, though: query-qmp-schema shows an enum type's members as an
> array of member names (SchemaInfoEnum member @values). If it showed
> an array of objects with a name member, we could simply add more
> members to these objects. Since it's just strings, we can't.
>
> I can see three ways to correct this design mistake:
>
> 1. Do it the way we should have done it, plus compatibility goo.
>
> We want a ['SchemaInfoEnumMember'] member in SchemaInfoEnum. Since
> changing @values would be a compatibility break, add a new member
> @members instead.
>
> @values is now redundant. In my testing, output of
> qemu-system-x86_64's query-qmp-schema grows by 11% (18.5KiB).
>
> We can deprecate @values now and drop it later. This will break
> outmoded clients. Well-behaved clients such as libvirt are
> expected to break cleanly.
>
> 2. Like 1, but omit "boring" elements of @member, and empty @member.
>
> @values does not become redundant. @members augments it. Somewhat
> cumbersome, but output of query-qmp-schema grows only as we make
> enum members non-boring.
>
> There is nothing to deprecate here.
>
> 3. Versioned query-qmp-schema.
>
> query-qmp-schema provides either @values or @members. The QMP
> client can select which version it wants. There is no redundant
> output.
>
> We can deprecate old versions and eventually drop them. This will
> break outmoded clients. Breaking cleanly is easier than for 1.
>
> While 1 and 2 operate within the common rules for compatible
> evolution apply (section "Compatibility considerations" in
> docs/devel/qapi-code-gen.rst), 3 bypasses them. Attractive when
> operating within the rules is just too awkward. Not the case here.
>
> This commit implements 1. Libvirt developers prefer it.
>
> Signed-off-by: Markus Armbruster <armbru@xxxxxxxxxx>
> Reviewed-by: Eric Blake <eblake@xxxxxxxxxx>
> Tested-by: Peter Krempa <pkrempa@xxxxxxxxxx>
> Acked-by: Peter Krempa <pkrempa@xxxxxxxxxx>
I meant to deprecate @values, but forgot. I should really do it right
away, because...
> ---
> docs/devel/qapi-code-gen.rst | 15 +++++++++++----
> qapi/introspect.json | 21 +++++++++++++++++++--
> scripts/qapi/introspect.py | 18 ++++++++++++++----
> 3 files changed, 44 insertions(+), 10 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index b2569de486..d267889d2c 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -1231,14 +1231,21 @@ Example: the SchemaInfo for ['str'] ::
> "element-type": "str" }
>
> The SchemaInfo for an enumeration type has meta-type "enum" and
> -variant member "values". The values are listed in no particular
> -order; clients must search the entire enum when learning whether a
> -particular value is supported.
> +variant member "members".
> +
> +"members" is a JSON array describing the enumeration values. Each
> +element is a JSON object with member "name" (the member's name). The
> +"members" array is in no particular order; clients must search the
> +entire array when learning whether a particular value is supported.
>
> Example: the SchemaInfo for MyEnum from section `Enumeration types`_ ::
>
> { "name": "MyEnum", "meta-type": "enum",
> - "values": [ "value1", "value2", "value3" ] }
> + "members": [
> + { "name": "value1" },
> + { "name": "value2" },
> + { "name": "value3" }
> + ] }
>
> The SchemaInfo for a built-in type has the same name as the type in
> the QAPI schema (see section `Built-in Types`_), with one exception
... this doesn't document @values anymore, only @members.
Done in v5.
[...]
