OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

docs: update the documentation upfront about schema configuration

Browse Source 
Update the documentation describing the changes in this series.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Tested-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20210804083105.97531-2-marcandre.lureau@redhat.com>
[Rebased with straightforward conflicts]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
Marc-André Lureau 2021-08-04 12:30:56 +04:00 committed by Markus Armbruster
parent b32abbb2f5
commit 3248c1aaf2
1 changed files with 18 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/devel/qapi-code-gen.rst
View File

@ -826,25 +826,31 @@ Configuring the schema
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 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
@ -855,7 +861,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.
@ -867,7 +873,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_.
@ -877,7 +883,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