@@ -82,13 +82,14 @@ schema. A type name should not be defined more than once.
There are seven top-level expressions recognized by the parser:
'include', 'command', 'type', 'enum', 'union', 'alternate', and
'event'. There are several built-in types, such as 'int' and 'str';
-additionally, the top-level expressions can define complex types,
-enumeration types, two flavors of union types, and an alternate type.
-The 'command' expression can refer to existing types by name, or list
-an anonymous type as a dictionary. Listing a type name inside an
-array refers to a single-dimension array of that type; multi-dimension
-arrays are not directly supported (although an array of a complex
-struct that contains an array member is possible).
+additionally, the top-level expressions can define complex types
+(structs and two flavors of unions), as well as enumeration and
+alternate types. The 'command' and 'event' expressions can refer to
+existing types by name, or list an anonymous type as a dictionary.
+Listing a type name inside an array refers to a single-dimension array
+of that type; multi-dimension arrays are not directly supported
+(although an array of a complex struct that contains an array member
+is possible).
Types, commands, and events share a common namespace. Therefore,
generally speaking, type definitions should always use CamelCase for
@@ -117,6 +118,12 @@ underscore. It is okay to reuse names that match C keywords; the
generator will rename a field named "default" in the QAPI to
"q_default" in the generated C code.
+In the rest of this document, usage lines are given for each
+expression type, written in the style of the QAPI syntax. For
+example, a usage statement that includes '*base':'complex-type-name'
+means that an expression has an optional key 'base', which if present
+must have a value that forms a 'complex-type-name'.
+
=== Built-in Types ===
@@ -138,7 +145,7 @@ Usage: { 'include': 'str' }
The QAPI schema definitions can be modularized using the 'include' directive:
- { 'include': 'path/to/file.json'}
+ { 'include': 'path/to/file.json' }
The directive is evaluated recursively, and include paths are relative to the
file using the directive. Multiple includes of the same file are
@@ -159,8 +166,8 @@ Usage: { 'type': 'str', 'data': 'dict', '*base': 'complex-type-name' }
A complex type is a dictionary containing a single 'data' key whose
value is a dictionary. This corresponds to a struct in C or an Object
in JSON. Each value of the 'data' dictionary must be the name of a
-complex, enum, union, alternate, or built-in type, or a one-element
-array containing a type name. An example of a complex type is:
+type, or a one-element array containing a type name. An example of a
+complex type is:
{ 'type': 'MyType',
'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
@@ -280,8 +287,9 @@ implicit enum.
A flat union definition specifies a complex type as its base, and
avoids nesting on the wire. In this case, the fields of the complex
type are included as top-level fields of the union dictionary in the
-QMP wire format, and the 'discriminator' field must be the name of an
-enum-typed member of the base type. An example definition is:
+QMP wire format common to all branches of the union, and the
+'discriminator' field must be the name of an enum-typed member of the
+base type. An example definition is:
{ 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
{ 'union': 'BlockdevOptions',
@@ -350,7 +358,7 @@ This example allows using both of the following example objects:
=== Commands ===
Usage: { 'command': 'str', '*data': 'dict-or-complex-type-name',
- '*returns': 'type',
+ '*returns': 'dict-or-type-name',
'*gen': false, '*success-response': false }
Commands are defined by using a dictionary containing several members,
@@ -358,13 +366,13 @@ where three members are most common. The 'command' member is a
mandatory string, and determines the "execute" value passed in a QMP
command exchange.
-The 'data' member is optional; if absent, the command accepts an
-optional empty dictionary. If present, it must be the string name of
-a complex type, a one-element array containing the name of a complex
+The 'data' argument maps to the "arguments" dictionary passed in as
+part of a QMP command. The 'data' member is optional and defaults to
+{} (an empty dictionary). If present, it must be the string name of a
+complex type, a one-element array containing the name of a complex
type, or a dictionary that declares an anonymous type with the same
semantics as a 'type' expression, with one exception noted below when
-'gen' is used. The 'data' argument maps to the "arguments" dictionary
-passed in as part of a QMP command.
+'gen' is used.
The 'returns' member describes what will appear in the "return" field
of a QMP reply on successful completion of a command. The member is
Several minor things pointed out by Markus during review of my sweeping changes. Signed-off-by: Eric Blake <eblake@redhat.com> --- docs/qapi-code-gen.txt | 44 ++++++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 18 deletions(-)