spice: move auth functions to QemuSpiceOps.
[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                 '*coroutine': true,
476                 '*if': COND,
477                 '*features': FEATURES }
478
479 Member 'command' names the command.
480
481 Member 'data' defines the arguments.  It defaults to an empty MEMBERS
482 object.
483
484 If 'data' is a MEMBERS object, then MEMBERS defines arguments just
485 like a struct type's 'data' defines struct type members.
486
487 If 'data' is a STRING, then STRING names a complex type whose members
488 are the arguments.  A union type requires 'boxed': true.
489
490 Member 'returns' defines the command's return type.  It defaults to an
491 empty struct type.  It must normally be a complex type or an array of
492 a complex type.  To return anything else, the command must be listed
493 in pragma 'returns-whitelist'.  If you do this, extending the command
494 to return additional information will be harder.  Use of
495 'returns-whitelist' for new commands is strongly discouraged.
496
497 A command's error responses are not specified in the QAPI schema.
498 Error conditions should be documented in comments.
499
500 In the Client JSON Protocol, the value of the "execute" or "exec-oob"
501 member is the command name.  The value of the "arguments" member then
502 has to conform to the arguments, and the value of the success
503 response's "return" member will conform to the return type.
504
505 Some example commands:
506
507  { 'command': 'my-first-command',
508    'data': { 'arg1': 'str', '*arg2': 'str' } }
509  { 'struct': 'MyType', 'data': { '*value': 'str' } }
510  { 'command': 'my-second-command',
511    'returns': [ 'MyType' ] }
512
513 which would validate this Client JSON Protocol transaction:
514
515  => { "execute": "my-first-command",
516       "arguments": { "arg1": "hello" } }
517  <= { "return": { } }
518  => { "execute": "my-second-command" }
519  <= { "return": [ { "value": "one" }, { } ] }
520
521 The generator emits a prototype for the C function implementing the
522 command.  The function itself needs to be written by hand.  See
523 section "Code generated for commands" for examples.
524
525 The function returns the return type.  When member 'boxed' is absent,
526 it takes the command arguments as arguments one by one, in QAPI schema
527 order.  Else it takes them wrapped in the C struct generated for the
528 complex argument type.  It takes an additional Error ** argument in
529 either case.
530
531 The generator also emits a marshalling function that extracts
532 arguments for the user's function out of an input QDict, calls the
533 user's function, and if it succeeded, builds an output QObject from
534 its return value.  This is for use by the QMP monitor core.
535
536 In rare cases, QAPI cannot express a type-safe representation of a
537 corresponding Client JSON Protocol command.  You then have to suppress
538 generation of a marshalling function by including a member 'gen' with
539 boolean value false, and instead write your own function.  For
540 example:
541
542  { 'command': 'netdev_add',
543    'data': {'type': 'str', 'id': 'str'},
544    'gen': false }
545
546 Please try to avoid adding new commands that rely on this, and instead
547 use type-safe unions.
548
549 Normally, the QAPI schema is used to describe synchronous exchanges,
550 where a response is expected.  But in some cases, the action of a
551 command is expected to change state in a way that a successful
552 response is not possible (although the command will still return an
553 error object on failure).  When a successful reply is not possible,
554 the command definition includes the optional member 'success-response'
555 with boolean value false.  So far, only QGA makes use of this member.
556
557 Member 'allow-oob' declares whether the command supports out-of-band
558 (OOB) execution.  It defaults to false.  For example:
559
560  { 'command': 'migrate_recover',
561    'data': { 'uri': 'str' }, 'allow-oob': true }
562
563 See qmp-spec.txt for out-of-band execution syntax and semantics.
564
565 Commands supporting out-of-band execution can still be executed
566 in-band.
567
568 When a command is executed in-band, its handler runs in the main
569 thread with the BQL held.
570
571 When a command is executed out-of-band, its handler runs in a
572 dedicated monitor I/O thread with the BQL *not* held.
573
574 An OOB-capable command handler must satisfy the following conditions:
575
576 - It terminates quickly.
577 - It does not invoke system calls that may block.
578 - It does not access guest RAM that may block when userfaultfd is
579   enabled for postcopy live migration.
580 - It takes only "fast" locks, i.e. all critical sections protected by
581   any lock it takes also satisfy the conditions for OOB command
582   handler code.
583
584 The restrictions on locking limit access to shared state.  Such access
585 requires synchronization, but OOB commands can't take the BQL or any
586 other "slow" lock.
587
588 When in doubt, do not implement OOB execution support.
589
590 Member 'allow-preconfig' declares whether the command is available
591 before the machine is built.  It defaults to false.  For example:
592
593  { 'command': 'qmp_capabilities',
594    'data': { '*enable': [ 'QMPCapability' ] },
595    'allow-preconfig': true }
596
597 QMP is available before the machine is built only when QEMU was
598 started with --preconfig.
599
600 Member 'coroutine' tells the QMP dispatcher whether the command handler
601 is safe to be run in a coroutine.  It defaults to false.  If it is true,
602 the command handler is called from coroutine context and may yield while
603 waiting for an external event (such as I/O completion) in order to avoid
604 blocking the guest and other background operations.
605
606 Coroutine safety can be hard to prove, similar to thread safety.  Common
607 pitfalls are:
608
609 - The global mutex isn't held across qemu_coroutine_yield(), so
610   operations that used to assume that they execute atomically may have
611   to be more careful to protect against changes in the global state.
612
613 - Nested event loops (AIO_WAIT_WHILE() etc.) are problematic in
614   coroutine context and can easily lead to deadlocks.  They should be
615   replaced by yielding and reentering the coroutine when the condition
616   becomes false.
617
618 Since the command handler may assume coroutine context, any callers
619 other than the QMP dispatcher must also call it in coroutine context.
620 In particular, HMP commands calling such a QMP command handler must be
621 marked .coroutine = true in hmp-commands.hx.
622
623 It is an error to specify both 'coroutine': true and 'allow-oob': true
624 for a command.  We don't currently have a use case for both together and
625 without a use case, it's not entirely clear what the semantics should
626 be.
627
628 The optional 'if' member specifies a conditional.  See "Configuring
629 the schema" below for more on this.
630
631 The optional 'features' member specifies features.  See "Features"
632 below for more on this.
633
634
635 === Events ===
636
637 Syntax:
638     EVENT = { 'event': STRING,
639               (
640               '*data': ( MEMBERS | STRING ),
641               |
642               'data': STRING,
643               'boxed': true,
644               )
645               '*if': COND,
646               '*features': FEATURES }
647
648 Member 'event' names the event.  This is the event name used in the
649 Client JSON Protocol.
650
651 Member 'data' defines the event-specific data.  It defaults to an
652 empty MEMBERS object.
653
654 If 'data' is a MEMBERS object, then MEMBERS defines event-specific
655 data just like a struct type's 'data' defines struct type members.
656
657 If 'data' is a STRING, then STRING names a complex type whose members
658 are the event-specific data.  A union type requires 'boxed': true.
659
660 An example event is:
661
662 { 'event': 'EVENT_C',
663   'data': { '*a': 'int', 'b': 'str' } }
664
665 Resulting in this JSON object:
666
667 { "event": "EVENT_C",
668   "data": { "b": "test string" },
669   "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
670
671 The generator emits a function to send the event.  When member 'boxed'
672 is absent, it takes event-specific data one by one, in QAPI schema
673 order.  Else it takes them wrapped in the C struct generated for the
674 complex type.  See section "Code generated for events" for examples.
675
676 The optional 'if' member specifies a conditional.  See "Configuring
677 the schema" below for more on this.
678
679 The optional 'features' member specifies features.  See "Features"
680 below for more on this.
681
682
683 === Features ===
684
685 Syntax:
686     FEATURES = [ FEATURE, ... ]
687     FEATURE = STRING
688             | { 'name': STRING, '*if': COND }
689
690 Sometimes, the behaviour of QEMU changes compatibly, but without a
691 change in the QMP syntax (usually by allowing values or operations
692 that previously resulted in an error).  QMP clients may still need to
693 know whether the extension is available.
694
695 For this purpose, a list of features can be specified for a command or
696 struct type.  Each list member can either be { 'name': STRING, '*if':
697 COND }, or STRING, which is shorthand for { 'name': STRING }.
698
699 The optional 'if' member specifies a conditional.  See "Configuring
700 the schema" below for more on this.
701
702 Example:
703
704 { 'struct': 'TestType',
705   'data': { 'number': 'int' },
706   'features': [ 'allow-negative-numbers' ] }
707
708 The feature strings are exposed to clients in introspection, as
709 explained in section "Client JSON Protocol introspection".
710
711 Intended use is to have each feature string signal that this build of
712 QEMU shows a certain behaviour.
713
714
715 ==== Special features ====
716
717 Feature "deprecated" marks a command, event, or struct member as
718 deprecated.  It is not supported elsewhere so far.
719
720
721 === Naming rules and reserved names ===
722
723 All names must begin with a letter, and contain only ASCII letters,
724 digits, hyphen, and underscore.  There are two exceptions: enum values
725 may start with a digit, and names that are downstream extensions (see
726 section Downstream extensions) start with underscore.
727
728 Names beginning with 'q_' are reserved for the generator, which uses
729 them for munging QMP names that resemble C keywords or other
730 problematic strings.  For example, a member named "default" in qapi
731 becomes "q_default" in the generated C code.
732
733 Types, commands, and events share a common namespace.  Therefore,
734 generally speaking, type definitions should always use CamelCase for
735 user-defined type names, while built-in types are lowercase.
736
737 Type names ending with 'Kind' or 'List' are reserved for the
738 generator, which uses them for implicit union enums and array types,
739 respectively.
740
741 Command names, and member names within a type, should be all lower
742 case with words separated by a hyphen.  However, some existing older
743 commands and complex types use underscore; when extending them,
744 consistency is preferred over blindly avoiding underscore.
745
746 Event names should be ALL_CAPS with words separated by underscore.
747
748 Member name 'u' and names starting with 'has-' or 'has_' are reserved
749 for the generator, which uses them for unions and for tracking
750 optional members.
751
752 Any name (command, event, type, member, or enum value) beginning with
753 "x-" is marked experimental, and may be withdrawn or changed
754 incompatibly in a future release.
755
756 Pragma 'name-case-whitelist' lets you violate the rules on use of
757 upper and lower case.  Use for new code is strongly discouraged.
758
759
760 === Downstream extensions ===
761
762 QAPI schema names that are externally visible, say in the Client JSON
763 Protocol, need to be managed with care.  Names starting with a
764 downstream prefix of the form __RFQDN_ are reserved for the downstream
765 who controls the valid, reverse fully qualified domain name RFQDN.
766 RFQDN may only contain ASCII letters, digits, hyphen and period.
767
768 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
769 downstream command __com.redhat_drive-mirror.
770
771
772 === Configuring the schema ===
773
774 Syntax:
775     COND = STRING
776          | [ STRING, ... ]
777
778 All definitions take an optional 'if' member.  Its value must be a
779 string or a list of strings.  A string is shorthand for a list
780 containing just that string.  The code generated for the definition
781 will then be guarded by #if STRING for each STRING in the COND list.
782
783 Example: a conditional struct
784
785  { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
786    'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] }
787
788 gets its generated code guarded like this:
789
790  #if defined(CONFIG_FOO)
791  #if defined(HAVE_BAR)
792  ... generated code ...
793  #endif /* defined(HAVE_BAR) */
794  #endif /* defined(CONFIG_FOO) */
795
796 Individual members of complex types, commands arguments, and
797 event-specific data can also be made conditional.  This requires the
798 longhand form of MEMBER.
799
800 Example: a struct type with unconditional member 'foo' and conditional
801 member 'bar'
802
803 { 'struct': 'IfStruct', 'data':
804   { 'foo': 'int',
805     'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
806
807 A union's discriminator may not be conditional.
808
809 Likewise, individual enumeration values be conditional.  This requires
810 the longhand form of ENUM-VALUE.
811
812 Example: an enum type with unconditional value 'foo' and conditional
813 value 'bar'
814
815 { 'enum': 'IfEnum', 'data':
816   [ 'foo',
817     { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
818
819 Likewise, features can be conditional.  This requires the longhand
820 form of FEATURE.
821
822 Example: a struct with conditional feature 'allow-negative-numbers'
823
824 { 'struct': 'TestType',
825   'data': { 'number': 'int' },
826   'features': [ { 'name': 'allow-negative-numbers',
827                   'if' 'defined(IFCOND)' } ] }
828
829 Please note that you are responsible to ensure that the C code will
830 compile with an arbitrary combination of conditions, since the
831 generator is unable to check it at this point.
832
833 The conditions apply to introspection as well, i.e. introspection
834 shows a conditional entity only when the condition is satisfied in
835 this particular build.
836
837
838 === Documentation comments ===
839
840 A multi-line comment that starts and ends with a '##' line is a
841 documentation comment.
842
843 If the documentation comment starts like
844
845     ##
846     # @SYMBOL:
847
848 it documents the definition if SYMBOL, else it's free-form
849 documentation.
850
851 See below for more on definition documentation.
852
853 Free-form documentation may be used to provide additional text and
854 structuring content.
855
856 ==== Headings and subheadings ====
857
858 A free-form documentation comment containing a line which starts with
859 some '=' symbols and then a space defines a section heading:
860
861     ##
862     # = This is a top level heading
863     #
864     # This is a free-form comment which will go under the
865     # top level heading.
866     ##
867
868     ##
869     # == This is a second level heading
870     ##
871
872 A heading line must be the first line of the documentation
873 comment block.
874
875 Section headings must always be correctly nested, so you can only
876 define a third-level heading inside a second-level heading, and so on.
877
878 ==== Documentation markup ====
879
880 Documentation comments can use most rST markup.  In particular,
881 a '::' literal block can be used for examples:
882
883     # ::
884     #
885     #   Text of the example, may span
886     #   multiple lines
887
888 '*' starts an itemized list:
889
890     # * First item, may span
891     #   multiple lines
892     # * Second item
893
894 You can also use '-' instead of '*'.
895
896 A decimal number followed by '.' starts a numbered list:
897
898     # 1. First item, may span
899     #    multiple lines
900     # 2. Second item
901
902 The actual number doesn't matter.
903
904 Lists of either kind must be preceded and followed by a blank line.
905 If a list item's text spans multiple lines, then the second and
906 subsequent lines must be correctly indented to line up with the
907 first character of the first line.
908
909 The usual '**strong**', '*emphasised*' and '``literal``' markup should
910 be used.  If you need a single literal '*' you will need to
911 backslash-escape it.  As an extension beyond the usual rST syntax, you
912 can also use '@foo' to reference a name in the schema; this is
913 rendered the same way as '``foo``'.
914
915 Example:
916
917 ##
918 # Some text foo with **bold** and *emphasis*
919 # 1. with a list
920 # 2. like that
921 #
922 # And some code:
923 #
924 # ::
925 #
926 #   $ echo foo
927 #   -> do this
928 #   <- get that
929 ##
930
931
932 ==== Definition documentation ====
933
934 Definition documentation, if present, must immediately precede the
935 definition it documents.
936
937 When documentation is required (see pragma 'doc-required'), every
938 definition must have documentation.
939
940 Definition documentation starts with a line naming the definition,
941 followed by an optional overview, a description of each argument (for
942 commands and events), member (for structs and unions), branch (for
943 alternates), or value (for enums), and finally optional tagged
944 sections.
945
946 Descriptions of arguments can span multiple lines.  The description
947 text can start on the line following the '@argname:', in which case it
948 must not be indented at all.  It can also start on the same line as
949 the '@argname:'.  In this case if it spans multiple lines then second
950 and subsequent lines must be indented to line up with the first
951 character of the first line of the description:
952
953 # @argone:
954 # This is a two line description
955 # in the first style.
956 #
957 # @argtwo: This is a two line description
958 #          in the second style.
959
960 The number of spaces between the ':' and the text is not significant.
961
962 FIXME: the parser accepts these things in almost any order.
963 FIXME: union branches should be described, too.
964
965 Extensions added after the definition was first released carry a
966 '(since x.y.z)' comment.
967
968 A tagged section starts with one of the following words:
969 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
970 The section ends with the start of a new section.
971
972 The text of a section can start on a new line, in
973 which case it must not be indented at all.  It can also start
974 on the same line as the 'Note:', 'Returns:', etc tag.  In this
975 case if it spans multiple lines then second and subsequent
976 lines must be indented to match the first, in the same way as
977 multiline argument descriptions.
978
979 A 'Since: x.y.z' tagged section lists the release that introduced the
980 definition.
981
982 The text of a section can start on a new line, in
983 which case it must not be indented at all.  It can also start
984 on the same line as the 'Note:', 'Returns:', etc tag.  In this
985 case if it spans multiple lines then second and subsequent
986 lines must be indented to match the first.
987
988 An 'Example' or 'Examples' section is automatically rendered
989 entirely as literal fixed-width text.  In other sections,
990 the text is formatted, and rST markup can be used.
991
992 For example:
993
994 ##
995 # @BlockStats:
996 #
997 # Statistics of a virtual block device or a block backing device.
998 #
999 # @device: If the stats are for a virtual block device, the name
1000 #          corresponding to the virtual block device.
1001 #
1002 # @node-name: The node name of the device. (since 2.3)
1003 #
1004 # ... more members ...
1005 #
1006 # Since: 0.14.0
1007 ##
1008 { 'struct': 'BlockStats',
1009   'data': {'*device': 'str', '*node-name': 'str',
1010            ... more members ... } }
1011
1012 ##
1013 # @query-blockstats:
1014 #
1015 # Query the @BlockStats for all virtual block devices.
1016 #
1017 # @query-nodes: If true, the command will query all the
1018 #               block nodes ... explain, explain ...  (since 2.3)
1019 #
1020 # Returns: A list of @BlockStats for each virtual block devices.
1021 #
1022 # Since: 0.14.0
1023 #
1024 # Example:
1025 #
1026 # -> { "execute": "query-blockstats" }
1027 # <- {
1028 #      ... lots of output ...
1029 #    }
1030 #
1031 ##
1032 { 'command': 'query-blockstats',
1033   'data': { '*query-nodes': 'bool' },
1034   'returns': ['BlockStats'] }
1035
1036
1037 == Client JSON Protocol introspection ==
1038
1039 Clients of a Client JSON Protocol commonly need to figure out what
1040 exactly the server (QEMU) supports.
1041
1042 For this purpose, QMP provides introspection via command
1043 query-qmp-schema.  QGA currently doesn't support introspection.
1044
1045 While Client JSON Protocol wire compatibility should be maintained
1046 between qemu versions, we cannot make the same guarantees for
1047 introspection stability.  For example, one version of qemu may provide
1048 a non-variant optional member of a struct, and a later version rework
1049 the member to instead be non-optional and associated with a variant.
1050 Likewise, one version of qemu may list a member with open-ended type
1051 'str', and a later version could convert it to a finite set of strings
1052 via an enum type; or a member may be converted from a specific type to
1053 an alternate that represents a choice between the original type and
1054 something else.
1055
1056 query-qmp-schema returns a JSON array of SchemaInfo objects.  These
1057 objects together describe the wire ABI, as defined in the QAPI schema.
1058 There is no specified order to the SchemaInfo objects returned; a
1059 client must search for a particular name throughout the entire array
1060 to learn more about that name, but is at least guaranteed that there
1061 will be no collisions between type, command, and event names.
1062
1063 However, the SchemaInfo can't reflect all the rules and restrictions
1064 that apply to QMP.  It's interface introspection (figuring out what's
1065 there), not interface specification.  The specification is in the QAPI
1066 schema.  To understand how QMP is to be used, you need to study the
1067 QAPI schema.
1068
1069 Like any other command, query-qmp-schema is itself defined in the QAPI
1070 schema, along with the SchemaInfo type.  This text attempts to give an
1071 overview how things work.  For details you need to consult the QAPI
1072 schema.
1073
1074 SchemaInfo objects have common members "name", "meta-type",
1075 "features", and additional variant members depending on the value of
1076 meta-type.
1077
1078 Each SchemaInfo object describes a wire ABI entity of a certain
1079 meta-type: a command, event or one of several kinds of type.
1080
1081 SchemaInfo for commands and events have the same name as in the QAPI
1082 schema.
1083
1084 Command and event names are part of the wire ABI, but type names are
1085 not.  Therefore, the SchemaInfo for types have auto-generated
1086 meaningless names.  For readability, the examples in this section use
1087 meaningful type names instead.
1088
1089 Optional member "features" exposes the entity's feature strings as a
1090 JSON array of strings.
1091
1092 To examine a type, start with a command or event using it, then follow
1093 references by name.
1094
1095 QAPI schema definitions not reachable that way are omitted.
1096
1097 The SchemaInfo for a command has meta-type "command", and variant
1098 members "arg-type", "ret-type" and "allow-oob".  On the wire, the
1099 "arguments" member of a client's "execute" command must conform to the
1100 object type named by "arg-type".  The "return" member that the server
1101 passes in a success response conforms to the type named by "ret-type".
1102 When "allow-oob" is true, it means the command supports out-of-band
1103 execution.  It defaults to false.
1104
1105 If the command takes no arguments, "arg-type" names an object type
1106 without members.  Likewise, if the command returns nothing, "ret-type"
1107 names an object type without members.
1108
1109 Example: the SchemaInfo for command query-qmp-schema
1110
1111     { "name": "query-qmp-schema", "meta-type": "command",
1112       "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1113
1114     Type "q_empty" is an automatic object type without members, and type
1115     "SchemaInfoList" is the array of SchemaInfo type.
1116
1117 The SchemaInfo for an event has meta-type "event", and variant member
1118 "arg-type".  On the wire, a "data" member that the server passes in an
1119 event conforms to the object type named by "arg-type".
1120
1121 If the event carries no additional information, "arg-type" names an
1122 object type without members.  The event may not have a data member on
1123 the wire then.
1124
1125 Each command or event defined with 'data' as MEMBERS object in the
1126 QAPI schema implicitly defines an object type.
1127
1128 Example: the SchemaInfo for EVENT_C from section Events
1129
1130     { "name": "EVENT_C", "meta-type": "event",
1131       "arg-type": "q_obj-EVENT_C-arg" }
1132
1133     Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1134     the two members from the event's definition.
1135
1136 The SchemaInfo for struct and union types has meta-type "object".
1137
1138 The SchemaInfo for a struct type has variant member "members".
1139
1140 The SchemaInfo for a union type additionally has variant members "tag"
1141 and "variants".
1142
1143 "members" is a JSON array describing the object's common members, if
1144 any.  Each element is a JSON object with members "name" (the member's
1145 name), "type" (the name of its type), and optionally "default".  The
1146 member is optional if "default" is present.  Currently, "default" can
1147 only have value null.  Other values are reserved for future
1148 extensions.  The "members" array is in no particular order; clients
1149 must search the entire object when learning whether a particular
1150 member is supported.
1151
1152 Example: the SchemaInfo for MyType from section Struct types
1153
1154     { "name": "MyType", "meta-type": "object",
1155       "members": [
1156           { "name": "member1", "type": "str" },
1157           { "name": "member2", "type": "int" },
1158           { "name": "member3", "type": "str", "default": null } ] }
1159
1160 "features" exposes the command's feature strings as a JSON array of
1161 strings.
1162
1163 Example: the SchemaInfo for TestType from section Features:
1164
1165     { "name": "TestType", "meta-type": "object",
1166       "members": [
1167           { "name": "number", "type": "int" } ],
1168       "features": ["allow-negative-numbers"] }
1169
1170 "tag" is the name of the common member serving as type tag.
1171 "variants" is a JSON array describing the object's variant members.
1172 Each element is a JSON object with members "case" (the value of type
1173 tag this element applies to) and "type" (the name of an object type
1174 that provides the variant members for this type tag value).  The
1175 "variants" array is in no particular order, and is not guaranteed to
1176 list cases in the same order as the corresponding "tag" enum type.
1177
1178 Example: the SchemaInfo for flat union BlockdevOptions from section
1179 Union types
1180
1181     { "name": "BlockdevOptions", "meta-type": "object",
1182       "members": [
1183           { "name": "driver", "type": "BlockdevDriver" },
1184           { "name": "read-only", "type": "bool", "default": null } ],
1185       "tag": "driver",
1186       "variants": [
1187           { "case": "file", "type": "BlockdevOptionsFile" },
1188           { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
1189
1190 Note that base types are "flattened": its members are included in the
1191 "members" array.
1192
1193 A simple union implicitly defines an enumeration type for its implicit
1194 discriminator (called "type" on the wire, see section Union types).
1195
1196 A simple union implicitly defines an object type for each of its
1197 variants.
1198
1199 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
1200 Union types
1201
1202     { "name": "BlockdevOptionsSimple", "meta-type": "object",
1203       "members": [
1204           { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
1205       "tag": "type",
1206       "variants": [
1207           { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
1208           { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
1209
1210     Enumeration type "BlockdevOptionsSimpleKind" and the object types
1211     "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
1212     are implicitly defined.
1213
1214 The SchemaInfo for an alternate type has meta-type "alternate", and
1215 variant member "members".  "members" is a JSON array.  Each element is
1216 a JSON object with member "type", which names a type.  Values of the
1217 alternate type conform to exactly one of its member types.  There is
1218 no guarantee on the order in which "members" will be listed.
1219
1220 Example: the SchemaInfo for BlockdevRef from section Alternate types
1221
1222     { "name": "BlockdevRef", "meta-type": "alternate",
1223       "members": [
1224           { "type": "BlockdevOptions" },
1225           { "type": "str" } ] }
1226
1227 The SchemaInfo for an array type has meta-type "array", and variant
1228 member "element-type", which names the array's element type.  Array
1229 types are implicitly defined.  For convenience, the array's name may
1230 resemble the element type; however, clients should examine member
1231 "element-type" instead of making assumptions based on parsing member
1232 "name".
1233
1234 Example: the SchemaInfo for ['str']
1235
1236     { "name": "[str]", "meta-type": "array",
1237       "element-type": "str" }
1238
1239 The SchemaInfo for an enumeration type has meta-type "enum" and
1240 variant member "values".  The values are listed in no particular
1241 order; clients must search the entire enum when learning whether a
1242 particular value is supported.
1243
1244 Example: the SchemaInfo for MyEnum from section Enumeration types
1245
1246     { "name": "MyEnum", "meta-type": "enum",
1247       "values": [ "value1", "value2", "value3" ] }
1248
1249 The SchemaInfo for a built-in type has the same name as the type in
1250 the QAPI schema (see section Built-in Types), with one exception
1251 detailed below.  It has variant member "json-type" that shows how
1252 values of this type are encoded on the wire.
1253
1254 Example: the SchemaInfo for str
1255
1256     { "name": "str", "meta-type": "builtin", "json-type": "string" }
1257
1258 The QAPI schema supports a number of integer types that only differ in
1259 how they map to C.  They are identical as far as SchemaInfo is
1260 concerned.  Therefore, they get all mapped to a single type "int" in
1261 SchemaInfo.
1262
1263 As explained above, type names are not part of the wire ABI.  Not even
1264 the names of built-in types.  Clients should examine member
1265 "json-type" instead of hard-coding names of built-in types.
1266
1267
1268 == Compatibility considerations ==
1269
1270 Maintaining backward compatibility at the Client JSON Protocol level
1271 while evolving the schema requires some care.  This section is about
1272 syntactic compatibility, which is necessary, but not sufficient, for
1273 actual compatibility.
1274
1275 Clients send commands with argument data, and receive command
1276 responses with return data and events with event data.
1277
1278 Adding opt-in functionality to the send direction is backwards
1279 compatible: adding commands, optional arguments, enumeration values,
1280 union and alternate branches; turning an argument type into an
1281 alternate of that type; making mandatory arguments optional.  Clients
1282 oblivious of the new functionality continue to work.
1283
1284 Incompatible changes include removing commands, command arguments,
1285 enumeration values, union and alternate branches, adding mandatory
1286 command arguments, and making optional arguments mandatory.
1287
1288 The specified behavior of an absent optional argument should remain
1289 the same.  With proper documentation, this policy still allows some
1290 flexibility; for example, when an optional 'buffer-size' argument is
1291 specified to default to a sensible buffer size, the actual default
1292 value can still be changed.  The specified default behavior is not the
1293 exact size of the buffer, only that the default size is sensible.
1294
1295 Adding functionality to the receive direction is generally backwards
1296 compatible: adding events, adding return and event data members.
1297 Clients are expected to ignore the ones they don't know.
1298
1299 Removing "unreachable" stuff like events that can't be triggered
1300 anymore, optional return or event data members that can't be sent
1301 anymore, and return or event data member (enumeration) values that
1302 can't be sent anymore makes no difference to clients, except for
1303 introspection.  The latter can conceivably confuse clients, so tread
1304 carefully.
1305
1306 Incompatible changes include removing return and event data members.
1307
1308 Any change to a command definition's 'data' or one of the types used
1309 there (recursively) needs to consider send direction compatibility.
1310
1311 Any change to a command definition's 'return', an event definition's
1312 'data', or one of the types used there (recursively) needs to consider
1313 receive direction compatibility.
1314
1315 Any change to types used in both contexts need to consider both.
1316
1317 Enumeration type values and complex and alternate type members may be
1318 reordered freely.  For enumerations and alternate types, this doesn't
1319 affect the wire encoding.  For complex types, this might make the
1320 implementation emit JSON object members in a different order, which
1321 the Client JSON Protocol permits.
1322
1323 Since type names are not visible in the Client JSON Protocol, types
1324 may be freely renamed.  Even certain refactorings are invisible, such
1325 as splitting members from one type into a common base type.
1326
1327
1328 == Code generation ==
1329
1330 The QAPI code generator qapi-gen.py generates code and documentation
1331 from the schema.  Together with the core QAPI libraries, this code
1332 provides everything required to take JSON commands read in by a Client
1333 JSON Protocol server, unmarshal the arguments into the underlying C
1334 types, call into the corresponding C function, map the response back
1335 to a Client JSON Protocol response to be returned to the user, and
1336 introspect the commands.
1337
1338 As an example, we'll use the following schema, which describes a
1339 single complex user-defined type, along with command which takes a
1340 list of that type as a parameter, and returns a single element of that
1341 type.  The user is responsible for writing the implementation of
1342 qmp_my_command(); everything else is produced by the generator.
1343
1344     $ cat example-schema.json
1345     { 'struct': 'UserDefOne',
1346       'data': { 'integer': 'int', '*string': 'str' } }
1347
1348     { 'command': 'my-command',
1349       'data': { 'arg1': ['UserDefOne'] },
1350       'returns': 'UserDefOne' }
1351
1352     { 'event': 'MY_EVENT' }
1353
1354 We run qapi-gen.py like this:
1355
1356     $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1357     --prefix="example-" example-schema.json
1358
1359 For a more thorough look at generated code, the testsuite includes
1360 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1361 what the generator will accept, and compiles the resulting C code as
1362 part of 'make check-unit'.
1363
1364 === Code generated for QAPI types ===
1365
1366 The following files are created:
1367
1368 $(prefix)qapi-types.h - C types corresponding to types defined in
1369                         the schema
1370
1371 $(prefix)qapi-types.c - Cleanup functions for the above C types
1372
1373 The $(prefix) is an optional parameter used as a namespace to keep the
1374 generated code from one schema/code-generation separated from others so code
1375 can be generated/used from multiple schemas without clobbering previously
1376 created code.
1377
1378 Example:
1379
1380     $ cat qapi-generated/example-qapi-types.h
1381 [Uninteresting stuff omitted...]
1382
1383     #ifndef EXAMPLE_QAPI_TYPES_H
1384     #define EXAMPLE_QAPI_TYPES_H
1385
1386     #include "qapi/qapi-builtin-types.h"
1387
1388     typedef struct UserDefOne UserDefOne;
1389
1390     typedef struct UserDefOneList UserDefOneList;
1391
1392     typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1393
1394     struct UserDefOne {
1395         int64_t integer;
1396         bool has_string;
1397         char *string;
1398     };
1399
1400     void qapi_free_UserDefOne(UserDefOne *obj);
1401     G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne)
1402
1403     struct UserDefOneList {
1404         UserDefOneList *next;
1405         UserDefOne *value;
1406     };
1407
1408     void qapi_free_UserDefOneList(UserDefOneList *obj);
1409     G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList)
1410
1411     struct q_obj_my_command_arg {
1412         UserDefOneList *arg1;
1413     };
1414
1415     #endif /* EXAMPLE_QAPI_TYPES_H */
1416     $ cat qapi-generated/example-qapi-types.c
1417 [Uninteresting stuff omitted...]
1418
1419     void qapi_free_UserDefOne(UserDefOne *obj)
1420     {
1421         Visitor *v;
1422
1423         if (!obj) {
1424             return;
1425         }
1426
1427         v = qapi_dealloc_visitor_new();
1428         visit_type_UserDefOne(v, NULL, &obj, NULL);
1429         visit_free(v);
1430     }
1431
1432     void qapi_free_UserDefOneList(UserDefOneList *obj)
1433     {
1434         Visitor *v;
1435
1436         if (!obj) {
1437             return;
1438         }
1439
1440         v = qapi_dealloc_visitor_new();
1441         visit_type_UserDefOneList(v, NULL, &obj, NULL);
1442         visit_free(v);
1443     }
1444
1445 [Uninteresting stuff omitted...]
1446
1447 For a modular QAPI schema (see section Include directives), code for
1448 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1449
1450 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1451 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1452
1453 If qapi-gen.py is run with option --builtins, additional files are
1454 created:
1455
1456 qapi-builtin-types.h - C types corresponding to built-in types
1457
1458 qapi-builtin-types.c - Cleanup functions for the above C types
1459
1460 === Code generated for visiting QAPI types ===
1461
1462 These are the visitor functions used to walk through and convert
1463 between a native QAPI C data structure and some other format (such as
1464 QObject); the generated functions are named visit_type_FOO() and
1465 visit_type_FOO_members().
1466
1467 The following files are generated:
1468
1469 $(prefix)qapi-visit.c: Visitor function for a particular C type, used
1470                        to automagically convert QObjects into the
1471                        corresponding C type and vice-versa, as well
1472                        as for deallocating memory for an existing C
1473                        type
1474
1475 $(prefix)qapi-visit.h: Declarations for previously mentioned visitor
1476                        functions
1477
1478 Example:
1479
1480     $ cat qapi-generated/example-qapi-visit.h
1481 [Uninteresting stuff omitted...]
1482
1483     #ifndef EXAMPLE_QAPI_VISIT_H
1484     #define EXAMPLE_QAPI_VISIT_H
1485
1486     #include "qapi/qapi-builtin-visit.h"
1487     #include "example-qapi-types.h"
1488
1489
1490     bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1491     bool visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1492     bool visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1493
1494     bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1495
1496     #endif /* EXAMPLE_QAPI_VISIT_H */
1497     $ cat qapi-generated/example-qapi-visit.c
1498 [Uninteresting stuff omitted...]
1499
1500     bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1501     {
1502         if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1503             return false;
1504         }
1505         if (visit_optional(v, "string", &obj->has_string)) {
1506             if (!visit_type_str(v, "string", &obj->string, errp)) {
1507                 return false;
1508             }
1509         }
1510         return true;
1511     }
1512
1513     bool visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1514     {
1515         bool ok = false;
1516
1517         if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) {
1518             return false;
1519         }
1520         if (!*obj) {
1521             /* incomplete */
1522             assert(visit_is_dealloc(v));
1523             goto out_obj;
1524         }
1525         if (!visit_type_UserDefOne_members(v, *obj, errp)) {
1526             goto out_obj;
1527         }
1528         ok = visit_check_struct(v, errp);
1529     out_obj:
1530         visit_end_struct(v, (void **)obj);
1531         if (!ok && visit_is_input(v)) {
1532             qapi_free_UserDefOne(*obj);
1533             *obj = NULL;
1534         }
1535         return ok;
1536     }
1537
1538     bool visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1539     {
1540         bool ok = false;
1541         UserDefOneList *tail;
1542         size_t size = sizeof(**obj);
1543
1544         if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) {
1545             return false;
1546         }
1547
1548         for (tail = *obj; tail;
1549              tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1550             if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
1551                 goto out_obj;
1552             }
1553         }
1554
1555         ok = visit_check_list(v, errp);
1556     out_obj:
1557         visit_end_list(v, (void **)obj);
1558         if (!ok && visit_is_input(v)) {
1559             qapi_free_UserDefOneList(*obj);
1560             *obj = NULL;
1561         }
1562         return ok;
1563     }
1564
1565     bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1566     {
1567         if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1568             return false;
1569         }
1570         return true;
1571     }
1572
1573 [Uninteresting stuff omitted...]
1574
1575 For a modular QAPI schema (see section Include directives), code for
1576 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1577
1578 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1579 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1580
1581 If qapi-gen.py is run with option --builtins, additional files are
1582 created:
1583
1584 qapi-builtin-visit.h - Visitor functions for built-in types
1585
1586 qapi-builtin-visit.c - Declarations for these visitor functions
1587
1588 === Code generated for commands ===
1589
1590 These are the marshaling/dispatch functions for the commands defined
1591 in the schema.  The generated code provides qmp_marshal_COMMAND(), and
1592 declares qmp_COMMAND() that the user must implement.
1593
1594 The following files are generated:
1595
1596 $(prefix)qapi-commands.c: Command marshal/dispatch functions for each
1597                           QMP command defined in the schema
1598
1599 $(prefix)qapi-commands.h: Function prototypes for the QMP commands
1600                           specified in the schema
1601
1602 $(prefix)qapi-init-commands.h - Command initialization prototype
1603
1604 $(prefix)qapi-init-commands.c - Command initialization code
1605
1606 Example:
1607
1608     $ cat qapi-generated/example-qapi-commands.h
1609 [Uninteresting stuff omitted...]
1610
1611     #ifndef EXAMPLE_QAPI_COMMANDS_H
1612     #define EXAMPLE_QAPI_COMMANDS_H
1613
1614     #include "example-qapi-types.h"
1615
1616     UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1617     void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1618
1619     #endif /* EXAMPLE_QAPI_COMMANDS_H */
1620     $ cat qapi-generated/example-qapi-commands.c
1621 [Uninteresting stuff omitted...]
1622
1623     static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1624     {
1625         Visitor *v;
1626
1627         v = qobject_output_visitor_new(ret_out);
1628         if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) {
1629             visit_complete(v, ret_out);
1630         }
1631         visit_free(v);
1632         v = qapi_dealloc_visitor_new();
1633         visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1634         visit_free(v);
1635     }
1636
1637     void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1638     {
1639         Error *err = NULL;
1640         bool ok = false;
1641         Visitor *v;
1642         UserDefOne *retval;
1643         q_obj_my_command_arg arg = {0};
1644
1645         v = qobject_input_visitor_new(QOBJECT(args));
1646         if (!visit_start_struct(v, NULL, NULL, 0, errp)) {
1647             goto out;
1648         }
1649         if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) {
1650             ok = visit_check_struct(v, errp);
1651         }
1652         visit_end_struct(v, NULL);
1653         if (!ok) {
1654             goto out;
1655         }
1656
1657         retval = qmp_my_command(arg.arg1, &err);
1658         error_propagate(errp, err);
1659         if (err) {
1660             goto out;
1661         }
1662
1663         qmp_marshal_output_UserDefOne(retval, ret, errp);
1664
1665     out:
1666         visit_free(v);
1667         v = qapi_dealloc_visitor_new();
1668         visit_start_struct(v, NULL, NULL, 0, NULL);
1669         visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1670         visit_end_struct(v, NULL);
1671         visit_free(v);
1672     }
1673
1674 [Uninteresting stuff omitted...]
1675     $ cat qapi-generated/example-qapi-init-commands.h
1676 [Uninteresting stuff omitted...]
1677     #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H
1678     #define EXAMPLE_QAPI_INIT_COMMANDS_H
1679
1680     #include "qapi/qmp/dispatch.h"
1681
1682     void example_qmp_init_marshal(QmpCommandList *cmds);
1683
1684     #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */
1685     $ cat qapi-generated/example-qapi-init-commands.c
1686 [Uninteresting stuff omitted...]
1687     void example_qmp_init_marshal(QmpCommandList *cmds)
1688     {
1689         QTAILQ_INIT(cmds);
1690
1691         qmp_register_command(cmds, "my-command",
1692                              qmp_marshal_my_command, QCO_NO_OPTIONS);
1693     }
1694 [Uninteresting stuff omitted...]
1695
1696 For a modular QAPI schema (see section Include directives), code for
1697 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1698
1699 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1700 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1701
1702 === Code generated for events ===
1703
1704 This is the code related to events defined in the schema, providing
1705 qapi_event_send_EVENT().
1706
1707 The following files are created:
1708
1709 $(prefix)qapi-events.h - Function prototypes for each event type
1710
1711 $(prefix)qapi-events.c - Implementation of functions to send an event
1712
1713 $(prefix)qapi-emit-events.h - Enumeration of all event names, and
1714                               common event code declarations
1715
1716 $(prefix)qapi-emit-events.c - Common event code definitions
1717
1718 Example:
1719
1720     $ cat qapi-generated/example-qapi-events.h
1721 [Uninteresting stuff omitted...]
1722
1723     #ifndef EXAMPLE_QAPI_EVENTS_H
1724     #define EXAMPLE_QAPI_EVENTS_H
1725
1726     #include "qapi/util.h"
1727     #include "example-qapi-types.h"
1728
1729     void qapi_event_send_my_event(void);
1730
1731     #endif /* EXAMPLE_QAPI_EVENTS_H */
1732     $ cat qapi-generated/example-qapi-events.c
1733 [Uninteresting stuff omitted...]
1734
1735     void qapi_event_send_my_event(void)
1736     {
1737         QDict *qmp;
1738
1739         qmp = qmp_event_build_dict("MY_EVENT");
1740
1741         example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
1742
1743         qobject_unref(qmp);
1744     }
1745
1746 [Uninteresting stuff omitted...]
1747     $ cat qapi-generated/example-qapi-emit-events.h
1748 [Uninteresting stuff omitted...]
1749
1750     #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
1751     #define EXAMPLE_QAPI_EMIT_EVENTS_H
1752
1753     #include "qapi/util.h"
1754
1755     typedef enum example_QAPIEvent {
1756         EXAMPLE_QAPI_EVENT_MY_EVENT,
1757         EXAMPLE_QAPI_EVENT__MAX,
1758     } example_QAPIEvent;
1759
1760     #define example_QAPIEvent_str(val) \
1761         qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
1762
1763     extern const QEnumLookup example_QAPIEvent_lookup;
1764
1765     void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
1766
1767     #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
1768     $ cat qapi-generated/example-qapi-emit-events.c
1769 [Uninteresting stuff omitted...]
1770
1771     const QEnumLookup example_QAPIEvent_lookup = {
1772         .array = (const char *const[]) {
1773             [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1774         },
1775         .size = EXAMPLE_QAPI_EVENT__MAX
1776     };
1777
1778 [Uninteresting stuff omitted...]
1779
1780 For a modular QAPI schema (see section Include directives), code for
1781 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1782
1783 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1784 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1785
1786 === Code generated for introspection ===
1787
1788 The following files are created:
1789
1790 $(prefix)qapi-introspect.c - Defines a string holding a JSON
1791                             description of the schema
1792
1793 $(prefix)qapi-introspect.h - Declares the above string
1794
1795 Example:
1796
1797     $ cat qapi-generated/example-qapi-introspect.h
1798 [Uninteresting stuff omitted...]
1799
1800     #ifndef EXAMPLE_QAPI_INTROSPECT_H
1801     #define EXAMPLE_QAPI_INTROSPECT_H
1802
1803     #include "qapi/qmp/qlit.h"
1804
1805     extern const QLitObject example_qmp_schema_qlit;
1806
1807     #endif /* EXAMPLE_QAPI_INTROSPECT_H */
1808     $ cat qapi-generated/example-qapi-introspect.c
1809 [Uninteresting stuff omitted...]
1810
1811     const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
1812         QLIT_QDICT(((QLitDictEntry[]) {
1813             { "arg-type", QLIT_QSTR("0"), },
1814             { "meta-type", QLIT_QSTR("command"), },
1815             { "name", QLIT_QSTR("my-command"), },
1816             { "ret-type", QLIT_QSTR("1"), },
1817             {}
1818         })),
1819         QLIT_QDICT(((QLitDictEntry[]) {
1820             { "arg-type", QLIT_QSTR("2"), },
1821             { "meta-type", QLIT_QSTR("event"), },
1822             { "name", QLIT_QSTR("MY_EVENT"), },
1823             {}
1824         })),
1825         /* "0" = q_obj_my-command-arg */
1826         QLIT_QDICT(((QLitDictEntry[]) {
1827             { "members", QLIT_QLIST(((QLitObject[]) {
1828                 QLIT_QDICT(((QLitDictEntry[]) {
1829                     { "name", QLIT_QSTR("arg1"), },
1830                     { "type", QLIT_QSTR("[1]"), },
1831                     {}
1832                 })),
1833                 {}
1834             })), },
1835             { "meta-type", QLIT_QSTR("object"), },
1836             { "name", QLIT_QSTR("0"), },
1837             {}
1838         })),
1839         /* "1" = UserDefOne */
1840         QLIT_QDICT(((QLitDictEntry[]) {
1841             { "members", QLIT_QLIST(((QLitObject[]) {
1842                 QLIT_QDICT(((QLitDictEntry[]) {
1843                     { "name", QLIT_QSTR("integer"), },
1844                     { "type", QLIT_QSTR("int"), },
1845                     {}
1846                 })),
1847                 QLIT_QDICT(((QLitDictEntry[]) {
1848                     { "default", QLIT_QNULL, },
1849                     { "name", QLIT_QSTR("string"), },
1850                     { "type", QLIT_QSTR("str"), },
1851                     {}
1852                 })),
1853                 {}
1854             })), },
1855             { "meta-type", QLIT_QSTR("object"), },
1856             { "name", QLIT_QSTR("1"), },
1857             {}
1858         })),
1859         /* "2" = q_empty */
1860         QLIT_QDICT(((QLitDictEntry[]) {
1861             { "members", QLIT_QLIST(((QLitObject[]) {
1862                 {}
1863             })), },
1864             { "meta-type", QLIT_QSTR("object"), },
1865             { "name", QLIT_QSTR("2"), },
1866             {}
1867         })),
1868         QLIT_QDICT(((QLitDictEntry[]) {
1869             { "element-type", QLIT_QSTR("1"), },
1870             { "meta-type", QLIT_QSTR("array"), },
1871             { "name", QLIT_QSTR("[1]"), },
1872             {}
1873         })),
1874         QLIT_QDICT(((QLitDictEntry[]) {
1875             { "json-type", QLIT_QSTR("int"), },
1876             { "meta-type", QLIT_QSTR("builtin"), },
1877             { "name", QLIT_QSTR("int"), },
1878             {}
1879         })),
1880         QLIT_QDICT(((QLitDictEntry[]) {
1881             { "json-type", QLIT_QSTR("string"), },
1882             { "meta-type", QLIT_QSTR("builtin"), },
1883             { "name", QLIT_QSTR("str"), },
1884             {}
1885         })),
1886         {}
1887     }));
1888
1889 [Uninteresting stuff omitted...]