@@ -5,7 +5,9 @@ This document is licensed under the GPLv2 (or later).
QAPI is a native C API within QEMU which provides management-level
functionality to internal and external users. For external
users/processes, this interface is made available by a JSON-based
-QEMU Monitor protocol that is provided by the QMP server.
+wire format for the QEMU Monitor Protocol (QMP) for controlling
+qemu, as well as the QEMU Guest Agent (QGA) for communicating with the
+guest.
To map QMP-defined interfaces to the native C QAPI implementations, a
JSON-based schema is used to define types and function signatures, and
@@ -20,21 +22,28 @@ code are used.
== QMP/Guest agent schema ==
-This file defines the types, commands, and events used by QMP. It should
-fully describe the interface used by QMP.
+This file defines the types, commands, and events documented in a QAPI
+schema. The QMP and QGA protocols should be fully described by their
+respective schema. The remainder of this document uses "Client JSON
+Protocol" when referring to the wire contents of a QMP or QGA
+connection.
-A QAPI file is designed to be loosely based on JSON, which is then
-parsed by a python code generation program. A valid QAPI schema
-consists of a list of top-level expressions, with no commas between
-them. Where dictionaries are used, they are parsed as OrderedDicts so
-that ordering is preserved (for predictable layout of generated C
-structs and parameter lists). Ordering doesn't matter for top-level
-expressions, but does matter within 'data' members of a single
-expression. QAPI input is written using 'single quotes' instead of
-JSON's "double quotes" (in contrast, QMP is strict JSON and only uses
-"double quotes"). As in JSON, trailing commas are not permitted in
-arrays or dictionaries. Input must be ASCII (although QMP supports
-full Unicode strings, the QAPI parser does not).
+A QAPI file is designed to be loosely based on JSON
+(http://www.ietf.org/rfc/rfc7159.txt), which is then parsed by a
+python code generation program. A valid QAPI schema consists of a
+list of top-level expressions, all resembling JSON objects, with no
+commas between expressions. Where dictionaries (JSON objects) are
+used, they are parsed as OrderedDicts so that ordering is preserved
+(for predictable layout of generated C structs and parameter lists).
+Ordering doesn't matter between top-level expressions or for the
+top-level keys within the expression, but does matter within 'data'
+members of a single expression. QAPI input is written using 'single
+quotes' instead of JSON's "double quotes" (in contrast, client use of
+JSON Protocol is strict JSON and only uses "double quotes"). As in
+JSON, trailing commas are not permitted in arrays or dictionaries.
+Input must be ASCII (although Client JSON Protocol supports full
+Unicode strings, the QAPI parser does not). At present, there is no
+place where a QAPI schema requires the use of JSON numbers or null.
Comments are allowed; anything between an unquoted # and the following
newline is ignored. Although there is not yet a documentation
@@ -76,8 +85,11 @@ that will use those types. Forward references are allowed: the parser
scans in two passes, where the first pass learns all type names, and
the second validates the schema and generates the code. This allows
the definition of complex structs that can have mutually recursive
-types, and allows for indefinite nesting of QMP that satisfies the
-schema. A type name should not be defined more than once.
+types, and allows for indefinite nesting of Client JSON Protocol that
+satisfies the schema. A type name should not be defined more than
+once. It is permissible for the schema to contain additional types
+not used by any commands or events in the Client JSON Protocol, for
+the side effect of generated C code used internally.
There are seven top-level expressions recognized by the parser:
'include', 'command', 'type', 'enum', 'union', 'alternate', and
@@ -175,7 +187,7 @@ complex type is:
'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
The use of '*' as a prefix to the name means the member is optional in
-the corresponding QMP usage.
+the corresponding JSON protocol usage.
The default initialization value of an optional argument should not be changed
between versions of QEMU unless the new default maintains backward
@@ -206,8 +218,8 @@ of use.
A complex type definition can specify another complex type as its base.
In this case, the fields of the base type are included as top-level fields
-of the new complex type's dictionary in the QMP wire format. An example
-definition is:
+of the new complex type's dictionary in the Client JSON Protocol wire
+format. An example definition is:
{ 'type': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
{ 'type': 'BlockdevOptionsGenericCOWFormat',
@@ -235,19 +247,19 @@ useful. The list of strings should be lower case; if an enum name
represents multiple words, use '-' between words. The string 'max' is
not allowed as an enum value, and values should not be repeated.
-The enumeration values are passed as strings over the QMP protocol,
-but are encoded as C enum integral values in generated code. While
-the C code starts numbering at 0, it is better to use explicit
+The enumeration values are passed as strings over the Client JSON
+Protocol, but are encoded as C enum integral values in generated code.
+While the C code starts numbering at 0, it is better to use explicit
comparisons to enum values than implicit comparisons to 0; the C code
will also include a generated enum member ending in _MAX for tracking
the size of the enum, useful when using common functions for
converting between strings and enum values. Since the wire format
always passes by name, it is acceptable to reorder or add new
-enumeration members in any location without breaking QMP clients;
-however, removing enum values would break compatibility. For any
-complex type that has a field that will only contain a finite set of
-string values, using an enum type for that field is better than
-open-coding the field to be type 'str'.
+enumeration members in any location without breaking clients of Client
+JSON Protocol; however, removing enum values would break
+compatibility. For any complex type that has a field that will only
+contain a finite set of string values, using an enum type for that
+field is better than open-coding the field to be type 'str'.
=== Union types ===
@@ -273,7 +285,7 @@ values to data types like in this example:
'data': { 'file': 'FileOptions',
'qcow2': 'Qcow2Options' } }
-In the QMP wire format, a simple union is represented by a dictionary that
+In the Client JSON Protocol, a simple union is represented by a dictionary that
contains the 'type' field as a discriminator, and a 'data' field that is of the
specified data type corresponding to the discriminator value:
@@ -288,8 +300,8 @@ 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 common to all branches of the union, and the
+type are included as top-level fields of the union, common to all
+branches of the dictionary in the Client JSON Protocol, and the
'discriminator' field must be the name of an enum-typed member of the
base type. An example definition is:
@@ -337,17 +349,18 @@ An alternate type is one that allows a choice between two or more JSON
data types on the wire. The definition is similar to a simple union
type, where each branch of the dictionary names a QAPI type, and where
an implicit C enum NameKind is created for the alternate Name. But
-unlike a union, the discriminator string is never passed on the wire
-for QMP, instead appearing only in the generated C code. Rather, the
-first byte of the value on the wire serves an implicit discriminator:
-if the branch is typed as the 'bool' built-in, it accepts true and
-false; if it is typed as any of the various numeric built-ins, it
-accepts a JSON number; if it is typed as a 'str' built-in or named
-enum types it accepts a JSON string, and if it is typed as a named
-struct or union type it accepts a JSON object. Thus, an alternate can
-express a choice between a string and a single complex type (passed as
-a dictionary), but cannot distinguish between two different complex
-types or two different numeric built-in types. For example:
+unlike a union, the discriminator string is never passed in the Client
+JSON Protocol, instead appearing only in the generated C code.
+Rather, the first byte of the value on the wire serves an implicit
+discriminator: if the branch is typed as the 'bool' built-in, it
+accepts true and false; if it is typed as any of the various numeric
+built-ins, it accepts a JSON number; if it is typed as a 'str'
+built-in or named enum types it accepts a JSON string, and if it is
+typed as a named struct or union type it accepts a JSON object. Thus,
+an alternate can express a choice between a string and a single
+complex type (passed as a dictionary), but cannot distinguish between
+two different complex types or two different numeric built-in types.
+For example:
{ 'alternate': 'BlockRef',
'data': { 'definition': 'BlockdevOptions',
@@ -369,37 +382,37 @@ Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
Commands are defined by using a dictionary containing several members,
where three members are most common. The 'command' member is a
-mandatory string, and determines the "execute" value passed in a QMP
-command exchange.
+mandatory string, and determines the "execute" value passed in a
+Client JSON Protocol command exchange.
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.
+part of a Client JSON Protocol 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 'returns' member describes what will appear in the "return" field
-of a QMP reply on successful completion of a command. The member is
-optional from the command declaration; if absent, the "return" field
-will be an empty dictionary. If 'returns' is present, it 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, 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.
-Although it is permitted to have the 'returns' member name a built-in
-type or an array of built-in types, any command that does this cannot
-be extended to return additional information in the future; thus, new
-commands should strongly consider returning a dictionary-based type or
-an array of dictionaries, even if the dictionary only contains one
-field at the present.
+of a Client JSON Protocol reply on successful completion of a command.
+The member is optional from the command declaration; if absent, the
+"return" field will be an empty dictionary. If 'returns' is present,
+it 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,
+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. Although it is permitted to have the 'returns' member
+name a built-in type or an array of built-in types, any command that
+does this cannot be extended to return additional information in the
+future; thus, new commands should strongly consider returning a
+dictionary-based type or an array of dictionaries, even if the
+dictionary only contains one field at the present.
-All commands use a dictionary to report failure, with no way to
-specify that in QAPI. Where the error return is different than the
-usual GenericError class in order to help the client react differently
-to certain error conditions, it is worth documenting this in the
-comments before the command declaration.
+All commands in Client JSON Protocol use a dictionary to report
+failure, with no way to specify that in QAPI. Where the error return
+is different than the usual GenericError class in order to help the
+client react differently to certain error conditions, it is worth
+documenting this in the comments before the command declaration.
Some example commands:
@@ -409,7 +422,7 @@ Some example commands:
{ 'command': 'my-second-command',
'returns': [ 'MyType' ] }
-which would validate this QMP transaction:
+which would validate this Client JSON Protocol transaction:
=> { "execute": "my-first-command",
"arguments": { "arg1": "hello" } }
@@ -418,12 +431,13 @@ which would validate this QMP transaction:
<= { "return": [ { "value": "one" }, { } ] }
In rare cases, QAPI cannot express a type-safe representation of a
-corresponding QMP command. In these cases, if the command expression
-includes the key 'gen' with boolean value false, then the 'data' or
-'returns' member that intends to bypass generated type-safety and do
-its own manual validation should use '**' rather than a valid type
-name. Please try to avoid adding new commands that rely on this, and
-instead use type-safe unions. For an example of bypass usage:
+corresponding Client JSON Protocol command. In these cases, if the
+command expression includes the key 'gen' with boolean value false,
+then the 'data' or 'returns' member that intends to bypass generated
+type-safety and do its own manual validation should use '**' rather
+than a valid type name. Please try to avoid adding new commands that
+rely on this, and instead use type-safe unions. For an example of
+bypass usage:
{ 'command': 'netdev_add',
'data': {'type': 'str', 'id': 'str', '*props': '**'},
@@ -467,9 +481,9 @@ Resulting in this JSON object:
Schemas are fed into 3 scripts to generate all the code/files that, paired
with the core QAPI libraries, comprise everything required to take JSON
-commands read in by a QMP/guest agent server, unmarshal the arguments into
+commands read in by a Client JSON Protocol server, unmarshal the arguments into
the underlying C types, call into the corresponding C function, and map the
-response back to a QMP/guest agent response to be returned to the user.
+response back to a Client JSON Protocol response to be returned to the user.
As an example, we'll use the following schema, which describes a single
complex user-defined type (which will produce a C struct, along with a list
We have more than one qapi schema in use by more than one protocol. Add a new term 'Client JSON Protocol' for use throughout the document, to avoid confusion on whether something refers only to QMP and not QGA. Signed-off-by: Eric Blake <eblake@redhat.com> --- docs/qapi-code-gen.txt | 168 ++++++++++++++++++++++++++----------------------- 1 file changed, 91 insertions(+), 77 deletions(-)