configure: move accelerator logic to meson
[qemu.git] / docs / devel / qapi-code-gen.txt
1 = How to use the QAPI code generator =
2
3 Copyright IBM Corp. 2011
4 Copyright (C) 2012-2016 Red Hat, Inc.
5
6 This work is licensed under the terms of the GNU GPL, version 2 or
7 later.  See the COPYING file in the top-level directory.
8
9 == Introduction ==
10
11 QAPI is a native C API within QEMU which provides management-level
12 functionality to internal and external users.  For external
13 users/processes, this interface is made available by a JSON-based wire
14 format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
15 well as the QEMU Guest Agent (QGA) for communicating with the guest.
16 The remainder of this document uses "Client JSON Protocol" when
17 referring to the wire contents of a QMP or QGA connection.
18
19 To map between Client JSON Protocol interfaces and the native C API,
20 we generate C code from a QAPI schema.  This document describes the
21 QAPI schema language, and how it gets mapped to the Client JSON
22 Protocol and to C.  It additionally provides guidance on maintaining
23 Client JSON Protocol compatibility.
24
25
26 == The QAPI schema language ==
27
28 The QAPI schema defines the Client JSON Protocol's commands and
29 events, as well as types used by them.  Forward references are
30 allowed.
31
32 It is permissible for the schema to contain additional types not used
33 by any commands or events, for the side effect of generated C code
34 used internally.
35
36 There are several kinds of types: simple types (a number of built-in
37 types, such as 'int' and 'str'; as well as enumerations), arrays,
38 complex types (structs and two flavors of unions), and alternate types
39 (a choice between other types).
40
41
42 === Schema syntax ===
43
44 Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt).
45 Differences:
46
47 * Comments: start with a hash character (#) that is not part of a
48   string, and extend to the end of the line.
49
50 * Strings are enclosed in 'single quotes', not "double quotes".
51
52 * Strings are restricted to printable ASCII, and escape sequences to
53   just '\\'.
54
55 * Numbers and null are not supported.
56
57 A second layer of syntax defines the sequences of JSON texts that are
58 a correctly structured QAPI schema.  We provide a grammar for this
59 syntax in an EBNF-like notation:
60
61 * Production rules look like non-terminal = expression
62 * Concatenation: expression A B matches expression A, then B
63 * Alternation: expression A | B matches expression A or B
64 * Repetition: expression A... matches zero or more occurrences of
65   expression A
66 * Repetition: expression A, ... matches zero or more occurrences of
67   expression A separated by ,
68 * Grouping: expression ( A ) matches expression A
69 * JSON's structural characters are terminals: { } [ ] : ,
70 * JSON's literal names are terminals: false true
71 * String literals enclosed in 'single quotes' are terminal, and match
72   this JSON string, with a leading '*' stripped off
73 * When JSON object member's name starts with '*', the member is
74   optional.
75 * The symbol STRING is a terminal, and matches any JSON string
76 * The symbol BOOL is a terminal, and matches JSON false or true
77 * ALL-CAPS words other than STRING are non-terminals
78
79 The order of members within JSON objects does not matter unless
80 explicitly noted.
81
82 A QAPI schema consists of a series of top-level expressions:
83
84     SCHEMA = TOP-LEVEL-EXPR...
85
86 The top-level expressions are all JSON objects.  Code and
87 documentation is generated in schema definition order.  Code order
88 should not matter.
89
90 A top-level expressions is either a directive or a definition:
91
92     TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION
93
94 There are two kinds of directives and six kinds of definitions:
95
96     DIRECTIVE = INCLUDE | PRAGMA
97     DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT
98
99 These are discussed in detail below.
100
101
102 === Built-in Types ===
103
104 The following types are predefined, and map to C as follows:
105
106   Schema    C          JSON
107   str       char *     any JSON string, UTF-8
108   number    double     any JSON number
109   int       int64_t    a JSON number without fractional part
110                        that fits into the C integer type
111   int8      int8_t     likewise
112   int16     int16_t    likewise
113   int32     int32_t    likewise
114   int64     int64_t    likewise
115   uint8     uint8_t    likewise
116   uint16    uint16_t   likewise
117   uint32    uint32_t   likewise
118   uint64    uint64_t   likewise
119   size      uint64_t   like uint64_t, except StringInputVisitor
120                        accepts size suffixes
121   bool      bool       JSON true or false
122   null      QNull *    JSON null
123   any       QObject *  any JSON value
124   QType     QType      JSON string matching enum QType values
125
126
127 === Include directives ===
128
129 Syntax:
130     INCLUDE = { 'include': STRING }
131
132 The QAPI schema definitions can be modularized using the 'include' directive:
133
134  { 'include': 'path/to/file.json' }
135
136 The directive is evaluated recursively, and include paths are relative
137 to the file using the directive.  Multiple includes of the same file
138 are idempotent.
139
140 As a matter of style, it is a good idea to have all files be
141 self-contained, but at the moment, nothing prevents an included file
142 from making a forward reference to a type that is only introduced by
143 an outer file.  The parser may be made stricter in the future to
144 prevent incomplete include files.
145
146
147 === Pragma directives ===
148
149 Syntax:
150     PRAGMA = { 'pragma': { '*doc-required': BOOL,
151                            '*returns-whitelist': [ STRING, ... ],
152                            '*name-case-whitelist': [ STRING, ... ] } }
153
154 The pragma directive lets you control optional generator behavior.
155
156 Pragma's scope is currently the complete schema.  Setting the same
157 pragma to different values in parts of the schema doesn't work.
158
159 Pragma 'doc-required' takes a boolean value.  If true, documentation
160 is required.  Default is false.
161
162 Pragma 'returns-whitelist' takes a list of command names that may
163 violate the rules on permitted return types.  Default is none.
164
165 Pragma 'name-case-whitelist' takes a list of names that may violate
166 rules on use of upper- vs. lower-case letters.  Default is none.
167
168
169 === Enumeration types ===
170
171 Syntax:
172     ENUM = { 'enum': STRING,
173              'data': [ ENUM-VALUE, ... ],
174              '*prefix': STRING,
175              '*if': COND,
176              '*features': FEATURES }
177     ENUM-VALUE = STRING
178                | { 'name': STRING, '*if': COND }
179
180 Member 'enum' names the enum type.
181
182 Each member of the 'data' array defines a value of the enumeration
183 type.  The form STRING is shorthand for { 'name': STRING }.  The
184 'name' values must be be distinct.
185
186 Example:
187
188  { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
189
190 Nothing prevents an empty enumeration, although it is probably not
191 useful.
192
193 On the wire, an enumeration type's value is represented by its
194 (string) name.  In C, it's represented by an enumeration constant.
195 These are of the form PREFIX_NAME, where PREFIX is derived from the
196 enumeration type's name, and NAME from the value's name.  For the
197 example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to
198 VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1.  The
199 optional 'prefix' member overrides PREFIX.
200
201 The generated C enumeration constants have values 0, 1, ..., N-1 (in
202 QAPI schema order), where N is the number of values.  There is an
203 additional enumeration constant PREFIX__MAX with value N.
204
205 Do not use string or an integer type when an enumeration type can do
206 the job satisfactorily.
207
208 The optional 'if' member specifies a conditional.  See "Configuring
209 the schema" below for more on this.
210
211 The optional 'features' member specifies features.  See "Features"
212 below for more on this.
213
214
215 === Type references and array types ===
216
217 Syntax:
218     TYPE-REF = STRING | ARRAY-TYPE
219     ARRAY-TYPE = [ STRING ]
220
221 A string denotes the type named by the string.
222
223 A one-element array containing a string denotes an array of the type
224 named by the string.  Example: ['int'] denotes an array of 'int'.
225
226
227 === Struct types ===
228
229 Syntax:
230     STRUCT = { 'struct': STRING,
231                'data': MEMBERS,
232                '*base': STRING,
233                '*if': COND,
234                '*features': FEATURES }
235     MEMBERS = { MEMBER, ... }
236     MEMBER = STRING : TYPE-REF
237            | STRING : { 'type': TYPE-REF,
238                         '*if': COND,
239                         '*features': FEATURES }
240
241 Member 'struct' names the struct type.
242
243 Each MEMBER of the 'data' object defines a member of the struct type.
244
245 The MEMBER's STRING name consists of an optional '*' prefix and the
246 struct member name.  If '*' is present, the member is optional.
247
248 The MEMBER's value defines its properties, in particular its type.
249 The form TYPE-REF is shorthand for { 'type': TYPE-REF }.
250
251 Example:
252
253  { 'struct': 'MyType',
254    'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } }
255
256 A struct type corresponds to a struct in C, and an object in JSON.
257 The C struct's members are generated in QAPI schema order.
258
259 The optional 'base' member names a struct type whose members are to be
260 included in this type.  They go first in the C struct.
261
262 Example:
263
264  { 'struct': 'BlockdevOptionsGenericFormat',
265    'data': { 'file': 'str' } }
266  { 'struct': 'BlockdevOptionsGenericCOWFormat',
267    'base': 'BlockdevOptionsGenericFormat',
268    'data': { '*backing': 'str' } }
269
270 An example BlockdevOptionsGenericCOWFormat object on the wire could use
271 both members like this:
272
273  { "file": "/some/place/my-image",
274    "backing": "/some/place/my-backing-file" }
275
276 The optional 'if' member specifies a conditional.  See "Configuring
277 the schema" below for more on this.
278
279 The optional 'features' member specifies features.  See "Features"
280 below for more on this.
281
282
283 === Union types ===
284
285 Syntax:
286     UNION = { 'union': STRING,
287               'data': BRANCHES,
288               '*if': COND,
289               '*features': FEATURES }
290           | { 'union': STRING,
291               'data': BRANCHES,
292               'base': ( MEMBERS | STRING ),
293               'discriminator': STRING,
294               '*if': COND,
295               '*features': FEATURES }
296     BRANCHES = { BRANCH, ... }
297     BRANCH = STRING : TYPE-REF
298            | STRING : { 'type': TYPE-REF, '*if': COND }
299
300 Member 'union' names the union type.
301
302 There are two flavors of union types: simple (no discriminator or
303 base), and flat (both discriminator and base).
304
305 Each BRANCH of the 'data' object defines a branch of the union.  A
306 union must have at least one branch.
307
308 The BRANCH's STRING name is the branch name.
309
310 The BRANCH's value defines the branch's properties, in particular its
311 type.  The form TYPE-REF is shorthand for { 'type': TYPE-REF }.
312
313 A simple union type defines a mapping from automatic discriminator
314 values to data types like in this example:
315
316  { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
317  { 'struct': 'BlockdevOptionsQcow2',
318    'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
319
320  { 'union': 'BlockdevOptionsSimple',
321    'data': { 'file': 'BlockdevOptionsFile',
322              'qcow2': 'BlockdevOptionsQcow2' } }
323
324 In the Client JSON Protocol, a simple union is represented by an
325 object that contains the 'type' member as a discriminator, and a
326 'data' member that is of the specified data type corresponding to the
327 discriminator value, as in these examples:
328
329  { "type": "file", "data": { "filename": "/some/place/my-image" } }
330  { "type": "qcow2", "data": { "backing": "/some/place/my-image",
331                               "lazy-refcounts": true } }
332
333 The generated C code uses a struct containing a union.  Additionally,
334 an implicit C enum 'NameKind' is created, corresponding to the union
335 'Name', for accessing the various branches of the union.  The value
336 for each branch can be of any type.
337
338 Flat unions permit arbitrary common members that occur in all variants
339 of the union, not just a discriminator.  Their discriminators need not
340 be named 'type'.  They also avoid nesting on the wire.
341
342 The 'base' member defines the common members.  If it is a MEMBERS
343 object, it defines common members just like a struct type's 'data'
344 member defines struct type members.  If it is a STRING, it names a
345 struct type whose members are the common members.
346
347 All flat union branches must be of struct type.
348
349 In the Client JSON Protocol, a flat union is represented by an object
350 with the common members (from the base type) and the selected branch's
351 members.  The two sets of member names must be disjoint.  Member
352 'discriminator' must name a non-optional enum-typed member of the base
353 struct.
354
355 The following example enhances the above simple union example by
356 adding an optional common member 'read-only', renaming the
357 discriminator to something more applicable than the simple union's
358 default of 'type', and reducing the number of {} required on the wire:
359
360  { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
361  { 'union': 'BlockdevOptions',
362    'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
363    'discriminator': 'driver',
364    'data': { 'file': 'BlockdevOptionsFile',
365              'qcow2': 'BlockdevOptionsQcow2' } }
366
367 Resulting in these JSON objects:
368
369  { "driver": "file", "read-only": true,
370    "filename": "/some/place/my-image" }
371  { "driver": "qcow2", "read-only": false,
372    "backing": "/some/place/my-image", "lazy-refcounts": true }
373
374 Notice that in a flat union, the discriminator name is controlled by
375 the user, but because it must map to a base member with enum type, the
376 code generator ensures that branches match the existing values of the
377 enum.  The order of branches need not match the order of the enum
378 values.  The branches need not cover all possible enum values.
379 Omitted enum values are still valid branches that add no additional
380 members to the data type.  In the resulting generated C data types, a
381 flat union is represented as a struct with the base members in QAPI
382 schema order, and then a union of structures for each branch of the
383 struct.
384
385 A simple union can always be re-written as a flat union where the base
386 class has a single member named 'type', and where each branch of the
387 union has a struct with a single member named 'data'.  That is,
388
389  { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
390
391 is identical on the wire to:
392
393  { 'enum': 'Enum', 'data': ['one', 'two'] }
394  { 'struct': 'Branch1', 'data': { 'data': 'str' } }
395  { 'struct': 'Branch2', 'data': { 'data': 'int' } }
396  { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type',
397    'data': { 'one': 'Branch1', 'two': 'Branch2' } }
398
399 The optional 'if' member specifies a conditional.  See "Configuring
400 the schema" below for more on this.
401
402 The optional 'features' member specifies features.  See "Features"
403 below for more on this.
404
405
406 === Alternate types ===
407
408 Syntax:
409     ALTERNATE = { 'alternate': STRING,
410                   'data': ALTERNATIVES,
411                   '*if': COND,
412                   '*features': FEATURES }
413     ALTERNATIVES = { ALTERNATIVE, ... }
414     ALTERNATIVE = STRING : STRING
415                 | STRING : { 'type': STRING, '*if': COND }
416
417 Member 'alternate' names the alternate type.
418
419 Each ALTERNATIVE of the 'data' object defines a branch of the
420 alternate.  An alternate must have at least one branch.
421
422 The ALTERNATIVE's STRING name is the branch name.
423
424 The ALTERNATIVE's value defines the branch's properties, in particular
425 its type.  The form STRING is shorthand for { 'type': STRING }.
426
427 Example:
428
429  { 'alternate': 'BlockdevRef',
430    'data': { 'definition': 'BlockdevOptions',
431              'reference': 'str' } }
432
433 An alternate type is like a union type, except there is no
434 discriminator on the wire.  Instead, the branch to use is inferred
435 from the value.  An alternate can only express a choice between types
436 represented differently on the wire.
437
438 If a branch is typed as the 'bool' built-in, the alternate accepts
439 true and false; if it is typed as any of the various numeric
440 built-ins, it accepts a JSON number; if it is typed as a 'str'
441 built-in or named enum type, it accepts a JSON string; if it is typed
442 as the 'null' built-in, it accepts JSON null; and if it is typed as a
443 complex type (struct or union), it accepts a JSON object.
444
445 The example alternate declaration above allows using both of the
446 following example objects:
447
448  { "file": "my_existing_block_device_id" }
449  { "file": { "driver": "file",
450              "read-only": false,
451              "filename": "/tmp/mydisk.qcow2" } }
452
453 The optional 'if' member specifies a conditional.  See "Configuring
454 the schema" below for more on this.
455
456 The optional 'features' member specifies features.  See "Features"
457 below for more on this.
458
459
460 === Commands ===
461
462 Syntax:
463     COMMAND = { 'command': STRING,
464                 (
465                 '*data': ( MEMBERS | STRING ),
466                 |
467                 'data': STRING,
468                 'boxed': true,
469                 )
470                 '*returns': TYPE-REF,
471                 '*success-response': false,
472                 '*gen': false,
473                 '*allow-oob': true,
474                 '*allow-preconfig': true,
475                 '*if': COND,
476                 '*features': FEATURES }
477
478 Member 'command' names the command.
479
480 Member 'data' defines the arguments.  It defaults to an empty MEMBERS
481 object.
482
483 If 'data' is a MEMBERS object, then MEMBERS defines arguments just
484 like a struct type's 'data' defines struct type members.
485
486 If 'data' is a STRING, then STRING names a complex type whose members
487 are the arguments.  A union type requires 'boxed': true.
488
489 Member 'returns' defines the command's return type.  It defaults to an
490 empty struct type.  It must normally be a complex type or an array of
491 a complex type.  To return anything else, the command must be listed
492 in pragma 'returns-whitelist'.  If you do this, extending the command
493 to return additional information will be harder.  Use of
494 'returns-whitelist' for new commands is strongly discouraged.
495
496 A command's error responses are not specified in the QAPI schema.
497 Error conditions should be documented in comments.
498
499 In the Client JSON Protocol, the value of the "execute" or "exec-oob"
500 member is the command name.  The value of the "arguments" member then
501 has to conform to the arguments, and the value of the success
502 response's "return" member will conform to the return type.
503
504 Some example commands:
505
506  { 'command': 'my-first-command',
507    'data': { 'arg1': 'str', '*arg2': 'str' } }
508  { 'struct': 'MyType', 'data': { '*value': 'str' } }
509  { 'command': 'my-second-command',
510    'returns': [ 'MyType' ] }
511
512 which would validate this Client JSON Protocol transaction:
513
514  => { "execute": "my-first-command",
515       "arguments": { "arg1": "hello" } }
516  <= { "return": { } }
517  => { "execute": "my-second-command" }
518  <= { "return": [ { "value": "one" }, { } ] }
519
520 The generator emits a prototype for the C function implementing the
521 command.  The function itself needs to be written by hand.  See
522 section "Code generated for commands" for examples.
523
524 The function returns the return type.  When member 'boxed' is absent,
525 it takes the command arguments as arguments one by one, in QAPI schema
526 order.  Else it takes them wrapped in the C struct generated for the
527 complex argument type.  It takes an additional Error ** argument in
528 either case.
529
530 The generator also emits a marshalling function that extracts
531 arguments for the user's function out of an input QDict, calls the
532 user's function, and if it succeeded, builds an output QObject from
533 its return value.  This is for use by the QMP monitor core.
534
535 In rare cases, QAPI cannot express a type-safe representation of a
536 corresponding Client JSON Protocol command.  You then have to suppress
537 generation of a marshalling function by including a member 'gen' with
538 boolean value false, and instead write your own function.  For
539 example:
540
541  { 'command': 'netdev_add',
542    'data': {'type': 'str', 'id': 'str'},
543    'gen': false }
544
545 Please try to avoid adding new commands that rely on this, and instead
546 use type-safe unions.
547
548 Normally, the QAPI schema is used to describe synchronous exchanges,
549 where a response is expected.  But in some cases, the action of a
550 command is expected to change state in a way that a successful
551 response is not possible (although the command will still return an
552 error object on failure).  When a successful reply is not possible,
553 the command definition includes the optional member 'success-response'
554 with boolean value false.  So far, only QGA makes use of this member.
555
556 Member 'allow-oob' declares whether the command supports out-of-band
557 (OOB) execution.  It defaults to false.  For example:
558
559  { 'command': 'migrate_recover',
560    'data': { 'uri': 'str' }, 'allow-oob': true }
561
562 See qmp-spec.txt for out-of-band execution syntax and semantics.
563
564 Commands supporting out-of-band execution can still be executed
565 in-band.
566
567 When a command is executed in-band, its handler runs in the main
568 thread with the BQL held.
569
570 When a command is executed out-of-band, its handler runs in a
571 dedicated monitor I/O thread with the BQL *not* held.
572
573 An OOB-capable command handler must satisfy the following conditions:
574
575 - It terminates quickly.
576 - It does not invoke system calls that may block.
577 - It does not access guest RAM that may block when userfaultfd is
578   enabled for postcopy live migration.
579 - It takes only "fast" locks, i.e. all critical sections protected by
580   any lock it takes also satisfy the conditions for OOB command
581   handler code.
582
583 The restrictions on locking limit access to shared state.  Such access
584 requires synchronization, but OOB commands can't take the BQL or any
585 other "slow" lock.
586
587 When in doubt, do not implement OOB execution support.
588
589 Member 'allow-preconfig' declares whether the command is available
590 before the machine is built.  It defaults to false.  For example:
591
592  { 'command': 'qmp_capabilities',
593    'data': { '*enable': [ 'QMPCapability' ] },
594    'allow-preconfig': true }
595
596 QMP is available before the machine is built only when QEMU was
597 started with --preconfig.
598
599 The optional 'if' member specifies a conditional.  See "Configuring
600 the schema" below for more on this.
601
602 The optional 'features' member specifies features.  See "Features"
603 below for more on this.
604
605
606 === Events ===
607
608 Syntax:
609     EVENT = { 'event': STRING,
610               (
611               '*data': ( MEMBERS | STRING ),
612               |
613               'data': STRING,
614               'boxed': true,
615               )
616               '*if': COND,
617               '*features': FEATURES }
618
619 Member 'event' names the event.  This is the event name used in the
620 Client JSON Protocol.
621
622 Member 'data' defines the event-specific data.  It defaults to an
623 empty MEMBERS object.
624
625 If 'data' is a MEMBERS object, then MEMBERS defines event-specific
626 data just like a struct type's 'data' defines struct type members.
627
628 If 'data' is a STRING, then STRING names a complex type whose members
629 are the event-specific data.  A union type requires 'boxed': true.
630
631 An example event is:
632
633 { 'event': 'EVENT_C',
634   'data': { '*a': 'int', 'b': 'str' } }
635
636 Resulting in this JSON object:
637
638 { "event": "EVENT_C",
639   "data": { "b": "test string" },
640   "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
641
642 The generator emits a function to send the event.  When member 'boxed'
643 is absent, it takes event-specific data one by one, in QAPI schema
644 order.  Else it takes them wrapped in the C struct generated for the
645 complex type.  See section "Code generated for events" for examples.
646
647 The optional 'if' member specifies a conditional.  See "Configuring
648 the schema" below for more on this.
649
650 The optional 'features' member specifies features.  See "Features"
651 below for more on this.
652
653
654 === Features ===
655
656 Syntax:
657     FEATURES = [ FEATURE, ... ]
658     FEATURE = STRING
659             | { 'name': STRING, '*if': COND }
660
661 Sometimes, the behaviour of QEMU changes compatibly, but without a
662 change in the QMP syntax (usually by allowing values or operations
663 that previously resulted in an error).  QMP clients may still need to
664 know whether the extension is available.
665
666 For this purpose, a list of features can be specified for a command or
667 struct type.  Each list member can either be { 'name': STRING, '*if':
668 COND }, or STRING, which is shorthand for { 'name': STRING }.
669
670 The optional 'if' member specifies a conditional.  See "Configuring
671 the schema" below for more on this.
672
673 Example:
674
675 { 'struct': 'TestType',
676   'data': { 'number': 'int' },
677   'features': [ 'allow-negative-numbers' ] }
678
679 The feature strings are exposed to clients in introspection, as
680 explained in section "Client JSON Protocol introspection".
681
682 Intended use is to have each feature string signal that this build of
683 QEMU shows a certain behaviour.
684
685
686 ==== Special features ====
687
688 Feature "deprecated" marks a command, event, or struct member as
689 deprecated.  It is not supported elsewhere so far.
690
691
692 === Naming rules and reserved names ===
693
694 All names must begin with a letter, and contain only ASCII letters,
695 digits, hyphen, and underscore.  There are two exceptions: enum values
696 may start with a digit, and names that are downstream extensions (see
697 section Downstream extensions) start with underscore.
698
699 Names beginning with 'q_' are reserved for the generator, which uses
700 them for munging QMP names that resemble C keywords or other
701 problematic strings.  For example, a member named "default" in qapi
702 becomes "q_default" in the generated C code.
703
704 Types, commands, and events share a common namespace.  Therefore,
705 generally speaking, type definitions should always use CamelCase for
706 user-defined type names, while built-in types are lowercase.
707
708 Type names ending with 'Kind' or 'List' are reserved for the
709 generator, which uses them for implicit union enums and array types,
710 respectively.
711
712 Command names, and member names within a type, should be all lower
713 case with words separated by a hyphen.  However, some existing older
714 commands and complex types use underscore; when extending them,
715 consistency is preferred over blindly avoiding underscore.
716
717 Event names should be ALL_CAPS with words separated by underscore.
718
719 Member name 'u' and names starting with 'has-' or 'has_' are reserved
720 for the generator, which uses them for unions and for tracking
721 optional members.
722
723 Any name (command, event, type, member, or enum value) beginning with
724 "x-" is marked experimental, and may be withdrawn or changed
725 incompatibly in a future release.
726
727 Pragma 'name-case-whitelist' lets you violate the rules on use of
728 upper and lower case.  Use for new code is strongly discouraged.
729
730
731 === Downstream extensions ===
732
733 QAPI schema names that are externally visible, say in the Client JSON
734 Protocol, need to be managed with care.  Names starting with a
735 downstream prefix of the form __RFQDN_ are reserved for the downstream
736 who controls the valid, reverse fully qualified domain name RFQDN.
737 RFQDN may only contain ASCII letters, digits, hyphen and period.
738
739 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
740 downstream command __com.redhat_drive-mirror.
741
742
743 === Configuring the schema ===
744
745 Syntax:
746     COND = STRING
747          | [ STRING, ... ]
748
749 All definitions take an optional 'if' member.  Its value must be a
750 string or a list of strings.  A string is shorthand for a list
751 containing just that string.  The code generated for the definition
752 will then be guarded by #if STRING for each STRING in the COND list.
753
754 Example: a conditional struct
755
756  { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
757    'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] }
758
759 gets its generated code guarded like this:
760
761  #if defined(CONFIG_FOO)
762  #if defined(HAVE_BAR)
763  ... generated code ...
764  #endif /* defined(HAVE_BAR) */
765  #endif /* defined(CONFIG_FOO) */
766
767 Individual members of complex types, commands arguments, and
768 event-specific data can also be made conditional.  This requires the
769 longhand form of MEMBER.
770
771 Example: a struct type with unconditional member 'foo' and conditional
772 member 'bar'
773
774 { 'struct': 'IfStruct', 'data':
775   { 'foo': 'int',
776     'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
777
778 A union's discriminator may not be conditional.
779
780 Likewise, individual enumeration values be conditional.  This requires
781 the longhand form of ENUM-VALUE.
782
783 Example: an enum type with unconditional value 'foo' and conditional
784 value 'bar'
785
786 { 'enum': 'IfEnum', 'data':
787   [ 'foo',
788     { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
789
790 Likewise, features can be conditional.  This requires the longhand
791 form of FEATURE.
792
793 Example: a struct with conditional feature 'allow-negative-numbers'
794
795 { 'struct': 'TestType',
796   'data': { 'number': 'int' },
797   'features': [ { 'name': 'allow-negative-numbers',
798                   'if' 'defined(IFCOND)' } ] }
799
800 Please note that you are responsible to ensure that the C code will
801 compile with an arbitrary combination of conditions, since the
802 generator is unable to check it at this point.
803
804 The conditions apply to introspection as well, i.e. introspection
805 shows a conditional entity only when the condition is satisfied in
806 this particular build.
807
808
809 === Documentation comments ===
810
811 A multi-line comment that starts and ends with a '##' line is a
812 documentation comment.
813
814 If the documentation comment starts like
815
816     ##
817     # @SYMBOL:
818
819 it documents the definition if SYMBOL, else it's free-form
820 documentation.
821
822 See below for more on definition documentation.
823
824 Free-form documentation may be used to provide additional text and
825 structuring content.
826
827 ==== Headings and subheadings ====
828
829 A free-form documentation comment containing a line which starts with
830 some '=' symbols and then a space defines a section heading:
831
832     ##
833     # = This is a top level heading
834     #
835     # This is a free-form comment which will go under the
836     # top level heading.
837     ##
838
839     ##
840     # == This is a second level heading
841     ##
842
843 A heading line must be the first line of the documentation
844 comment block.
845
846 Section headings must always be correctly nested, so you can only
847 define a third-level heading inside a second-level heading, and so on.
848
849 ==== Documentation markup ====
850
851 Documentation comments can use most rST markup.  In particular,
852 a '::' literal block can be used for examples:
853
854     # ::
855     #
856     #   Text of the example, may span
857     #   multiple lines
858
859 '*' starts an itemized list:
860
861     # * First item, may span
862     #   multiple lines
863     # * Second item
864
865 You can also use '-' instead of '*'.
866
867 A decimal number followed by '.' starts a numbered list:
868
869     # 1. First item, may span
870     #    multiple lines
871     # 2. Second item
872
873 The actual number doesn't matter.
874
875 Lists of either kind must be preceded and followed by a blank line.
876 If a list item's text spans multiple lines, then the second and
877 subsequent lines must be correctly indented to line up with the
878 first character of the first line.
879
880 The usual '**strong**', '*emphasised*' and '``literal``' markup should
881 be used.  If you need a single literal '*' you will need to
882 backslash-escape it.  As an extension beyond the usual rST syntax, you
883 can also use '@foo' to reference a name in the schema; this is
884 rendered the same way as '``foo``'.
885
886 Example:
887
888 ##
889 # Some text foo with **bold** and *emphasis*
890 # 1. with a list
891 # 2. like that
892 #
893 # And some code:
894 #
895 # ::
896 #
897 #   $ echo foo
898 #   -> do this
899 #   <- get that
900 ##
901
902
903 ==== Definition documentation ====
904
905 Definition documentation, if present, must immediately precede the
906 definition it documents.
907
908 When documentation is required (see pragma 'doc-required'), every
909 definition must have documentation.
910
911 Definition documentation starts with a line naming the definition,
912 followed by an optional overview, a description of each argument (for
913 commands and events), member (for structs and unions), branch (for
914 alternates), or value (for enums), and finally optional tagged
915 sections.
916
917 Descriptions of arguments can span multiple lines.  The description
918 text can start on the line following the '@argname:', in which case it
919 must not be indented at all.  It can also start on the same line as
920 the '@argname:'.  In this case if it spans multiple lines then second
921 and subsequent lines must be indented to line up with the first
922 character of the first line of the description:
923
924 # @argone:
925 # This is a two line description
926 # in the first style.
927 #
928 # @argtwo: This is a two line description
929 #          in the second style.
930
931 The number of spaces between the ':' and the text is not significant.
932
933 FIXME: the parser accepts these things in almost any order.
934 FIXME: union branches should be described, too.
935
936 Extensions added after the definition was first released carry a
937 '(since x.y.z)' comment.
938
939 A tagged section starts with one of the following words:
940 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
941 The section ends with the start of a new section.
942
943 The text of a section can start on a new line, in
944 which case it must not be indented at all.  It can also start
945 on the same line as the 'Note:', 'Returns:', etc tag.  In this
946 case if it spans multiple lines then second and subsequent
947 lines must be indented to match the first, in the same way as
948 multiline argument descriptions.
949
950 A 'Since: x.y.z' tagged section lists the release that introduced the
951 definition.
952
953 The text of a section can start on a new line, in
954 which case it must not be indented at all.  It can also start
955 on the same line as the 'Note:', 'Returns:', etc tag.  In this
956 case if it spans multiple lines then second and subsequent
957 lines must be indented to match the first.
958
959 An 'Example' or 'Examples' section is automatically rendered
960 entirely as literal fixed-width text.  In other sections,
961 the text is formatted, and rST markup can be used.
962
963 For example:
964
965 ##
966 # @BlockStats:
967 #
968 # Statistics of a virtual block device or a block backing device.
969 #
970 # @device: If the stats are for a virtual block device, the name
971 #          corresponding to the virtual block device.
972 #
973 # @node-name: The node name of the device. (since 2.3)
974 #
975 # ... more members ...
976 #
977 # Since: 0.14.0
978 ##
979 { 'struct': 'BlockStats',
980   'data': {'*device': 'str', '*node-name': 'str',
981            ... more members ... } }
982
983 ##
984 # @query-blockstats:
985 #
986 # Query the @BlockStats for all virtual block devices.
987 #
988 # @query-nodes: If true, the command will query all the
989 #               block nodes ... explain, explain ...  (since 2.3)
990 #
991 # Returns: A list of @BlockStats for each virtual block devices.
992 #
993 # Since: 0.14.0
994 #
995 # Example:
996 #
997 # -> { "execute": "query-blockstats" }
998 # <- {
999 #      ... lots of output ...
1000 #    }
1001 #
1002 ##
1003 { 'command': 'query-blockstats',
1004   'data': { '*query-nodes': 'bool' },
1005   'returns': ['BlockStats'] }
1006
1007
1008 == Client JSON Protocol introspection ==
1009
1010 Clients of a Client JSON Protocol commonly need to figure out what
1011 exactly the server (QEMU) supports.
1012
1013 For this purpose, QMP provides introspection via command
1014 query-qmp-schema.  QGA currently doesn't support introspection.
1015
1016 While Client JSON Protocol wire compatibility should be maintained
1017 between qemu versions, we cannot make the same guarantees for
1018 introspection stability.  For example, one version of qemu may provide
1019 a non-variant optional member of a struct, and a later version rework
1020 the member to instead be non-optional and associated with a variant.
1021 Likewise, one version of qemu may list a member with open-ended type
1022 'str', and a later version could convert it to a finite set of strings
1023 via an enum type; or a member may be converted from a specific type to
1024 an alternate that represents a choice between the original type and
1025 something else.
1026
1027 query-qmp-schema returns a JSON array of SchemaInfo objects.  These
1028 objects together describe the wire ABI, as defined in the QAPI schema.
1029 There is no specified order to the SchemaInfo objects returned; a
1030 client must search for a particular name throughout the entire array
1031 to learn more about that name, but is at least guaranteed that there
1032 will be no collisions between type, command, and event names.
1033
1034 However, the SchemaInfo can't reflect all the rules and restrictions
1035 that apply to QMP.  It's interface introspection (figuring out what's
1036 there), not interface specification.  The specification is in the QAPI
1037 schema.  To understand how QMP is to be used, you need to study the
1038 QAPI schema.
1039
1040 Like any other command, query-qmp-schema is itself defined in the QAPI
1041 schema, along with the SchemaInfo type.  This text attempts to give an
1042 overview how things work.  For details you need to consult the QAPI
1043 schema.
1044
1045 SchemaInfo objects have common members "name", "meta-type",
1046 "features", and additional variant members depending on the value of
1047 meta-type.
1048
1049 Each SchemaInfo object describes a wire ABI entity of a certain
1050 meta-type: a command, event or one of several kinds of type.
1051
1052 SchemaInfo for commands and events have the same name as in the QAPI
1053 schema.
1054
1055 Command and event names are part of the wire ABI, but type names are
1056 not.  Therefore, the SchemaInfo for types have auto-generated
1057 meaningless names.  For readability, the examples in this section use
1058 meaningful type names instead.
1059
1060 Optional member "features" exposes the entity's feature strings as a
1061 JSON array of strings.
1062
1063 To examine a type, start with a command or event using it, then follow
1064 references by name.
1065
1066 QAPI schema definitions not reachable that way are omitted.
1067
1068 The SchemaInfo for a command has meta-type "command", and variant
1069 members "arg-type", "ret-type" and "allow-oob".  On the wire, the
1070 "arguments" member of a client's "execute" command must conform to the
1071 object type named by "arg-type".  The "return" member that the server
1072 passes in a success response conforms to the type named by "ret-type".
1073 When "allow-oob" is true, it means the command supports out-of-band
1074 execution.  It defaults to false.
1075
1076 If the command takes no arguments, "arg-type" names an object type
1077 without members.  Likewise, if the command returns nothing, "ret-type"
1078 names an object type without members.
1079
1080 Example: the SchemaInfo for command query-qmp-schema
1081
1082     { "name": "query-qmp-schema", "meta-type": "command",
1083       "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1084
1085     Type "q_empty" is an automatic object type without members, and type
1086     "SchemaInfoList" is the array of SchemaInfo type.
1087
1088 The SchemaInfo for an event has meta-type "event", and variant member
1089 "arg-type".  On the wire, a "data" member that the server passes in an
1090 event conforms to the object type named by "arg-type".
1091
1092 If the event carries no additional information, "arg-type" names an
1093 object type without members.  The event may not have a data member on
1094 the wire then.
1095
1096 Each command or event defined with 'data' as MEMBERS object in the
1097 QAPI schema implicitly defines an object type.
1098
1099 Example: the SchemaInfo for EVENT_C from section Events
1100
1101     { "name": "EVENT_C", "meta-type": "event",
1102       "arg-type": "q_obj-EVENT_C-arg" }
1103
1104     Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1105     the two members from the event's definition.
1106
1107 The SchemaInfo for struct and union types has meta-type "object".
1108
1109 The SchemaInfo for a struct type has variant member "members".
1110
1111 The SchemaInfo for a union type additionally has variant members "tag"
1112 and "variants".
1113
1114 "members" is a JSON array describing the object's common members, if
1115 any.  Each element is a JSON object with members "name" (the member's
1116 name), "type" (the name of its type), and optionally "default".  The
1117 member is optional if "default" is present.  Currently, "default" can
1118 only have value null.  Other values are reserved for future
1119 extensions.  The "members" array is in no particular order; clients
1120 must search the entire object when learning whether a particular
1121 member is supported.
1122
1123 Example: the SchemaInfo for MyType from section Struct types
1124
1125     { "name": "MyType", "meta-type": "object",
1126       "members": [
1127           { "name": "member1", "type": "str" },
1128           { "name": "member2", "type": "int" },
1129           { "name": "member3", "type": "str", "default": null } ] }
1130
1131 "features" exposes the command's feature strings as a JSON array of
1132 strings.
1133
1134 Example: the SchemaInfo for TestType from section Features:
1135
1136     { "name": "TestType", "meta-type": "object",
1137       "members": [
1138           { "name": "number", "type": "int" } ],
1139       "features": ["allow-negative-numbers"] }
1140
1141 "tag" is the name of the common member serving as type tag.
1142 "variants" is a JSON array describing the object's variant members.
1143 Each element is a JSON object with members "case" (the value of type
1144 tag this element applies to) and "type" (the name of an object type
1145 that provides the variant members for this type tag value).  The
1146 "variants" array is in no particular order, and is not guaranteed to
1147 list cases in the same order as the corresponding "tag" enum type.
1148
1149 Example: the SchemaInfo for flat union BlockdevOptions from section
1150 Union types
1151
1152     { "name": "BlockdevOptions", "meta-type": "object",
1153       "members": [
1154           { "name": "driver", "type": "BlockdevDriver" },
1155           { "name": "read-only", "type": "bool", "default": null } ],
1156       "tag": "driver",
1157       "variants": [
1158           { "case": "file", "type": "BlockdevOptionsFile" },
1159           { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
1160
1161 Note that base types are "flattened": its members are included in the
1162 "members" array.
1163
1164 A simple union implicitly defines an enumeration type for its implicit
1165 discriminator (called "type" on the wire, see section Union types).
1166
1167 A simple union implicitly defines an object type for each of its
1168 variants.
1169
1170 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
1171 Union types
1172
1173     { "name": "BlockdevOptionsSimple", "meta-type": "object",
1174       "members": [
1175           { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
1176       "tag": "type",
1177       "variants": [
1178           { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
1179           { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
1180
1181     Enumeration type "BlockdevOptionsSimpleKind" and the object types
1182     "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
1183     are implicitly defined.
1184
1185 The SchemaInfo for an alternate type has meta-type "alternate", and
1186 variant member "members".  "members" is a JSON array.  Each element is
1187 a JSON object with member "type", which names a type.  Values of the
1188 alternate type conform to exactly one of its member types.  There is
1189 no guarantee on the order in which "members" will be listed.
1190
1191 Example: the SchemaInfo for BlockdevRef from section Alternate types
1192
1193     { "name": "BlockdevRef", "meta-type": "alternate",
1194       "members": [
1195           { "type": "BlockdevOptions" },
1196           { "type": "str" } ] }
1197
1198 The SchemaInfo for an array type has meta-type "array", and variant
1199 member "element-type", which names the array's element type.  Array
1200 types are implicitly defined.  For convenience, the array's name may
1201 resemble the element type; however, clients should examine member
1202 "element-type" instead of making assumptions based on parsing member
1203 "name".
1204
1205 Example: the SchemaInfo for ['str']
1206
1207     { "name": "[str]", "meta-type": "array",
1208       "element-type": "str" }
1209
1210 The SchemaInfo for an enumeration type has meta-type "enum" and
1211 variant member "values".  The values are listed in no particular
1212 order; clients must search the entire enum when learning whether a
1213 particular value is supported.
1214
1215 Example: the SchemaInfo for MyEnum from section Enumeration types
1216
1217     { "name": "MyEnum", "meta-type": "enum",
1218       "values": [ "value1", "value2", "value3" ] }
1219
1220 The SchemaInfo for a built-in type has the same name as the type in
1221 the QAPI schema (see section Built-in Types), with one exception
1222 detailed below.  It has variant member "json-type" that shows how
1223 values of this type are encoded on the wire.
1224
1225 Example: the SchemaInfo for str
1226
1227     { "name": "str", "meta-type": "builtin", "json-type": "string" }
1228
1229 The QAPI schema supports a number of integer types that only differ in
1230 how they map to C.  They are identical as far as SchemaInfo is
1231 concerned.  Therefore, they get all mapped to a single type "int" in
1232 SchemaInfo.
1233
1234 As explained above, type names are not part of the wire ABI.  Not even
1235 the names of built-in types.  Clients should examine member
1236 "json-type" instead of hard-coding names of built-in types.
1237
1238
1239 == Compatibility considerations ==
1240
1241 Maintaining backward compatibility at the Client JSON Protocol level
1242 while evolving the schema requires some care.  This section is about
1243 syntactic compatibility, which is necessary, but not sufficient, for
1244 actual compatibility.
1245
1246 Clients send commands with argument data, and receive command
1247 responses with return data and events with event data.
1248
1249 Adding opt-in functionality to the send direction is backwards
1250 compatible: adding commands, optional arguments, enumeration values,
1251 union and alternate branches; turning an argument type into an
1252 alternate of that type; making mandatory arguments optional.  Clients
1253 oblivious of the new functionality continue to work.
1254
1255 Incompatible changes include removing commands, command arguments,
1256 enumeration values, union and alternate branches, adding mandatory
1257 command arguments, and making optional arguments mandatory.
1258
1259 The specified behavior of an absent optional argument should remain
1260 the same.  With proper documentation, this policy still allows some
1261 flexibility; for example, when an optional 'buffer-size' argument is
1262 specified to default to a sensible buffer size, the actual default
1263 value can still be changed.  The specified default behavior is not the
1264 exact size of the buffer, only that the default size is sensible.
1265
1266 Adding functionality to the receive direction is generally backwards
1267 compatible: adding events, adding return and event data members.
1268 Clients are expected to ignore the ones they don't know.
1269
1270 Removing "unreachable" stuff like events that can't be triggered
1271 anymore, optional return or event data members that can't be sent
1272 anymore, and return or event data member (enumeration) values that
1273 can't be sent anymore makes no difference to clients, except for
1274 introspection.  The latter can conceivably confuse clients, so tread
1275 carefully.
1276
1277 Incompatible changes include removing return and event data members.
1278
1279 Any change to a command definition's 'data' or one of the types used
1280 there (recursively) needs to consider send direction compatibility.
1281
1282 Any change to a command definition's 'return', an event definition's
1283 'data', or one of the types used there (recursively) needs to consider
1284 receive direction compatibility.
1285
1286 Any change to types used in both contexts need to consider both.
1287
1288 Enumeration type values and complex and alternate type members may be
1289 reordered freely.  For enumerations and alternate types, this doesn't
1290 affect the wire encoding.  For complex types, this might make the
1291 implementation emit JSON object members in a different order, which
1292 the Client JSON Protocol permits.
1293
1294 Since type names are not visible in the Client JSON Protocol, types
1295 may be freely renamed.  Even certain refactorings are invisible, such
1296 as splitting members from one type into a common base type.
1297
1298
1299 == Code generation ==
1300
1301 The QAPI code generator qapi-gen.py generates code and documentation
1302 from the schema.  Together with the core QAPI libraries, this code
1303 provides everything required to take JSON commands read in by a Client
1304 JSON Protocol server, unmarshal the arguments into the underlying C
1305 types, call into the corresponding C function, map the response back
1306 to a Client JSON Protocol response to be returned to the user, and
1307 introspect the commands.
1308
1309 As an example, we'll use the following schema, which describes a
1310 single complex user-defined type, along with command which takes a
1311 list of that type as a parameter, and returns a single element of that
1312 type.  The user is responsible for writing the implementation of
1313 qmp_my_command(); everything else is produced by the generator.
1314
1315     $ cat example-schema.json
1316     { 'struct': 'UserDefOne',
1317       'data': { 'integer': 'int', '*string': 'str' } }
1318
1319     { 'command': 'my-command',
1320       'data': { 'arg1': ['UserDefOne'] },
1321       'returns': 'UserDefOne' }
1322
1323     { 'event': 'MY_EVENT' }
1324
1325 We run qapi-gen.py like this:
1326
1327     $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1328     --prefix="example-" example-schema.json
1329
1330 For a more thorough look at generated code, the testsuite includes
1331 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1332 what the generator will accept, and compiles the resulting C code as
1333 part of 'make check-unit'.
1334
1335 === Code generated for QAPI types ===
1336
1337 The following files are created:
1338
1339 $(prefix)qapi-types.h - C types corresponding to types defined in
1340                         the schema
1341
1342 $(prefix)qapi-types.c - Cleanup functions for the above C types
1343
1344 The $(prefix) is an optional parameter used as a namespace to keep the
1345 generated code from one schema/code-generation separated from others so code
1346 can be generated/used from multiple schemas without clobbering previously
1347 created code.
1348
1349 Example:
1350
1351     $ cat qapi-generated/example-qapi-types.h
1352 [Uninteresting stuff omitted...]
1353
1354     #ifndef EXAMPLE_QAPI_TYPES_H
1355     #define EXAMPLE_QAPI_TYPES_H
1356
1357     #include "qapi/qapi-builtin-types.h"
1358
1359     typedef struct UserDefOne UserDefOne;
1360
1361     typedef struct UserDefOneList UserDefOneList;
1362
1363     typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1364
1365     struct UserDefOne {
1366         int64_t integer;
1367         bool has_string;
1368         char *string;
1369     };
1370
1371     void qapi_free_UserDefOne(UserDefOne *obj);
1372     G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne)
1373
1374     struct UserDefOneList {
1375         UserDefOneList *next;
1376         UserDefOne *value;
1377     };
1378
1379     void qapi_free_UserDefOneList(UserDefOneList *obj);
1380     G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList)
1381
1382     struct q_obj_my_command_arg {
1383         UserDefOneList *arg1;
1384     };
1385
1386     #endif /* EXAMPLE_QAPI_TYPES_H */
1387     $ cat qapi-generated/example-qapi-types.c
1388 [Uninteresting stuff omitted...]
1389
1390     void qapi_free_UserDefOne(UserDefOne *obj)
1391     {
1392         Visitor *v;
1393
1394         if (!obj) {
1395             return;
1396         }
1397
1398         v = qapi_dealloc_visitor_new();
1399         visit_type_UserDefOne(v, NULL, &obj, NULL);
1400         visit_free(v);
1401     }
1402
1403     void qapi_free_UserDefOneList(UserDefOneList *obj)
1404     {
1405         Visitor *v;
1406
1407         if (!obj) {
1408             return;
1409         }
1410
1411         v = qapi_dealloc_visitor_new();
1412         visit_type_UserDefOneList(v, NULL, &obj, NULL);
1413         visit_free(v);
1414     }
1415
1416 [Uninteresting stuff omitted...]
1417
1418 For a modular QAPI schema (see section Include directives), code for
1419 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1420
1421 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1422 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1423
1424 If qapi-gen.py is run with option --builtins, additional files are
1425 created:
1426
1427 qapi-builtin-types.h - C types corresponding to built-in types
1428
1429 qapi-builtin-types.c - Cleanup functions for the above C types
1430
1431 === Code generated for visiting QAPI types ===
1432
1433 These are the visitor functions used to walk through and convert
1434 between a native QAPI C data structure and some other format (such as
1435 QObject); the generated functions are named visit_type_FOO() and
1436 visit_type_FOO_members().
1437
1438 The following files are generated:
1439
1440 $(prefix)qapi-visit.c: Visitor function for a particular C type, used
1441                        to automagically convert QObjects into the
1442                        corresponding C type and vice-versa, as well
1443                        as for deallocating memory for an existing C
1444                        type
1445
1446 $(prefix)qapi-visit.h: Declarations for previously mentioned visitor
1447                        functions
1448
1449 Example:
1450
1451     $ cat qapi-generated/example-qapi-visit.h
1452 [Uninteresting stuff omitted...]
1453
1454     #ifndef EXAMPLE_QAPI_VISIT_H
1455     #define EXAMPLE_QAPI_VISIT_H
1456
1457     #include "qapi/qapi-builtin-visit.h"
1458     #include "example-qapi-types.h"
1459
1460
1461     bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1462     bool visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1463     bool visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1464
1465     bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1466
1467     #endif /* EXAMPLE_QAPI_VISIT_H */
1468     $ cat qapi-generated/example-qapi-visit.c
1469 [Uninteresting stuff omitted...]
1470
1471     bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1472     {
1473         if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1474             return false;
1475         }
1476         if (visit_optional(v, "string", &obj->has_string)) {
1477             if (!visit_type_str(v, "string", &obj->string, errp)) {
1478                 return false;
1479             }
1480         }
1481         return true;
1482     }
1483
1484     bool visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1485     {
1486         bool ok = false;
1487
1488         if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) {
1489             return false;
1490         }
1491         if (!*obj) {
1492             /* incomplete */
1493             assert(visit_is_dealloc(v));
1494             goto out_obj;
1495         }
1496         if (!visit_type_UserDefOne_members(v, *obj, errp)) {
1497             goto out_obj;
1498         }
1499         ok = visit_check_struct(v, errp);
1500     out_obj:
1501         visit_end_struct(v, (void **)obj);
1502         if (!ok && visit_is_input(v)) {
1503             qapi_free_UserDefOne(*obj);
1504             *obj = NULL;
1505         }
1506         return ok;
1507     }
1508
1509     bool visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1510     {
1511         bool ok = false;
1512         UserDefOneList *tail;
1513         size_t size = sizeof(**obj);
1514
1515         if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) {
1516             return false;
1517         }
1518
1519         for (tail = *obj; tail;
1520              tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1521             if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
1522                 goto out_obj;
1523             }
1524         }
1525
1526         ok = visit_check_list(v, errp);
1527     out_obj:
1528         visit_end_list(v, (void **)obj);
1529         if (!ok && visit_is_input(v)) {
1530             qapi_free_UserDefOneList(*obj);
1531             *obj = NULL;
1532         }
1533         return ok;
1534     }
1535
1536     bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1537     {
1538         if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1539             return false;
1540         }
1541         return true;
1542     }
1543
1544 [Uninteresting stuff omitted...]
1545
1546 For a modular QAPI schema (see section Include directives), code for
1547 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1548
1549 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1550 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1551
1552 If qapi-gen.py is run with option --builtins, additional files are
1553 created:
1554
1555 qapi-builtin-visit.h - Visitor functions for built-in types
1556
1557 qapi-builtin-visit.c - Declarations for these visitor functions
1558
1559 === Code generated for commands ===
1560
1561 These are the marshaling/dispatch functions for the commands defined
1562 in the schema.  The generated code provides qmp_marshal_COMMAND(), and
1563 declares qmp_COMMAND() that the user must implement.
1564
1565 The following files are generated:
1566
1567 $(prefix)qapi-commands.c: Command marshal/dispatch functions for each
1568                           QMP command defined in the schema
1569
1570 $(prefix)qapi-commands.h: Function prototypes for the QMP commands
1571                           specified in the schema
1572
1573 $(prefix)qapi-init-commands.h - Command initialization prototype
1574
1575 $(prefix)qapi-init-commands.c - Command initialization code
1576
1577 Example:
1578
1579     $ cat qapi-generated/example-qapi-commands.h
1580 [Uninteresting stuff omitted...]
1581
1582     #ifndef EXAMPLE_QAPI_COMMANDS_H
1583     #define EXAMPLE_QAPI_COMMANDS_H
1584
1585     #include "example-qapi-types.h"
1586
1587     UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1588     void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1589
1590     #endif /* EXAMPLE_QAPI_COMMANDS_H */
1591     $ cat qapi-generated/example-qapi-commands.c
1592 [Uninteresting stuff omitted...]
1593
1594     static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1595     {
1596         Visitor *v;
1597
1598         v = qobject_output_visitor_new(ret_out);
1599         if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) {
1600             visit_complete(v, ret_out);
1601         }
1602         visit_free(v);
1603         v = qapi_dealloc_visitor_new();
1604         visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1605         visit_free(v);
1606     }
1607
1608     void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1609     {
1610         Error *err = NULL;
1611         bool ok = false;
1612         Visitor *v;
1613         UserDefOne *retval;
1614         q_obj_my_command_arg arg = {0};
1615
1616         v = qobject_input_visitor_new(QOBJECT(args));
1617         if (!visit_start_struct(v, NULL, NULL, 0, errp)) {
1618             goto out;
1619         }
1620         if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) {
1621             ok = visit_check_struct(v, errp);
1622         }
1623         visit_end_struct(v, NULL);
1624         if (!ok) {
1625             goto out;
1626         }
1627
1628         retval = qmp_my_command(arg.arg1, &err);
1629         error_propagate(errp, err);
1630         if (err) {
1631             goto out;
1632         }
1633
1634         qmp_marshal_output_UserDefOne(retval, ret, errp);
1635
1636     out:
1637         visit_free(v);
1638         v = qapi_dealloc_visitor_new();
1639         visit_start_struct(v, NULL, NULL, 0, NULL);
1640         visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1641         visit_end_struct(v, NULL);
1642         visit_free(v);
1643     }
1644
1645 [Uninteresting stuff omitted...]
1646     $ cat qapi-generated/example-qapi-init-commands.h
1647 [Uninteresting stuff omitted...]
1648     #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H
1649     #define EXAMPLE_QAPI_INIT_COMMANDS_H
1650
1651     #include "qapi/qmp/dispatch.h"
1652
1653     void example_qmp_init_marshal(QmpCommandList *cmds);
1654
1655     #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */
1656     $ cat qapi-generated/example-qapi-init-commands.c
1657 [Uninteresting stuff omitted...]
1658     void example_qmp_init_marshal(QmpCommandList *cmds)
1659     {
1660         QTAILQ_INIT(cmds);
1661
1662         qmp_register_command(cmds, "my-command",
1663                              qmp_marshal_my_command, QCO_NO_OPTIONS);
1664     }
1665 [Uninteresting stuff omitted...]
1666
1667 For a modular QAPI schema (see section Include directives), code for
1668 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1669
1670 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1671 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1672
1673 === Code generated for events ===
1674
1675 This is the code related to events defined in the schema, providing
1676 qapi_event_send_EVENT().
1677
1678 The following files are created:
1679
1680 $(prefix)qapi-events.h - Function prototypes for each event type
1681
1682 $(prefix)qapi-events.c - Implementation of functions to send an event
1683
1684 $(prefix)qapi-emit-events.h - Enumeration of all event names, and
1685                               common event code declarations
1686
1687 $(prefix)qapi-emit-events.c - Common event code definitions
1688
1689 Example:
1690
1691     $ cat qapi-generated/example-qapi-events.h
1692 [Uninteresting stuff omitted...]
1693
1694     #ifndef EXAMPLE_QAPI_EVENTS_H
1695     #define EXAMPLE_QAPI_EVENTS_H
1696
1697     #include "qapi/util.h"
1698     #include "example-qapi-types.h"
1699
1700     void qapi_event_send_my_event(void);
1701
1702     #endif /* EXAMPLE_QAPI_EVENTS_H */
1703     $ cat qapi-generated/example-qapi-events.c
1704 [Uninteresting stuff omitted...]
1705
1706     void qapi_event_send_my_event(void)
1707     {
1708         QDict *qmp;
1709
1710         qmp = qmp_event_build_dict("MY_EVENT");
1711
1712         example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
1713
1714         qobject_unref(qmp);
1715     }
1716
1717 [Uninteresting stuff omitted...]
1718     $ cat qapi-generated/example-qapi-emit-events.h
1719 [Uninteresting stuff omitted...]
1720
1721     #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
1722     #define EXAMPLE_QAPI_EMIT_EVENTS_H
1723
1724     #include "qapi/util.h"
1725
1726     typedef enum example_QAPIEvent {
1727         EXAMPLE_QAPI_EVENT_MY_EVENT,
1728         EXAMPLE_QAPI_EVENT__MAX,
1729     } example_QAPIEvent;
1730
1731     #define example_QAPIEvent_str(val) \
1732         qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
1733
1734     extern const QEnumLookup example_QAPIEvent_lookup;
1735
1736     void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
1737
1738     #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
1739     $ cat qapi-generated/example-qapi-emit-events.c
1740 [Uninteresting stuff omitted...]
1741
1742     const QEnumLookup example_QAPIEvent_lookup = {
1743         .array = (const char *const[]) {
1744             [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1745         },
1746         .size = EXAMPLE_QAPI_EVENT__MAX
1747     };
1748
1749 [Uninteresting stuff omitted...]
1750
1751 For a modular QAPI schema (see section Include directives), code for
1752 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1753
1754 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1755 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1756
1757 === Code generated for introspection ===
1758
1759 The following files are created:
1760
1761 $(prefix)qapi-introspect.c - Defines a string holding a JSON
1762                             description of the schema
1763
1764 $(prefix)qapi-introspect.h - Declares the above string
1765
1766 Example:
1767
1768     $ cat qapi-generated/example-qapi-introspect.h
1769 [Uninteresting stuff omitted...]
1770
1771     #ifndef EXAMPLE_QAPI_INTROSPECT_H
1772     #define EXAMPLE_QAPI_INTROSPECT_H
1773
1774     #include "qapi/qmp/qlit.h"
1775
1776     extern const QLitObject example_qmp_schema_qlit;
1777
1778     #endif /* EXAMPLE_QAPI_INTROSPECT_H */
1779     $ cat qapi-generated/example-qapi-introspect.c
1780 [Uninteresting stuff omitted...]
1781
1782     const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
1783         QLIT_QDICT(((QLitDictEntry[]) {
1784             { "arg-type", QLIT_QSTR("0"), },
1785             { "meta-type", QLIT_QSTR("command"), },
1786             { "name", QLIT_QSTR("my-command"), },
1787             { "ret-type", QLIT_QSTR("1"), },
1788             {}
1789         })),
1790         QLIT_QDICT(((QLitDictEntry[]) {
1791             { "arg-type", QLIT_QSTR("2"), },
1792             { "meta-type", QLIT_QSTR("event"), },
1793             { "name", QLIT_QSTR("MY_EVENT"), },
1794             {}
1795         })),
1796         /* "0" = q_obj_my-command-arg */
1797         QLIT_QDICT(((QLitDictEntry[]) {
1798             { "members", QLIT_QLIST(((QLitObject[]) {
1799                 QLIT_QDICT(((QLitDictEntry[]) {
1800                     { "name", QLIT_QSTR("arg1"), },
1801                     { "type", QLIT_QSTR("[1]"), },
1802                     {}
1803                 })),
1804                 {}
1805             })), },
1806             { "meta-type", QLIT_QSTR("object"), },
1807             { "name", QLIT_QSTR("0"), },
1808             {}
1809         })),
1810         /* "1" = UserDefOne */
1811         QLIT_QDICT(((QLitDictEntry[]) {
1812             { "members", QLIT_QLIST(((QLitObject[]) {
1813                 QLIT_QDICT(((QLitDictEntry[]) {
1814                     { "name", QLIT_QSTR("integer"), },
1815                     { "type", QLIT_QSTR("int"), },
1816                     {}
1817                 })),
1818                 QLIT_QDICT(((QLitDictEntry[]) {
1819                     { "default", QLIT_QNULL, },
1820                     { "name", QLIT_QSTR("string"), },
1821                     { "type", QLIT_QSTR("str"), },
1822                     {}
1823                 })),
1824                 {}
1825             })), },
1826             { "meta-type", QLIT_QSTR("object"), },
1827             { "name", QLIT_QSTR("1"), },
1828             {}
1829         })),
1830         /* "2" = q_empty */
1831         QLIT_QDICT(((QLitDictEntry[]) {
1832             { "members", QLIT_QLIST(((QLitObject[]) {
1833                 {}
1834             })), },
1835             { "meta-type", QLIT_QSTR("object"), },
1836             { "name", QLIT_QSTR("2"), },
1837             {}
1838         })),
1839         QLIT_QDICT(((QLitDictEntry[]) {
1840             { "element-type", QLIT_QSTR("1"), },
1841             { "meta-type", QLIT_QSTR("array"), },
1842             { "name", QLIT_QSTR("[1]"), },
1843             {}
1844         })),
1845         QLIT_QDICT(((QLitDictEntry[]) {
1846             { "json-type", QLIT_QSTR("int"), },
1847             { "meta-type", QLIT_QSTR("builtin"), },
1848             { "name", QLIT_QSTR("int"), },
1849             {}
1850         })),
1851         QLIT_QDICT(((QLitDictEntry[]) {
1852             { "json-type", QLIT_QSTR("string"), },
1853             { "meta-type", QLIT_QSTR("builtin"), },
1854             { "name", QLIT_QSTR("str"), },
1855             {}
1856         })),
1857         {}
1858     }));
1859
1860 [Uninteresting stuff omitted...]