ShuriZma
/
xemu
mirror of https://github.com/xemu-project/xemu.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs/devel/qapi-code-gen: Rewrite introduction to schema 

The introduction to the QAPI schema is somewhat rambling.  Rewrite for
clarity.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-15-armbru@redhat.com>
This commit is contained in:
Markus Armbruster 2019-09-13 22:13:47 +02:00
parent ab76bc2794
commit 634c82c163
1 changed files with 38 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
docs/devel/qapi-code-gen.txt
View File

@ -16,65 +16,54 @@ well as the QEMU Guest Agent (QGA) for communicating with the guest.
The remainder of this document uses "Client JSON Protocol" when The remainder of this document uses "Client JSON Protocol" when
referring to the wire contents of a QMP or QGA connection. referring to the wire contents of a QMP or QGA connection.
To map Client JSON Protocol interfaces to the native C QAPI To map between Client JSON Protocol interfaces and the native C API,
implementations, a JSON-based schema is used to define types and we generate C code from a QAPI schema. This document describes the
function signatures, and a set of scripts is used to generate types, QAPI schema language, and how it gets mapped to the Client JSON
signatures, and marshaling/dispatch code. This document will describe Protocol and to C. It additionally provides guidance on maintaining
how the schemas, scripts, and resulting code are used. Client JSON Protocol compatibility.
== QMP/Guest agent schema == == The QAPI schema language ==
A QAPI schema file is designed to be loosely based on JSON The QAPI schema defines the Client JSON Protocol's commands and
(http://www.ietf.org/rfc/rfc8259.txt) with changes for quoting style events, as well as types used by them. Forward references are
and the use of comments; a QAPI schema file is then parsed by a python allowed.
code generation program. A valid QAPI schema consists of a series of
top-level expressions, with no commas between them. Where It is permissible for the schema to contain additional types not used
dictionaries (JSON objects) are used, they are parsed as python by any commands or events, for the side effect of generated C code
OrderedDicts so that ordering is preserved (for predictable layout of used internally.
generated C structs and parameter lists). Ordering doesn't matter
between top-level expressions or the keys within an expression, but There are several kinds of types: simple types (a number of built-in
does matter within dictionary values for 'data' and 'returns' members types, such as 'int' and 'str'; as well as enumerations), arrays,
of a single expression. QAPI schema input is written using 'single complex types (structs and two flavors of unions), and alternate types
quotes' instead of JSON's "double quotes" (in contrast, Client JSON (a choice between other types).
Protocol uses no comments, and while input accepts 'single quotes' as
an extension, output is strict JSON using only "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). At present, there is no place where a QAPI
schema requires the use of JSON numbers or null.
=== Comments === === Schema syntax ===
Comments are allowed; anything between an unquoted # and the following Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt).
newline is ignored. Differences:
* Comments: start with a hash character (#) that is not part of a
string, and extend to the end of the line.
=== Schema overview === * Strings are enclosed in 'single quotes', not "double quotes".
The schema sets up a series of types, as well as commands and events * Strings are restricted to printable ASCII, and escape sequences to
that will use those types. Forward references are allowed: the parser just '\\'.
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 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 eight top-level expressions recognized by the parser: * Numbers are not supported.
'include', 'pragma', 'command', 'struct', 'enum', 'union',
'alternate', and 'event'. There are several groups of types: simple A QAPI schema consists of a series of top-level expressions (JSON
types (a number of built-in types, such as 'int' and 'str'; as well as objects). Code and documentation is generated in schema definition
enumerations), complex types (structs and two flavors of unions), and order. Code order should not matter.
alternate types (a choice between other types). The 'command' and
'event' expressions can refer to existing types by name, or list an The order of keys within JSON objects does not matter unless
anonymous type as a dictionary. Listing a type name inside an array explicitly noted.
refers to a single-dimension array of that type; multi-dimension
arrays are not directly supported (although an array of a complex There are eight kinds of top-level expressions: 'include', 'pragma',
struct that contains an array member is possible). 'command', 'struct', 'enum', 'union', 'alternate', and 'event'. These
are discussed in detail below.
In the rest of this document, usage lines are given for each In the rest of this document, usage lines are given for each
expression type, with literal strings written in lower case and expression type, with literal strings written in lower case and