1 ==================================
2 How to use the QAPI code generator
3 ==================================
6 Copyright IBM Corp. 2011
7 Copyright (C) 2012-2016 Red Hat, Inc.
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.
16 QAPI is a native C API within QEMU which provides management-level
17 functionality to internal and external users. For external
18 users/processes, this interface is made available by a JSON-based wire
19 format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
20 well as the QEMU Guest Agent (QGA) for communicating with the guest.
21 The remainder of this document uses "Client JSON Protocol" when
22 referring to the wire contents of a QMP or QGA connection.
24 To map between Client JSON Protocol interfaces and the native C API,
25 we generate C code from a QAPI schema. This document describes the
26 QAPI schema language, and how it gets mapped to the Client JSON
27 Protocol and to C. It additionally provides guidance on maintaining
28 Client JSON Protocol compatibility.
31 The QAPI schema language
32 ========================
34 The QAPI schema defines the Client JSON Protocol's commands and
35 events, as well as types used by them. Forward references are
38 It is permissible for the schema to contain additional types not used
39 by any commands or events, for the side effect of generated C code
42 There are several kinds of types: simple types (a number of built-in
43 types, such as ``int`` and ``str``; as well as enumerations), arrays,
44 complex types (structs and unions), and alternate types (a choice
51 Syntax is loosely based on `JSON <http://www.ietf.org/rfc/rfc8259.txt>`_.
54 * Comments: start with a hash character (``#``) that is not part of a
55 string, and extend to the end of the line.
57 * Strings are enclosed in ``'single quotes'``, not ``"double quotes"``.
59 * Strings are restricted to printable ASCII, and escape sequences to
62 * Numbers and ``null`` are not supported.
64 A second layer of syntax defines the sequences of JSON texts that are
65 a correctly structured QAPI schema. We provide a grammar for this
66 syntax in an EBNF-like notation:
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
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
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
86 The order of members within JSON objects does not matter unless
89 A QAPI schema consists of a series of top-level expressions::
91 SCHEMA = TOP-LEVEL-EXPR...
93 The top-level expressions are all JSON objects. Code and
94 documentation is generated in schema definition order. Code order
97 A top-level expressions is either a directive or a definition::
99 TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION
101 There are two kinds of directives and six kinds of definitions::
103 DIRECTIVE = INCLUDE | PRAGMA
104 DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT
106 These are discussed in detail below.
112 The following types are predefined, and map to C as follows:
114 ============= ============== ============================================
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 ============= ============== ============================================
143 INCLUDE = { 'include': STRING }
145 The QAPI schema definitions can be modularized using the 'include' directive::
147 { 'include': 'path/to/file.json' }
149 The directive is evaluated recursively, and include paths are relative
150 to the file using the directive. Multiple includes of the same file
153 As a matter of style, it is a good idea to have all files be
154 self-contained, but at the moment, nothing prevents an included file
155 from making a forward reference to a type that is only introduced by
156 an outer file. The parser may be made stricter in the future to
157 prevent incomplete include files.
166 PRAGMA = { 'pragma': {
167 '*doc-required': BOOL,
168 '*command-name-exceptions': [ STRING, ... ],
169 '*command-returns-exceptions': [ STRING, ... ],
170 '*member-name-exceptions': [ STRING, ... ] } }
172 The pragma directive lets you control optional generator behavior.
174 Pragma's scope is currently the complete schema. Setting the same
175 pragma to different values in parts of the schema doesn't work.
177 Pragma 'doc-required' takes a boolean value. If true, documentation
178 is required. Default is false.
180 Pragma 'command-name-exceptions' takes a list of commands whose names
181 may contain ``"_"`` instead of ``"-"``. Default is none.
183 Pragma 'command-returns-exceptions' takes a list of commands that may
184 violate the rules on permitted return types. Default is none.
186 Pragma 'member-name-exceptions' takes a list of types whose member
187 names may contain uppercase letters, and ``"_"`` instead of ``"-"``.
197 ENUM = { 'enum': STRING,
198 'data': [ ENUM-VALUE, ... ],
201 '*features': FEATURES }
205 '*features': FEATURES }
207 Member 'enum' names the enum type.
209 Each member of the 'data' array defines a value of the enumeration
210 type. The form STRING is shorthand for :code:`{ 'name': STRING }`. The
211 'name' values must be be distinct.
215 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
217 Nothing prevents an empty enumeration, although it is probably not
220 On the wire, an enumeration type's value is represented by its
221 (string) name. In C, it's represented by an enumeration constant.
222 These are of the form PREFIX_NAME, where PREFIX is derived from the
223 enumeration type's name, and NAME from the value's name. For the
224 example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to
225 VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The
226 optional 'prefix' member overrides PREFIX.
228 The generated C enumeration constants have values 0, 1, ..., N-1 (in
229 QAPI schema order), where N is the number of values. There is an
230 additional enumeration constant PREFIX__MAX with value N.
232 Do not use string or an integer type when an enumeration type can do
233 the job satisfactorily.
235 The optional 'if' member specifies a conditional. See `Configuring the
236 schema`_ below for more on this.
238 The optional 'features' member specifies features. See Features_
239 below for more on this.
244 Type references and array types
245 -------------------------------
249 TYPE-REF = STRING | ARRAY-TYPE
250 ARRAY-TYPE = [ STRING ]
252 A string denotes the type named by the string.
254 A one-element array containing a string denotes an array of the type
255 named by the string. Example: ``['int']`` denotes an array of ``int``.
263 STRUCT = { 'struct': STRING,
267 '*features': FEATURES }
268 MEMBERS = { MEMBER, ... }
269 MEMBER = STRING : TYPE-REF
270 | STRING : { 'type': TYPE-REF,
272 '*features': FEATURES }
274 Member 'struct' names the struct type.
276 Each MEMBER of the 'data' object defines a member of the struct type.
280 The MEMBER's STRING name consists of an optional ``*`` prefix and the
281 struct member name. If ``*`` is present, the member is optional.
283 The MEMBER's value defines its properties, in particular its type.
284 The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`.
288 { 'struct': 'MyType',
289 'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } }
291 A struct type corresponds to a struct in C, and an object in JSON.
292 The C struct's members are generated in QAPI schema order.
294 The optional 'base' member names a struct type whose members are to be
295 included in this type. They go first in the C struct.
299 { 'struct': 'BlockdevOptionsGenericFormat',
300 'data': { 'file': 'str' } }
301 { 'struct': 'BlockdevOptionsGenericCOWFormat',
302 'base': 'BlockdevOptionsGenericFormat',
303 'data': { '*backing': 'str' } }
305 An example BlockdevOptionsGenericCOWFormat object on the wire could use
306 both members like this::
308 { "file": "/some/place/my-image",
309 "backing": "/some/place/my-backing-file" }
311 The optional 'if' member specifies a conditional. See `Configuring
312 the schema`_ below for more on this.
314 The optional 'features' member specifies features. See Features_
315 below for more on this.
323 UNION = { 'union': STRING,
324 'base': ( MEMBERS | STRING ),
325 'discriminator': STRING,
328 '*features': FEATURES }
329 BRANCHES = { BRANCH, ... }
330 BRANCH = STRING : TYPE-REF
331 | STRING : { 'type': TYPE-REF, '*if': COND }
333 Member 'union' names the union type.
335 The 'base' member defines the common members. If it is a MEMBERS_
336 object, it defines common members just like a struct type's 'data'
337 member defines struct type members. If it is a STRING, it names a
338 struct type whose members are the common members.
340 Member 'discriminator' must name a non-optional enum-typed member of
341 the base struct. That member's value selects a branch by its name.
342 If no such branch exists, an empty branch is assumed.
344 Each BRANCH of the 'data' object defines a branch of the union. A
345 union must have at least one branch.
347 The BRANCH's STRING name is the branch name. It must be a value of
348 the discriminator enum type.
350 The BRANCH's value defines the branch's properties, in particular its
351 type. The type must a struct type. The form TYPE-REF_ is shorthand
352 for :code:`{ 'type': TYPE-REF }`.
354 In the Client JSON Protocol, a union is represented by an object with
355 the common members (from the base type) and the selected branch's
356 members. The two sets of member names must be disjoint.
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' } }
367 Resulting in these JSON objects::
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 }
374 The order of branches need not match the order of the enum values.
375 The branches need not cover all possible enum values. In the
376 resulting generated C data types, a union is represented as a struct
377 with the base members in QAPI schema order, and then a union of
378 structures for each branch of the struct.
380 The optional 'if' member specifies a conditional. See `Configuring
381 the schema`_ below for more on this.
383 The optional 'features' member specifies features. See Features_
384 below for more on this.
392 ALTERNATE = { 'alternate': STRING,
393 'data': ALTERNATIVES,
395 '*features': FEATURES }
396 ALTERNATIVES = { ALTERNATIVE, ... }
397 ALTERNATIVE = STRING : STRING
398 | STRING : { 'type': STRING, '*if': COND }
400 Member 'alternate' names the alternate type.
402 Each ALTERNATIVE of the 'data' object defines a branch of the
403 alternate. An alternate must have at least one branch.
405 The ALTERNATIVE's STRING name is the branch name.
407 The ALTERNATIVE's value defines the branch's properties, in particular
408 its type. The form STRING is shorthand for :code:`{ 'type': STRING }`.
412 { 'alternate': 'BlockdevRef',
413 'data': { 'definition': 'BlockdevOptions',
414 'reference': 'str' } }
416 An alternate type is like a union type, except there is no
417 discriminator on the wire. Instead, the branch to use is inferred
418 from the value. An alternate can only express a choice between types
419 represented differently on the wire.
421 If a branch is typed as the 'bool' built-in, the alternate accepts
422 true and false; if it is typed as any of the various numeric
423 built-ins, it accepts a JSON number; if it is typed as a 'str'
424 built-in or named enum type, it accepts a JSON string; if it is typed
425 as the 'null' built-in, it accepts JSON null; and if it is typed as a
426 complex type (struct or union), it accepts a JSON object.
428 The example alternate declaration above allows using both of the
429 following example objects::
431 { "file": "my_existing_block_device_id" }
432 { "file": { "driver": "file",
434 "filename": "/tmp/mydisk.qcow2" } }
436 The optional 'if' member specifies a conditional. See `Configuring
437 the schema`_ below for more on this.
439 The optional 'features' member specifies features. See Features_
440 below for more on this.
448 COMMAND = { 'command': STRING,
450 '*data': ( MEMBERS | STRING ),
455 '*returns': TYPE-REF,
456 '*success-response': false,
459 '*allow-preconfig': true,
462 '*features': FEATURES }
464 Member 'command' names the command.
466 Member 'data' defines the arguments. It defaults to an empty MEMBERS_
469 If 'data' is a MEMBERS_ object, then MEMBERS defines arguments just
470 like a struct type's 'data' defines struct type members.
472 If 'data' is a STRING, then STRING names a complex type whose members
473 are the arguments. A union type requires ``'boxed': true``.
475 Member 'returns' defines the command's return type. It defaults to an
476 empty struct type. It must normally be a complex type or an array of
477 a complex type. To return anything else, the command must be listed
478 in pragma 'commands-returns-exceptions'. If you do this, extending
479 the command to return additional information will be harder. Use of
480 the pragma for new commands is strongly discouraged.
482 A command's error responses are not specified in the QAPI schema.
483 Error conditions should be documented in comments.
485 In the Client JSON Protocol, the value of the "execute" or "exec-oob"
486 member is the command name. The value of the "arguments" member then
487 has to conform to the arguments, and the value of the success
488 response's "return" member will conform to the return type.
490 Some example commands::
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' ] }
498 which would validate this Client JSON Protocol transaction::
500 => { "execute": "my-first-command",
501 "arguments": { "arg1": "hello" } }
503 => { "execute": "my-second-command" }
504 <= { "return": [ { "value": "one" }, { } ] }
506 The generator emits a prototype for the C function implementing the
507 command. The function itself needs to be written by hand. See
508 section `Code generated for commands`_ for examples.
510 The function returns the return type. When member 'boxed' is absent,
511 it takes the command arguments as arguments one by one, in QAPI schema
512 order. Else it takes them wrapped in the C struct generated for the
513 complex argument type. It takes an additional ``Error **`` argument in
516 The generator also emits a marshalling function that extracts
517 arguments for the user's function out of an input QDict, calls the
518 user's function, and if it succeeded, builds an output QObject from
519 its return value. This is for use by the QMP monitor core.
521 In rare cases, QAPI cannot express a type-safe representation of a
522 corresponding Client JSON Protocol command. You then have to suppress
523 generation of a marshalling function by including a member 'gen' with
524 boolean value false, and instead write your own function. For
527 { 'command': 'netdev_add',
528 'data': {'type': 'str', 'id': 'str'},
531 Please try to avoid adding new commands that rely on this, and instead
532 use type-safe unions.
534 Normally, the QAPI schema is used to describe synchronous exchanges,
535 where a response is expected. But in some cases, the action of a
536 command is expected to change state in a way that a successful
537 response is not possible (although the command will still return an
538 error object on failure). When a successful reply is not possible,
539 the command definition includes the optional member 'success-response'
540 with boolean value false. So far, only QGA makes use of this member.
542 Member 'allow-oob' declares whether the command supports out-of-band
543 (OOB) execution. It defaults to false. For example::
545 { 'command': 'migrate_recover',
546 'data': { 'uri': 'str' }, 'allow-oob': true }
548 See the :doc:`/interop/qmp-spec` for out-of-band execution syntax
551 Commands supporting out-of-band execution can still be executed
554 When a command is executed in-band, its handler runs in the main
555 thread with the BQL held.
557 When a command is executed out-of-band, its handler runs in a
558 dedicated monitor I/O thread with the BQL *not* held.
560 An OOB-capable command handler must satisfy the following conditions:
562 - It terminates quickly.
563 - It does not invoke system calls that may block.
564 - It does not access guest RAM that may block when userfaultfd is
565 enabled for postcopy live migration.
566 - It takes only "fast" locks, i.e. all critical sections protected by
567 any lock it takes also satisfy the conditions for OOB command
570 The restrictions on locking limit access to shared state. Such access
571 requires synchronization, but OOB commands can't take the BQL or any
574 When in doubt, do not implement OOB execution support.
576 Member 'allow-preconfig' declares whether the command is available
577 before the machine is built. It defaults to false. For example::
579 { 'enum': 'QMPCapability',
581 { 'command': 'qmp_capabilities',
582 'data': { '*enable': [ 'QMPCapability' ] },
583 'allow-preconfig': true }
585 QMP is available before the machine is built only when QEMU was
586 started with --preconfig.
588 Member 'coroutine' tells the QMP dispatcher whether the command handler
589 is safe to be run in a coroutine. It defaults to false. If it is true,
590 the command handler is called from coroutine context and may yield while
591 waiting for an external event (such as I/O completion) in order to avoid
592 blocking the guest and other background operations.
594 Coroutine safety can be hard to prove, similar to thread safety. Common
597 - The BQL isn't held across ``qemu_coroutine_yield()``, so
598 operations that used to assume that they execute atomically may have
599 to be more careful to protect against changes in the global state.
601 - Nested event loops (``AIO_WAIT_WHILE()`` etc.) are problematic in
602 coroutine context and can easily lead to deadlocks. They should be
603 replaced by yielding and reentering the coroutine when the condition
606 Since the command handler may assume coroutine context, any callers
607 other than the QMP dispatcher must also call it in coroutine context.
608 In particular, HMP commands calling such a QMP command handler must be
609 marked ``.coroutine = true`` in hmp-commands.hx.
611 It is an error to specify both ``'coroutine': true`` and ``'allow-oob': true``
612 for a command. We don't currently have a use case for both together and
613 without a use case, it's not entirely clear what the semantics should
616 The optional 'if' member specifies a conditional. See `Configuring
617 the schema`_ below for more on this.
619 The optional 'features' member specifies features. See Features_
620 below for more on this.
628 EVENT = { 'event': STRING,
630 '*data': ( MEMBERS | STRING ),
636 '*features': FEATURES }
638 Member 'event' names the event. This is the event name used in the
639 Client JSON Protocol.
641 Member 'data' defines the event-specific data. It defaults to an
642 empty MEMBERS object.
644 If 'data' is a MEMBERS object, then MEMBERS defines event-specific
645 data just like a struct type's 'data' defines struct type members.
647 If 'data' is a STRING, then STRING names a complex type whose members
648 are the event-specific data. A union type requires ``'boxed': true``.
650 An example event is::
652 { 'event': 'EVENT_C',
653 'data': { '*a': 'int', 'b': 'str' } }
655 Resulting in this JSON object::
657 { "event": "EVENT_C",
658 "data": { "b": "test string" },
659 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
661 The generator emits a function to send the event. When member 'boxed'
662 is absent, it takes event-specific data one by one, in QAPI schema
663 order. Else it takes them wrapped in the C struct generated for the
664 complex type. See section `Code generated for events`_ for examples.
666 The optional 'if' member specifies a conditional. See `Configuring
667 the schema`_ below for more on this.
669 The optional 'features' member specifies features. See Features_
670 below for more on this.
680 FEATURES = [ FEATURE, ... ]
682 | { 'name': STRING, '*if': COND }
684 Sometimes, the behaviour of QEMU changes compatibly, but without a
685 change in the QMP syntax (usually by allowing values or operations
686 that previously resulted in an error). QMP clients may still need to
687 know whether the extension is available.
689 For this purpose, a list of features can be specified for definitions,
690 enumeration values, and struct members. Each feature list member can
691 either be ``{ 'name': STRING, '*if': COND }``, or STRING, which is
692 shorthand for ``{ 'name': STRING }``.
694 The optional 'if' member specifies a conditional. See `Configuring
695 the schema`_ below for more on this.
699 { 'struct': 'TestType',
700 'data': { 'number': 'int' },
701 'features': [ 'allow-negative-numbers' ] }
703 The feature strings are exposed to clients in introspection, as
704 explained in section `Client JSON Protocol introspection`_.
706 Intended use is to have each feature string signal that this build of
707 QEMU shows a certain behaviour.
713 Feature "deprecated" marks a command, event, enum value, or struct
714 member as deprecated. It is not supported elsewhere so far.
715 Interfaces so marked may be withdrawn in future releases in accordance
716 with QEMU's deprecation policy.
718 Feature "unstable" marks a command, event, enum value, or struct
719 member as unstable. It is not supported elsewhere so far. Interfaces
720 so marked may be withdrawn or changed incompatibly in future releases.
723 Naming rules and reserved names
724 -------------------------------
726 All names must begin with a letter, and contain only ASCII letters,
727 digits, hyphen, and underscore. There are two exceptions: enum values
728 may start with a digit, and names that are downstream extensions (see
729 section `Downstream extensions`_) start with underscore.
731 Names beginning with ``q_`` are reserved for the generator, which uses
732 them for munging QMP names that resemble C keywords or other
733 problematic strings. For example, a member named ``default`` in qapi
734 becomes ``q_default`` in the generated C code.
736 Types, commands, and events share a common namespace. Therefore,
737 generally speaking, type definitions should always use CamelCase for
738 user-defined type names, while built-in types are lowercase.
740 Type names ending with ``List`` are reserved for the generator, which
741 uses them for array types.
743 Command names, member names within a type, and feature names should be
744 all lower case with words separated by a hyphen. However, some
745 existing older commands and complex types use underscore; when
746 extending them, consistency is preferred over blindly avoiding
749 Event names should be ALL_CAPS with words separated by underscore.
751 Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved
752 for the generator, which uses them for unions and for tracking
755 Names beginning with ``x-`` used to signify "experimental". This
756 convention has been replaced by special feature "unstable".
758 Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
759 you violate naming rules. Use for new code is strongly discouraged. See
760 `Pragma directives`_ for details.
763 Downstream extensions
764 ---------------------
766 QAPI schema names that are externally visible, say in the Client JSON
767 Protocol, need to be managed with care. Names starting with a
768 downstream prefix of the form __RFQDN_ are reserved for the downstream
769 who controls the valid, reverse fully qualified domain name RFQDN.
770 RFQDN may only contain ASCII letters, digits, hyphen and period.
772 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
773 downstream command ``__com.redhat_drive-mirror``.
776 Configuring the schema
777 ----------------------
782 | { 'all: [ COND, ... ] }
783 | { 'any: [ COND, ... ] }
786 All definitions take an optional 'if' member. Its value must be a
787 string, or an object with a single member 'all', 'any' or 'not'.
789 The C code generated for the definition will then be guarded by an #if
790 preprocessing directive with an operand generated from that condition:
792 * STRING will generate defined(STRING)
793 * { 'all': [COND, ...] } will generate (COND && ...)
794 * { 'any': [COND, ...] } will generate (COND || ...)
795 * { 'not': COND } will generate !COND
797 Example: a conditional struct ::
799 { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
800 'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } }
802 gets its generated code guarded like this::
804 #if defined(CONFIG_FOO) && defined(HAVE_BAR)
805 ... generated code ...
806 #endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */
808 Individual members of complex types can also be made conditional.
809 This requires the longhand form of MEMBER.
811 Example: a struct type with unconditional member 'foo' and conditional
814 { 'struct': 'IfStruct',
815 'data': { 'foo': 'int',
816 'bar': { 'type': 'int', 'if': 'IFCOND'} } }
818 A union's discriminator may not be conditional.
820 Likewise, individual enumeration values may be conditional. This
821 requires the longhand form of ENUM-VALUE_.
823 Example: an enum type with unconditional value 'foo' and conditional
828 { 'name' : 'bar', 'if': 'IFCOND' } ] }
830 Likewise, features can be conditional. This requires the longhand
833 Example: a struct with conditional feature 'allow-negative-numbers' ::
835 { 'struct': 'TestType',
836 'data': { 'number': 'int' },
837 'features': [ { 'name': 'allow-negative-numbers',
840 Please note that you are responsible to ensure that the C code will
841 compile with an arbitrary combination of conditions, since the
842 generator is unable to check it at this point.
844 The conditions apply to introspection as well, i.e. introspection
845 shows a conditional entity only when the condition is satisfied in
846 this particular build.
849 Documentation comments
850 ----------------------
852 A multi-line comment that starts and ends with a ``##`` line is a
853 documentation comment.
855 If the documentation comment starts like ::
860 it documents the definition of SYMBOL, else it's free-form
863 See below for more on `Definition documentation`_.
865 Free-form documentation may be used to provide additional text and
869 Headings and subheadings
870 ~~~~~~~~~~~~~~~~~~~~~~~~
872 A free-form documentation comment containing a line which starts with
873 some ``=`` symbols and then a space defines a section heading::
876 # = This is a top level heading
878 # This is a free-form comment which will go under the
883 # == This is a second level heading
886 A heading line must be the first line of the documentation
889 Section headings must always be correctly nested, so you can only
890 define a third-level heading inside a second-level heading, and so on.
896 Documentation comments can use most rST markup. In particular,
897 a ``::`` literal block can be used for examples::
901 # Text of the example, may span
904 ``*`` starts an itemized list::
906 # * First item, may span
910 You can also use ``-`` instead of ``*``.
912 A decimal number followed by ``.`` starts a numbered list::
914 # 1. First item, may span
918 The actual number doesn't matter.
920 Lists of either kind must be preceded and followed by a blank line.
921 If a list item's text spans multiple lines, then the second and
922 subsequent lines must be correctly indented to line up with the
923 first character of the first line.
925 The usual ****strong****, *\*emphasized\** and ````literal```` markup
926 should be used. If you need a single literal ``*``, you will need to
929 Use ``@foo`` to reference a name in the schema. This is an rST
930 extension. It is rendered the same way as ````foo````, but carries
936 # Some text foo with **bold** and *emphasis*
950 For legibility, wrap text paragraphs so every line is at most 70
953 Separate sentences with two spaces.
956 Definition documentation
957 ~~~~~~~~~~~~~~~~~~~~~~~~
959 Definition documentation, if present, must immediately precede the
960 definition it documents.
962 When documentation is required (see pragma_ 'doc-required'), every
963 definition must have documentation.
965 Definition documentation starts with a line naming the definition,
966 followed by an optional overview, a description of each argument (for
967 commands and events), member (for structs and unions), branch (for
968 alternates), or value (for enums), a description of each feature (if
969 any), and finally optional tagged sections.
971 Descriptions start with '\@name:'. The description text should be
974 # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
975 # do eiusmod tempor incididunt ut labore et dolore magna aliqua.
977 .. FIXME The parser accepts these things in almost any order.
979 .. FIXME union branches should be described, too.
981 Extensions added after the definition was first released carry a
982 "(since x.y.z)" comment.
984 The feature descriptions must be preceded by a line "Features:", like
989 # @feature: Description text
991 A tagged section starts with one of the following words:
992 "Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:",
993 "TODO:". The section ends with the start of a new section.
995 The second and subsequent lines of sections other than
996 "Example"/"Examples" should be indented like this::
998 # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
999 # laboris nisi ut aliquip ex ea commodo consequat.
1001 # Duis aute irure dolor in reprehenderit in voluptate velit esse
1002 # cillum dolore eu fugiat nulla pariatur.
1004 A "Since: x.y.z" tagged section lists the release that introduced the
1007 An "Example" or "Examples" section is rendered entirely
1008 as literal fixed-width text. "TODO" sections are not rendered at all
1009 (they are for developers, not users of QMP). In other sections, the
1010 text is formatted, and rST markup can be used.
1017 # Statistics of a virtual block device or a block backing device.
1019 # @device: If the stats are for a virtual block device, the name
1020 # corresponding to the virtual block device.
1022 # @node-name: The node name of the device. (since 2.3)
1024 # ... more members ...
1028 { 'struct': 'BlockStats',
1029 'data': {'*device': 'str', '*node-name': 'str',
1030 ... more members ... } }
1033 # @query-blockstats:
1035 # Query the @BlockStats for all virtual block devices.
1037 # @query-nodes: If true, the command will query all the block nodes
1038 # ... explain, explain ... (since 2.3)
1040 # Returns: A list of @BlockStats for each virtual block devices.
1046 # -> { "execute": "query-blockstats" }
1048 # ... lots of output ...
1052 { 'command': 'query-blockstats',
1053 'data': { '*query-nodes': 'bool' },
1054 'returns': ['BlockStats'] }
1060 A blank line is required between list items and paragraphs. Without
1061 it, the list may not be recognized, resulting in garbled output. Good
1064 # An event's state is modified if:
1066 # - its name matches the @name pattern, and
1067 # - if @vcpu is given, the event has the "vcpu" property.
1069 Without the blank line this would be a single paragraph.
1071 Indentation matters. Bad example::
1073 # @none: None (no memory side cache in this proximity domain,
1074 # or cache associativity unknown)
1077 The last line's de-indent is wrong. The second and subsequent lines
1078 need to line up with each other, like this::
1080 # @none: None (no memory side cache in this proximity domain,
1081 # or cache associativity unknown)
1084 Section tags are case-sensitive and end with a colon. Good example::
1088 Bad examples (all ordinary paragraphs)::
1096 Likewise, member descriptions require a colon. Good example::
1098 # @interface-id: Interface ID
1100 Bad examples (all ordinary paragraphs)::
1102 # @interface-id Interface ID
1104 # @interface-id : Interface ID
1106 Undocumented members are not flagged, yet. Instead, the generated
1107 documentation describes them as "Not documented". Think twice before
1108 adding more undocumented members.
1110 When you change documentation comments, please check the generated
1111 documentation comes out as intended!
1114 Client JSON Protocol introspection
1115 ==================================
1117 Clients of a Client JSON Protocol commonly need to figure out what
1118 exactly the server (QEMU) supports.
1120 For this purpose, QMP provides introspection via command
1121 query-qmp-schema. QGA currently doesn't support introspection.
1123 While Client JSON Protocol wire compatibility should be maintained
1124 between qemu versions, we cannot make the same guarantees for
1125 introspection stability. For example, one version of qemu may provide
1126 a non-variant optional member of a struct, and a later version rework
1127 the member to instead be non-optional and associated with a variant.
1128 Likewise, 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
1130 via an enum type; or a member may be converted from a specific type to
1131 an alternate that represents a choice between the original type and
1134 query-qmp-schema returns a JSON array of SchemaInfo objects. These
1135 objects together describe the wire ABI, as defined in the QAPI schema.
1136 There is no specified order to the SchemaInfo objects returned; a
1137 client must search for a particular name throughout the entire array
1138 to learn more about that name, but is at least guaranteed that there
1139 will be no collisions between type, command, and event names.
1141 However, the SchemaInfo can't reflect all the rules and restrictions
1142 that apply to QMP. It's interface introspection (figuring out what's
1143 there), not interface specification. The specification is in the QAPI
1144 schema. To understand how QMP is to be used, you need to study the
1147 Like any other command, query-qmp-schema is itself defined in the QAPI
1148 schema, along with the SchemaInfo type. This text attempts to give an
1149 overview how things work. For details you need to consult the QAPI
1152 SchemaInfo objects have common members "name", "meta-type",
1153 "features", and additional variant members depending on the value of
1156 Each SchemaInfo object describes a wire ABI entity of a certain
1157 meta-type: a command, event or one of several kinds of type.
1159 SchemaInfo for commands and events have the same name as in the QAPI
1162 Command and event names are part of the wire ABI, but type names are
1163 not. Therefore, the SchemaInfo for types have auto-generated
1164 meaningless names. For readability, the examples in this section use
1165 meaningful type names instead.
1167 Optional member "features" exposes the entity's feature strings as a
1168 JSON array of strings.
1170 To examine a type, start with a command or event using it, then follow
1173 QAPI schema definitions not reachable that way are omitted.
1175 The SchemaInfo for a command has meta-type "command", and variant
1176 members "arg-type", "ret-type" and "allow-oob". On the wire, the
1177 "arguments" member of a client's "execute" command must conform to the
1178 object type named by "arg-type". The "return" member that the server
1179 passes in a success response conforms to the type named by "ret-type".
1180 When "allow-oob" is true, it means the command supports out-of-band
1181 execution. It defaults to false.
1183 If the command takes no arguments, "arg-type" names an object type
1184 without members. Likewise, if the command returns nothing, "ret-type"
1185 names an object type without members.
1187 Example: the SchemaInfo for command query-qmp-schema ::
1189 { "name": "query-qmp-schema", "meta-type": "command",
1190 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1192 Type "q_empty" is an automatic object type without members, and type
1193 "SchemaInfoList" is the array of SchemaInfo type.
1195 The 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
1197 event conforms to the object type named by "arg-type".
1199 If the event carries no additional information, "arg-type" names an
1200 object type without members. The event may not have a data member on
1203 Each command or event defined with 'data' as MEMBERS object in the
1204 QAPI schema implicitly defines an object type.
1206 Example: the SchemaInfo for EVENT_C from section Events_ ::
1208 { "name": "EVENT_C", "meta-type": "event",
1209 "arg-type": "q_obj-EVENT_C-arg" }
1211 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1212 the two members from the event's definition.
1214 The SchemaInfo for struct and union types has meta-type "object" and
1215 variant member "members".
1217 The SchemaInfo for a union type additionally has variant members "tag"
1220 "members" is a JSON array describing the object's common members, if
1221 any. Each element is a JSON object with members "name" (the member's
1222 name), "type" (the name of its type), "features" (a JSON array of
1223 feature strings), and "default". The latter two are optional. The
1224 member is optional if "default" is present. Currently, "default" can
1225 only have value null. Other values are reserved for future
1226 extensions. The "members" array is in no particular order; clients
1227 must search the entire object when learning whether a particular
1228 member is supported.
1230 Example: the SchemaInfo for MyType from section `Struct types`_ ::
1232 { "name": "MyType", "meta-type": "object",
1234 { "name": "member1", "type": "str" },
1235 { "name": "member2", "type": "int" },
1236 { "name": "member3", "type": "str", "default": null } ] }
1238 "features" exposes the command's feature strings as a JSON array of
1241 Example: the SchemaInfo for TestType from section Features_::
1243 { "name": "TestType", "meta-type": "object",
1245 { "name": "number", "type": "int" } ],
1246 "features": ["allow-negative-numbers"] }
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.
1250 Each element is a JSON object with members "case" (the value of type
1251 tag this element applies to) and "type" (the name of an object type
1252 that provides the variant members for this type tag value). The
1253 "variants" array is in no particular order, and is not guaranteed to
1254 list cases in the same order as the corresponding "tag" enum type.
1256 Example: the SchemaInfo for union BlockdevOptions from section
1259 { "name": "BlockdevOptions", "meta-type": "object",
1261 { "name": "driver", "type": "BlockdevDriver" },
1262 { "name": "read-only", "type": "bool", "default": null } ],
1265 { "case": "file", "type": "BlockdevOptionsFile" },
1266 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
1268 Note that base types are "flattened": its members are included in the
1271 The SchemaInfo for an alternate type has meta-type "alternate", and
1272 variant member "members". "members" is a JSON array. Each element is
1273 a JSON object with member "type", which names a type. Values of the
1274 alternate type conform to exactly one of its member types. There is
1275 no guarantee on the order in which "members" will be listed.
1277 Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ ::
1279 { "name": "BlockdevRef", "meta-type": "alternate",
1281 { "type": "BlockdevOptions" },
1282 { "type": "str" } ] }
1284 The SchemaInfo for an array type has meta-type "array", and variant
1285 member "element-type", which names the array's element type. Array
1286 types are implicitly defined. For convenience, the array's name may
1287 resemble the element type; however, clients should examine member
1288 "element-type" instead of making assumptions based on parsing member
1291 Example: the SchemaInfo for ['str'] ::
1293 { "name": "[str]", "meta-type": "array",
1294 "element-type": "str" }
1296 The SchemaInfo for an enumeration type has meta-type "enum" and
1297 variant member "members".
1299 "members" is a JSON array describing the enumeration values. Each
1300 element is a JSON object with member "name" (the member's name), and
1301 optionally "features" (a JSON array of feature strings). The
1302 "members" array is in no particular order; clients must search the
1303 entire array when learning whether a particular value is supported.
1305 Example: the SchemaInfo for MyEnum from section `Enumeration types`_ ::
1307 { "name": "MyEnum", "meta-type": "enum",
1309 { "name": "value1" },
1310 { "name": "value2" },
1311 { "name": "value3" }
1314 The SchemaInfo for a built-in type has the same name as the type in
1315 the QAPI schema (see section `Built-in Types`_), with one exception
1316 detailed below. It has variant member "json-type" that shows how
1317 values of this type are encoded on the wire.
1319 Example: the SchemaInfo for str ::
1321 { "name": "str", "meta-type": "builtin", "json-type": "string" }
1323 The QAPI schema supports a number of integer types that only differ in
1324 how they map to C. They are identical as far as SchemaInfo is
1325 concerned. Therefore, they get all mapped to a single type "int" in
1328 As explained above, type names are not part of the wire ABI. Not even
1329 the names of built-in types. Clients should examine member
1330 "json-type" instead of hard-coding names of built-in types.
1333 Compatibility considerations
1334 ============================
1336 Maintaining backward compatibility at the Client JSON Protocol level
1337 while evolving the schema requires some care. This section is about
1338 syntactic compatibility, which is necessary, but not sufficient, for
1339 actual compatibility.
1341 Clients send commands with argument data, and receive command
1342 responses with return data and events with event data.
1344 Adding opt-in functionality to the send direction is backwards
1345 compatible: adding commands, optional arguments, enumeration values,
1346 union and alternate branches; turning an argument type into an
1347 alternate of that type; making mandatory arguments optional. Clients
1348 oblivious of the new functionality continue to work.
1350 Incompatible changes include removing commands, command arguments,
1351 enumeration values, union and alternate branches, adding mandatory
1352 command arguments, and making optional arguments mandatory.
1354 The specified behavior of an absent optional argument should remain
1355 the same. With proper documentation, this policy still allows some
1356 flexibility; for example, when an optional 'buffer-size' argument is
1357 specified to default to a sensible buffer size, the actual default
1358 value can still be changed. The specified default behavior is not the
1359 exact size of the buffer, only that the default size is sensible.
1361 Adding functionality to the receive direction is generally backwards
1362 compatible: adding events, adding return and event data members.
1363 Clients are expected to ignore the ones they don't know.
1365 Removing "unreachable" stuff like events that can't be triggered
1366 anymore, optional return or event data members that can't be sent
1367 anymore, and return or event data member (enumeration) values that
1368 can't be sent anymore makes no difference to clients, except for
1369 introspection. The latter can conceivably confuse clients, so tread
1372 Incompatible changes include removing return and event data members.
1374 Any change to a command definition's 'data' or one of the types used
1375 there (recursively) needs to consider send direction compatibility.
1377 Any change to a command definition's 'return', an event definition's
1378 'data', or one of the types used there (recursively) needs to consider
1379 receive direction compatibility.
1381 Any change to types used in both contexts need to consider both.
1383 Enumeration type values and complex and alternate type members may be
1384 reordered freely. For enumerations and alternate types, this doesn't
1385 affect the wire encoding. For complex types, this might make the
1386 implementation emit JSON object members in a different order, which
1387 the Client JSON Protocol permits.
1389 Since type names are not visible in the Client JSON Protocol, types
1390 may be freely renamed. Even certain refactorings are invisible, such
1391 as splitting members from one type into a common base type.
1397 The QAPI code generator qapi-gen.py generates code and documentation
1398 from the schema. Together with the core QAPI libraries, this code
1399 provides everything required to take JSON commands read in by a Client
1400 JSON Protocol server, unmarshal the arguments into the underlying C
1401 types, call into the corresponding C function, map the response back
1402 to a Client JSON Protocol response to be returned to the user, and
1403 introspect the commands.
1405 As an example, we'll use the following schema, which describes a
1406 single complex user-defined type, along with command which takes a
1407 list of that type as a parameter, and returns a single element of that
1408 type. The user is responsible for writing the implementation of
1409 qmp_my_command(); everything else is produced by the generator. ::
1411 $ cat example-schema.json
1412 { 'struct': 'UserDefOne',
1413 'data': { 'integer': 'int', '*string': 'str', '*flag': 'bool' } }
1415 { 'command': 'my-command',
1416 'data': { 'arg1': ['UserDefOne'] },
1417 'returns': 'UserDefOne' }
1419 { 'event': 'MY_EVENT' }
1421 We run qapi-gen.py like this::
1423 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1424 --prefix="example-" example-schema.json
1426 For a more thorough look at generated code, the testsuite includes
1427 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1428 what the generator will accept, and compiles the resulting C code as
1429 part of 'make check-unit'.
1432 Code generated for QAPI types
1433 -----------------------------
1435 The following files are created:
1437 ``$(prefix)qapi-types.h``
1438 C types corresponding to types defined in the schema
1440 ``$(prefix)qapi-types.c``
1441 Cleanup functions for the above C types
1443 The $(prefix) is an optional parameter used as a namespace to keep the
1444 generated code from one schema/code-generation separated from others so code
1445 can be generated/used from multiple schemas without clobbering previously
1450 $ cat qapi-generated/example-qapi-types.h
1451 [Uninteresting stuff omitted...]
1453 #ifndef EXAMPLE_QAPI_TYPES_H
1454 #define EXAMPLE_QAPI_TYPES_H
1456 #include "qapi/qapi-builtin-types.h"
1458 typedef struct UserDefOne UserDefOne;
1460 typedef struct UserDefOneList UserDefOneList;
1462 typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1471 void qapi_free_UserDefOne(UserDefOne *obj);
1472 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne)
1474 struct UserDefOneList {
1475 UserDefOneList *next;
1479 void qapi_free_UserDefOneList(UserDefOneList *obj);
1480 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList)
1482 struct q_obj_my_command_arg {
1483 UserDefOneList *arg1;
1486 #endif /* EXAMPLE_QAPI_TYPES_H */
1487 $ cat qapi-generated/example-qapi-types.c
1488 [Uninteresting stuff omitted...]
1490 void qapi_free_UserDefOne(UserDefOne *obj)
1498 v = qapi_dealloc_visitor_new();
1499 visit_type_UserDefOne(v, NULL, &obj, NULL);
1503 void qapi_free_UserDefOneList(UserDefOneList *obj)
1511 v = qapi_dealloc_visitor_new();
1512 visit_type_UserDefOneList(v, NULL, &obj, NULL);
1516 [Uninteresting stuff omitted...]
1518 For a modular QAPI schema (see section `Include directives`_), code for
1519 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1521 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1522 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1524 If qapi-gen.py is run with option --builtins, additional files are
1527 ``qapi-builtin-types.h``
1528 C types corresponding to built-in types
1530 ``qapi-builtin-types.c``
1531 Cleanup functions for the above C types
1534 Code generated for visiting QAPI types
1535 --------------------------------------
1537 These are the visitor functions used to walk through and convert
1538 between a native QAPI C data structure and some other format (such as
1539 QObject); the generated functions are named visit_type_FOO() and
1540 visit_type_FOO_members().
1542 The following files are generated:
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
1549 ``$(prefix)qapi-visit.h``
1550 Declarations for previously mentioned visitor functions
1554 $ cat qapi-generated/example-qapi-visit.h
1555 [Uninteresting stuff omitted...]
1557 #ifndef EXAMPLE_QAPI_VISIT_H
1558 #define EXAMPLE_QAPI_VISIT_H
1560 #include "qapi/qapi-builtin-visit.h"
1561 #include "example-qapi-types.h"
1564 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1566 bool visit_type_UserDefOne(Visitor *v, const char *name,
1567 UserDefOne **obj, Error **errp);
1569 bool visit_type_UserDefOneList(Visitor *v, const char *name,
1570 UserDefOneList **obj, Error **errp);
1572 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1574 #endif /* EXAMPLE_QAPI_VISIT_H */
1575 $ cat qapi-generated/example-qapi-visit.c
1576 [Uninteresting stuff omitted...]
1578 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1580 bool has_string = !!obj->string;
1582 if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1585 if (visit_optional(v, "string", &has_string)) {
1586 if (!visit_type_str(v, "string", &obj->string, errp)) {
1590 if (visit_optional(v, "flag", &obj->has_flag)) {
1591 if (!visit_type_bool(v, "flag", &obj->flag, errp)) {
1598 bool visit_type_UserDefOne(Visitor *v, const char *name,
1599 UserDefOne **obj, Error **errp)
1603 if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) {
1608 assert(visit_is_dealloc(v));
1612 if (!visit_type_UserDefOne_members(v, *obj, errp)) {
1615 ok = visit_check_struct(v, errp);
1617 visit_end_struct(v, (void **)obj);
1618 if (!ok && visit_is_input(v)) {
1619 qapi_free_UserDefOne(*obj);
1625 bool visit_type_UserDefOneList(Visitor *v, const char *name,
1626 UserDefOneList **obj, Error **errp)
1629 UserDefOneList *tail;
1630 size_t size = sizeof(**obj);
1632 if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) {
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)) {
1643 ok = visit_check_list(v, errp);
1645 visit_end_list(v, (void **)obj);
1646 if (!ok && visit_is_input(v)) {
1647 qapi_free_UserDefOneList(*obj);
1653 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1655 if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1661 [Uninteresting stuff omitted...]
1663 For a modular QAPI schema (see section `Include directives`_), code for
1664 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1666 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1667 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1669 If qapi-gen.py is run with option --builtins, additional files are
1672 ``qapi-builtin-visit.h``
1673 Visitor functions for built-in types
1675 ``qapi-builtin-visit.c``
1676 Declarations for these visitor functions
1679 Code generated for commands
1680 ---------------------------
1682 These are the marshaling/dispatch functions for the commands defined
1683 in the schema. The generated code provides qmp_marshal_COMMAND(), and
1684 declares qmp_COMMAND() that the user must implement.
1686 The following files are generated:
1688 ``$(prefix)qapi-commands.c``
1689 Command marshal/dispatch functions for each QMP command defined in
1692 ``$(prefix)qapi-commands.h``
1693 Function prototypes for the QMP commands specified in the schema
1695 ``$(prefix)qapi-commands.trace-events``
1696 Trace event declarations, see :ref:`tracing`.
1698 ``$(prefix)qapi-init-commands.h``
1699 Command initialization prototype
1701 ``$(prefix)qapi-init-commands.c``
1702 Command initialization code
1706 $ cat qapi-generated/example-qapi-commands.h
1707 [Uninteresting stuff omitted...]
1709 #ifndef EXAMPLE_QAPI_COMMANDS_H
1710 #define EXAMPLE_QAPI_COMMANDS_H
1712 #include "example-qapi-types.h"
1714 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1715 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1717 #endif /* EXAMPLE_QAPI_COMMANDS_H */
1719 $ cat qapi-generated/example-qapi-commands.trace-events
1720 # AUTOMATICALLY GENERATED, DO NOT MODIFY
1722 qmp_enter_my_command(const char *json) "%s"
1723 qmp_exit_my_command(const char *result, bool succeeded) "%s %d"
1725 $ cat qapi-generated/example-qapi-commands.c
1726 [Uninteresting stuff omitted...]
1728 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in,
1729 QObject **ret_out, Error **errp)
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);
1738 v = qapi_dealloc_visitor_new();
1739 visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1743 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1749 q_obj_my_command_arg arg = {0};
1751 v = qobject_input_visitor_new_qmp(QOBJECT(args));
1752 if (!visit_start_struct(v, NULL, NULL, 0, errp)) {
1755 if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) {
1756 ok = visit_check_struct(v, errp);
1758 visit_end_struct(v, NULL);
1763 if (trace_event_get_state_backends(TRACE_QMP_ENTER_MY_COMMAND)) {
1764 g_autoptr(GString) req_json = qobject_to_json(QOBJECT(args));
1766 trace_qmp_enter_my_command(req_json->str);
1769 retval = qmp_my_command(arg.arg1, &err);
1771 trace_qmp_exit_my_command(error_get_pretty(err), false);
1772 error_propagate(errp, err);
1776 qmp_marshal_output_UserDefOne(retval, ret, errp);
1778 if (trace_event_get_state_backends(TRACE_QMP_EXIT_MY_COMMAND)) {
1779 g_autoptr(GString) ret_json = qobject_to_json(*ret);
1781 trace_qmp_exit_my_command(ret_json->str, true);
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);
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
1799 #include "qapi/qmp/dispatch.h"
1801 void example_qmp_init_marshal(QmpCommandList *cmds);
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)
1810 qmp_register_command(cmds, "my-command",
1811 qmp_marshal_my_command, 0, 0);
1813 [Uninteresting stuff omitted...]
1815 For a modular QAPI schema (see section `Include directives`_), code for
1816 each sub-module SUBDIR/SUBMODULE.json is actually generated into::
1818 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1819 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1822 Code generated for events
1823 -------------------------
1825 This is the code related to events defined in the schema, providing
1826 qapi_event_send_EVENT().
1828 The following files are created:
1830 ``$(prefix)qapi-events.h``
1831 Function prototypes for each event type
1833 ``$(prefix)qapi-events.c``
1834 Implementation of functions to send an event
1836 ``$(prefix)qapi-emit-events.h``
1837 Enumeration of all event names, and common event code declarations
1839 ``$(prefix)qapi-emit-events.c``
1840 Common event code definitions
1844 $ cat qapi-generated/example-qapi-events.h
1845 [Uninteresting stuff omitted...]
1847 #ifndef EXAMPLE_QAPI_EVENTS_H
1848 #define EXAMPLE_QAPI_EVENTS_H
1850 #include "qapi/util.h"
1851 #include "example-qapi-types.h"
1853 void qapi_event_send_my_event(void);
1855 #endif /* EXAMPLE_QAPI_EVENTS_H */
1856 $ cat qapi-generated/example-qapi-events.c
1857 [Uninteresting stuff omitted...]
1859 void qapi_event_send_my_event(void)
1863 qmp = qmp_event_build_dict("MY_EVENT");
1865 example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
1870 [Uninteresting stuff omitted...]
1871 $ cat qapi-generated/example-qapi-emit-events.h
1872 [Uninteresting stuff omitted...]
1874 #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
1875 #define EXAMPLE_QAPI_EMIT_EVENTS_H
1877 #include "qapi/util.h"
1879 typedef enum example_QAPIEvent {
1880 EXAMPLE_QAPI_EVENT_MY_EVENT,
1881 EXAMPLE_QAPI_EVENT__MAX,
1882 } example_QAPIEvent;
1884 #define example_QAPIEvent_str(val) \
1885 qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
1887 extern const QEnumLookup example_QAPIEvent_lookup;
1889 void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
1891 #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
1892 $ cat qapi-generated/example-qapi-emit-events.c
1893 [Uninteresting stuff omitted...]
1895 const QEnumLookup example_QAPIEvent_lookup = {
1896 .array = (const char *const[]) {
1897 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1899 .size = EXAMPLE_QAPI_EVENT__MAX
1902 [Uninteresting stuff omitted...]
1904 For a modular QAPI schema (see section `Include directives`_), code for
1905 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1907 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1908 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1911 Code generated for introspection
1912 --------------------------------
1914 The following files are created:
1916 ``$(prefix)qapi-introspect.c``
1917 Defines a string holding a JSON description of the schema
1919 ``$(prefix)qapi-introspect.h``
1920 Declares the above string
1924 $ cat qapi-generated/example-qapi-introspect.h
1925 [Uninteresting stuff omitted...]
1927 #ifndef EXAMPLE_QAPI_INTROSPECT_H
1928 #define EXAMPLE_QAPI_INTROSPECT_H
1930 #include "qapi/qmp/qlit.h"
1932 extern const QLitObject example_qmp_schema_qlit;
1934 #endif /* EXAMPLE_QAPI_INTROSPECT_H */
1935 $ cat qapi-generated/example-qapi-introspect.c
1936 [Uninteresting stuff omitted...]
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"), },
1946 QLIT_QDICT(((QLitDictEntry[]) {
1947 { "arg-type", QLIT_QSTR("2"), },
1948 { "meta-type", QLIT_QSTR("event"), },
1949 { "name", QLIT_QSTR("MY_EVENT"), },
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]"), },
1962 { "meta-type", QLIT_QSTR("object"), },
1963 { "name", QLIT_QSTR("0"), },
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"), },
1974 QLIT_QDICT(((QLitDictEntry[]) {
1975 { "default", QLIT_QNULL, },
1976 { "name", QLIT_QSTR("string"), },
1977 { "type", QLIT_QSTR("str"), },
1980 QLIT_QDICT(((QLitDictEntry[]) {
1981 { "default", QLIT_QNULL, },
1982 { "name", QLIT_QSTR("flag"), },
1983 { "type", QLIT_QSTR("bool"), },
1988 { "meta-type", QLIT_QSTR("object"), },
1989 { "name", QLIT_QSTR("1"), },
1993 QLIT_QDICT(((QLitDictEntry[]) {
1994 { "members", QLIT_QLIST(((QLitObject[]) {
1997 { "meta-type", QLIT_QSTR("object"), },
1998 { "name", QLIT_QSTR("2"), },
2001 QLIT_QDICT(((QLitDictEntry[]) {
2002 { "element-type", QLIT_QSTR("1"), },
2003 { "meta-type", QLIT_QSTR("array"), },
2004 { "name", QLIT_QSTR("[1]"), },
2007 QLIT_QDICT(((QLitDictEntry[]) {
2008 { "json-type", QLIT_QSTR("int"), },
2009 { "meta-type", QLIT_QSTR("builtin"), },
2010 { "name", QLIT_QSTR("int"), },
2013 QLIT_QDICT(((QLitDictEntry[]) {
2014 { "json-type", QLIT_QSTR("string"), },
2015 { "meta-type", QLIT_QSTR("builtin"), },
2016 { "name", QLIT_QSTR("str"), },
2019 QLIT_QDICT(((QLitDictEntry[]) {
2020 { "json-type", QLIT_QSTR("boolean"), },
2021 { "meta-type", QLIT_QSTR("builtin"), },
2022 { "name", QLIT_QSTR("bool"), },
2028 [Uninteresting stuff omitted...]