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