linux-user: Add support for btrfs ioctls used to manage quota
[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
828 ==== Documentation markup ====
829
830 Comment text starting with '=' is a section title:
831
832     # = Section title
833
834 Double the '=' for a subsection title:
835
836     # == Subsection title
837
838 '|' denotes examples:
839
840     # | Text of the example, may span
841     # | multiple lines
842
843 '*' starts an itemized list:
844
845     # * First item, may span
846     #   multiple lines
847     # * Second item
848
849 You can also use '-' instead of '*'.
850
851 A decimal number followed by '.' starts a numbered list:
852
853     # 1. First item, may span
854     #    multiple lines
855     # 2. Second item
856
857 The actual number doesn't matter.  You could even use '*' instead of
858 '2.' for the second item.
859
860 Lists can't be nested.  Blank lines are currently not supported within
861 lists.
862
863 Additional whitespace between the initial '#' and the comment text is
864 permitted.
865
866 *foo* and _foo_ are for strong and emphasis styles respectively (they
867 do not work over multiple lines).  @foo is used to reference a name in
868 the schema.
869
870 Example:
871
872 ##
873 # = Section
874 # == Subsection
875 #
876 # Some text foo with *strong* and _emphasis_
877 # 1. with a list
878 # 2. like that
879 #
880 # And some code:
881 # | $ echo foo
882 # | -> do this
883 # | <- get that
884 #
885 ##
886
887
888 ==== Definition documentation ====
889
890 Definition documentation, if present, must immediately precede the
891 definition it documents.
892
893 When documentation is required (see pragma 'doc-required'), every
894 definition must have documentation.
895
896 Definition documentation starts with a line naming the definition,
897 followed by an optional overview, a description of each argument (for
898 commands and events), member (for structs and unions), branch (for
899 alternates), or value (for enums), and finally optional tagged
900 sections.
901
902 FIXME: the parser accepts these things in almost any order.
903 FIXME: union branches should be described, too.
904
905 Extensions added after the definition was first released carry a
906 '(since x.y.z)' comment.
907
908 A tagged section starts with one of the following words:
909 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
910 The section ends with the start of a new section.
911
912 A 'Since: x.y.z' tagged section lists the release that introduced the
913 definition.
914
915 For example:
916
917 ##
918 # @BlockStats:
919 #
920 # Statistics of a virtual block device or a block backing device.
921 #
922 # @device: If the stats are for a virtual block device, the name
923 #          corresponding to the virtual block device.
924 #
925 # @node-name: The node name of the device. (since 2.3)
926 #
927 # ... more members ...
928 #
929 # Since: 0.14.0
930 ##
931 { 'struct': 'BlockStats',
932   'data': {'*device': 'str', '*node-name': 'str',
933            ... more members ... } }
934
935 ##
936 # @query-blockstats:
937 #
938 # Query the @BlockStats for all virtual block devices.
939 #
940 # @query-nodes: If true, the command will query all the
941 #               block nodes ... explain, explain ...  (since 2.3)
942 #
943 # Returns: A list of @BlockStats for each virtual block devices.
944 #
945 # Since: 0.14.0
946 #
947 # Example:
948 #
949 # -> { "execute": "query-blockstats" }
950 # <- {
951 #      ... lots of output ...
952 #    }
953 #
954 ##
955 { 'command': 'query-blockstats',
956   'data': { '*query-nodes': 'bool' },
957   'returns': ['BlockStats'] }
958
959
960 == Client JSON Protocol introspection ==
961
962 Clients of a Client JSON Protocol commonly need to figure out what
963 exactly the server (QEMU) supports.
964
965 For this purpose, QMP provides introspection via command
966 query-qmp-schema.  QGA currently doesn't support introspection.
967
968 While Client JSON Protocol wire compatibility should be maintained
969 between qemu versions, we cannot make the same guarantees for
970 introspection stability.  For example, one version of qemu may provide
971 a non-variant optional member of a struct, and a later version rework
972 the member to instead be non-optional and associated with a variant.
973 Likewise, one version of qemu may list a member with open-ended type
974 'str', and a later version could convert it to a finite set of strings
975 via an enum type; or a member may be converted from a specific type to
976 an alternate that represents a choice between the original type and
977 something else.
978
979 query-qmp-schema returns a JSON array of SchemaInfo objects.  These
980 objects together describe the wire ABI, as defined in the QAPI schema.
981 There is no specified order to the SchemaInfo objects returned; a
982 client must search for a particular name throughout the entire array
983 to learn more about that name, but is at least guaranteed that there
984 will be no collisions between type, command, and event names.
985
986 However, the SchemaInfo can't reflect all the rules and restrictions
987 that apply to QMP.  It's interface introspection (figuring out what's
988 there), not interface specification.  The specification is in the QAPI
989 schema.  To understand how QMP is to be used, you need to study the
990 QAPI schema.
991
992 Like any other command, query-qmp-schema is itself defined in the QAPI
993 schema, along with the SchemaInfo type.  This text attempts to give an
994 overview how things work.  For details you need to consult the QAPI
995 schema.
996
997 SchemaInfo objects have common members "name", "meta-type",
998 "features", and additional variant members depending on the value of
999 meta-type.
1000
1001 Each SchemaInfo object describes a wire ABI entity of a certain
1002 meta-type: a command, event or one of several kinds of type.
1003
1004 SchemaInfo for commands and events have the same name as in the QAPI
1005 schema.
1006
1007 Command and event names are part of the wire ABI, but type names are
1008 not.  Therefore, the SchemaInfo for types have auto-generated
1009 meaningless names.  For readability, the examples in this section use
1010 meaningful type names instead.
1011
1012 Optional member "features" exposes the entity's feature strings as a
1013 JSON array of strings.
1014
1015 To examine a type, start with a command or event using it, then follow
1016 references by name.
1017
1018 QAPI schema definitions not reachable that way are omitted.
1019
1020 The SchemaInfo for a command has meta-type "command", and variant
1021 members "arg-type", "ret-type" and "allow-oob".  On the wire, the
1022 "arguments" member of a client's "execute" command must conform to the
1023 object type named by "arg-type".  The "return" member that the server
1024 passes in a success response conforms to the type named by "ret-type".
1025 When "allow-oob" is true, it means the command supports out-of-band
1026 execution.  It defaults to false.
1027
1028 If the command takes no arguments, "arg-type" names an object type
1029 without members.  Likewise, if the command returns nothing, "ret-type"
1030 names an object type without members.
1031
1032 Example: the SchemaInfo for command query-qmp-schema
1033
1034     { "name": "query-qmp-schema", "meta-type": "command",
1035       "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1036
1037     Type "q_empty" is an automatic object type without members, and type
1038     "SchemaInfoList" is the array of SchemaInfo type.
1039
1040 The SchemaInfo for an event has meta-type "event", and variant member
1041 "arg-type".  On the wire, a "data" member that the server passes in an
1042 event conforms to the object type named by "arg-type".
1043
1044 If the event carries no additional information, "arg-type" names an
1045 object type without members.  The event may not have a data member on
1046 the wire then.
1047
1048 Each command or event defined with 'data' as MEMBERS object in the
1049 QAPI schema implicitly defines an object type.
1050
1051 Example: the SchemaInfo for EVENT_C from section Events
1052
1053     { "name": "EVENT_C", "meta-type": "event",
1054       "arg-type": "q_obj-EVENT_C-arg" }
1055
1056     Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1057     the two members from the event's definition.
1058
1059 The SchemaInfo for struct and union types has meta-type "object".
1060
1061 The SchemaInfo for a struct type has variant member "members".
1062
1063 The SchemaInfo for a union type additionally has variant members "tag"
1064 and "variants".
1065
1066 "members" is a JSON array describing the object's common members, if
1067 any.  Each element is a JSON object with members "name" (the member's
1068 name), "type" (the name of its type), and optionally "default".  The
1069 member is optional if "default" is present.  Currently, "default" can
1070 only have value null.  Other values are reserved for future
1071 extensions.  The "members" array is in no particular order; clients
1072 must search the entire object when learning whether a particular
1073 member is supported.
1074
1075 Example: the SchemaInfo for MyType from section Struct types
1076
1077     { "name": "MyType", "meta-type": "object",
1078       "members": [
1079           { "name": "member1", "type": "str" },
1080           { "name": "member2", "type": "int" },
1081           { "name": "member3", "type": "str", "default": null } ] }
1082
1083 "features" exposes the command's feature strings as a JSON array of
1084 strings.
1085
1086 Example: the SchemaInfo for TestType from section Features:
1087
1088     { "name": "TestType", "meta-type": "object",
1089       "members": [
1090           { "name": "number", "type": "int" } ],
1091       "features": ["allow-negative-numbers"] }
1092
1093 "tag" is the name of the common member serving as type tag.
1094 "variants" is a JSON array describing the object's variant members.
1095 Each element is a JSON object with members "case" (the value of type
1096 tag this element applies to) and "type" (the name of an object type
1097 that provides the variant members for this type tag value).  The
1098 "variants" array is in no particular order, and is not guaranteed to
1099 list cases in the same order as the corresponding "tag" enum type.
1100
1101 Example: the SchemaInfo for flat union BlockdevOptions from section
1102 Union types
1103
1104     { "name": "BlockdevOptions", "meta-type": "object",
1105       "members": [
1106           { "name": "driver", "type": "BlockdevDriver" },
1107           { "name": "read-only", "type": "bool", "default": null } ],
1108       "tag": "driver",
1109       "variants": [
1110           { "case": "file", "type": "BlockdevOptionsFile" },
1111           { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
1112
1113 Note that base types are "flattened": its members are included in the
1114 "members" array.
1115
1116 A simple union implicitly defines an enumeration type for its implicit
1117 discriminator (called "type" on the wire, see section Union types).
1118
1119 A simple union implicitly defines an object type for each of its
1120 variants.
1121
1122 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
1123 Union types
1124
1125     { "name": "BlockdevOptionsSimple", "meta-type": "object",
1126       "members": [
1127           { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
1128       "tag": "type",
1129       "variants": [
1130           { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
1131           { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
1132
1133     Enumeration type "BlockdevOptionsSimpleKind" and the object types
1134     "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
1135     are implicitly defined.
1136
1137 The SchemaInfo for an alternate type has meta-type "alternate", and
1138 variant member "members".  "members" is a JSON array.  Each element is
1139 a JSON object with member "type", which names a type.  Values of the
1140 alternate type conform to exactly one of its member types.  There is
1141 no guarantee on the order in which "members" will be listed.
1142
1143 Example: the SchemaInfo for BlockdevRef from section Alternate types
1144
1145     { "name": "BlockdevRef", "meta-type": "alternate",
1146       "members": [
1147           { "type": "BlockdevOptions" },
1148           { "type": "str" } ] }
1149
1150 The SchemaInfo for an array type has meta-type "array", and variant
1151 member "element-type", which names the array's element type.  Array
1152 types are implicitly defined.  For convenience, the array's name may
1153 resemble the element type; however, clients should examine member
1154 "element-type" instead of making assumptions based on parsing member
1155 "name".
1156
1157 Example: the SchemaInfo for ['str']
1158
1159     { "name": "[str]", "meta-type": "array",
1160       "element-type": "str" }
1161
1162 The SchemaInfo for an enumeration type has meta-type "enum" and
1163 variant member "values".  The values are listed in no particular
1164 order; clients must search the entire enum when learning whether a
1165 particular value is supported.
1166
1167 Example: the SchemaInfo for MyEnum from section Enumeration types
1168
1169     { "name": "MyEnum", "meta-type": "enum",
1170       "values": [ "value1", "value2", "value3" ] }
1171
1172 The SchemaInfo for a built-in type has the same name as the type in
1173 the QAPI schema (see section Built-in Types), with one exception
1174 detailed below.  It has variant member "json-type" that shows how
1175 values of this type are encoded on the wire.
1176
1177 Example: the SchemaInfo for str
1178
1179     { "name": "str", "meta-type": "builtin", "json-type": "string" }
1180
1181 The QAPI schema supports a number of integer types that only differ in
1182 how they map to C.  They are identical as far as SchemaInfo is
1183 concerned.  Therefore, they get all mapped to a single type "int" in
1184 SchemaInfo.
1185
1186 As explained above, type names are not part of the wire ABI.  Not even
1187 the names of built-in types.  Clients should examine member
1188 "json-type" instead of hard-coding names of built-in types.
1189
1190
1191 == Compatibility considerations ==
1192
1193 Maintaining backward compatibility at the Client JSON Protocol level
1194 while evolving the schema requires some care.  This section is about
1195 syntactic compatibility, which is necessary, but not sufficient, for
1196 actual compatibility.
1197
1198 Clients send commands with argument data, and receive command
1199 responses with return data and events with event data.
1200
1201 Adding opt-in functionality to the send direction is backwards
1202 compatible: adding commands, optional arguments, enumeration values,
1203 union and alternate branches; turning an argument type into an
1204 alternate of that type; making mandatory arguments optional.  Clients
1205 oblivious of the new functionality continue to work.
1206
1207 Incompatible changes include removing commands, command arguments,
1208 enumeration values, union and alternate branches, adding mandatory
1209 command arguments, and making optional arguments mandatory.
1210
1211 The specified behavior of an absent optional argument should remain
1212 the same.  With proper documentation, this policy still allows some
1213 flexibility; for example, when an optional 'buffer-size' argument is
1214 specified to default to a sensible buffer size, the actual default
1215 value can still be changed.  The specified default behavior is not the
1216 exact size of the buffer, only that the default size is sensible.
1217
1218 Adding functionality to the receive direction is generally backwards
1219 compatible: adding events, adding return and event data members.
1220 Clients are expected to ignore the ones they don't know.
1221
1222 Removing "unreachable" stuff like events that can't be triggered
1223 anymore, optional return or event data members that can't be sent
1224 anymore, and return or event data member (enumeration) values that
1225 can't be sent anymore makes no difference to clients, except for
1226 introspection.  The latter can conceivably confuse clients, so tread
1227 carefully.
1228
1229 Incompatible changes include removing return and event data members.
1230
1231 Any change to a command definition's 'data' or one of the types used
1232 there (recursively) needs to consider send direction compatibility.
1233
1234 Any change to a command definition's 'return', an event definition's
1235 'data', or one of the types used there (recursively) needs to consider
1236 receive direction compatibility.
1237
1238 Any change to types used in both contexts need to consider both.
1239
1240 Enumeration type values and complex and alternate type members may be
1241 reordered freely.  For enumerations and alternate types, this doesn't
1242 affect the wire encoding.  For complex types, this might make the
1243 implementation emit JSON object members in a different order, which
1244 the Client JSON Protocol permits.
1245
1246 Since type names are not visible in the Client JSON Protocol, types
1247 may be freely renamed.  Even certain refactorings are invisible, such
1248 as splitting members from one type into a common base type.
1249
1250
1251 == Code generation ==
1252
1253 The QAPI code generator qapi-gen.py generates code and documentation
1254 from the schema.  Together with the core QAPI libraries, this code
1255 provides everything required to take JSON commands read in by a Client
1256 JSON Protocol server, unmarshal the arguments into the underlying C
1257 types, call into the corresponding C function, map the response back
1258 to a Client JSON Protocol response to be returned to the user, and
1259 introspect the commands.
1260
1261 As an example, we'll use the following schema, which describes a
1262 single complex user-defined type, along with command which takes a
1263 list of that type as a parameter, and returns a single element of that
1264 type.  The user is responsible for writing the implementation of
1265 qmp_my_command(); everything else is produced by the generator.
1266
1267     $ cat example-schema.json
1268     { 'struct': 'UserDefOne',
1269       'data': { 'integer': 'int', '*string': 'str' } }
1270
1271     { 'command': 'my-command',
1272       'data': { 'arg1': ['UserDefOne'] },
1273       'returns': 'UserDefOne' }
1274
1275     { 'event': 'MY_EVENT' }
1276
1277 We run qapi-gen.py like this:
1278
1279     $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1280     --prefix="example-" example-schema.json
1281
1282 For a more thorough look at generated code, the testsuite includes
1283 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1284 what the generator will accept, and compiles the resulting C code as
1285 part of 'make check-unit'.
1286
1287 === Code generated for QAPI types ===
1288
1289 The following files are created:
1290
1291 $(prefix)qapi-types.h - C types corresponding to types defined in
1292                         the schema
1293
1294 $(prefix)qapi-types.c - Cleanup functions for the above C types
1295
1296 The $(prefix) is an optional parameter used as a namespace to keep the
1297 generated code from one schema/code-generation separated from others so code
1298 can be generated/used from multiple schemas without clobbering previously
1299 created code.
1300
1301 Example:
1302
1303     $ cat qapi-generated/example-qapi-types.h
1304 [Uninteresting stuff omitted...]
1305
1306     #ifndef EXAMPLE_QAPI_TYPES_H
1307     #define EXAMPLE_QAPI_TYPES_H
1308
1309     #include "qapi/qapi-builtin-types.h"
1310
1311     typedef struct UserDefOne UserDefOne;
1312
1313     typedef struct UserDefOneList UserDefOneList;
1314
1315     typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1316
1317     struct UserDefOne {
1318         int64_t integer;
1319         bool has_string;
1320         char *string;
1321     };
1322
1323     void qapi_free_UserDefOne(UserDefOne *obj);
1324
1325     struct UserDefOneList {
1326         UserDefOneList *next;
1327         UserDefOne *value;
1328     };
1329
1330     void qapi_free_UserDefOneList(UserDefOneList *obj);
1331
1332     struct q_obj_my_command_arg {
1333         UserDefOneList *arg1;
1334     };
1335
1336     #endif /* EXAMPLE_QAPI_TYPES_H */
1337     $ cat qapi-generated/example-qapi-types.c
1338 [Uninteresting stuff omitted...]
1339
1340     void qapi_free_UserDefOne(UserDefOne *obj)
1341     {
1342         Visitor *v;
1343
1344         if (!obj) {
1345             return;
1346         }
1347
1348         v = qapi_dealloc_visitor_new();
1349         visit_type_UserDefOne(v, NULL, &obj, NULL);
1350         visit_free(v);
1351     }
1352
1353     void qapi_free_UserDefOneList(UserDefOneList *obj)
1354     {
1355         Visitor *v;
1356
1357         if (!obj) {
1358             return;
1359         }
1360
1361         v = qapi_dealloc_visitor_new();
1362         visit_type_UserDefOneList(v, NULL, &obj, NULL);
1363         visit_free(v);
1364     }
1365
1366 [Uninteresting stuff omitted...]
1367
1368 For a modular QAPI schema (see section Include directives), code for
1369 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1370
1371 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1372 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1373
1374 If qapi-gen.py is run with option --builtins, additional files are
1375 created:
1376
1377 qapi-builtin-types.h - C types corresponding to built-in types
1378
1379 qapi-builtin-types.c - Cleanup functions for the above C types
1380
1381 === Code generated for visiting QAPI types ===
1382
1383 These are the visitor functions used to walk through and convert
1384 between a native QAPI C data structure and some other format (such as
1385 QObject); the generated functions are named visit_type_FOO() and
1386 visit_type_FOO_members().
1387
1388 The following files are generated:
1389
1390 $(prefix)qapi-visit.c: Visitor function for a particular C type, used
1391                        to automagically convert QObjects into the
1392                        corresponding C type and vice-versa, as well
1393                        as for deallocating memory for an existing C
1394                        type
1395
1396 $(prefix)qapi-visit.h: Declarations for previously mentioned visitor
1397                        functions
1398
1399 Example:
1400
1401     $ cat qapi-generated/example-qapi-visit.h
1402 [Uninteresting stuff omitted...]
1403
1404     #ifndef EXAMPLE_QAPI_VISIT_H
1405     #define EXAMPLE_QAPI_VISIT_H
1406
1407     #include "qapi/qapi-builtin-visit.h"
1408     #include "example-qapi-types.h"
1409
1410
1411     bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1412     bool visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1413     bool visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1414
1415     bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1416
1417     #endif /* EXAMPLE_QAPI_VISIT_H */
1418     $ cat qapi-generated/example-qapi-visit.c
1419 [Uninteresting stuff omitted...]
1420
1421     bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1422     {
1423         if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1424             return false;
1425         }
1426         if (visit_optional(v, "string", &obj->has_string)) {
1427             if (!visit_type_str(v, "string", &obj->string, errp)) {
1428                 return false;
1429             }
1430         }
1431         return true;
1432     }
1433
1434     bool visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1435     {
1436         bool ok = false;
1437
1438         if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) {
1439             return false;
1440         }
1441         if (!*obj) {
1442             /* incomplete */
1443             assert(visit_is_dealloc(v));
1444             goto out_obj;
1445         }
1446         if (!visit_type_UserDefOne_members(v, *obj, errp)) {
1447             goto out_obj;
1448         }
1449         ok = visit_check_struct(v, errp);
1450     out_obj:
1451         visit_end_struct(v, (void **)obj);
1452         if (!ok && visit_is_input(v)) {
1453             qapi_free_UserDefOne(*obj);
1454             *obj = NULL;
1455         }
1456         return ok;
1457     }
1458
1459     bool visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1460     {
1461         bool ok = false;
1462         UserDefOneList *tail;
1463         size_t size = sizeof(**obj);
1464
1465         if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) {
1466             return false;
1467         }
1468
1469         for (tail = *obj; tail;
1470              tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1471             if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
1472                 goto out_obj;
1473             }
1474         }
1475
1476         ok = visit_check_list(v, errp);
1477     out_obj:
1478         visit_end_list(v, (void **)obj);
1479         if (!ok && visit_is_input(v)) {
1480             qapi_free_UserDefOneList(*obj);
1481             *obj = NULL;
1482         }
1483         return ok;
1484     }
1485
1486     bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1487     {
1488         if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1489             return false;
1490         }
1491         return true;
1492     }
1493
1494 [Uninteresting stuff omitted...]
1495
1496 For a modular QAPI schema (see section Include directives), code for
1497 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1498
1499 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1500 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1501
1502 If qapi-gen.py is run with option --builtins, additional files are
1503 created:
1504
1505 qapi-builtin-visit.h - Visitor functions for built-in types
1506
1507 qapi-builtin-visit.c - Declarations for these visitor functions
1508
1509 === Code generated for commands ===
1510
1511 These are the marshaling/dispatch functions for the commands defined
1512 in the schema.  The generated code provides qmp_marshal_COMMAND(), and
1513 declares qmp_COMMAND() that the user must implement.
1514
1515 The following files are generated:
1516
1517 $(prefix)qapi-commands.c: Command marshal/dispatch functions for each
1518                           QMP command defined in the schema
1519
1520 $(prefix)qapi-commands.h: Function prototypes for the QMP commands
1521                           specified in the schema
1522
1523 $(prefix)qapi-init-commands.h - Command initialization prototype
1524
1525 $(prefix)qapi-init-commands.c - Command initialization code
1526
1527 Example:
1528
1529     $ cat qapi-generated/example-qapi-commands.h
1530 [Uninteresting stuff omitted...]
1531
1532     #ifndef EXAMPLE_QAPI_COMMANDS_H
1533     #define EXAMPLE_QAPI_COMMANDS_H
1534
1535     #include "example-qapi-types.h"
1536
1537     UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1538     void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1539
1540     #endif /* EXAMPLE_QAPI_COMMANDS_H */
1541     $ cat qapi-generated/example-qapi-commands.c
1542 [Uninteresting stuff omitted...]
1543
1544     static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1545     {
1546         Visitor *v;
1547
1548         v = qobject_output_visitor_new(ret_out);
1549         if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) {
1550             visit_complete(v, ret_out);
1551         }
1552         visit_free(v);
1553         v = qapi_dealloc_visitor_new();
1554         visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1555         visit_free(v);
1556     }
1557
1558     void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1559     {
1560         Error *err = NULL;
1561         bool ok = false;
1562         Visitor *v;
1563         UserDefOne *retval;
1564         q_obj_my_command_arg arg = {0};
1565
1566         v = qobject_input_visitor_new(QOBJECT(args));
1567         if (!visit_start_struct(v, NULL, NULL, 0, errp)) {
1568             goto out;
1569         }
1570         if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) {
1571             ok = visit_check_struct(v, errp);
1572         }
1573         visit_end_struct(v, NULL);
1574         if (!ok) {
1575             goto out;
1576         }
1577
1578         retval = qmp_my_command(arg.arg1, &err);
1579         error_propagate(errp, err);
1580         if (err) {
1581             goto out;
1582         }
1583
1584         qmp_marshal_output_UserDefOne(retval, ret, errp);
1585
1586     out:
1587         visit_free(v);
1588         v = qapi_dealloc_visitor_new();
1589         visit_start_struct(v, NULL, NULL, 0, NULL);
1590         visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1591         visit_end_struct(v, NULL);
1592         visit_free(v);
1593     }
1594
1595 [Uninteresting stuff omitted...]
1596     $ cat qapi-generated/example-qapi-init-commands.h
1597 [Uninteresting stuff omitted...]
1598     #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H
1599     #define EXAMPLE_QAPI_INIT_COMMANDS_H
1600
1601     #include "qapi/qmp/dispatch.h"
1602
1603     void example_qmp_init_marshal(QmpCommandList *cmds);
1604
1605     #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */
1606     $ cat qapi-generated/example-qapi-init-commands.c
1607 [Uninteresting stuff omitted...]
1608     void example_qmp_init_marshal(QmpCommandList *cmds)
1609     {
1610         QTAILQ_INIT(cmds);
1611
1612         qmp_register_command(cmds, "my-command",
1613                              qmp_marshal_my_command, QCO_NO_OPTIONS);
1614     }
1615 [Uninteresting stuff omitted...]
1616
1617 For a modular QAPI schema (see section Include directives), code for
1618 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1619
1620 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1621 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1622
1623 === Code generated for events ===
1624
1625 This is the code related to events defined in the schema, providing
1626 qapi_event_send_EVENT().
1627
1628 The following files are created:
1629
1630 $(prefix)qapi-events.h - Function prototypes for each event type
1631
1632 $(prefix)qapi-events.c - Implementation of functions to send an event
1633
1634 $(prefix)qapi-emit-events.h - Enumeration of all event names, and
1635                               common event code declarations
1636
1637 $(prefix)qapi-emit-events.c - Common event code definitions
1638
1639 Example:
1640
1641     $ cat qapi-generated/example-qapi-events.h
1642 [Uninteresting stuff omitted...]
1643
1644     #ifndef EXAMPLE_QAPI_EVENTS_H
1645     #define EXAMPLE_QAPI_EVENTS_H
1646
1647     #include "qapi/util.h"
1648     #include "example-qapi-types.h"
1649
1650     void qapi_event_send_my_event(void);
1651
1652     #endif /* EXAMPLE_QAPI_EVENTS_H */
1653     $ cat qapi-generated/example-qapi-events.c
1654 [Uninteresting stuff omitted...]
1655
1656     void qapi_event_send_my_event(void)
1657     {
1658         QDict *qmp;
1659
1660         qmp = qmp_event_build_dict("MY_EVENT");
1661
1662         example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
1663
1664         qobject_unref(qmp);
1665     }
1666
1667 [Uninteresting stuff omitted...]
1668     $ cat qapi-generated/example-qapi-emit-events.h
1669 [Uninteresting stuff omitted...]
1670
1671     #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
1672     #define EXAMPLE_QAPI_EMIT_EVENTS_H
1673
1674     #include "qapi/util.h"
1675
1676     typedef enum example_QAPIEvent {
1677         EXAMPLE_QAPI_EVENT_MY_EVENT,
1678         EXAMPLE_QAPI_EVENT__MAX,
1679     } example_QAPIEvent;
1680
1681     #define example_QAPIEvent_str(val) \
1682         qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
1683
1684     extern const QEnumLookup example_QAPIEvent_lookup;
1685
1686     void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
1687
1688     #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
1689     $ cat qapi-generated/example-qapi-emit-events.c
1690 [Uninteresting stuff omitted...]
1691
1692     const QEnumLookup example_QAPIEvent_lookup = {
1693         .array = (const char *const[]) {
1694             [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1695         },
1696         .size = EXAMPLE_QAPI_EVENT__MAX
1697     };
1698
1699 [Uninteresting stuff omitted...]
1700
1701 For a modular QAPI schema (see section Include directives), code for
1702 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1703
1704 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1705 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1706
1707 === Code generated for introspection ===
1708
1709 The following files are created:
1710
1711 $(prefix)qapi-introspect.c - Defines a string holding a JSON
1712                             description of the schema
1713
1714 $(prefix)qapi-introspect.h - Declares the above string
1715
1716 Example:
1717
1718     $ cat qapi-generated/example-qapi-introspect.h
1719 [Uninteresting stuff omitted...]
1720
1721     #ifndef EXAMPLE_QAPI_INTROSPECT_H
1722     #define EXAMPLE_QAPI_INTROSPECT_H
1723
1724     #include "qapi/qmp/qlit.h"
1725
1726     extern const QLitObject example_qmp_schema_qlit;
1727
1728     #endif /* EXAMPLE_QAPI_INTROSPECT_H */
1729     $ cat qapi-generated/example-qapi-introspect.c
1730 [Uninteresting stuff omitted...]
1731
1732     const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
1733         QLIT_QDICT(((QLitDictEntry[]) {
1734             { "arg-type", QLIT_QSTR("0"), },
1735             { "meta-type", QLIT_QSTR("command"), },
1736             { "name", QLIT_QSTR("my-command"), },
1737             { "ret-type", QLIT_QSTR("1"), },
1738             {}
1739         })),
1740         QLIT_QDICT(((QLitDictEntry[]) {
1741             { "arg-type", QLIT_QSTR("2"), },
1742             { "meta-type", QLIT_QSTR("event"), },
1743             { "name", QLIT_QSTR("MY_EVENT"), },
1744             {}
1745         })),
1746         /* "0" = q_obj_my-command-arg */
1747         QLIT_QDICT(((QLitDictEntry[]) {
1748             { "members", QLIT_QLIST(((QLitObject[]) {
1749                 QLIT_QDICT(((QLitDictEntry[]) {
1750                     { "name", QLIT_QSTR("arg1"), },
1751                     { "type", QLIT_QSTR("[1]"), },
1752                     {}
1753                 })),
1754                 {}
1755             })), },
1756             { "meta-type", QLIT_QSTR("object"), },
1757             { "name", QLIT_QSTR("0"), },
1758             {}
1759         })),
1760         /* "1" = UserDefOne */
1761         QLIT_QDICT(((QLitDictEntry[]) {
1762             { "members", QLIT_QLIST(((QLitObject[]) {
1763                 QLIT_QDICT(((QLitDictEntry[]) {
1764                     { "name", QLIT_QSTR("integer"), },
1765                     { "type", QLIT_QSTR("int"), },
1766                     {}
1767                 })),
1768                 QLIT_QDICT(((QLitDictEntry[]) {
1769                     { "default", QLIT_QNULL, },
1770                     { "name", QLIT_QSTR("string"), },
1771                     { "type", QLIT_QSTR("str"), },
1772                     {}
1773                 })),
1774                 {}
1775             })), },
1776             { "meta-type", QLIT_QSTR("object"), },
1777             { "name", QLIT_QSTR("1"), },
1778             {}
1779         })),
1780         /* "2" = q_empty */
1781         QLIT_QDICT(((QLitDictEntry[]) {
1782             { "members", QLIT_QLIST(((QLitObject[]) {
1783                 {}
1784             })), },
1785             { "meta-type", QLIT_QSTR("object"), },
1786             { "name", QLIT_QSTR("2"), },
1787             {}
1788         })),
1789         QLIT_QDICT(((QLitDictEntry[]) {
1790             { "element-type", QLIT_QSTR("1"), },
1791             { "meta-type", QLIT_QSTR("array"), },
1792             { "name", QLIT_QSTR("[1]"), },
1793             {}
1794         })),
1795         QLIT_QDICT(((QLitDictEntry[]) {
1796             { "json-type", QLIT_QSTR("int"), },
1797             { "meta-type", QLIT_QSTR("builtin"), },
1798             { "name", QLIT_QSTR("int"), },
1799             {}
1800         })),
1801         QLIT_QDICT(((QLitDictEntry[]) {
1802             { "json-type", QLIT_QSTR("string"), },
1803             { "meta-type", QLIT_QSTR("builtin"), },
1804             { "name", QLIT_QSTR("str"), },
1805             {}
1806         })),
1807         {}
1808     }));
1809
1810 [Uninteresting stuff omitted...]