mirror of
https://gitlab.com/qemu-project/qemu
synced 2024-07-21 10:24:33 +00:00
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>
This commit is contained in:
John Snow
Markus Armbruster
parent
e0366f9f2b
commit
f7aa076dbd
|
|
@ -42,3 +42,4 @@ modifying QEMU's source code.
|
|||
multi-process
|
||||
ebpf_rss
|
||||
vfio-migration
|
||||
qapi-code-gen
|
||||
|
|
|
|||
|
|
@ -1,12 +1,17 @@
|
|||
= How to use the QAPI code generator =
|
||||
==================================
|
||||
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 ==
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
QAPI is a native C API within QEMU which provides management-level
|
||||
functionality to internal and external users. For external
|
||||
|
|
@ -23,7 +28,8 @@ Protocol and to C. It additionally provides guidance on maintaining
|
|||
Client JSON Protocol compatibility.
|
||||
|
||||
|
||||
== The QAPI schema language ==
|
||||
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
|
||||
|
|
@ -39,9 +45,10 @@ complex types (structs and two flavors of unions), and alternate types
|
|||
(a choice between other types).
|
||||
|
||||
|
||||
=== Schema syntax ===
|
||||
Schema syntax
|
||||
-------------
|
||||
|
||||
Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt).
|
||||
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
|
||||
|
|
@ -79,7 +86,7 @@ syntax in an EBNF-like notation:
|
|||
The order of members within JSON objects does not matter unless
|
||||
explicitly noted.
|
||||
|
||||
A QAPI schema consists of a series of top-level expressions:
|
||||
A QAPI schema consists of a series of top-level expressions::
|
||||
|
||||
SCHEMA = TOP-LEVEL-EXPR...
|
||||
|
||||
|
|
@ -87,11 +94,11 @@ 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:
|
||||
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:
|
||||
There are two kinds of directives and six kinds of definitions::
|
||||
|
||||
DIRECTIVE = INCLUDE | PRAGMA
|
||||
DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT
|
||||
|
|
@ -99,9 +106,10 @@ There are two kinds of directives and six kinds of definitions:
|
|||
These are discussed in detail below.
|
||||
|
||||
|
||||
=== Built-in Types ===
|
||||
Built-in Types
|
||||
--------------
|
||||
|
||||
The following types are predefined, and map to C as follows:
|
||||
The following types are predefined, and map to C as follows::
|
||||
|
||||
Schema C JSON
|
||||
str char * any JSON string, UTF-8
|
||||
|
|
@ -124,12 +132,14 @@ The following types are predefined, and map to C as follows:
|
|||
QType QType JSON string matching enum QType values
|
||||
|
||||
|
||||
=== Include directives ===
|
||||
Include directives
|
||||
------------------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
INCLUDE = { 'include': STRING }
|
||||
|
||||
The QAPI schema definitions can be modularized using the 'include' directive:
|
||||
The QAPI schema definitions can be modularized using the 'include' directive::
|
||||
|
||||
{ 'include': 'path/to/file.json' }
|
||||
|
||||
|
|
@ -144,9 +154,11 @@ an outer file. The parser may be made stricter in the future to
|
|||
prevent incomplete include files.
|
||||
|
||||
|
||||
=== Pragma directives ===
|
||||
Pragma directives
|
||||
-----------------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
PRAGMA = { 'pragma': {
|
||||
'*doc-required': BOOL,
|
||||
'*command-name-exceptions': [ STRING, ... ],
|
||||
|
|
@ -172,9 +184,11 @@ names may contain uppercase letters, and '_' instead of '-'. Default
|
|||
is none.
|
||||
|
||||
|
||||
=== Enumeration types ===
|
||||
Enumeration types
|
||||
-----------------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
ENUM = { 'enum': STRING,
|
||||
'data': [ ENUM-VALUE, ... ],
|
||||
'*prefix': STRING,
|
||||
|
|
@ -189,7 +203,7 @@ 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:
|
||||
Example::
|
||||
|
||||
{ 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
|
||||
|
||||
|
|
@ -218,9 +232,11 @@ The optional 'features' member specifies features. See "Features"
|
|||
below for more on this.
|
||||
|
||||
|
||||
=== Type references and array types ===
|
||||
Type references and array types
|
||||
-------------------------------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
TYPE-REF = STRING | ARRAY-TYPE
|
||||
ARRAY-TYPE = [ STRING ]
|
||||
|
||||
|
|
@ -230,9 +246,11 @@ 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 ===
|
||||
Struct types
|
||||
------------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
STRUCT = { 'struct': STRING,
|
||||
'data': MEMBERS,
|
||||
'*base': STRING,
|
||||
|
|
@ -254,7 +272,7 @@ 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:
|
||||
Example::
|
||||
|
||||
{ 'struct': 'MyType',
|
||||
'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } }
|
||||
|
|
@ -265,7 +283,7 @@ 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:
|
||||
Example::
|
||||
|
||||
{ 'struct': 'BlockdevOptionsGenericFormat',
|
||||
'data': { 'file': 'str' } }
|
||||
|
|
@ -274,7 +292,7 @@ Example:
|
|||
'data': { '*backing': 'str' } }
|
||||
|
||||
An example BlockdevOptionsGenericCOWFormat object on the wire could use
|
||||
both members like this:
|
||||
both members like this::
|
||||
|
||||
{ "file": "/some/place/my-image",
|
||||
"backing": "/some/place/my-backing-file" }
|
||||
|
|
@ -286,9 +304,11 @@ The optional 'features' member specifies features. See "Features"
|
|||
below for more on this.
|
||||
|
||||
|
||||
=== Union types ===
|
||||
Union types
|
||||
-----------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
UNION = { 'union': STRING,
|
||||
'data': BRANCHES,
|
||||
'*if': COND,
|
||||
|
|
@ -317,7 +337,7 @@ 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:
|
||||
values to data types like in this example::
|
||||
|
||||
{ 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
|
||||
{ 'struct': 'BlockdevOptionsQcow2',
|
||||
|
|
@ -330,7 +350,7 @@ values to data types like in this example:
|
|||
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:
|
||||
discriminator value, as in these examples::
|
||||
|
||||
{ "type": "file", "data": { "filename": "/some/place/my-image" } }
|
||||
{ "type": "qcow2", "data": { "backing": "/some/place/my-image",
|
||||
|
|
@ -361,7 +381,7 @@ 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:
|
||||
default of 'type', and reducing the number of {} required on the wire::
|
||||
|
||||
{ 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
|
||||
{ 'union': 'BlockdevOptions',
|
||||
|
|
@ -370,7 +390,7 @@ default of 'type', and reducing the number of {} required on the wire:
|
|||
'data': { 'file': 'BlockdevOptionsFile',
|
||||
'qcow2': 'BlockdevOptionsQcow2' } }
|
||||
|
||||
Resulting in these JSON objects:
|
||||
Resulting in these JSON objects::
|
||||
|
||||
{ "driver": "file", "read-only": true,
|
||||
"filename": "/some/place/my-image" }
|
||||
|
|
@ -390,11 +410,11 @@ 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 has a struct with a single member named 'data'. That is, ::
|
||||
|
||||
{ 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
|
||||
|
||||
is identical on the wire to:
|
||||
is identical on the wire to::
|
||||
|
||||
{ 'enum': 'Enum', 'data': ['one', 'two'] }
|
||||
{ 'struct': 'Branch1', 'data': { 'data': 'str' } }
|
||||
|
|
@ -409,9 +429,11 @@ The optional 'features' member specifies features. See "Features"
|
|||
below for more on this.
|
||||
|
||||
|
||||
=== Alternate types ===
|
||||
Alternate types
|
||||
---------------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
ALTERNATE = { 'alternate': STRING,
|
||||
'data': ALTERNATIVES,
|
||||
'*if': COND,
|
||||
|
|
@ -430,7 +452,7 @@ 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:
|
||||
Example::
|
||||
|
||||
{ 'alternate': 'BlockdevRef',
|
||||
'data': { 'definition': 'BlockdevOptions',
|
||||
|
|
@ -449,7 +471,7 @@ 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:
|
||||
following example objects::
|
||||
|
||||
{ "file": "my_existing_block_device_id" }
|
||||
{ "file": { "driver": "file",
|
||||
|
|
@ -463,9 +485,11 @@ The optional 'features' member specifies features. See "Features"
|
|||
below for more on this.
|
||||
|
||||
|
||||
=== Commands ===
|
||||
Commands
|
||||
--------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
COMMAND = { 'command': STRING,
|
||||
(
|
||||
'*data': ( MEMBERS | STRING ),
|
||||
|
|
@ -508,7 +532,7 @@ 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:
|
||||
Some example commands::
|
||||
|
||||
{ 'command': 'my-first-command',
|
||||
'data': { 'arg1': 'str', '*arg2': 'str' } }
|
||||
|
|
@ -516,7 +540,7 @@ Some example commands:
|
|||
{ 'command': 'my-second-command',
|
||||
'returns': [ 'MyType' ] }
|
||||
|
||||
which would validate this Client JSON Protocol transaction:
|
||||
which would validate this Client JSON Protocol transaction::
|
||||
|
||||
=> { "execute": "my-first-command",
|
||||
"arguments": { "arg1": "hello" } }
|
||||
|
|
@ -543,7 +567,7 @@ 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:
|
||||
example::
|
||||
|
||||
{ 'command': 'netdev_add',
|
||||
'data': {'type': 'str', 'id': 'str'},
|
||||
|
|
@ -561,7 +585,7 @@ 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:
|
||||
(OOB) execution. It defaults to false. For example::
|
||||
|
||||
{ 'command': 'migrate_recover',
|
||||
'data': { 'uri': 'str' }, 'allow-oob': true }
|
||||
|
|
@ -594,7 +618,7 @@ 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:
|
||||
before the machine is built. It defaults to false. For example::
|
||||
|
||||
{ 'enum': 'QMPCapability',
|
||||
'data': [ 'oob' ] }
|
||||
|
|
@ -640,9 +664,11 @@ The optional 'features' member specifies features. See "Features"
|
|||
below for more on this.
|
||||
|
||||
|
||||
=== Events ===
|
||||
Events
|
||||
------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
EVENT = { 'event': STRING,
|
||||
(
|
||||
'*data': ( MEMBERS | STRING ),
|
||||
|
|
@ -665,12 +691,12 @@ 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:
|
||||
An example event is::
|
||||
|
||||
{ 'event': 'EVENT_C',
|
||||
'data': { '*a': 'int', 'b': 'str' } }
|
||||
|
||||
Resulting in this JSON object:
|
||||
Resulting in this JSON object::
|
||||
|
||||
{ "event": "EVENT_C",
|
||||
"data": { "b": "test string" },
|
||||
|
|
@ -688,9 +714,11 @@ The optional 'features' member specifies features. See "Features"
|
|||
below for more on this.
|
||||
|
||||
|
||||
=== Features ===
|
||||
Features
|
||||
--------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
FEATURES = [ FEATURE, ... ]
|
||||
FEATURE = STRING
|
||||
| { 'name': STRING, '*if': COND }
|
||||
|
|
@ -701,13 +729,13 @@ 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 }.
|
||||
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:
|
||||
Example::
|
||||
|
||||
{ 'struct': 'TestType',
|
||||
'data': { 'number': 'int' },
|
||||
|
|
@ -720,20 +748,22 @@ Intended use is to have each feature string signal that this build of
|
|||
QEMU shows a certain behaviour.
|
||||
|
||||
|
||||
==== Special features ====
|
||||
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 ===
|
||||
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
|
||||
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.
|
||||
|
|
@ -753,7 +783,7 @@ 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
|
||||
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.
|
||||
|
||||
|
|
@ -765,7 +795,8 @@ Pragmas 'command-name-exceptions' and 'member-name-exceptions' let you
|
|||
violate naming rules. Use for new code is strongly discouraged.
|
||||
|
||||
|
||||
=== Downstream extensions ===
|
||||
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
|
||||
|
|
@ -777,9 +808,11 @@ Example: Red Hat, Inc. controls redhat.com, and may therefore add a
|
|||
downstream command __com.redhat_drive-mirror.
|
||||
|
||||
|
||||
=== Configuring the schema ===
|
||||
Configuring the schema
|
||||
----------------------
|
||||
|
||||
Syntax::
|
||||
|
||||
Syntax:
|
||||
COND = STRING
|
||||
| [ STRING, ... ]
|
||||
|
||||
|
|
@ -788,12 +821,12 @@ 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
|
||||
Example: a conditional struct ::
|
||||
|
||||
{ 'struct': 'IfStruct', 'data': { 'foo': 'int' },
|
||||
'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] }
|
||||
|
||||
gets its generated code guarded like this:
|
||||
gets its generated code guarded like this::
|
||||
|
||||
#if defined(CONFIG_FOO)
|
||||
#if defined(HAVE_BAR)
|
||||
|
|
@ -806,7 +839,7 @@ 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'
|
||||
member 'bar' ::
|
||||
|
||||
{ 'struct': 'IfStruct', 'data':
|
||||
{ 'foo': 'int',
|
||||
|
|
@ -818,7 +851,7 @@ 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'
|
||||
value 'bar' ::
|
||||
|
||||
{ 'enum': 'IfEnum', 'data':
|
||||
[ 'foo',
|
||||
|
|
@ -827,7 +860,7 @@ value 'bar'
|
|||
Likewise, features can be conditional. This requires the longhand
|
||||
form of FEATURE.
|
||||
|
||||
Example: a struct with conditional feature 'allow-negative-numbers'
|
||||
Example: a struct with conditional feature 'allow-negative-numbers' ::
|
||||
|
||||
{ 'struct': 'TestType',
|
||||
'data': { 'number': 'int' },
|
||||
|
|
@ -843,12 +876,13 @@ shows a conditional entity only when the condition is satisfied in
|
|||
this particular build.
|
||||
|
||||
|
||||
=== Documentation comments ===
|
||||
Documentation comments
|
||||
----------------------
|
||||
|
||||
A multi-line comment that starts and ends with a '##' line is a
|
||||
documentation comment.
|
||||
|
||||
If the documentation comment starts like
|
||||
If the documentation comment starts like ::
|
||||
|
||||
##
|
||||
# @SYMBOL:
|
||||
|
|
@ -861,10 +895,12 @@ See below for more on definition documentation.
|
|||
Free-form documentation may be used to provide additional text and
|
||||
structuring content.
|
||||
|
||||
==== Headings and subheadings ====
|
||||
|
||||
Headings and subheadings
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A free-form documentation comment containing a line which starts with
|
||||
some '=' symbols and then a space defines a section heading:
|
||||
some '=' symbols and then a space defines a section heading::
|
||||
|
||||
##
|
||||
# = This is a top level heading
|
||||
|
|
@ -883,17 +919,19 @@ 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 markup
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Documentation comments can use most rST markup. In particular,
|
||||
a '::' literal block can be used for examples:
|
||||
a '::' literal block can be used for examples::
|
||||
|
||||
# ::
|
||||
#
|
||||
# Text of the example, may span
|
||||
# multiple lines
|
||||
|
||||
'*' starts an itemized list:
|
||||
'*' starts an itemized list::
|
||||
|
||||
# * First item, may span
|
||||
# multiple lines
|
||||
|
|
@ -901,7 +939,7 @@ a '::' literal block can be used for examples:
|
|||
|
||||
You can also use '-' instead of '*'.
|
||||
|
||||
A decimal number followed by '.' starts a numbered list:
|
||||
A decimal number followed by '.' starts a numbered list::
|
||||
|
||||
# 1. First item, may span
|
||||
# multiple lines
|
||||
|
|
@ -920,7 +958,7 @@ 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:
|
||||
Example::
|
||||
|
||||
##
|
||||
# Some text foo with **bold** and *emphasis*
|
||||
|
|
@ -937,7 +975,8 @@ Example:
|
|||
##
|
||||
|
||||
|
||||
==== Definition documentation ====
|
||||
Definition documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Definition documentation, if present, must immediately precede the
|
||||
definition it documents.
|
||||
|
|
@ -956,7 +995,7 @@ 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:
|
||||
character of the first line of the description::
|
||||
|
||||
# @argone:
|
||||
# This is a two line description
|
||||
|
|
@ -997,7 +1036,7 @@ 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:
|
||||
For example::
|
||||
|
||||
##
|
||||
# @BlockStats:
|
||||
|
|
@ -1042,7 +1081,8 @@ For example:
|
|||
'returns': ['BlockStats'] }
|
||||
|
||||
|
||||
== Client JSON Protocol introspection ==
|
||||
Client JSON Protocol introspection
|
||||
==================================
|
||||
|
||||
Clients of a Client JSON Protocol commonly need to figure out what
|
||||
exactly the server (QEMU) supports.
|
||||
|
|
@ -1114,7 +1154,7 @@ 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
|
||||
Example: the SchemaInfo for command query-qmp-schema ::
|
||||
|
||||
{ "name": "query-qmp-schema", "meta-type": "command",
|
||||
"arg-type": "q_empty", "ret-type": "SchemaInfoList" }
|
||||
|
|
@ -1133,7 +1173,7 @@ 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
|
||||
Example: the SchemaInfo for EVENT_C from section Events ::
|
||||
|
||||
{ "name": "EVENT_C", "meta-type": "event",
|
||||
"arg-type": "q_obj-EVENT_C-arg" }
|
||||
|
|
@ -1157,7 +1197,7 @@ 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
|
||||
Example: the SchemaInfo for MyType from section Struct types ::
|
||||
|
||||
{ "name": "MyType", "meta-type": "object",
|
||||
"members": [
|
||||
|
|
@ -1168,7 +1208,7 @@ Example: the SchemaInfo for MyType from section Struct types
|
|||
"features" exposes the command's feature strings as a JSON array of
|
||||
strings.
|
||||
|
||||
Example: the SchemaInfo for TestType from section Features:
|
||||
Example: the SchemaInfo for TestType from section Features::
|
||||
|
||||
{ "name": "TestType", "meta-type": "object",
|
||||
"members": [
|
||||
|
|
@ -1184,7 +1224,7 @@ that provides the variant members for this type tag value). The
|
|||
list cases in the same order as the corresponding "tag" enum type.
|
||||
|
||||
Example: the SchemaInfo for flat union BlockdevOptions from section
|
||||
Union types
|
||||
Union types ::
|
||||
|
||||
{ "name": "BlockdevOptions", "meta-type": "object",
|
||||
"members": [
|
||||
|
|
@ -1205,7 +1245,7 @@ A simple union implicitly defines an object type for each of its
|
|||
variants.
|
||||
|
||||
Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
|
||||
Union types
|
||||
Union types ::
|
||||
|
||||
{ "name": "BlockdevOptionsSimple", "meta-type": "object",
|
||||
"members": [
|
||||
|
|
@ -1225,7 +1265,7 @@ 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
|
||||
Example: the SchemaInfo for BlockdevRef from section Alternate types ::
|
||||
|
||||
{ "name": "BlockdevRef", "meta-type": "alternate",
|
||||
"members": [
|
||||
|
|
@ -1239,7 +1279,7 @@ 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']
|
||||
Example: the SchemaInfo for ['str'] ::
|
||||
|
||||
{ "name": "[str]", "meta-type": "array",
|
||||
"element-type": "str" }
|
||||
|
|
@ -1249,7 +1289,7 @@ 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
|
||||
Example: the SchemaInfo for MyEnum from section Enumeration types ::
|
||||
|
||||
{ "name": "MyEnum", "meta-type": "enum",
|
||||
"values": [ "value1", "value2", "value3" ] }
|
||||
|
|
@ -1259,7 +1299,7 @@ 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
|
||||
Example: the SchemaInfo for str ::
|
||||
|
||||
{ "name": "str", "meta-type": "builtin", "json-type": "string" }
|
||||
|
||||
|
|
@ -1273,7 +1313,8 @@ the names of built-in types. Clients should examine member
|
|||
"json-type" instead of hard-coding names of built-in types.
|
||||
|
||||
|
||||
== Compatibility considerations ==
|
||||
Compatibility considerations
|
||||
============================
|
||||
|
||||
Maintaining backward compatibility at the Client JSON Protocol level
|
||||
while evolving the schema requires some care. This section is about
|
||||
|
|
@ -1333,7 +1374,8 @@ may be freely renamed. Even certain refactorings are invisible, such
|
|||
as splitting members from one type into a common base type.
|
||||
|
||||
|
||||
== Code generation ==
|
||||
Code generation
|
||||
===============
|
||||
|
||||
The QAPI code generator qapi-gen.py generates code and documentation
|
||||
from the schema. Together with the core QAPI libraries, this code
|
||||
|
|
@ -1347,7 +1389,7 @@ 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.
|
||||
qmp_my_command(); everything else is produced by the generator. ::
|
||||
|
||||
$ cat example-schema.json
|
||||
{ 'struct': 'UserDefOne',
|
||||
|
|
@ -1359,7 +1401,7 @@ qmp_my_command(); everything else is produced by the generator.
|
|||
|
||||
{ 'event': 'MY_EVENT' }
|
||||
|
||||
We run qapi-gen.py like this:
|
||||
We run qapi-gen.py like this::
|
||||
|
||||
$ python scripts/qapi-gen.py --output-dir="qapi-generated" \
|
||||
--prefix="example-" example-schema.json
|
||||
|
|
@ -1369,21 +1411,24 @@ 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 ===
|
||||
|
||||
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.h``
|
||||
C types corresponding to types defined in the schema
|
||||
|
||||
$(prefix)qapi-types.c - Cleanup functions for the above C types
|
||||
``$(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:
|
||||
Example::
|
||||
|
||||
$ cat qapi-generated/example-qapi-types.h
|
||||
[Uninteresting stuff omitted...]
|
||||
|
|
@ -1453,7 +1498,7 @@ Example:
|
|||
[Uninteresting stuff omitted...]
|
||||
|
||||
For a modular QAPI schema (see section Include directives), code for
|
||||
each sub-module SUBDIR/SUBMODULE.json is actually generated into
|
||||
each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
|
||||
|
||||
SUBDIR/$(prefix)qapi-types-SUBMODULE.h
|
||||
SUBDIR/$(prefix)qapi-types-SUBMODULE.c
|
||||
|
|
@ -1461,11 +1506,15 @@ 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.h``
|
||||
C types corresponding to built-in types
|
||||
|
||||
qapi-builtin-types.c - Cleanup functions for the above C types
|
||||
``qapi-builtin-types.c``
|
||||
Cleanup functions for the above C types
|
||||
|
||||
=== Code generated for visiting QAPI 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
|
||||
|
|
@ -1474,16 +1523,15 @@ 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.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
|
||||
``$(prefix)qapi-visit.h``
|
||||
Declarations for previously mentioned visitor functions
|
||||
|
||||
Example:
|
||||
Example::
|
||||
|
||||
$ cat qapi-generated/example-qapi-visit.h
|
||||
[Uninteresting stuff omitted...]
|
||||
|
|
@ -1588,7 +1636,7 @@ Example:
|
|||
[Uninteresting stuff omitted...]
|
||||
|
||||
For a modular QAPI schema (see section Include directives), code for
|
||||
each sub-module SUBDIR/SUBMODULE.json is actually generated into
|
||||
each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
|
||||
|
||||
SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
|
||||
SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
|
||||
|
|
@ -1596,11 +1644,15 @@ 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.h``
|
||||
Visitor functions for built-in types
|
||||
|
||||
qapi-builtin-visit.c - Declarations for these visitor functions
|
||||
``qapi-builtin-visit.c``
|
||||
Declarations for these visitor functions
|
||||
|
||||
=== Code generated for commands ===
|
||||
|
||||
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
|
||||
|
|
@ -1608,17 +1660,20 @@ 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.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-commands.h``
|
||||
Function prototypes for the QMP commands specified in the schema
|
||||
|
||||
$(prefix)qapi-init-commands.h - Command initialization prototype
|
||||
``$(prefix)qapi-init-commands.h``
|
||||
Command initialization prototype
|
||||
|
||||
$(prefix)qapi-init-commands.c - Command initialization code
|
||||
``$(prefix)qapi-init-commands.c``
|
||||
Command initialization code
|
||||
|
||||
Example:
|
||||
Example::
|
||||
|
||||
$ cat qapi-generated/example-qapi-commands.h
|
||||
[Uninteresting stuff omitted...]
|
||||
|
|
@ -1711,28 +1766,33 @@ Example:
|
|||
[Uninteresting stuff omitted...]
|
||||
|
||||
For a modular QAPI schema (see section Include directives), code for
|
||||
each sub-module SUBDIR/SUBMODULE.json is actually generated into
|
||||
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 ===
|
||||
|
||||
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.h``
|
||||
Function prototypes for each event type
|
||||
|
||||
$(prefix)qapi-events.c - Implementation of functions to send an event
|
||||
``$(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.h``
|
||||
Enumeration of all event names, and common event code declarations
|
||||
|
||||
$(prefix)qapi-emit-events.c - Common event code definitions
|
||||
``$(prefix)qapi-emit-events.c``
|
||||
Common event code definitions
|
||||
|
||||
Example:
|
||||
Example::
|
||||
|
||||
$ cat qapi-generated/example-qapi-events.h
|
||||
[Uninteresting stuff omitted...]
|
||||
|
|
@ -1795,21 +1855,24 @@ Example:
|
|||
[Uninteresting stuff omitted...]
|
||||
|
||||
For a modular QAPI schema (see section Include directives), code for
|
||||
each sub-module SUBDIR/SUBMODULE.json is actually generated into
|
||||
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 ===
|
||||
|
||||
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.c``
|
||||
Defines a string holding a JSON description of the schema
|
||||
|
||||
$(prefix)qapi-introspect.h - Declares the above string
|
||||
``$(prefix)qapi-introspect.h``
|
||||
Declares the above string
|
||||
|
||||
Example:
|
||||
Example::
|
||||
|
||||
$ cat qapi-generated/example-qapi-introspect.h
|
||||
[Uninteresting stuff omitted...]
|
||||
Loading…
Reference in a new issue