docs: convert qapi-code-gen.txt to ReST

This is a very rudimentary conversion from .txt to .rst changing as
little as possible, but getting it to render somewhat nicely; without
using any Sphinx directives. (It is 'native' ReST.)

Further patches will add cross-references and Sphinx-specific extensions
to make it sparkle.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-Id: <20210720235619.2048797-2-jsnow@redhat.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

1 files changed, 1969 insertions, 0 deletions

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
new file mode 100644
index 0000000..9155dba
--- /dev/null
+++ b/docs/devel/qapi-code-gen.rst
@@ -0,0 +1,1969 @@
+==================================
+How to use the QAPI code generator
+==================================
+
+..
+   Copyright IBM Corp. 2011
+   Copyright (C) 2012-2016 Red Hat, Inc.
+
+   This work is licensed under the terms of the GNU GPL, version 2 or
+   later.  See the COPYING file in the top-level directory.
+
+
+Introduction
+============
+
+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 wire
+format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
+well as the QEMU Guest Agent (QGA) for communicating with the guest.
+The remainder of this document uses "Client JSON Protocol" when
+referring to the wire contents of a QMP or QGA connection.
+
+To map between Client JSON Protocol interfaces and the native C API,
+we generate C code from a QAPI schema.  This document describes the
+QAPI schema language, and how it gets mapped to the Client JSON
+Protocol and to C.  It additionally provides guidance on maintaining
+Client JSON Protocol compatibility.
+
+
+The QAPI schema language
+========================
+
+The QAPI schema defines the Client JSON Protocol's commands and
+events, as well as types used by them.  Forward references are
+allowed.
+
+It is permissible for the schema to contain additional types not used
+by any commands or events, for the side effect of generated C code
+used internally.
+
+There are several kinds of types: simple types (a number of built-in
+types, such as 'int' and 'str'; as well as enumerations), arrays,
+complex types (structs and two flavors of unions), and alternate types
+(a choice between other types).
+
+
+Schema syntax
+-------------
+
+Syntax is loosely based on `JSON <http://www.ietf.org/rfc/rfc8259.txt>`_.
+Differences:
+
+* Comments: start with a hash character (#) that is not part of a
+  string, and extend to the end of the line.
+
+* Strings are enclosed in 'single quotes', not "double quotes".
+
+* Strings are restricted to printable ASCII, and escape sequences to
+  just '\\'.
+
+* Numbers and null are not supported.
+
+A second layer of syntax defines the sequences of JSON texts that are
+a correctly structured QAPI schema.  We provide a grammar for this
+syntax in an EBNF-like notation:
+
+* Production rules look like non-terminal = expression
+* Concatenation: expression A B matches expression A, then B
+* Alternation: expression A | B matches expression A or B
+* Repetition: expression A... matches zero or more occurrences of
+  expression A
+* Repetition: expression A, ... matches zero or more occurrences of
+  expression A separated by ,
+* Grouping: expression ( A ) matches expression A
+* JSON's structural characters are terminals: { } [ ] : ,
+* JSON's literal names are terminals: false true
+* String literals enclosed in 'single quotes' are terminal, and match
+  this JSON string, with a leading '*' stripped off
+* When JSON object member's name starts with '*', the member is
+  optional.
+* The symbol STRING is a terminal, and matches any JSON string
+* The symbol BOOL is a terminal, and matches JSON false or true
+* ALL-CAPS words other than STRING are non-terminals
+
+The order of members within JSON objects does not matter unless
+explicitly noted.
+
+A QAPI schema consists of a series of top-level expressions::
+
+    SCHEMA = TOP-LEVEL-EXPR...
+
+The top-level expressions are all JSON objects.  Code and
+documentation is generated in schema definition order.  Code order
+should not matter.
+
+A top-level expressions is either a directive or a definition::
+
+    TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION
+
+There are two kinds of directives and six kinds of definitions::
+
+    DIRECTIVE = INCLUDE | PRAGMA
+    DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT
+
+These are discussed in detail below.
+
+
+Built-in Types
+--------------
+
+The following types are predefined, and map to C as follows::
+
+  Schema    C          JSON
+  str       char *     any JSON string, UTF-8
+  number    double     any JSON number
+  int       int64_t    a JSON number without fractional part
+                       that fits into the C integer type
+  int8      int8_t     likewise
+  int16     int16_t    likewise
+  int32     int32_t    likewise
+  int64     int64_t    likewise
+  uint8     uint8_t    likewise
+  uint16    uint16_t   likewise
+  uint32    uint32_t   likewise
+  uint64    uint64_t   likewise
+  size      uint64_t   like uint64_t, except StringInputVisitor
+                       accepts size suffixes
+  bool      bool       JSON true or false
+  null      QNull *    JSON null
+  any       QObject *  any JSON value
+  QType     QType      JSON string matching enum QType values
+
+
+Include directives
+------------------
+
+Syntax::
+
+    INCLUDE = { 'include': STRING }
+
+The QAPI schema definitions can be modularized using the 'include' directive::
+
+ { '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 idempotent.
+
+As a matter of style, it is a good idea to have all files be
+self-contained, but at the moment, nothing prevents an included file
+from making a forward reference to a type that is only introduced by
+an outer file.  The parser may be made stricter in the future to
+prevent incomplete include files.
+
+
+Pragma directives
+-----------------
+
+Syntax::
+
+    PRAGMA = { 'pragma': {
+                   '*doc-required': BOOL,
+                   '*command-name-exceptions': [ STRING, ... ],
+                   '*command-returns-exceptions': [ STRING, ... ],
+                   '*member-name-exceptions': [ STRING, ... ] } }
+
+The pragma directive lets you control optional generator behavior.
+
+Pragma's scope is currently the complete schema.  Setting the same
+pragma to different values in parts of the schema doesn't work.
+
+Pragma 'doc-required' takes a boolean value.  If true, documentation
+is required.  Default is false.
+
+Pragma 'command-name-exceptions' takes a list of commands whose names
+may contain '_' instead of '-'.  Default is none.
+
+Pragma 'command-returns-exceptions' takes a list of commands that may
+violate the rules on permitted return types.  Default is none.
+
+Pragma 'member-name-exceptions' takes a list of types whose member
+names may contain uppercase letters, and '_' instead of '-'.  Default
+is none.
+
+
+Enumeration types
+-----------------
+
+Syntax::
+
+    ENUM = { 'enum': STRING,
+             'data': [ ENUM-VALUE, ... ],
+             '*prefix': STRING,
+             '*if': COND,
+             '*features': FEATURES }
+    ENUM-VALUE = STRING
+               | { 'name': STRING, '*if': COND }
+
+Member 'enum' names the enum type.
+
+Each member of the 'data' array defines a value of the enumeration
+type.  The form STRING is shorthand for { 'name': STRING }.  The
+'name' values must be be distinct.
+
+Example::
+
+ { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
+
+Nothing prevents an empty enumeration, although it is probably not
+useful.
+
+On the wire, an enumeration type's value is represented by its
+(string) name.  In C, it's represented by an enumeration constant.
+These are of the form PREFIX_NAME, where PREFIX is derived from the
+enumeration type's name, and NAME from the value's name.  For the
+example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to
+VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1.  The
+optional 'prefix' member overrides PREFIX.
+
+The generated C enumeration constants have values 0, 1, ..., N-1 (in
+QAPI schema order), where N is the number of values.  There is an
+additional enumeration constant PREFIX__MAX with value N.
+
+Do not use string or an integer type when an enumeration type can do
+the job satisfactorily.
+
+The optional 'if' member specifies a conditional.  See "Configuring
+the schema" below for more on this.
+
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
+
+Type references and array types
+-------------------------------
+
+Syntax::
+
+    TYPE-REF = STRING | ARRAY-TYPE
+    ARRAY-TYPE = [ STRING ]
+
+A string denotes the type named by the string.
+
+A one-element array containing a string denotes an array of the type
+named by the string.  Example: ['int'] denotes an array of 'int'.
+
+
+Struct types
+------------
+
+Syntax::
+
+    STRUCT = { 'struct': STRING,
+               'data': MEMBERS,
+               '*base': STRING,
+               '*if': COND,
+               '*features': FEATURES }
+    MEMBERS = { MEMBER, ... }
+    MEMBER = STRING : TYPE-REF
+           | STRING : { 'type': TYPE-REF,
+                        '*if': COND,
+                        '*features': FEATURES }
+
+Member 'struct' names the struct type.
+
+Each MEMBER of the 'data' object defines a member of the struct type.
+
+The MEMBER's STRING name consists of an optional '*' prefix and the
+struct member name.  If '*' is present, the member is optional.
+
+The MEMBER's value defines its properties, in particular its type.
+The form TYPE-REF is shorthand for { 'type': TYPE-REF }.
+
+Example::
+
+ { 'struct': 'MyType',
+   'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } }
+
+A struct type corresponds to a struct in C, and an object in JSON.
+The C struct's members are generated in QAPI schema order.
+
+The optional 'base' member names a struct type whose members are to be
+included in this type.  They go first in the C struct.
+
+Example::
+
+ { 'struct': 'BlockdevOptionsGenericFormat',
+   'data': { 'file': 'str' } }
+ { 'struct': 'BlockdevOptionsGenericCOWFormat',
+   'base': 'BlockdevOptionsGenericFormat',
+   'data': { '*backing': 'str' } }
+
+An example BlockdevOptionsGenericCOWFormat object on the wire could use
+both members like this::
+
+ { "file": "/some/place/my-image",
+   "backing": "/some/place/my-backing-file" }
+
+The optional 'if' member specifies a conditional.  See "Configuring
+the schema" below for more on this.
+
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
+
+Union types
+-----------
+
+Syntax::
+
+    UNION = { 'union': STRING,
+              'data': BRANCHES,
+              '*if': COND,
+              '*features': FEATURES }
+          | { 'union': STRING,
+              'data': BRANCHES,
+              'base': ( MEMBERS | STRING ),
+              'discriminator': STRING,
+              '*if': COND,
+              '*features': FEATURES }
+    BRANCHES = { BRANCH, ... }
+    BRANCH = STRING : TYPE-REF
+           | STRING : { 'type': TYPE-REF, '*if': COND }
+
+Member 'union' names the union type.
+
+There are two flavors of union types: simple (no discriminator or
+base), and flat (both discriminator and base).
+
+Each BRANCH of the 'data' object defines a branch of the union.  A
+union must have at least one branch.
+
+The BRANCH's STRING name is the branch name.
+
+The BRANCH's value defines the branch's properties, in particular its
+type.  The form TYPE-REF is shorthand for { 'type': TYPE-REF }.
+
+A simple union type defines a mapping from automatic discriminator
+values to data types like in this example::
+
+ { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
+ { 'struct': 'BlockdevOptionsQcow2',
+   'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
+
+ { 'union': 'BlockdevOptionsSimple',
+   'data': { 'file': 'BlockdevOptionsFile',
+             'qcow2': 'BlockdevOptionsQcow2' } }
+
+In the Client JSON Protocol, a simple union is represented by an
+object that contains the 'type' member as a discriminator, and a
+'data' member that is of the specified data type corresponding to the
+discriminator value, as in these examples::
+
+ { "type": "file", "data": { "filename": "/some/place/my-image" } }
+ { "type": "qcow2", "data": { "backing": "/some/place/my-image",
+                              "lazy-refcounts": true } }
+
+The generated C code uses a struct containing a union.  Additionally,
+an implicit C enum 'NameKind' is created, corresponding to the union
+'Name', for accessing the various branches of the union.  The value
+for each branch can be of any type.
+
+Flat unions permit arbitrary common members that occur in all variants
+of the union, not just a discriminator.  Their discriminators need not
+be named 'type'.  They also avoid nesting on the wire.
+
+The 'base' member defines the common members.  If it is a MEMBERS
+object, it defines common members just like a struct type's 'data'
+member defines struct type members.  If it is a STRING, it names a
+struct type whose members are the common members.
+
+All flat union branches must be of struct type.
+
+In the Client JSON Protocol, a flat union is represented by an object
+with the common members (from the base type) and the selected branch's
+members.  The two sets of member names must be disjoint.  Member
+'discriminator' must name a non-optional enum-typed member of the base
+struct.
+
+The following example enhances the above simple union example by
+adding an optional common member 'read-only', renaming the
+discriminator to something more applicable than the simple union's
+default of 'type', and reducing the number of {} required on the wire::
+
+ { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
+ { 'union': 'BlockdevOptions',
+   'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
+   'discriminator': 'driver',
+   'data': { 'file': 'BlockdevOptionsFile',
+             'qcow2': 'BlockdevOptionsQcow2' } }
+
+Resulting in these JSON objects::
+
+ { "driver": "file", "read-only": true,
+   "filename": "/some/place/my-image" }
+ { "driver": "qcow2", "read-only": false,
+   "backing": "/some/place/my-image", "lazy-refcounts": true }
+
+Notice that in a flat union, the discriminator name is controlled by
+the user, but because it must map to a base member with enum type, the
+code generator ensures that branches match the existing values of the
+enum.  The order of branches need not match the order of the enum
+values.  The branches need not cover all possible enum values.
+Omitted enum values are still valid branches that add no additional
+members to the data type.  In the resulting generated C data types, a
+flat union is represented as a struct with the base members in QAPI
+schema order, and then a union of structures for each branch of the
+struct.
+
+A simple union can always be re-written as a flat union where the base
+class has a single member named 'type', and where each branch of the
+union has a struct with a single member named 'data'.  That is, ::
+
+ { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
+
+is identical on the wire to::
+
+ { 'enum': 'Enum', 'data': ['one', 'two'] }
+ { 'struct': 'Branch1', 'data': { 'data': 'str' } }
+ { 'struct': 'Branch2', 'data': { 'data': 'int' } }
+ { 'union': 'Flat', 'base': { 'type': 'Enum' }, 'discriminator': 'type',
+   'data': { 'one': 'Branch1', 'two': 'Branch2' } }
+
+The optional 'if' member specifies a conditional.  See "Configuring
+the schema" below for more on this.
+
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
+
+Alternate types
+---------------
+
+Syntax::
+
+    ALTERNATE = { 'alternate': STRING,
+                  'data': ALTERNATIVES,
+                  '*if': COND,
+                  '*features': FEATURES }
+    ALTERNATIVES = { ALTERNATIVE, ... }
+    ALTERNATIVE = STRING : STRING
+                | STRING : { 'type': STRING, '*if': COND }
+
+Member 'alternate' names the alternate type.
+
+Each ALTERNATIVE of the 'data' object defines a branch of the
+alternate.  An alternate must have at least one branch.
+
+The ALTERNATIVE's STRING name is the branch name.
+
+The ALTERNATIVE's value defines the branch's properties, in particular
+its type.  The form STRING is shorthand for { 'type': STRING }.
+
+Example::
+
+ { 'alternate': 'BlockdevRef',
+   'data': { 'definition': 'BlockdevOptions',
+             'reference': 'str' } }
+
+An alternate type is like a union type, except there is no
+discriminator on the wire.  Instead, the branch to use is inferred
+from the value.  An alternate can only express a choice between types
+represented differently on the wire.
+
+If a branch is typed as the 'bool' built-in, the alternate 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 type, it accepts a JSON string; if it is typed
+as the 'null' built-in, it accepts JSON null; and if it is typed as a
+complex type (struct or union), it accepts a JSON object.
+
+The example alternate declaration above allows using both of the
+following example objects::
+
+ { "file": "my_existing_block_device_id" }
+ { "file": { "driver": "file",
+             "read-only": false,
+             "filename": "/tmp/mydisk.qcow2" } }
+
+The optional 'if' member specifies a conditional.  See "Configuring
+the schema" below for more on this.
+
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
+
+Commands
+--------
+
+Syntax::
+
+    COMMAND = { 'command': STRING,
+                (
+                '*data': ( MEMBERS | STRING ),
+                |
+                'data': STRING,
+                'boxed': true,
+                )
+                '*returns': TYPE-REF,
+                '*success-response': false,
+                '*gen': false,
+                '*allow-oob': true,
+                '*allow-preconfig': true,
+                '*coroutine': true,
+                '*if': COND,
+                '*features': FEATURES }
+
+Member 'command' names the command.
+
+Member 'data' defines the arguments.  It defaults to an empty MEMBERS
+object.
+
+If 'data' is a MEMBERS object, then MEMBERS defines arguments just
+like a struct type's 'data' defines struct type members.
+
+If 'data' is a STRING, then STRING names a complex type whose members
+are the arguments.  A union type requires 'boxed': true.
+
+Member 'returns' defines the command's return type.  It defaults to an
+empty struct type.  It must normally be a complex type or an array of
+a complex type.  To return anything else, the command must be listed
+in pragma 'commands-returns-exceptions'.  If you do this, extending
+the command to return additional information will be harder.  Use of
+the pragma for new commands is strongly discouraged.
+
+A command's error responses are not specified in the QAPI schema.
+Error conditions should be documented in comments.
+
+In the Client JSON Protocol, the value of the "execute" or "exec-oob"
+member is the command name.  The value of the "arguments" member then
+has to conform to the arguments, and the value of the success
+response's "return" member will conform to the return type.
+
+Some example commands::
+
+ { 'command': 'my-first-command',
+   'data': { 'arg1': 'str', '*arg2': 'str' } }
+ { 'struct': 'MyType', 'data': { '*value': 'str' } }
+ { 'command': 'my-second-command',
+   'returns': [ 'MyType' ] }
+
+which would validate this Client JSON Protocol transaction::
+
+ => { "execute": "my-first-command",
+      "arguments": { "arg1": "hello" } }
+ <= { "return": { } }
+ => { "execute": "my-second-command" }
+ <= { "return": [ { "value": "one" }, { } ] }
+
+The generator emits a prototype for the C function implementing the
+command.  The function itself needs to be written by hand.  See
+section "Code generated for commands" for examples.
+
+The function returns the return type.  When member 'boxed' is absent,
+it takes the command arguments as arguments one by one, in QAPI schema
+order.  Else it takes them wrapped in the C struct generated for the
+complex argument type.  It takes an additional Error ** argument in
+either case.
+
+The generator also emits a marshalling function that extracts
+arguments for the user's function out of an input QDict, calls the
+user's function, and if it succeeded, builds an output QObject from
+its return value.  This is for use by the QMP monitor core.
+
+In rare cases, QAPI cannot express a type-safe representation of a
+corresponding Client JSON Protocol command.  You then have to suppress
+generation of a marshalling function by including a member 'gen' with
+boolean value false, and instead write your own function.  For
+example::
+
+ { 'command': 'netdev_add',
+   'data': {'type': 'str', 'id': 'str'},
+   'gen': false }
+
+Please try to avoid adding new commands that rely on this, and instead
+use type-safe unions.
+
+Normally, the QAPI schema is used to describe synchronous exchanges,
+where a response is expected.  But in some cases, the action of a
+command is expected to change state in a way that a successful
+response is not possible (although the command will still return an
+error object on failure).  When a successful reply is not possible,
+the command definition includes the optional member 'success-response'
+with boolean value false.  So far, only QGA makes use of this member.
+
+Member 'allow-oob' declares whether the command supports out-of-band
+(OOB) execution.  It defaults to false.  For example::
+
+ { 'command': 'migrate_recover',
+   'data': { 'uri': 'str' }, 'allow-oob': true }
+
+See qmp-spec.txt for out-of-band execution syntax and semantics.
+
+Commands supporting out-of-band execution can still be executed
+in-band.
+
+When a command is executed in-band, its handler runs in the main
+thread with the BQL held.
+
+When a command is executed out-of-band, its handler runs in a
+dedicated monitor I/O thread with the BQL *not* held.
+
+An OOB-capable command handler must satisfy the following conditions:
+
+- It terminates quickly.
+- It does not invoke system calls that may block.
+- It does not access guest RAM that may block when userfaultfd is
+  enabled for postcopy live migration.
+- It takes only "fast" locks, i.e. all critical sections protected by
+  any lock it takes also satisfy the conditions for OOB command
+  handler code.
+
+The restrictions on locking limit access to shared state.  Such access
+requires synchronization, but OOB commands can't take the BQL or any
+other "slow" lock.
+
+When in doubt, do not implement OOB execution support.
+
+Member 'allow-preconfig' declares whether the command is available
+before the machine is built.  It defaults to false.  For example::
+
+ { 'enum': 'QMPCapability',
+   'data': [ 'oob' ] }
+ { 'command': 'qmp_capabilities',
+   'data': { '*enable': [ 'QMPCapability' ] },
+   'allow-preconfig': true }
+
+QMP is available before the machine is built only when QEMU was
+started with --preconfig.
+
+Member 'coroutine' tells the QMP dispatcher whether the command handler
+is safe to be run in a coroutine.  It defaults to false.  If it is true,
+the command handler is called from coroutine context and may yield while
+waiting for an external event (such as I/O completion) in order to avoid
+blocking the guest and other background operations.
+
+Coroutine safety can be hard to prove, similar to thread safety.  Common
+pitfalls are:
+
+- The global mutex isn't held across qemu_coroutine_yield(), so
+  operations that used to assume that they execute atomically may have
+  to be more careful to protect against changes in the global state.
+
+- Nested event loops (AIO_WAIT_WHILE() etc.) are problematic in
+  coroutine context and can easily lead to deadlocks.  They should be
+  replaced by yielding and reentering the coroutine when the condition
+  becomes false.
+
+Since the command handler may assume coroutine context, any callers
+other than the QMP dispatcher must also call it in coroutine context.
+In particular, HMP commands calling such a QMP command handler must be
+marked .coroutine = true in hmp-commands.hx.
+
+It is an error to specify both 'coroutine': true and 'allow-oob': true
+for a command.  We don't currently have a use case for both together and
+without a use case, it's not entirely clear what the semantics should
+be.
+
+The optional 'if' member specifies a conditional.  See "Configuring
+the schema" below for more on this.
+
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
+
+Events
+------
+
+Syntax::
+
+    EVENT = { 'event': STRING,
+              (
+              '*data': ( MEMBERS | STRING ),
+              |
+              'data': STRING,
+              'boxed': true,
+              )
+              '*if': COND,
+              '*features': FEATURES }
+
+Member 'event' names the event.  This is the event name used in the
+Client JSON Protocol.
+
+Member 'data' defines the event-specific data.  It defaults to an
+empty MEMBERS object.
+
+If 'data' is a MEMBERS object, then MEMBERS defines event-specific
+data just like a struct type's 'data' defines struct type members.
+
+If 'data' is a STRING, then STRING names a complex type whose members
+are the event-specific data.  A union type requires 'boxed': true.
+
+An example event is::
+
+ { 'event': 'EVENT_C',
+   'data': { '*a': 'int', 'b': 'str' } }
+
+Resulting in this JSON object::
+
+ { "event": "EVENT_C",
+   "data": { "b": "test string" },
+   "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+
+The generator emits a function to send the event.  When member 'boxed'
+is absent, it takes event-specific data one by one, in QAPI schema
+order.  Else it takes them wrapped in the C struct generated for the
+complex type.  See section "Code generated for events" for examples.
+
+The optional 'if' member specifies a conditional.  See "Configuring
+the schema" below for more on this.
+
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
+
+Features
+--------
+
+Syntax::
+
+    FEATURES = [ FEATURE, ... ]
+    FEATURE = STRING
+            | { 'name': STRING, '*if': COND }
+
+Sometimes, the behaviour of QEMU changes compatibly, but without a
+change in the QMP syntax (usually by allowing values or operations
+that previously resulted in an error).  QMP clients may still need to
+know whether the extension is available.
+
+For this purpose, a list of features can be specified for a command or
+struct type.  Each list member can either be ``{ 'name': STRING, '*if':
+COND }``, or STRING, which is shorthand for ``{ 'name': STRING }``.
+
+The optional 'if' member specifies a conditional.  See "Configuring
+the schema" below for more on this.
+
+Example::
+
+ { 'struct': 'TestType',
+   'data': { 'number': 'int' },
+   'features': [ 'allow-negative-numbers' ] }
+
+The feature strings are exposed to clients in introspection, as
+explained in section "Client JSON Protocol introspection".
+
+Intended use is to have each feature string signal that this build of
+QEMU shows a certain behaviour.
+
+
+Special features
+~~~~~~~~~~~~~~~~
+
+Feature "deprecated" marks a command, event, or struct member as
+deprecated.  It is not supported elsewhere so far.
+
+
+Naming rules and reserved names
+-------------------------------
+
+All names must begin with a letter, and contain only ASCII letters,
+digits, hyphen, and underscore.  There are two exceptions: enum values
+may start with a digit, and names that are downstream extensions (see
+section Downstream extensions) start with underscore.
+
+Names beginning with 'q\_' are reserved for the generator, which uses
+them for munging QMP names that resemble C keywords or other
+problematic strings.  For example, a member named "default" in qapi
+becomes "q_default" in the generated C code.
+
+Types, commands, and events share a common namespace.  Therefore,
+generally speaking, type definitions should always use CamelCase for
+user-defined type names, while built-in types are lowercase.
+
+Type names ending with 'Kind' or 'List' are reserved for the
+generator, which uses them for implicit union enums and array types,
+respectively.
+
+Command names, and member names within a type, should be all lower
+case with words separated by a hyphen.  However, some existing older
+commands and complex types use underscore; when extending them,
+consistency is preferred over blindly avoiding underscore.
+
+Event names should be ALL_CAPS with words separated by underscore.
+
+Member name 'u' and names starting with 'has-' or 'has\_' are reserved
+for the generator, which uses them for unions and for tracking
+optional members.
+
+Any name (command, event, type, member, or enum value) beginning with
+"x-" is marked experimental, and may be withdrawn or changed
+incompatibly in a future release.
+
+Pragmas 'command-name-exceptions' and 'member-name-exceptions' let you
+violate naming rules.  Use for new code is strongly discouraged.
+
+
+Downstream extensions
+---------------------
+
+QAPI schema names that are externally visible, say in the Client JSON
+Protocol, need to be managed with care.  Names starting with a
+downstream prefix of the form __RFQDN_ are reserved for the downstream
+who controls the valid, reverse fully qualified domain name RFQDN.
+RFQDN may only contain ASCII letters, digits, hyphen and period.
+
+Example: Red Hat, Inc. controls redhat.com, and may therefore add a
+downstream command __com.redhat_drive-mirror.
+
+
+Configuring the schema
+----------------------
+
+Syntax::
+
+    COND = STRING
+         | [ STRING, ... ]
+
+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.
+
+Example: a conditional struct ::
+
+ { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
+   'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] }
+
+gets its generated code guarded like this::
+
+ #if defined(CONFIG_FOO)
+ #if defined(HAVE_BAR)
+ ... generated code ...
+ #endif /* defined(HAVE_BAR) */
+ #endif /* defined(CONFIG_FOO) */
+
+Individual members of complex types, commands arguments, and
+event-specific data can also be made conditional.  This requires the
+longhand form of MEMBER.
+
+Example: a struct type with unconditional member 'foo' and conditional
+member 'bar' ::
+
+ { 'struct': 'IfStruct', 'data':
+   { 'foo': 'int',
+     'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
+
+A union's discriminator may not be conditional.
+
+Likewise, individual enumeration values be conditional.  This requires
+the longhand form of ENUM-VALUE.
+
+Example: an enum type with unconditional value 'foo' and conditional
+value 'bar' ::
+
+ { 'enum': 'IfEnum', 'data':
+   [ 'foo',
+     { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
+
+Likewise, features can be conditional.  This requires the longhand
+form of FEATURE.
+
+Example: a struct with conditional feature 'allow-negative-numbers' ::
+
+ { 'struct': 'TestType',
+   'data': { 'number': 'int' },
+   'features': [ { 'name': 'allow-negative-numbers',
+                   'if': 'defined(IFCOND)' } ] }
+
+Please note that you are responsible to ensure that the C code will
+compile with an arbitrary combination of conditions, since the
+generator is unable to check it at this point.
+
+The conditions apply to introspection as well, i.e. introspection
+shows a conditional entity only when the condition is satisfied in
+this particular build.
+
+
+Documentation comments
+----------------------
+
+A multi-line comment that starts and ends with a '##' line is a
+documentation comment.
+
+If the documentation comment starts like ::
+
+    ##
+    # @SYMBOL:
+
+it documents the definition if SYMBOL, else it's free-form
+documentation.
+
+See below for more on definition documentation.
+
+Free-form documentation may be used to provide additional text and
+structuring content.
+
+
+Headings and subheadings
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A free-form documentation comment containing a line which starts with
+some '=' symbols and then a space defines a section heading::
+
+    ##
+    # = This is a top level heading
+    #
+    # This is a free-form comment which will go under the
+    # top level heading.
+    ##
+
+    ##
+    # == This is a second level heading
+    ##
+
+A heading line must be the first line of the documentation
+comment block.
+
+Section headings must always be correctly nested, so you can only
+define a third-level heading inside a second-level heading, and so on.
+
+
+Documentation markup
+~~~~~~~~~~~~~~~~~~~~
+
+Documentation comments can use most rST markup.  In particular,
+a '::' literal block can be used for examples::
+
+    # ::
+    #
+    #   Text of the example, may span
+    #   multiple lines
+
+'*' starts an itemized list::
+
+    # * First item, may span
+    #   multiple lines
+    # * Second item
+
+You can also use '-' instead of '*'.
+
+A decimal number followed by '.' starts a numbered list::
+
+    # 1. First item, may span
+    #    multiple lines
+    # 2. Second item
+
+The actual number doesn't matter.
+
+Lists of either kind must be preceded and followed by a blank line.
+If a list item's text spans multiple lines, then the second and
+subsequent lines must be correctly indented to line up with the
+first character of the first line.
+
+The usual '**strong**', '*emphasised*' and '``literal``' markup should
+be used.  If you need a single literal '*' you will need to
+backslash-escape it.  As an extension beyond the usual rST syntax, you
+can also use '@foo' to reference a name in the schema; this is
+rendered the same way as '``foo``'.
+
+Example::
+
+ ##
+ # Some text foo with **bold** and *emphasis*
+ # 1. with a list
+ # 2. like that
+ #
+ # And some code:
+ #
+ # ::
+ #
+ #   $ echo foo
+ #   -> do this
+ #   <- get that
+ ##
+
+
+Definition documentation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Definition documentation, if present, must immediately precede the
+definition it documents.
+
+When documentation is required (see pragma 'doc-required'), every
+definition must have documentation.
+
+Definition documentation starts with a line naming the definition,
+followed by an optional overview, a description of each argument (for
+commands and events), member (for structs and unions), branch (for
+alternates), or value (for enums), and finally optional tagged
+sections.
+
+Descriptions of arguments can span multiple lines.  The description
+text can start on the line following the '@argname:', in which case it
+must not be indented at all.  It can also start on the same line as
+the '@argname:'.  In this case if it spans multiple lines then second
+and subsequent lines must be indented to line up with the first
+character of the first line of the description::
+
+ # @argone:
+ # This is a two line description
+ # in the first style.
+ #
+ # @argtwo: This is a two line description
+ #          in the second style.
+
+The number of spaces between the ':' and the text is not significant.
+
+FIXME: the parser accepts these things in almost any order.
+FIXME: union branches should be described, too.
+
+Extensions added after the definition was first released carry a
+'(since x.y.z)' comment.
+
+A tagged section starts with one of the following words:
+"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
+The section ends with the start of a new section.
+
+The text of a section can start on a new line, in
+which case it must not be indented at all.  It can also start
+on the same line as the 'Note:', 'Returns:', etc tag.  In this
+case if it spans multiple lines then second and subsequent
+lines must be indented to match the first, in the same way as
+multiline argument descriptions.
+
+A 'Since: x.y.z' tagged section lists the release that introduced the
+definition.
+
+The text of a section can start on a new line, in
+which case it must not be indented at all.  It can also start
+on the same line as the 'Note:', 'Returns:', etc tag.  In this
+case if it spans multiple lines then second and subsequent
+lines must be indented to match the first.
+
+An 'Example' or 'Examples' section is automatically rendered
+entirely as literal fixed-width text.  In other sections,
+the text is formatted, and rST markup can be used.
+
+For example::
+
+ ##
+ # @BlockStats:
+ #
+ # Statistics of a virtual block device or a block backing device.
+ #
+ # @device: If the stats are for a virtual block device, the name
+ #          corresponding to the virtual block device.
+ #
+ # @node-name: The node name of the device. (since 2.3)
+ #
+ # ... more members ...
+ #
+ # Since: 0.14.0
+ ##
+ { 'struct': 'BlockStats',
+   'data': {'*device': 'str', '*node-name': 'str',
+            ... more members ... } }
+
+ ##
+ # @query-blockstats:
+ #
+ # Query the @BlockStats for all virtual block devices.
+ #
+ # @query-nodes: If true, the command will query all the
+ #               block nodes ... explain, explain ...  (since 2.3)
+ #
+ # Returns: A list of @BlockStats for each virtual block devices.
+ #
+ # Since: 0.14.0
+ #
+ # Example:
+ #
+ # -> { "execute": "query-blockstats" }
+ # <- {
+ #      ... lots of output ...
+ #    }
+ #
+ ##
+ { 'command': 'query-blockstats',
+   'data': { '*query-nodes': 'bool' },
+   'returns': ['BlockStats'] }
+
+
+Client JSON Protocol introspection
+==================================
+
+Clients of a Client JSON Protocol commonly need to figure out what
+exactly the server (QEMU) supports.
+
+For this purpose, QMP provides introspection via command
+query-qmp-schema.  QGA currently doesn't support introspection.
+
+While Client JSON Protocol wire compatibility should be maintained
+between qemu versions, we cannot make the same guarantees for
+introspection stability.  For example, one version of qemu may provide
+a non-variant optional member of a struct, and a later version rework
+the member to instead be non-optional and associated with a variant.
+Likewise, one version of qemu may list a member with open-ended type
+'str', and a later version could convert it to a finite set of strings
+via an enum type; or a member may be converted from a specific type to
+an alternate that represents a choice between the original type and
+something else.
+
+query-qmp-schema returns a JSON array of SchemaInfo objects.  These
+objects together describe the wire ABI, as defined in the QAPI schema.
+There is no specified order to the SchemaInfo objects returned; a
+client must search for a particular name throughout the entire array
+to learn more about that name, but is at least guaranteed that there
+will be no collisions between type, command, and event names.
+
+However, the SchemaInfo can't reflect all the rules and restrictions
+that apply to QMP.  It's interface introspection (figuring out what's
+there), not interface specification.  The specification is in the QAPI
+schema.  To understand how QMP is to be used, you need to study the
+QAPI schema.
+
+Like any other command, query-qmp-schema is itself defined in the QAPI
+schema, along with the SchemaInfo type.  This text attempts to give an
+overview how things work.  For details you need to consult the QAPI
+schema.
+
+SchemaInfo objects have common members "name", "meta-type",
+"features", and additional variant members depending on the value of
+meta-type.
+
+Each SchemaInfo object describes a wire ABI entity of a certain
+meta-type: a command, event or one of several kinds of type.
+
+SchemaInfo for commands and events have the same name as in the QAPI
+schema.
+
+Command and event names are part of the wire ABI, but type names are
+not.  Therefore, the SchemaInfo for types have auto-generated
+meaningless names.  For readability, the examples in this section use
+meaningful type names instead.
+
+Optional member "features" exposes the entity's feature strings as a
+JSON array of strings.
+
+To examine a type, start with a command or event using it, then follow
+references by name.
+
+QAPI schema definitions not reachable that way are omitted.
+
+The SchemaInfo for a command has meta-type "command", and variant
+members "arg-type", "ret-type" and "allow-oob".  On the wire, the
+"arguments" member of a client's "execute" command must conform to the
+object type named by "arg-type".  The "return" member that the server
+passes in a success response conforms to the type named by "ret-type".
+When "allow-oob" is true, it means the command supports out-of-band
+execution.  It defaults to false.
+
+If the command takes no arguments, "arg-type" names an object type
+without members.  Likewise, if the command returns nothing, "ret-type"
+names an object type without members.
+
+Example: the SchemaInfo for command query-qmp-schema ::
+
+ { "name": "query-qmp-schema", "meta-type": "command",
+   "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
+
+   Type "q_empty" is an automatic object type without members, and type
+   "SchemaInfoList" is the array of SchemaInfo type.
+
+The SchemaInfo for an event has meta-type "event", and variant member
+"arg-type".  On the wire, a "data" member that the server passes in an
+event conforms to the object type named by "arg-type".
+
+If the event carries no additional information, "arg-type" names an
+object type without members.  The event may not have a data member on
+the wire then.
+
+Each command or event defined with 'data' as MEMBERS object in the
+QAPI schema implicitly defines an object type.
+
+Example: the SchemaInfo for EVENT_C from section Events ::
+
+    { "name": "EVENT_C", "meta-type": "event",
+      "arg-type": "q_obj-EVENT_C-arg" }
+
+    Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
+    the two members from the event's definition.
+
+The SchemaInfo for struct and union types has meta-type "object".
+
+The SchemaInfo for a struct type has variant member "members".
+
+The SchemaInfo for a union type additionally has variant members "tag"
+and "variants".
+
+"members" is a JSON array describing the object's common members, if
+any.  Each element is a JSON object with members "name" (the member's
+name), "type" (the name of its type), and optionally "default".  The
+member is optional if "default" is present.  Currently, "default" can
+only have value null.  Other values are reserved for future
+extensions.  The "members" array is in no particular order; clients
+must search the entire object when learning whether a particular
+member is supported.
+
+Example: the SchemaInfo for MyType from section Struct types ::
+
+    { "name": "MyType", "meta-type": "object",
+      "members": [
+          { "name": "member1", "type": "str" },
+          { "name": "member2", "type": "int" },
+          { "name": "member3", "type": "str", "default": null } ] }
+
+"features" exposes the command's feature strings as a JSON array of
+strings.
+
+Example: the SchemaInfo for TestType from section Features::
+
+    { "name": "TestType", "meta-type": "object",
+      "members": [
+          { "name": "number", "type": "int" } ],
+      "features": ["allow-negative-numbers"] }
+
+"tag" is the name of the common member serving as type tag.
+"variants" is a JSON array describing the object's variant members.
+Each element is a JSON object with members "case" (the value of type
+tag this element applies to) and "type" (the name of an object type
+that provides the variant members for this type tag value).  The
+"variants" array is in no particular order, and is not guaranteed to
+list cases in the same order as the corresponding "tag" enum type.
+
+Example: the SchemaInfo for flat union BlockdevOptions from section
+Union types ::
+
+    { "name": "BlockdevOptions", "meta-type": "object",
+      "members": [
+          { "name": "driver", "type": "BlockdevDriver" },
+          { "name": "read-only", "type": "bool", "default": null } ],
+      "tag": "driver",
+      "variants": [
+          { "case": "file", "type": "BlockdevOptionsFile" },
+          { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
+
+Note that base types are "flattened": its members are included in the
+"members" array.
+
+A simple union implicitly defines an enumeration type for its implicit
+discriminator (called "type" on the wire, see section Union types).
+
+A simple union implicitly defines an object type for each of its
+variants.
+
+Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
+Union types ::
+
+    { "name": "BlockdevOptionsSimple", "meta-type": "object",
+      "members": [
+          { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
+      "tag": "type",
+      "variants": [
+          { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
+          { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
+
+    Enumeration type "BlockdevOptionsSimpleKind" and the object types
+    "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
+    are implicitly defined.
+
+The SchemaInfo for an alternate type has meta-type "alternate", and
+variant member "members".  "members" is a JSON array.  Each element is
+a JSON object with member "type", which names a type.  Values of the
+alternate type conform to exactly one of its member types.  There is
+no guarantee on the order in which "members" will be listed.
+
+Example: the SchemaInfo for BlockdevRef from section Alternate types ::
+
+    { "name": "BlockdevRef", "meta-type": "alternate",
+      "members": [
+          { "type": "BlockdevOptions" },
+          { "type": "str" } ] }
+
+The SchemaInfo for an array type has meta-type "array", and variant
+member "element-type", which names the array's element type.  Array
+types are implicitly defined.  For convenience, the array's name may
+resemble the element type; however, clients should examine member
+"element-type" instead of making assumptions based on parsing member
+"name".
+
+Example: the SchemaInfo for ['str'] ::
+
+    { "name": "[str]", "meta-type": "array",
+      "element-type": "str" }
+
+The SchemaInfo for an enumeration type has meta-type "enum" and
+variant member "values".  The values are listed in no particular
+order; clients must search the entire enum when learning whether a
+particular value is supported.
+
+Example: the SchemaInfo for MyEnum from section Enumeration types ::
+
+    { "name": "MyEnum", "meta-type": "enum",
+      "values": [ "value1", "value2", "value3" ] }
+
+The SchemaInfo for a built-in type has the same name as the type in
+the QAPI schema (see section Built-in Types), with one exception
+detailed below.  It has variant member "json-type" that shows how
+values of this type are encoded on the wire.
+
+Example: the SchemaInfo for str ::
+
+    { "name": "str", "meta-type": "builtin", "json-type": "string" }
+
+The QAPI schema supports a number of integer types that only differ in
+how they map to C.  They are identical as far as SchemaInfo is
+concerned.  Therefore, they get all mapped to a single type "int" in
+SchemaInfo.
+
+As explained above, type names are not part of the wire ABI.  Not even
+the names of built-in types.  Clients should examine member
+"json-type" instead of hard-coding names of built-in types.
+
+
+Compatibility considerations
+============================
+
+Maintaining backward compatibility at the Client JSON Protocol level
+while evolving the schema requires some care.  This section is about
+syntactic compatibility, which is necessary, but not sufficient, for
+actual compatibility.
+
+Clients send commands with argument data, and receive command
+responses with return data and events with event data.
+
+Adding opt-in functionality to the send direction is backwards
+compatible: adding commands, optional arguments, enumeration values,
+union and alternate branches; turning an argument type into an
+alternate of that type; making mandatory arguments optional.  Clients
+oblivious of the new functionality continue to work.
+
+Incompatible changes include removing commands, command arguments,
+enumeration values, union and alternate branches, adding mandatory
+command arguments, and making optional arguments mandatory.
+
+The specified behavior of an absent optional argument should remain
+the same.  With proper documentation, this policy still allows some
+flexibility; for example, when an optional 'buffer-size' argument is
+specified to default to a sensible buffer size, the actual default
+value can still be changed.  The specified default behavior is not the
+exact size of the buffer, only that the default size is sensible.
+
+Adding functionality to the receive direction is generally backwards
+compatible: adding events, adding return and event data members.
+Clients are expected to ignore the ones they don't know.
+
+Removing "unreachable" stuff like events that can't be triggered
+anymore, optional return or event data members that can't be sent
+anymore, and return or event data member (enumeration) values that
+can't be sent anymore makes no difference to clients, except for
+introspection.  The latter can conceivably confuse clients, so tread
+carefully.
+
+Incompatible changes include removing return and event data members.
+
+Any change to a command definition's 'data' or one of the types used
+there (recursively) needs to consider send direction compatibility.
+
+Any change to a command definition's 'return', an event definition's
+'data', or one of the types used there (recursively) needs to consider
+receive direction compatibility.
+
+Any change to types used in both contexts need to consider both.
+
+Enumeration type values and complex and alternate type members may be
+reordered freely.  For enumerations and alternate types, this doesn't
+affect the wire encoding.  For complex types, this might make the
+implementation emit JSON object members in a different order, which
+the Client JSON Protocol permits.
+
+Since type names are not visible in the Client JSON Protocol, types
+may be freely renamed.  Even certain refactorings are invisible, such
+as splitting members from one type into a common base type.
+
+
+Code generation
+===============
+
+The QAPI code generator qapi-gen.py generates code and documentation
+from the schema.  Together with the core QAPI libraries, this code
+provides everything required to take JSON commands read in by a Client
+JSON Protocol server, unmarshal the arguments into the underlying C
+types, call into the corresponding C function, map the response back
+to a Client JSON Protocol response to be returned to the user, and
+introspect the commands.
+
+As an example, we'll use the following schema, which describes a
+single complex user-defined type, along with command which takes a
+list of that type as a parameter, and returns a single element of that
+type.  The user is responsible for writing the implementation of
+qmp_my_command(); everything else is produced by the generator. ::
+
+    $ cat example-schema.json
+    { 'struct': 'UserDefOne',
+      'data': { 'integer': 'int', '*string': 'str' } }
+
+    { 'command': 'my-command',
+      'data': { 'arg1': ['UserDefOne'] },
+      'returns': 'UserDefOne' }
+
+    { 'event': 'MY_EVENT' }
+
+We run qapi-gen.py like this::
+
+    $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
+    --prefix="example-" example-schema.json
+
+For a more thorough look at generated code, the testsuite includes
+tests/qapi-schema/qapi-schema-tests.json that covers more examples of
+what the generator will accept, and compiles the resulting C code as
+part of 'make check-unit'.
+
+
+Code generated for QAPI types
+-----------------------------
+
+The following files are created:
+
+ ``$(prefix)qapi-types.h``
+     C types corresponding to types defined in the schema
+
+ ``$(prefix)qapi-types.c``
+     Cleanup functions for the above C types
+
+The $(prefix) is an optional parameter used as a namespace to keep the
+generated code from one schema/code-generation separated from others so code
+can be generated/used from multiple schemas without clobbering previously
+created code.
+
+Example::
+
+    $ cat qapi-generated/example-qapi-types.h
+    [Uninteresting stuff omitted...]
+
+    #ifndef EXAMPLE_QAPI_TYPES_H
+    #define EXAMPLE_QAPI_TYPES_H
+
+    #include "qapi/qapi-builtin-types.h"
+
+    typedef struct UserDefOne UserDefOne;
+
+    typedef struct UserDefOneList UserDefOneList;
+
+    typedef struct q_obj_my_command_arg q_obj_my_command_arg;
+
+    struct UserDefOne {
+        int64_t integer;
+        bool has_string;
+        char *string;
+    };
+
+    void qapi_free_UserDefOne(UserDefOne *obj);
+    G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne)
+
+    struct UserDefOneList {
+        UserDefOneList *next;
+        UserDefOne *value;
+    };
+
+    void qapi_free_UserDefOneList(UserDefOneList *obj);
+    G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList)
+
+    struct q_obj_my_command_arg {
+        UserDefOneList *arg1;
+    };
+
+    #endif /* EXAMPLE_QAPI_TYPES_H */
+    $ cat qapi-generated/example-qapi-types.c
+    [Uninteresting stuff omitted...]
+
+    void qapi_free_UserDefOne(UserDefOne *obj)
+    {
+        Visitor *v;
+
+        if (!obj) {
+            return;
+        }
+
+        v = qapi_dealloc_visitor_new();
+        visit_type_UserDefOne(v, NULL, &obj, NULL);
+        visit_free(v);
+    }
+
+    void qapi_free_UserDefOneList(UserDefOneList *obj)
+    {
+        Visitor *v;
+
+        if (!obj) {
+            return;
+        }
+
+        v = qapi_dealloc_visitor_new();
+        visit_type_UserDefOneList(v, NULL, &obj, NULL);
+        visit_free(v);
+    }
+
+    [Uninteresting stuff omitted...]
+
+For a modular QAPI schema (see section Include directives), code for
+each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
+
+ SUBDIR/$(prefix)qapi-types-SUBMODULE.h
+ SUBDIR/$(prefix)qapi-types-SUBMODULE.c
+
+If qapi-gen.py is run with option --builtins, additional files are
+created:
+
+ ``qapi-builtin-types.h``
+     C types corresponding to built-in types
+
+ ``qapi-builtin-types.c``
+     Cleanup functions for the above C types
+
+
+Code generated for visiting QAPI types
+--------------------------------------
+
+These are the visitor functions used to walk through and convert
+between a native QAPI C data structure and some other format (such as
+QObject); the generated functions are named visit_type_FOO() and
+visit_type_FOO_members().
+
+The following files are generated:
+
+ ``$(prefix)qapi-visit.c``
+     Visitor function for a particular C type, used to automagically
+     convert QObjects into the corresponding C type and vice-versa, as
+     well as for deallocating memory for an existing C type
+
+ ``$(prefix)qapi-visit.h``
+     Declarations for previously mentioned visitor functions
+
+Example::
+
+    $ cat qapi-generated/example-qapi-visit.h
+    [Uninteresting stuff omitted...]
+
+    #ifndef EXAMPLE_QAPI_VISIT_H
+    #define EXAMPLE_QAPI_VISIT_H
+
+    #include "qapi/qapi-builtin-visit.h"
+    #include "example-qapi-types.h"
+
+
+    bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
+
+    bool visit_type_UserDefOne(Visitor *v, const char *name,
+                     UserDefOne **obj, Error **errp);
+
+    bool visit_type_UserDefOneList(Visitor *v, const char *name,
+                     UserDefOneList **obj, Error **errp);
+
+    bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
+
+    #endif /* EXAMPLE_QAPI_VISIT_H */
+    $ cat qapi-generated/example-qapi-visit.c
+    [Uninteresting stuff omitted...]
+
+    bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
+    {
+        if (!visit_type_int(v, "integer", &obj->integer, errp)) {
+            return false;
+        }
+        if (visit_optional(v, "string", &obj->has_string)) {
+            if (!visit_type_str(v, "string", &obj->string, errp)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    bool visit_type_UserDefOne(Visitor *v, const char *name,
+                     UserDefOne **obj, Error **errp)
+    {
+        bool ok = false;
+
+        if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) {
+            return false;
+        }
+        if (!*obj) {
+            /* incomplete */
+            assert(visit_is_dealloc(v));
+            ok = true;
+            goto out_obj;
+        }
+        if (!visit_type_UserDefOne_members(v, *obj, errp)) {
+            goto out_obj;
+        }
+        ok = visit_check_struct(v, errp);
+    out_obj:
+        visit_end_struct(v, (void **)obj);
+        if (!ok && visit_is_input(v)) {
+            qapi_free_UserDefOne(*obj);
+            *obj = NULL;
+        }
+        return ok;
+    }
+
+    bool visit_type_UserDefOneList(Visitor *v, const char *name,
+                     UserDefOneList **obj, Error **errp)
+    {
+        bool ok = false;
+        UserDefOneList *tail;
+        size_t size = sizeof(**obj);
+
+        if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) {
+            return false;
+        }
+
+        for (tail = *obj; tail;
+             tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
+            if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
+                goto out_obj;
+            }
+        }
+
+        ok = visit_check_list(v, errp);
+    out_obj:
+        visit_end_list(v, (void **)obj);
+        if (!ok && visit_is_input(v)) {
+            qapi_free_UserDefOneList(*obj);
+            *obj = NULL;
+        }
+        return ok;
+    }
+
+    bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
+    {
+        if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
+            return false;
+        }
+        return true;
+    }
+
+    [Uninteresting stuff omitted...]
+
+For a modular QAPI schema (see section Include directives), code for
+each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
+
+ SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
+ SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
+
+If qapi-gen.py is run with option --builtins, additional files are
+created:
+
+ ``qapi-builtin-visit.h``
+     Visitor functions for built-in types
+
+ ``qapi-builtin-visit.c``
+     Declarations for these visitor functions
+
+
+Code generated for commands
+---------------------------
+
+These are the marshaling/dispatch functions for the commands defined
+in the schema.  The generated code provides qmp_marshal_COMMAND(), and
+declares qmp_COMMAND() that the user must implement.
+
+The following files are generated:
+
+ ``$(prefix)qapi-commands.c``
+     Command marshal/dispatch functions for each QMP command defined in
+     the schema
+
+ ``$(prefix)qapi-commands.h``
+     Function prototypes for the QMP commands specified in the schema
+
+ ``$(prefix)qapi-init-commands.h``
+     Command initialization prototype
+
+ ``$(prefix)qapi-init-commands.c``
+     Command initialization code
+
+Example::
+
+    $ cat qapi-generated/example-qapi-commands.h
+    [Uninteresting stuff omitted...]
+
+    #ifndef EXAMPLE_QAPI_COMMANDS_H
+    #define EXAMPLE_QAPI_COMMANDS_H
+
+    #include "example-qapi-types.h"
+
+    UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
+    void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
+
+    #endif /* EXAMPLE_QAPI_COMMANDS_H */
+    $ cat qapi-generated/example-qapi-commands.c
+    [Uninteresting stuff omitted...]
+
+
+    static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in,
+                                    QObject **ret_out, Error **errp)
+    {
+        Visitor *v;
+
+        v = qobject_output_visitor_new_qmp(ret_out);
+        if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) {
+            visit_complete(v, ret_out);
+        }
+        visit_free(v);
+        v = qapi_dealloc_visitor_new();
+        visit_type_UserDefOne(v, "unused", &ret_in, NULL);
+        visit_free(v);
+    }
+
+    void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
+    {
+        Error *err = NULL;
+        bool ok = false;
+        Visitor *v;
+        UserDefOne *retval;
+        q_obj_my_command_arg arg = {0};
+
+        v = qobject_input_visitor_new_qmp(QOBJECT(args));
+        if (!visit_start_struct(v, NULL, NULL, 0, errp)) {
+            goto out;
+        }
+        if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) {
+            ok = visit_check_struct(v, errp);
+        }
+        visit_end_struct(v, NULL);
+        if (!ok) {
+            goto out;
+        }
+
+        retval = qmp_my_command(arg.arg1, &err);
+        error_propagate(errp, err);
+        if (err) {
+            goto out;
+        }
+
+        qmp_marshal_output_UserDefOne(retval, ret, errp);
+
+    out:
+        visit_free(v);
+        v = qapi_dealloc_visitor_new();
+        visit_start_struct(v, NULL, NULL, 0, NULL);
+        visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
+        visit_end_struct(v, NULL);
+        visit_free(v);
+    }
+
+    [Uninteresting stuff omitted...]
+    $ cat qapi-generated/example-qapi-init-commands.h
+    [Uninteresting stuff omitted...]
+    #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H
+    #define EXAMPLE_QAPI_INIT_COMMANDS_H
+
+    #include "qapi/qmp/dispatch.h"
+
+    void example_qmp_init_marshal(QmpCommandList *cmds);
+
+    #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */
+    $ cat qapi-generated/example-qapi-init-commands.c
+    [Uninteresting stuff omitted...]
+    void example_qmp_init_marshal(QmpCommandList *cmds)
+    {
+        QTAILQ_INIT(cmds);
+
+        qmp_register_command(cmds, "my-command",
+                             qmp_marshal_my_command, QCO_NO_OPTIONS);
+    }
+    [Uninteresting stuff omitted...]
+
+For a modular QAPI schema (see section Include directives), code for
+each sub-module SUBDIR/SUBMODULE.json is actually generated into::
+
+ SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
+ SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
+
+
+Code generated for events
+-------------------------
+
+This is the code related to events defined in the schema, providing
+qapi_event_send_EVENT().
+
+The following files are created:
+
+ ``$(prefix)qapi-events.h``
+     Function prototypes for each event type
+
+ ``$(prefix)qapi-events.c``
+     Implementation of functions to send an event
+
+ ``$(prefix)qapi-emit-events.h``
+     Enumeration of all event names, and common event code declarations
+
+ ``$(prefix)qapi-emit-events.c``
+     Common event code definitions
+
+Example::
+
+    $ cat qapi-generated/example-qapi-events.h
+    [Uninteresting stuff omitted...]
+
+    #ifndef EXAMPLE_QAPI_EVENTS_H
+    #define EXAMPLE_QAPI_EVENTS_H
+
+    #include "qapi/util.h"
+    #include "example-qapi-types.h"
+
+    void qapi_event_send_my_event(void);
+
+    #endif /* EXAMPLE_QAPI_EVENTS_H */
+    $ cat qapi-generated/example-qapi-events.c
+    [Uninteresting stuff omitted...]
+
+    void qapi_event_send_my_event(void)
+    {
+        QDict *qmp;
+
+        qmp = qmp_event_build_dict("MY_EVENT");
+
+        example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
+
+        qobject_unref(qmp);
+    }
+
+    [Uninteresting stuff omitted...]
+    $ cat qapi-generated/example-qapi-emit-events.h
+    [Uninteresting stuff omitted...]
+
+    #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
+    #define EXAMPLE_QAPI_EMIT_EVENTS_H
+
+    #include "qapi/util.h"
+
+    typedef enum example_QAPIEvent {
+        EXAMPLE_QAPI_EVENT_MY_EVENT,
+        EXAMPLE_QAPI_EVENT__MAX,
+    } example_QAPIEvent;
+
+    #define example_QAPIEvent_str(val) \
+        qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
+
+    extern const QEnumLookup example_QAPIEvent_lookup;
+
+    void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
+
+    #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
+    $ cat qapi-generated/example-qapi-emit-events.c
+    [Uninteresting stuff omitted...]
+
+    const QEnumLookup example_QAPIEvent_lookup = {
+        .array = (const char *const[]) {
+            [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
+        },
+        .size = EXAMPLE_QAPI_EVENT__MAX
+    };
+
+    [Uninteresting stuff omitted...]
+
+For a modular QAPI schema (see section Include directives), code for
+each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
+
+ SUBDIR/$(prefix)qapi-events-SUBMODULE.h
+ SUBDIR/$(prefix)qapi-events-SUBMODULE.c
+
+
+Code generated for introspection
+--------------------------------
+
+The following files are created:
+
+ ``$(prefix)qapi-introspect.c``
+     Defines a string holding a JSON description of the schema
+
+ ``$(prefix)qapi-introspect.h``
+     Declares the above string
+
+Example::
+
+    $ cat qapi-generated/example-qapi-introspect.h
+    [Uninteresting stuff omitted...]
+
+    #ifndef EXAMPLE_QAPI_INTROSPECT_H
+    #define EXAMPLE_QAPI_INTROSPECT_H
+
+    #include "qapi/qmp/qlit.h"
+
+    extern const QLitObject example_qmp_schema_qlit;
+
+    #endif /* EXAMPLE_QAPI_INTROSPECT_H */
+    $ cat qapi-generated/example-qapi-introspect.c
+    [Uninteresting stuff omitted...]
+
+    const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "arg-type", QLIT_QSTR("0"), },
+            { "meta-type", QLIT_QSTR("command"), },
+            { "name", QLIT_QSTR("my-command"), },
+            { "ret-type", QLIT_QSTR("1"), },
+            {}
+        })),
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "arg-type", QLIT_QSTR("2"), },
+            { "meta-type", QLIT_QSTR("event"), },
+            { "name", QLIT_QSTR("MY_EVENT"), },
+            {}
+        })),
+        /* "0" = q_obj_my-command-arg */
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "members", QLIT_QLIST(((QLitObject[]) {
+                QLIT_QDICT(((QLitDictEntry[]) {
+                    { "name", QLIT_QSTR("arg1"), },
+                    { "type", QLIT_QSTR("[1]"), },
+                    {}
+                })),
+                {}
+            })), },
+            { "meta-type", QLIT_QSTR("object"), },
+            { "name", QLIT_QSTR("0"), },
+            {}
+        })),
+        /* "1" = UserDefOne */
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "members", QLIT_QLIST(((QLitObject[]) {
+                QLIT_QDICT(((QLitDictEntry[]) {
+                    { "name", QLIT_QSTR("integer"), },
+                    { "type", QLIT_QSTR("int"), },
+                    {}
+                })),
+                QLIT_QDICT(((QLitDictEntry[]) {
+                    { "default", QLIT_QNULL, },
+                    { "name", QLIT_QSTR("string"), },
+                    { "type", QLIT_QSTR("str"), },
+                    {}
+                })),
+                {}
+            })), },
+            { "meta-type", QLIT_QSTR("object"), },
+            { "name", QLIT_QSTR("1"), },
+            {}
+        })),
+        /* "2" = q_empty */
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "members", QLIT_QLIST(((QLitObject[]) {
+                {}
+            })), },
+            { "meta-type", QLIT_QSTR("object"), },
+            { "name", QLIT_QSTR("2"), },
+            {}
+        })),
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "element-type", QLIT_QSTR("1"), },
+            { "meta-type", QLIT_QSTR("array"), },
+            { "name", QLIT_QSTR("[1]"), },
+            {}
+        })),
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "json-type", QLIT_QSTR("int"), },
+            { "meta-type", QLIT_QSTR("builtin"), },
+            { "name", QLIT_QSTR("int"), },
+            {}
+        })),
+        QLIT_QDICT(((QLitDictEntry[]) {
+            { "json-type", QLIT_QSTR("string"), },
+            { "meta-type", QLIT_QSTR("builtin"), },
+            { "name", QLIT_QSTR("str"), },
+            {}
+        })),
+        {}
+    }));
+
+    [Uninteresting stuff omitted...]