Message ID | 20210608120723.2268181-2-marcandre.lureau@redhat.com |
---|---|
State | New |
Headers | show |
Series | qapi: untie 'if' conditions from C preprocessor | expand |
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
Hi On Tue, Jun 15, 2021 at 3:53 PM Markus Armbruster <armbru@redhat.com> wrote: > 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. > done > > > > 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 > > ok > > > > 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 > > >
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 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