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