Re: [PATCH v2 9/9] qapi: Extend -compat to set policy for unstable interfaces

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> writes:

> On Thu, Oct 28, 2021 at 12:25:20PM +0200, Markus Armbruster wrote:
>> New option parameters unstable-input and unstable-output set policy
>> for unstable interfaces just like deprecated-input and
>> deprecated-output set policy for deprecated interfaces (see commit
>> 6dd75472d5 "qemu-options: New -compat to set policy for deprecated
>> interfaces").  This is intended for testing users of the management
>> interfaces.  It is experimental.
>> 
>> For now, this covers only syntactic aspects of QMP, i.e. stuff tagged
>> with feature 'unstable'.  We may want to extend it to cover semantic
>> aspects, or the command line.
>> 
>> Note that there is no good way for management application to detect
>> presence of these new option parameters: they are not visible output
>> of query-qmp-schema or query-command-line-options.  Tolerable, because
>> it's meant for testing.  If running with -compat fails, skip the test.
>
> Not to mention, once we finish QAPIfying the command line, we could
> make sure it is visible through introspection at that time (it may
> require tagging the command line option with a feature, if nothing
> else makes it pop through).
>
>> 
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> Acked-by: John Snow <jsnow@redhat.com>
>> ---
>>  qapi/compat.json              |  6 +++++-
>>  include/qapi/util.h           |  1 +
>>  qapi/qmp-dispatch.c           |  6 ++++++
>>  qapi/qobject-output-visitor.c |  8 ++++++--
>>  qemu-options.hx               | 20 +++++++++++++++++++-
>>  scripts/qapi/events.py        | 10 ++++++----
>>  scripts/qapi/schema.py        | 10 ++++++----
>>  7 files changed, 49 insertions(+), 12 deletions(-)
>> 
>> diff --git a/qapi/compat.json b/qapi/compat.json
>> index 74a8493d3d..9bc9804abb 100644
>> --- a/qapi/compat.json
>> +++ b/qapi/compat.json
>> @@ -47,9 +47,13 @@
>>  #
>>  # @deprecated-input: how to handle deprecated input (default 'accept')
>>  # @deprecated-output: how to handle deprecated output (default 'accept')
>> +# @unstable-input: how to handle unstable input (default 'accept')
>> +# @unstable-output: how to handle unstable output (default 'accept')
>
> Missing '(since 6.2)' doc tags on the two new policies.

Fixing...

>>  #
>>  # Since: 6.0
>>  ##
>>  { 'struct': 'CompatPolicy',
>>    'data': { '*deprecated-input': 'CompatPolicyInput',
>> -            '*deprecated-output': 'CompatPolicyOutput' } }
>> +            '*deprecated-output': 'CompatPolicyOutput',
>> +            '*unstable-input': 'CompatPolicyInput',
>> +            '*unstable-output': 'CompatPolicyOutput' } }
>> diff --git a/include/qapi/util.h b/include/qapi/util.h
>> index 0cc98db9f9..81a2b13a33 100644
>> --- a/include/qapi/util.h
>> +++ b/include/qapi/util.h
>> @@ -13,6 +13,7 @@
>>  
>>  typedef enum {
>>      QAPI_DEPRECATED,
>> +    QAPI_UNSTABLE,
>>  } QapiSpecialFeature;
>
>> +++ b/qemu-options.hx
>> @@ -3641,7 +3641,9 @@ DEFHEADING(Debug/Expert options:)
>>  
>>  DEF("compat", HAS_ARG, QEMU_OPTION_compat,
>>      "-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]\n"
>> -    "                Policy for handling deprecated management interfaces\n",
>> +    "                Policy for handling deprecated management interfaces\n"
>> +    "-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]\n"
>> +    "                Policy for handling unstable management interfaces\n",
>
> It may not be machine-introspectible, but at least we can grep --help
> output to see when the policy is usable for testing.
>
>>      QEMU_ARCH_ALL)
>>  SRST
>>  ``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]``
>> @@ -3659,6 +3661,22 @@ SRST
>>          Suppress deprecated command results and events
>>  
>>      Limitation: covers only syntactic aspects of QMP.
>> +
>> +``-compat [unstable-input=@var{input-policy}][,unstable-output=@var{output-policy}]``
>> +    Set policy for handling unstable management interfaces (experimental):
>
> Once we QAPIfy the command line, this says we would add the 'unstable'
> feature flag to '-compat unstable-input'.  How meta ;)

Yes :)

>                                                        And goes along
> with your comments earlier in the series about how we may use the
> 'unstable' feature even without the 'x-' naming prefix, once it is
> machine-detectible.
>
> With the doc tweak,
> Reviewed-by: Eric Blake <eblake@redhat.com>

Thanks!