|
From: | Marc-André Lureau |
Subject: | Re: [PATCH v5 1/9] docs: update the documentation about schema configuration |
Date: | Fri, 18 Jun 2021 14:32:18 +0400 |
marcandre.lureau@redhat.com writes:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> Update the documentation describing the changes in this series.
Suggest to add "upfront" for clarity.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
> Tested-by: John Snow <jsnow@redhat.com>
> ---
> docs/devel/qapi-code-gen.txt | 30 ++++++++++++++++++------------
> 1 file changed, 18 insertions(+), 12 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index c1cb6f987d..0162b73119 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -781,25 +781,31 @@ downstream command __com.redhat_drive-mirror.
>
> Syntax:
> COND = STRING
> - | [ STRING, ... ]
> + | { 'all: [ COND, ... ] }
> + | { 'any: [ COND, ... ] }
> + | { 'not': COND }
>
> All definitions take an optional 'if' member. Its value must be a
> -string or a list of strings. A string is shorthand for a list
> -containing just that string. The code generated for the definition
> -will then be guarded by #if STRING for each STRING in the COND list.
> +string, or an object with a single member 'all', 'any' or 'not'.
> +
> +The C code generated for the definition will then be guarded by an #if
> +preprocessing directive generated from that condition:
> +
> + * STRING will generate #if defined(STRING)
> + * { 'all': [COND, ...] } will generate #if (COND && ...)
> + * { 'any': [COND, ...] } will generate #if (COND || ...)
> + * { 'not': COND } will generate #if !COND
I know this is exactly what I suggested. It gets the point across, but
it's not quite accurate: the #if of course only at the root of the tree,
not at every level. Better, I think:
The C code generated for the definition will then be guarded by an #if
preprocessing directive with an operand generated from that condition:
* STRING will generate defined(STRING)
* { 'all': [COND, ...] } will generate (COND && ...)
* { 'any': [COND, ...] } will generate (COND || ...)
* { 'not': COND } will generate !COND
>
> Example: a conditional struct
>
> { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
> - 'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] }
> + 'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } }
>
> gets its generated code guarded like this:
>
> - #if defined(CONFIG_FOO)
> - #if defined(HAVE_BAR)
> + #if defined(CONFIG_FOO) && defined(HAVE_BAR)
> ... generated code ...
> - #endif /* defined(HAVE_BAR) */
> - #endif /* defined(CONFIG_FOO) */
> + #endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */
>
> Individual members of complex types, commands arguments, and
> event-specific data can also be made conditional. This requires the
> @@ -810,7 +816,7 @@ member 'bar'
>
> { 'struct': 'IfStruct', 'data':
> { 'foo': 'int',
> - 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
> + 'bar': { 'type': 'int', 'if': 'IFCOND'} } }
>
> A union's discriminator may not be conditional.
>
> @@ -822,7 +828,7 @@ value 'bar'
>
> { 'enum': 'IfEnum', 'data':
> [ 'foo',
> - { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
> + { 'name' : 'bar', 'if': 'IFCOND' } ] }
>
> Likewise, features can be conditional. This requires the longhand
> form of FEATURE.
> @@ -832,7 +838,7 @@ Example: a struct with conditional feature 'allow-negative-numbers'
> { 'struct': 'TestType',
> 'data': { 'number': 'int' },
> 'features': [ { 'name': 'allow-negative-numbers',
> - 'if': 'defined(IFCOND)' } ] }
> + 'if': 'IFCOND' } ] }
>
> Please note that you are responsible to ensure that the C code will
> compile with an arbitrary combination of conditions, since the
[Prev in Thread] | Current Thread | [Next in Thread] |