Leonardo Bras Soares Passos <leob...@redhat.com> writes:
[...]
>> The general argument for having QAPI schema 'if' mirror the C
>> implementation's #if is introspection. Let me explain why that matters.
>>
>> Consider a management application that supports a range of QEMU
>> versions, say 5.0 to 6.2. Say it wants to use an QMP command that is
>> new in QEMU 6.2. The sane way to do that is to probe for the command
>> with query-qmp-schema. Same for command arguments, and anything else
>> QMP.
>>
>> If you doubt "sane", check out Part II of "QEMU interface introspection:
>> From hacks to solutions"[*].
>>
>> The same technique works when a QMP command / argument / whatever is
>> compile-time conditional ('if' in the schema). The code the management
>> application needs anyway to deal with older QEMU now also deals with
>> "compiled out". Nice.
>>
>> Of course, a command or argument present in QEMU can still fail, and the
>> management application still needs to handle failure. Distinguishing
>> different failure modes can be bothersome and/or fragile.
>>
>> By making the QAPI schema conditional mirror the C conditional, you
>> squash the failure mode "this version of QEMU supports it, but this
>> build of QEMU does not" into "this version of QEMU does not support
>> it". Makes sense, doesn't it?
>>
>> A minor additional advantage is less generated code.
>>
>>
>>
>> [*]
>> http://events17.linuxfoundation.org/sites/events/files/slides/armbru-qemu-introspection.pdf
>>
>
> This was very informative, thanks!
> I now understand the rationale about this choice.
>
> TBH I am not very used to this syntax.
> I did a take a peek at some other json files, and ended adding this
> lines in code, which compiled just fine:
>
> for : enum MigrationParameter
> {'name': 'multifd-zerocopy', 'if' : 'CONFIG_LINUX'},
>
> for : struct MigrateSetParameters and struct MigrationParameters:
> '*multifd-zerocopy': { 'type': 'bool', 'if': 'CONFIG_LINUX' },
>
> Is that enough? Is there any other necessary change?
Looks good to me.
The QAPI schema language is documented in docs/devel/qapi-code-gen.rst.
If you're curious, you can diff code generated into qapi/ before and
after adding the 'if'.
> Thanks for reviewing and for helping out with this!
My pleasure!
