qapi-code-gen.txt 32.4 KB
Newer Older
1 2
= How to use the QAPI code generator =

3 4 5 6 7 8 9 10
Copyright IBM Corp. 2011
Copyright (C) 2012-2015 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 ==

11
QAPI is a native C API within QEMU which provides management-level
12 13 14 15
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.
16 17
The remainder of this document uses "Client JSON Protocol" when
referring to the wire contents of a QMP or QGA connection.
18

19 20 21 22 23
To map Client JSON Protocol interfaces to the native C QAPI
implementations, a JSON-based schema is used to define types and
function signatures, and a set of scripts is used to generate types,
signatures, and marshaling/dispatch code. This document will describe
how the schemas, scripts, and resulting code are used.
24 25 26 27


== QMP/Guest agent schema ==

28 29 30 31 32 33 34 35 36 37 38
A QAPI schema file is designed to be loosely based on JSON
(http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style
and the use of comments; a QAPI schema file is then parsed by a python
code generation program.  A valid QAPI schema consists of a series of
top-level expressions, with no commas between them.  Where
dictionaries (JSON objects) are used, they are parsed as python
OrderedDicts so that ordering is preserved (for predictable layout of
generated C structs and parameter lists).  Ordering doesn't matter
between top-level expressions or the keys within an expression, but
does matter within dictionary values for 'data' and 'returns' members
of a single expression.  QAPI schema input is written using 'single
39 40 41 42 43 44 45
quotes' instead of JSON's "double quotes" (in contrast, Client JSON
Protocol uses no comments, and while input accepts 'single quotes' as
an extension, output is strict JSON using only "double quotes").  As
in JSON, trailing commas are not permitted in arrays or dictionaries.
Input must be ASCII (although QMP supports full Unicode strings, the
QAPI parser does not).  At present, there is no place where a QAPI
schema requires the use of JSON numbers or null.
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76

Comments are allowed; anything between an unquoted # and the following
newline is ignored.  Although there is not yet a documentation
generator, a form of stylized comments has developed for consistently
documenting details about an expression and when it was added to the
schema.  The documentation is delimited between two lines of ##, then
the first line names the expression, an optional overview is provided,
then individual documentation about each member of 'data' is provided,
and finally, a 'Since: x.y.z' tag lists the release that introduced
the expression.  Optional fields are tagged with the phrase
'#optional', often with their default value; and extensions added
after the expression was first released are also given a '(since
x.y.z)' comment.  For example:

    ##
    # @BlockStats:
    #
    # Statistics of a virtual block device or a block backing device.
    #
    # @device: #optional If the stats are for a virtual block device, the name
    #          corresponding to the virtual block device.
    #
    # @stats:  A @BlockDeviceStats for the device.
    #
    # @parent: #optional This describes the file block device if it has one.
    #
    # @backing: #optional This describes the backing block device if it has one.
    #           (Since 2.0)
    #
    # Since: 0.14.0
    ##
E
Eric Blake 已提交
77
    { 'struct': 'BlockStats',
78 79 80 81 82 83 84 85 86
      'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
               '*parent': 'BlockStats',
               '*backing': 'BlockStats'} }

The schema sets up a series of types, as well as commands and events
that will use those types.  Forward references are allowed: the parser
scans in two passes, where the first pass learns all type names, and
the second validates the schema and generates the code.  This allows
the definition of complex structs that can have mutually recursive
87 88 89 90 91
types, and allows for indefinite nesting of Client JSON Protocol that
satisfies the schema.  A type name should not be defined more than
once.  It is permissible for the schema to contain additional types
not used by any commands or events in the Client JSON Protocol, for
the side effect of generated C code used internally.
92

93
There are seven top-level expressions recognized by the parser:
E
Eric Blake 已提交
94
'include', 'command', 'struct', 'enum', 'union', 'alternate', and
95 96 97 98
'event'.  There are several groups of types: simple types (a number of
built-in types, such as 'int' and 'str'; as well as enumerations),
complex types (structs and two flavors of unions), and alternate types
(a choice between other types).  The 'command' and 'event' expressions
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
can refer to existing types by name, or list an anonymous type as a
dictionary. Listing a type name inside an array refers to a
single-dimension array of that type; multi-dimension arrays are not
directly supported (although an array of a complex struct that
contains an array member is possible).

Types, commands, and events share a common namespace.  Therefore,
generally speaking, type definitions should always use CamelCase for
user-defined type names, while built-in types are lowercase. Type
definitions should not end in 'Kind', as this namespace is used for
creating implicit C enums for visiting union types.  Command names,
and field 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 such expressions,
consistency is preferred over blindly avoiding underscore.  Event
names should be ALL_CAPS with words separated by underscore.  The
special string '**' appears for some commands that manually perform
their own type checking rather than relying on the type-safe code
produced by the qapi code generators.

Any name (command, event, type, field, or enum value) beginning with
"x-" is marked experimental, and may be withdrawn or changed
incompatibly in a future release.  Downstream vendors may add
extensions; such extensions should begin with a prefix matching
"__RFQDN_" (for the reverse-fully-qualified-domain-name of the
vendor), even if the rest of the name uses dash (example:
__com.redhat_drive-mirror).  Other than downstream extensions (with
leading underscore and the use of dots), all names should begin with a
letter, and contain only ASCII letters, digits, dash, and underscore.
It is okay to reuse names that match C keywords; the generator will
rename a field named "default" in the QAPI to "q_default" in the
generated C code.

In the rest of this document, usage lines are given for each
expression type, with literal strings written in lower case and
placeholders written in capitals.  If a literal string includes a
prefix of '*', that key/value pair can be omitted from the expression.
E
Eric Blake 已提交
136
For example, a usage statement that includes '*base':STRUCT-NAME
137
means that an expression has an optional key 'base', which if present
E
Eric Blake 已提交
138
must have a value that forms a struct name.
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153


=== Built-in Types ===

The following types are built-in to the parser:
  'str' - arbitrary UTF-8 string
  'int' - 64-bit signed integer (although the C code may place further
          restrictions on acceptable range)
  'number' - floating point number
  'bool' - JSON value of true or false
  'int8', 'int16', 'int32', 'int64' - like 'int', but enforce maximum
                                      bit size
  'uint8', 'uint16', 'uint32', 'uint64' - unsigned counterparts
  'size' - like 'uint64', but allows scaled suffix from command line
           visitor
K
Kevin Wolf 已提交
154

155 156 157

=== Includes ===

158 159
Usage: { 'include': STRING }

160 161
The QAPI schema definitions can be modularized using the 'include' directive:

162
 { 'include': 'path/to/file.json' }
163 164

The directive is evaluated recursively, and include paths are relative to the
165 166 167 168 169 170 171 172 173
file using the directive. Multiple includes of the same file are
safe.  No other keys should appear in the expression, and the include
value should be a string.

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.
174 175


E
Eric Blake 已提交
176
=== Struct types ===
K
Kevin Wolf 已提交
177

E
Eric Blake 已提交
178
Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
179

E
Eric Blake 已提交
180
A struct is a dictionary containing a single 'data' key whose
181 182 183
value is a dictionary.  This corresponds to a struct in C or an Object
in JSON. Each value of the 'data' dictionary must be the name of a
type, or a one-element array containing a type name.  An example of a
E
Eric Blake 已提交
184
struct is:
185

E
Eric Blake 已提交
186
 { 'struct': 'MyType',
187
   'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
188

189
The use of '*' as a prefix to the name means the member is optional in
190
the corresponding JSON protocol usage.
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217

The default initialization value of an optional argument should not be changed
between versions of QEMU unless the new default maintains backward
compatibility to the user-visible behavior of the old default.

With proper documentation, this policy still allows some flexibility; for
example, documenting that a default of 0 picks an optimal buffer size allows
one release to declare the optimal size at 512 while another release declares
the optimal size at 4096 - the user-visible behavior is not the bytes used by
the buffer, but the fact that the buffer was optimal size.

On input structures (only mentioned in the 'data' side of a command), changing
from mandatory to optional is safe (older clients will supply the option, and
newer clients can benefit from the default); changing from optional to
mandatory is backwards incompatible (older clients may be omitting the option,
and must continue to work).

On output structures (only mentioned in the 'returns' side of a command),
changing from mandatory to optional is in general unsafe (older clients may be
expecting the field, and could crash if it is missing), although it can be done
if the only way that the optional argument will be omitted is when it is
triggered by the presence of a new input flag to the command that older clients
don't know to send.  Changing from optional to mandatory is safe.

A structure that is used in both input and output of various commands
must consider the backwards compatibility constraints of both directions
of use.
218

E
Eric Blake 已提交
219
A struct definition can specify another struct as its base.
220
In this case, the fields of the base type are included as top-level fields
221 222
of the new struct's dictionary in the Client JSON Protocol wire
format. An example definition is:
223

E
Eric Blake 已提交
224 225
 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
 { 'struct': 'BlockdevOptionsGenericCOWFormat',
226 227 228 229 230 231 232 233 234
   'base': 'BlockdevOptionsGenericFormat',
   'data': { '*backing': 'str' } }

An example BlockdevOptionsGenericCOWFormat object on the wire could use
both fields like this:

 { "file": "/some/place/my-image",
   "backing": "/some/place/my-backing-file" }

235

K
Kevin Wolf 已提交
236 237
=== Enumeration types ===

238 239 240 241
Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }

An enumeration type is a dictionary containing a single 'data' key
whose value is a list of strings.  An example enumeration is:
242 243 244

 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }

245 246 247 248 249
Nothing prevents an empty enumeration, although it is probably not
useful.  The list of strings should be lower case; if an enum name
represents multiple words, use '-' between words.  The string 'max' is
not allowed as an enum value, and values should not be repeated.

250 251 252
The enumeration values are passed as strings over the Client JSON
Protocol, but are encoded as C enum integral values in generated code.
While the C code starts numbering at 0, it is better to use explicit
253 254 255 256 257
comparisons to enum values than implicit comparisons to 0; the C code
will also include a generated enum member ending in _MAX for tracking
the size of the enum, useful when using common functions for
converting between strings and enum values.  Since the wire format
always passes by name, it is acceptable to reorder or add new
258 259 260 261 262
enumeration members in any location without breaking clients of Client
JSON Protocol; however, removing enum values would break
compatibility.  For any struct that has a field that will only contain
a finite set of string values, using an enum type for that field is
better than open-coding the field to be type 'str'.
263 264


K
Kevin Wolf 已提交
265 266
=== Union types ===

267
Usage: { 'union': STRING, 'data': DICT }
E
Eric Blake 已提交
268
or:    { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME,
269
         'discriminator': ENUM-MEMBER-OF-BASE }
K
Kevin Wolf 已提交
270

271
Union types are used to let the user choose between several different
272 273 274 275
variants for an object.  There are two flavors: simple (no
discriminator or base), flat (both discriminator and base).  A union
type is defined using a data dictionary as explained in the following
paragraphs.
K
Kevin Wolf 已提交
276

277 278
A simple union type defines a mapping from automatic discriminator
values to data types like in this example:
K
Kevin Wolf 已提交
279

E
Eric Blake 已提交
280 281
 { 'struct': 'FileOptions', 'data': { 'filename': 'str' } }
 { 'struct': 'Qcow2Options',
K
Kevin Wolf 已提交
282 283 284 285 286 287
   'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }

 { 'union': 'BlockdevOptions',
   'data': { 'file': 'FileOptions',
             'qcow2': 'Qcow2Options' } }

288 289 290 291
In the Client JSON Protocol, a simple union is represented by a
dictionary that contains the 'type' field as a discriminator, and a
'data' field that is of the specified data type corresponding to the
discriminator value, as in these examples:
K
Kevin Wolf 已提交
292

293
 { "type": "file", "data" : { "filename": "/some/place/my-image" } }
K
Kevin Wolf 已提交
294 295 296
 { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
                               "lazy-refcounts": true } }

297 298 299 300 301
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.  No branch of
the union can be named 'max', as this would collide with the implicit
enum.  The value for each branch can be of any type.
K
Kevin Wolf 已提交
302 303


E
Eric Blake 已提交
304
A flat union definition specifies a struct as its base, and
305 306 307 308 309
avoids nesting on the wire.  All branches of the union must be
complex types, and the top-level fields of the union dictionary on
the wire will be combination of fields from both the base type and the
appropriate branch type (when merging two dictionaries, there must be
no keys in common).  The 'discriminator' field must be the name of an
E
Eric Blake 已提交
310
enum-typed member of the base struct.
K
Kevin Wolf 已提交
311

312 313 314 315
The following example enhances the above simple union example by
adding a common field 'readonly', renaming the discriminator to
something more applicable, and reducing the number of {} required on
the wire:
316

317
 { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] }
E
Eric Blake 已提交
318
 { 'struct': 'BlockdevCommonOptions',
319
   'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } }
320 321 322
 { 'union': 'BlockdevOptions',
   'base': 'BlockdevCommonOptions',
   'discriminator': 'driver',
323
   'data': { 'file': 'FileOptions',
324 325
             'qcow2': 'Qcow2Options' } }

326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
Resulting in these JSON objects:

 { "driver": "file", "readonly": true,
   "filename": "/some/place/my-image" }
 { "driver": "qcow2", "readonly": false,
   "backing-file": "/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 can ensure that branches exist for all values of the
enum (although the order of the keys need not match the declaration of
the enum).  In the resulting generated C data types, a flat union is
represented as a struct with the base member fields included directly,
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
E
Eric Blake 已提交
343
union has a struct with a single member named 'data'.  That is,
344

345
 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
346

347
is identical on the wire to:
348

349
 { 'enum': 'Enum', 'data': ['one', 'two'] }
E
Eric Blake 已提交
350 351 352
 { 'struct': 'Base', 'data': { 'type': 'Enum' } }
 { 'struct': 'Branch1', 'data': { 'data': 'str' } }
 { 'struct': 'Branch2', 'data': { 'data': 'int' } }
353 354
 { 'union': 'Flat': 'base': 'Base', 'discriminator': 'type',
   'data': { 'one': 'Branch1', 'two': 'Branch2' } }
K
Kevin Wolf 已提交
355

356

357
=== Alternate types ===
K
Kevin Wolf 已提交
358

359 360 361 362 363 364 365 366
Usage: { 'alternate': STRING, 'data': DICT }

An alternate type is one that allows a choice between two or more JSON
data types (string, integer, number, or object, but currently not
array) on the wire.  The definition is similar to a simple union type,
where each branch of the union names a QAPI type.  For example:

 { 'alternate': 'BlockRef',
K
Kevin Wolf 已提交
367 368 369
   'data': { 'definition': 'BlockdevOptions',
             'reference': 'str' } }

370 371 372 373
Just like for a simple union, an implicit C enum 'NameKind' is created
to enumerate the branches for the alternate 'Name'.

Unlike a union, the discriminator string is never passed on the wire
374 375 376 377 378 379 380 381 382 383
for the Client JSON Protocol.  Instead, the value's JSON type serves
as an implicit discriminator, which in turn means that an alternate
can only express a choice between types represented differently in
JSON.  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; and if it is
typed as a complex type (struct or union), it accepts a JSON object.
Two different complex types, for instance, aren't permitted, because
both are represented as a JSON object.
384 385 386

The example alternate declaration above allows using both of the
following example objects:
K
Kevin Wolf 已提交
387 388 389 390

 { "file": "my_existing_block_device_id" }
 { "file": { "driver": "file",
             "readonly": false,
E
Eric Blake 已提交
391
             "filename": "/tmp/mydisk.qcow2" } }
K
Kevin Wolf 已提交
392 393


K
Kevin Wolf 已提交
394
=== Commands ===
395

396 397 398 399 400 401
Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
         '*returns': TYPE-NAME-OR-DICT,
         '*gen': false, '*success-response': false }

Commands are defined by using a dictionary containing several members,
where three members are most common.  The 'command' member is a
402 403
mandatory string, and determines the "execute" value passed in a
Client JSON Protocol command exchange.
404 405

The 'data' argument maps to the "arguments" dictionary passed in as
406 407 408 409 410 411
part of a Client JSON Protocol command.  The 'data' member is optional
and defaults to {} (an empty dictionary).  If present, it must be the
string name of a complex type, a one-element array containing the name
of a complex type, or a dictionary that declares an anonymous type
with the same semantics as a 'struct' expression, with one exception
noted below when 'gen' is used.
412 413

The 'returns' member describes what will appear in the "return" field
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432
of a Client JSON Protocol reply on successful completion of a command.
The member is optional from the command declaration; if absent, the
"return" field will be an empty dictionary.  If 'returns' is present,
it must be the string name of a complex or built-in type, a
one-element array containing the name of a complex or built-in type,
or a dictionary that declares an anonymous type with the same
semantics as a 'struct' expression, with one exception noted below
when 'gen' is used.  Although it is permitted to have the 'returns'
member name a built-in type or an array of built-in types, any command
that does this cannot be extended to return additional information in
the future; thus, new commands should strongly consider returning a
dictionary-based type or an array of dictionaries, even if the
dictionary only contains one field at the present.

All commands in Client JSON Protocol use a dictionary to report
failure, with no way to specify that in QAPI.  Where the error return
is different than the usual GenericError class in order to help the
client react differently to certain error conditions, it is worth
documenting this in the comments before the command declaration.
433 434 435 436 437

Some example commands:

 { 'command': 'my-first-command',
   'data': { 'arg1': 'str', '*arg2': 'str' } }
E
Eric Blake 已提交
438
 { 'struct': 'MyType', 'data': { '*value': 'str' } }
439 440 441
 { 'command': 'my-second-command',
   'returns': [ 'MyType' ] }

442
which would validate this Client JSON Protocol transaction:
443 444 445 446 447 448 449 450

 => { "execute": "my-first-command",
      "arguments": { "arg1": "hello" } }
 <= { "return": { } }
 => { "execute": "my-second-command" }
 <= { "return": [ { "value": "one" }, { } ] }

In rare cases, QAPI cannot express a type-safe representation of a
451 452 453 454 455 456 457 458
corresponding Client JSON Protocol command.  In these cases, if the
command expression includes the key 'gen' with boolean value false,
then the 'data' or 'returns' member that intends to bypass generated
type-safety and do its own manual validation should use an inline
dictionary definition, with a value of '**' rather than a valid type
name for the keys that the generated code will not validate.  Please
try to avoid adding new commands that rely on this, and instead use
type-safe unions.  For an example of bypass usage:
459 460 461 462 463 464 465 466 467 468 469 470 471

 { 'command': 'netdev_add',
   'data': {'type': 'str', 'id': 'str', '*props': '**'},
   'gen': false }

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 a
normal dictionary error on failure).  When a successful reply is not
possible, the command expression should include the optional key
'success-response' with boolean value false.  So far, only QGA makes
use of this field.
472 473


W
Wenchao Xia 已提交
474 475
=== Events ===

476 477 478 479 480 481
Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT }

Events are defined with the keyword 'event'.  It is not allowed to
name an event 'MAX', since the generator also produces a C enumeration
of all event names with a generated _MAX value at the end.  When
'data' is also specified, additional info will be included in the
E
Eric Blake 已提交
482
event, with similar semantics to a 'struct' expression.  Finally there
483 484
will be C API generated in qapi-event.h; when called by QEMU code, a
message with timestamp will be emitted on the wire.
W
Wenchao Xia 已提交
485 486 487 488 489 490 491 492 493 494 495

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 } }
496

497

498 499 500 501
== Code generation ==

Schemas are fed into 3 scripts to generate all the code/files that, paired
with the core QAPI libraries, comprise everything required to take JSON
502
commands read in by a Client JSON Protocol server, unmarshal the arguments into
503
the underlying C types, call into the corresponding C function, and map the
504
response back to a Client JSON Protocol response to be returned to the user.
505 506 507 508 509 510 511

As an example, we'll use the following schema, which describes a single
complex user-defined type (which will produce a C struct, along with a list
node structure that can be used to chain together a list of such types in
case we want to accept/return a list of this type with a command), and a
command which takes that type as a parameter and returns the same type:

512
    $ cat example-schema.json
E
Eric Blake 已提交
513
    { 'struct': 'UserDefOne',
514 515 516 517 518 519
      'data': { 'integer': 'int', 'string': 'str' } }

    { 'command': 'my-command',
      'data':    {'arg1': 'UserDefOne'},
      'returns': 'UserDefOne' }

520 521
    { 'event': 'MY_EVENT' }

522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537
=== scripts/qapi-types.py ===

Used to generate the C types defined by a schema. The following files are
created:

$(prefix)qapi-types.h - C types corresponding to types defined in
                        the schema you pass in
$(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:

538
    $ python scripts/qapi-types.py --output-dir="qapi-generated" \
539
    --prefix="example-" example-schema.json
540
    $ cat qapi-generated/example-qapi-types.c
541 542
[Uninteresting stuff omitted...]

543
    void qapi_free_UserDefOneList(UserDefOneList *obj)
544 545 546 547 548 549 550 551 552 553 554 555 556
    {
        QapiDeallocVisitor *md;
        Visitor *v;

        if (!obj) {
            return;
        }

        md = qapi_dealloc_visitor_new();
        v = qapi_dealloc_get_visitor(md);
        visit_type_UserDefOneList(v, &obj, NULL, NULL);
        qapi_dealloc_visitor_cleanup(md);
    }
557

558
    void qapi_free_UserDefOne(UserDefOne *obj)
559 560 561 562 563 564 565 566 567 568 569 570 571 572
    {
        QapiDeallocVisitor *md;
        Visitor *v;

        if (!obj) {
            return;
        }

        md = qapi_dealloc_visitor_new();
        v = qapi_dealloc_get_visitor(md);
        visit_type_UserDefOne(v, &obj, NULL, NULL);
        qapi_dealloc_visitor_cleanup(md);
    }

573
    $ cat qapi-generated/example-qapi-types.h
574 575 576 577
[Uninteresting stuff omitted...]

    #ifndef EXAMPLE_QAPI_TYPES_H
    #define EXAMPLE_QAPI_TYPES_H
578

579
[Built-in types omitted...]
580 581 582 583 584

    typedef struct UserDefOne UserDefOne;

    typedef struct UserDefOneList
    {
585 586 587 588
        union {
            UserDefOne *value;
            uint64_t padding;
        };
589 590 591
        struct UserDefOneList *next;
    } UserDefOneList;

592
[Functions on built-in types omitted...]
593

594 595 596
    struct UserDefOne
    {
        int64_t integer;
597
        char *string;
598 599
    };

600 601
    void qapi_free_UserDefOneList(UserDefOneList *obj);
    void qapi_free_UserDefOne(UserDefOne *obj);
602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624

    #endif

=== scripts/qapi-visit.py ===

Used to generate the visitor functions used to walk through and convert
a QObject (as provided by QMP) to a native C data structure and
vice-versa, as well as the visitor function used to dealloc a complex
schema-defined C type.

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:

625
    $ python scripts/qapi-visit.py --output-dir="qapi-generated"
626
    --prefix="example-" example-schema.json
627
    $ cat qapi-generated/example-qapi-visit.c
628
[Uninteresting stuff omitted...]
629

630
    static void visit_type_UserDefOne_fields(Visitor *m, UserDefOne **obj, Error **errp)
631 632 633
    {
        Error *err = NULL;
        visit_type_int(m, &(*obj)->integer, "integer", &err);
634 635 636
        if (err) {
            goto out;
        }
637
        visit_type_str(m, &(*obj)->string, "string", &err);
638 639 640
        if (err) {
            goto out;
        }
641

642
    out:
643 644
        error_propagate(errp, err);
    }
645

646
    void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp)
647
    {
648 649 650 651 652 653
        Error *err = NULL;

        visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), &err);
        if (!err) {
            if (*obj) {
                visit_type_UserDefOne_fields(m, obj, errp);
654
            }
655
            visit_end_struct(m, &err);
656
        }
657
        error_propagate(errp, err);
658 659
    }

660
    void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp)
661
    {
662
        Error *err = NULL;
663
        GenericList *i, **prev;
664

665 666 667 668 669 670 671 672 673 674
        visit_start_list(m, name, &err);
        if (err) {
            goto out;
        }

        for (prev = (GenericList **)obj;
             !err && (i = visit_next_list(m, prev, &err)) != NULL;
             prev = &i) {
            UserDefOneList *native_i = (UserDefOneList *)i;
            visit_type_UserDefOne(m, &native_i->value, NULL, &err);
675
        }
676 677 678 679 680 681

        error_propagate(errp, err);
        err = NULL;
        visit_end_list(m, &err);
    out:
        error_propagate(errp, err);
682
    }
683
    $ cat qapi-generated/example-qapi-visit.h
684
[Uninteresting stuff omitted...]
685

686 687
    #ifndef EXAMPLE_QAPI_VISIT_H
    #define EXAMPLE_QAPI_VISIT_H
688

689
[Visitors for built-in types omitted...]
690

691 692
    void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp);
    void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp);
693 694 695 696 697 698 699 700 701 702 703

    #endif

=== scripts/qapi-commands.py ===

Used to generate the marshaling/dispatch functions for the commands defined
in the schema. The following files are generated:

$(prefix)qmp-marshal.c: command marshal/dispatch functions for each
                        QMP command defined in the schema. Functions
                        generated by qapi-visit.py are used to
704
                        convert QObjects received from the wire into
705 706 707 708 709 710 711 712 713 714
                        function parameters, and uses the same
                        visitor functions to convert native C return
                        values to QObjects from transmission back
                        over the wire.

$(prefix)qmp-commands.h: Function prototypes for the QMP commands
                         specified in the schema.

Example:

715
    $ python scripts/qapi-commands.py --output-dir="qapi-generated"
716
    --prefix="example-" example-schema.json
717
    $ cat qapi-generated/example-qmp-marshal.c
718
[Uninteresting stuff omitted...]
719

720
    static void qmp_marshal_output_my_command(UserDefOne *ret_in, QObject **ret_out, Error **errp)
721
    {
722
        Error *local_err = NULL;
723
        QmpOutputVisitor *mo = qmp_output_visitor_new();
724
        QapiDeallocVisitor *md;
725 726 727
        Visitor *v;

        v = qmp_output_get_visitor(mo);
728 729 730
        visit_type_UserDefOne(v, &ret_in, "unused", &local_err);
        if (local_err) {
            goto out;
731
        }
732 733 734 735
        *ret_out = qmp_output_get_qobject(mo);

    out:
        error_propagate(errp, local_err);
736
        qmp_output_visitor_cleanup(mo);
737
        md = qapi_dealloc_visitor_new();
738
        v = qapi_dealloc_get_visitor(md);
739
        visit_type_UserDefOne(v, &ret_in, "unused", NULL);
740 741 742
        qapi_dealloc_visitor_cleanup(md);
    }

743
    static void qmp_marshal_input_my_command(QDict *args, QObject **ret, Error **errp)
744
    {
745
        Error *local_err = NULL;
746
        UserDefOne *retval = NULL;
747
        QmpInputVisitor *mi = qmp_input_visitor_new_strict(QOBJECT(args));
748 749
        QapiDeallocVisitor *md;
        Visitor *v;
750
        UserDefOne *arg1 = NULL;
751 752

        v = qmp_input_get_visitor(mi);
753 754
        visit_type_UserDefOne(v, &arg1, "arg1", &local_err);
        if (local_err) {
755 756
            goto out;
        }
757 758 759 760

        retval = qmp_my_command(arg1, &local_err);
        if (local_err) {
            goto out;
761
        }
762

763 764
        qmp_marshal_output_my_command(retval, ret, &local_err);

765
    out:
766
        error_propagate(errp, local_err);
767
        qmp_input_visitor_cleanup(mi);
768 769
        md = qapi_dealloc_visitor_new();
        v = qapi_dealloc_get_visitor(md);
770
        visit_type_UserDefOne(v, &arg1, "arg1", NULL);
771 772 773 774 775 776
        qapi_dealloc_visitor_cleanup(md);
        return;
    }

    static void qmp_init_marshal(void)
    {
777
        qmp_register_command("my-command", qmp_marshal_input_my_command, QCO_NO_OPTIONS);
778 779 780
    }

    qapi_init(qmp_init_marshal);
781
    $ cat qapi-generated/example-qmp-commands.h
782
[Uninteresting stuff omitted...]
783

784 785
    #ifndef EXAMPLE_QMP_COMMANDS_H
    #define EXAMPLE_QMP_COMMANDS_H
786 787

    #include "example-qapi-types.h"
788 789
    #include "qapi/qmp/qdict.h"
    #include "qapi/error.h"
790

791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806
    UserDefOne *qmp_my_command(UserDefOne *arg1, Error **errp);

    #endif

=== scripts/qapi-event.py ===

Used to generate the event-related C code defined by a schema. The
following files are created:

$(prefix)qapi-event.h - Function prototypes for each event type, plus an
                        enumeration of all event names
$(prefix)qapi-event.c - Implementation of functions to send an event

Example:

    $ python scripts/qapi-event.py --output-dir="qapi-generated"
807
    --prefix="example-" example-schema.json
808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851
    $ cat qapi-generated/example-qapi-event.c
[Uninteresting stuff omitted...]

    void qapi_event_send_my_event(Error **errp)
    {
        QDict *qmp;
        Error *local_err = NULL;
        QMPEventFuncEmit emit;
        emit = qmp_event_get_func_emit();
        if (!emit) {
            return;
        }

        qmp = qmp_event_build_dict("MY_EVENT");

        emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &local_err);

        error_propagate(errp, local_err);
        QDECREF(qmp);
    }

    const char *EXAMPLE_QAPIEvent_lookup[] = {
        "MY_EVENT",
        NULL,
    };
    $ cat qapi-generated/example-qapi-event.h
[Uninteresting stuff omitted...]

    #ifndef EXAMPLE_QAPI_EVENT_H
    #define EXAMPLE_QAPI_EVENT_H

    #include "qapi/error.h"
    #include "qapi/qmp/qdict.h"
    #include "example-qapi-types.h"


    void qapi_event_send_my_event(Error **errp);

    extern const char *EXAMPLE_QAPIEvent_lookup[];
    typedef enum EXAMPLE_QAPIEvent
    {
        EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
        EXAMPLE_QAPI_EVENT_MAX = 1,
    } EXAMPLE_QAPIEvent;
852 853

    #endif