Daniel P. Berrangé <berra...@redhat.com> writes:
> On Wed, May 07, 2025 at 04:14:39PM -0700, Pierrick Bouvier wrote:
>> Signed-off-by: Pierrick Bouvier <pierrick.bouv...@linaro.org>
>> ---
>> qapi/machine-target.json | 84 ++++++++++++++++++++++++----------------
>> qapi/misc-target.json | 48 ++++++++++++-----------
>> scripts/qapi/expr.py | 9 +++--
>> 3 files changed, 81 insertions(+), 60 deletions(-)
>>
>> diff --git a/qapi/machine-target.json b/qapi/machine-target.json
>> index 541f93eeb78..6174b7291ca 100644
>> --- a/qapi/machine-target.json
>> +++ b/qapi/machine-target.json
>> @@ -96,7 +96,7 @@
>> ##
>> { 'struct': 'CpuModelBaselineInfo',
>> 'data': { 'model': 'CpuModelInfo' },
>> - 'if': 'TARGET_S390X' }
>> + 'runtime_if': 'target_s390x()' }
>
> The existing 'if' conditions are already slightly uncomfortable
> for QAPI when considering alternate code generators, because the
> definition of what "CONFIG_xxx" or "TARGET_xxx" condition means,
> is essentially known only to our build system. While we expose
> the conditions in the docs, the meaning of those conditions is
> totally opaque to anyone reading the docs. Essentially our QAPI
> schema ceased to be self-documenting/self-describing when we
> introduced the 'if' conditions :-(
>
>
> In retrospect, IMHO, for 'if' conditions we probably should have
> created some kind of built-in QAPI concept of feature flag constants
> with well defined & documented meaning.
>
> eg hypothetically
>
> ##
> # @target-s390x
> #
> # Whether this is an s390x emulator target
> { 'constant': 'target-s390x' }
>
> ##
> # @accel-kvm
> #
> # Whether the KVM accelerator is built
> { 'constant': 'accel-kvm' }
>
> Then our 'if' conditions would have only been permitted to
> reference defined 'constant'.
>
> { 'struct': 'CpuModelCompareInfo',
> 'data': { 'result': 'CpuModelCompareResult',
> 'responsible-properties': ['str'] },
> 'if': 'target-s390x' }
This adds mandatory declaration of identifiers used in conditions to the
QAPI schema language.
The declarations can then serve as hooks for doc comments. These should
ineed result in a more complete and useful generated manual. John,
thoughts?
The condition documentation would supplement / partially duplicate the
configure flag documentation in meson_options.txt.
We'd need to tie the two together to make the code work (see your next
paragraph). We should also tie their documentation together somehow.
Feels like a solvable problem.
> The build system would need generate an input document for the
> QAPI visitor that defines whether each constant is set to true
> or false, based on suitable CONFIG/TARGET conditions from meson.
I think the conditions that are evaluated at build time in handwritten C
code (with #if) should also be evaluated at build time in generated C
code.
Certain conditions are evaluated at build time in target-specific code,
and at runtime in target-independent code. Again, I think handwritten
and generated code should work the same way.
Thus, to eliminate target-specific QAPI-generated code, we either
evaluate them at runtime, or simply eliminate them. Elsewhere, we've
come to the conclusion (I think) that the latter should do at least for
now, likely forever, so we should try that first.
> With this QAPI schemas would have remained fully self-contained.
Fortunately, this is merely a matter of filling a gap we left, not a
matter of replacing a fundamentally flawed design.
> Anyway, this is a long way of saying that having 'runtime_if'
> conditions directly referencing the names of internal C
> functions makes me even more uncomfortable than I already am
> with the 'if' conditions.
>
> The meaning of the QAPI schema now varies based on both the build
> system, and an arbitrary amount of C, and is thus (conceptually)
> even more opaque, even if you could infer some meaning from the
> 'target_s390x()' function name you've used. I think this is a very
> undesirable characteristic for what is our public API definition.
I don't see much of a difference, to be honest.
Both kinds of conditionals have the exact same argument structure:
expression tree where the leaves are identifiers.
The meaning of these identifiers is not documented in the QAPI schema
now, and barely documented in the code.
This defect could be remedied the exact same way whether the identifiers
are preprocessor macros or function names.
I actually find another argument of yours (not repeated above) more
compelling: that certain aspects of the external interface should not
vary at runtime.
