haraldwolff/qemu-patch-raspberry4
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

docs/devel/qapi-code-gen: Minor specification fixes

Browse source 
The specification claims "Each expression that isn't an include
directive may be preceded by a documentation block", but the code also
rejects them for pragma directives.  The code is correct.  Fix the
specification.

The specification reserves member names starting with 'has_', but the
code also reserves name 'u'.  Fix the specification.

The specification claims "The string 'max' is not allowed as an enum
value".  Untrue.  Fix the specification.  While there, delete the
naming advice, because it's redundant with the naming rules in section
"Schema overview"

The specification claims "No branch of the union can be named 'max',
as this would collide with the implicit enum".  Untrue.  Fix the
specification.

The specification claims "It is not allowed to name an event 'MAX',
since the generator also produces a C enumeration of all event names
with a generated _MAX value at the end."  Untrue.  Fix the
specification.

The specification claims "All branches of the union must be complex
types", but the code permits only struct types.  The code is correct.
Fix the specification.

The specification claims a command's return type "must be the string
name of a complex or built-in type, a one-element array containing the
name of a complex or built-in type" unless the command is in pragma
'returns-whitelist'.  The code does not permit built-in types.  Fix
the specification.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-5-armbru@redhat.com>
This commit is contained in:
Markus Armbruster 2019-09-13 22:13:37 +02:00
parent b22e86585b
commit e24fe238e2
1 changed files with 16 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
docs/devel/qapi-code-gen.txt
View file

@ -117,9 +117,9 @@ Example:
==== Expression documentation ==== ==== Expression documentation ====
Each expression that isn't an include directive may be preceded by a Expressions other than include and pragma directives may be preceded
documentation block. Such blocks are called expression documentation by a documentation block. Such blocks are called expression
blocks. documentation blocks.
When documentation is required (see pragma 'doc-required'), expression When documentation is required (see pragma 'doc-required'), expression
documentation blocks are mandatory. documentation blocks are mandatory.
@ -243,8 +243,9 @@ underscore.
Event names should be ALL_CAPS with words separated by underscore. Event names should be ALL_CAPS with words separated by underscore.
Member names starting with 'has-' or 'has_' are reserved for the Member name 'u' and names starting with 'has-' or 'has_' are reserved
generator, which uses them for tracking optional members. for the generator, which uses them for unions and for tracking
optional members.
Any name (command, event, type, member, or enum value) beginning with Any name (command, event, type, member, or enum value) beginning with
"x-" is marked experimental, and may be withdrawn or changed "x-" is marked experimental, and may be withdrawn or changed
@ -460,15 +461,14 @@ discriminator value, as in these examples:
The generated C code uses a struct containing a union. Additionally, The generated C code uses a struct containing a union. Additionally,
an implicit C enum 'NameKind' is created, corresponding to the union an implicit C enum 'NameKind' is created, corresponding to the union
'Name', for accessing the various branches of the union. No branch of 'Name', for accessing the various branches of the union. The value
the union can be named 'max', as this would collide with the implicit for each branch can be of any type.
enum. The value for each branch can be of any type.
A flat union definition avoids nesting on the wire, and specifies a A flat union definition avoids nesting on the wire, and specifies a
set of common members that occur in all variants of the union. The set of common members that occur in all variants of the union. The
'base' key must specify either a type name (the type must be a 'base' key must specify either a type name (the type must be a
struct, not a union), or a dictionary representing an anonymous type. struct, not a union), or a dictionary representing an anonymous type.
All branches of the union must be complex types, and the top-level All branches of the union must be struct types, and the top-level
members of the union dictionary on the wire will be combination of members of the union dictionary on the wire will be combination of
members from both the base type and the appropriate branch type (when members from both the base type and the appropriate branch type (when
merging two dictionaries, there must be no keys in common). The merging two dictionaries, there must be no keys in common). The
@ -578,8 +578,8 @@ The 'returns' member describes what will appear in the "return" member
of a Client JSON Protocol reply on successful completion of a command. of a Client JSON Protocol reply on successful completion of a command.
The member is optional from the command declaration; if absent, the The member is optional from the command declaration; if absent, the
"return" member will be an empty dictionary. If 'returns' is present, "return" member will be an empty dictionary. If 'returns' is present,
it must be the string name of a complex or built-in type, a it must be the string name of a complex type, or a
one-element array containing the name of a complex or built-in type. one-element array containing the name of a complex type.
To return anything else, you have to list the command in pragma To return anything else, you have to list the command in pragma
'returns-whitelist'. If you do this, the command cannot be extended 'returns-whitelist'. If you do this, the command cannot be extended
to return additional information in the future. Use of to return additional information in the future. Use of
@ -691,13 +691,11 @@ started with --preconfig.
Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
'*boxed': true } '*boxed': true }
Events are defined with the keyword 'event'. It is not allowed to Events are defined with the keyword 'event'. When 'data' is also
name an event 'MAX', since the generator also produces a C enumeration specified, additional info will be included in the event, with similar
of all event names with a generated _MAX value at the end. When semantics to a 'struct' expression. Finally there will be C API
'data' is also specified, additional info will be included in the generated in qapi-events.h; when called by QEMU code, a message with
event, with similar semantics to a 'struct' expression. Finally there timestamp will be emitted on the wire.
will be C API generated in qapi-events.h; when called by QEMU code, a
message with timestamp will be emitted on the wire.
An example event is: An example event is: