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 qmp-spec.txt for out-of-band execution syntax and semantics.
550 Commands supporting out-of-band execution can still be executed
553 When a command is executed in-band, its handler runs in the main
554 thread with the BQL held.
556 When a command is executed out-of-band, its handler runs in a
557 dedicated monitor I/O thread with the BQL *not* held.
559 An OOB-capable command handler must satisfy the following conditions:
561 - It terminates quickly.
562 - It does not invoke system calls that may block.
563 - It does not access guest RAM that may block when userfaultfd is
564 enabled for postcopy live migration.
565 - It takes only "fast" locks, i.e. all critical sections protected by
566 any lock it takes also satisfy the conditions for OOB command
569 The restrictions on locking limit access to shared state. Such access
570 requires synchronization, but OOB commands can't take the BQL or any
573 When in doubt, do not implement OOB execution support.
575 Member 'allow-preconfig' declares whether the command is available
576 before the machine is built. It defaults to false. For example::
578 { 'enum': 'QMPCapability',
580 { 'command': 'qmp_capabilities',
581 'data': { '*enable': [ 'QMPCapability' ] },
582 'allow-preconfig': true }
584 QMP is available before the machine is built only when QEMU was
585 started with --preconfig.
587 Member 'coroutine' tells the QMP dispatcher whether the command handler
588 is safe to be run in a coroutine. It defaults to false. If it is true,
589 the command handler is called from coroutine context and may yield while
590 waiting for an external event (such as I/O completion) in order to avoid
591 blocking the guest and other background operations.
593 Coroutine safety can be hard to prove, similar to thread safety. Common
596 - The global mutex isn't held across ``qemu_coroutine_yield()``, so
597 operations that used to assume that they execute atomically may have
598 to be more careful to protect against changes in the global state.
600 - Nested event loops (``AIO_WAIT_WHILE()`` etc.) are problematic in
601 coroutine context and can easily lead to deadlocks. They should be
602 replaced by yielding and reentering the coroutine when the condition
605 Since the command handler may assume coroutine context, any callers
606 other than the QMP dispatcher must also call it in coroutine context.
607 In particular, HMP commands calling such a QMP command handler must be
608 marked ``.coroutine = true`` in hmp-commands.hx.
610 It is an error to specify both ``'coroutine': true`` and ``'allow-oob': true``
611 for a command. We don't currently have a use case for both together and
612 without a use case, it's not entirely clear what the semantics should
615 The optional 'if' member specifies a conditional. See `Configuring
616 the schema`_ below for more on this.
618 The optional 'features' member specifies features. See Features_
619 below for more on this.
627 EVENT = { 'event': STRING,
629 '*data': ( MEMBERS | STRING ),
635 '*features': FEATURES }
637 Member 'event' names the event. This is the event name used in the
638 Client JSON Protocol.
640 Member 'data' defines the event-specific data. It defaults to an
641 empty MEMBERS object.
643 If 'data' is a MEMBERS object, then MEMBERS defines event-specific
644 data just like a struct type's 'data' defines struct type members.
646 If 'data' is a STRING, then STRING names a complex type whose members
647 are the event-specific data. A union type requires ``'boxed': true``.
649 An example event is::
651 { 'event': 'EVENT_C',
652 'data': { '*a': 'int', 'b': 'str' } }
654 Resulting in this JSON object::
656 { "event": "EVENT_C",
657 "data": { "b": "test string" },
658 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
660 The generator emits a function to send the event. When member 'boxed'
661 is absent, it takes event-specific data one by one, in QAPI schema
662 order. Else it takes them wrapped in the C struct generated for the
663 complex type. See section `Code generated for events`_ for examples.
665 The optional 'if' member specifies a conditional. See `Configuring
666 the schema`_ below for more on this.
668 The optional 'features' member specifies features. See Features_
669 below for more on this.
679 FEATURES = [ FEATURE, ... ]
681 | { 'name': STRING, '*if': COND }
683 Sometimes, the behaviour of QEMU changes compatibly, but without a
684 change in the QMP syntax (usually by allowing values or operations
685 that previously resulted in an error). QMP clients may still need to
686 know whether the extension is available.
688 For this purpose, a list of features can be specified for a command or
689 struct type. Each list member can either be ``{ 'name': STRING, '*if':
690 COND }``, or STRING, which is shorthand for ``{ 'name': STRING }``.
692 The optional 'if' member specifies a conditional. See `Configuring
693 the schema`_ below for more on this.
697 { 'struct': 'TestType',
698 'data': { 'number': 'int' },
699 'features': [ 'allow-negative-numbers' ] }
701 The feature strings are exposed to clients in introspection, as
702 explained in section `Client JSON Protocol introspection`_.
704 Intended use is to have each feature string signal that this build of
705 QEMU shows a certain behaviour.
711 Feature "deprecated" marks a command, event, enum value, or struct
712 member as deprecated. It is not supported elsewhere so far.
713 Interfaces so marked may be withdrawn in future releases in accordance
714 with QEMU's deprecation policy.
716 Feature "unstable" marks a command, event, enum value, or struct
717 member as unstable. It is not supported elsewhere so far. Interfaces
718 so marked may be withdrawn or changed incompatibly in future releases.
721 Naming rules and reserved names
722 -------------------------------
724 All names must begin with a letter, and contain only ASCII letters,
725 digits, hyphen, and underscore. There are two exceptions: enum values
726 may start with a digit, and names that are downstream extensions (see
727 section `Downstream extensions`_) start with underscore.
729 Names beginning with ``q_`` are reserved for the generator, which uses
730 them for munging QMP names that resemble C keywords or other
731 problematic strings. For example, a member named ``default`` in qapi
732 becomes ``q_default`` in the generated C code.
734 Types, commands, and events share a common namespace. Therefore,
735 generally speaking, type definitions should always use CamelCase for
736 user-defined type names, while built-in types are lowercase.
738 Type names ending with ``Kind`` or ``List`` are reserved for the
739 generator, which uses them for implicit union enums and array types,
742 Command names, and member names within a type, should be all lower
743 case with words separated by a hyphen. However, some existing older
744 commands and complex types use underscore; when extending them,
745 consistency is preferred over blindly avoiding underscore.
747 Event names should be ALL_CAPS with words separated by underscore.
749 Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved
750 for the generator, which uses them for unions and for tracking
753 Names beginning with ``x-`` used to signify "experimental". This
754 convention has been replaced by special feature "unstable".
756 Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
757 you violate naming rules. Use for new code is strongly discouraged. See
758 `Pragma directives`_ for details.
761 Downstream extensions
762 ---------------------
764 QAPI schema names that are externally visible, say in the Client JSON
765 Protocol, need to be managed with care. Names starting with a
766 downstream prefix of the form __RFQDN_ are reserved for the downstream
767 who controls the valid, reverse fully qualified domain name RFQDN.
768 RFQDN may only contain ASCII letters, digits, hyphen and period.
770 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
771 downstream command ``__com.redhat_drive-mirror``.
774 Configuring the schema
775 ----------------------
780 | { 'all: [ COND, ... ] }
781 | { 'any: [ COND, ... ] }
784 All definitions take an optional 'if' member. Its value must be a
785 string, or an object with a single member 'all', 'any' or 'not'.
787 The C code generated for the definition will then be guarded by an #if
788 preprocessing directive with an operand generated from that condition:
790 * STRING will generate defined(STRING)
791 * { 'all': [COND, ...] } will generate (COND && ...)
792 * { 'any': [COND, ...] } will generate (COND || ...)
793 * { 'not': COND } will generate !COND
795 Example: a conditional struct ::
797 { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
798 'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } }
800 gets its generated code guarded like this::
802 #if defined(CONFIG_FOO) && defined(HAVE_BAR)
803 ... generated code ...
804 #endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */
806 Individual members of complex types, commands arguments, and
807 event-specific data can also be made conditional. This requires the
808 longhand form of MEMBER.
810 Example: a struct type with unconditional member 'foo' and conditional
813 { 'struct': 'IfStruct',
814 'data': { 'foo': 'int',
815 'bar': { 'type': 'int', 'if': 'IFCOND'} } }
817 A union's discriminator may not be conditional.
819 Likewise, individual enumeration values be conditional. This requires
820 the longhand form of ENUM-VALUE_.
822 Example: an enum type with unconditional value 'foo' and conditional
827 { 'name' : 'bar', 'if': 'IFCOND' } ] }
829 Likewise, features can be conditional. This requires the longhand
832 Example: a struct with conditional feature 'allow-negative-numbers' ::
834 { 'struct': 'TestType',
835 'data': { 'number': 'int' },
836 'features': [ { 'name': 'allow-negative-numbers',
839 Please note that you are responsible to ensure that the C code will
840 compile with an arbitrary combination of conditions, since the
841 generator is unable to check it at this point.
843 The conditions apply to introspection as well, i.e. introspection
844 shows a conditional entity only when the condition is satisfied in
845 this particular build.
848 Documentation comments
849 ----------------------
851 A multi-line comment that starts and ends with a ``##`` line is a
852 documentation comment.
854 If the documentation comment starts like ::
859 it documents the definition of SYMBOL, else it's free-form
862 See below for more on `Definition documentation`_.
864 Free-form documentation may be used to provide additional text and
868 Headings and subheadings
869 ~~~~~~~~~~~~~~~~~~~~~~~~
871 A free-form documentation comment containing a line which starts with
872 some ``=`` symbols and then a space defines a section heading::
875 # = This is a top level heading
877 # This is a free-form comment which will go under the
882 # == This is a second level heading
885 A heading line must be the first line of the documentation
888 Section headings must always be correctly nested, so you can only
889 define a third-level heading inside a second-level heading, and so on.
895 Documentation comments can use most rST markup. In particular,
896 a ``::`` literal block can be used for examples::
900 # Text of the example, may span
903 ``*`` starts an itemized list::
905 # * First item, may span
909 You can also use ``-`` instead of ``*``.
911 A decimal number followed by ``.`` starts a numbered list::
913 # 1. First item, may span
917 The actual number doesn't matter.
919 Lists of either kind must be preceded and followed by a blank line.
920 If a list item's text spans multiple lines, then the second and
921 subsequent lines must be correctly indented to line up with the
922 first character of the first line.
924 The usual ****strong****, *\*emphasized\** and ````literal```` markup
925 should be used. If you need a single literal ``*``, you will need to
926 backslash-escape it. As an extension beyond the usual rST syntax, you
927 can also use ``@foo`` to reference a name in the schema; this is rendered
928 the same way as ````foo````.
933 # Some text foo with **bold** and *emphasis*
947 Definition documentation
948 ~~~~~~~~~~~~~~~~~~~~~~~~
950 Definition documentation, if present, must immediately precede the
951 definition it documents.
953 When documentation is required (see pragma_ 'doc-required'), every
954 definition must have documentation.
956 Definition documentation starts with a line naming the definition,
957 followed by an optional overview, a description of each argument (for
958 commands and events), member (for structs and unions), branch (for
959 alternates), or value (for enums), a description of each feature (if
960 any), and finally optional tagged sections.
962 The description of an argument or feature 'name' starts with
963 '\@name:'. The description text can start on the line following the
964 '\@name:', in which case it must not be indented at all. It can also
965 start on the same line as the '\@name:'. In this case if it spans
966 multiple lines then second and subsequent lines must be indented to
967 line up with the first character of the first line of the
971 # This is a two line description
972 # in the first style.
974 # @argtwo: This is a two line description
975 # in the second style.
977 The number of spaces between the ':' and the text is not significant.
979 .. admonition:: FIXME
981 The parser accepts these things in almost any order.
983 .. admonition:: FIXME
985 union branches should be described, too.
987 Extensions added after the definition was first released carry a
988 '(since x.y.z)' comment.
990 The feature descriptions must be preceded by a line "Features:", like
994 # @feature: Description text
996 A tagged section starts with one of the following words:
997 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
998 The section ends with the start of a new section.
1000 The text of a section can start on a new line, in
1001 which case it must not be indented at all. It can also start
1002 on the same line as the 'Note:', 'Returns:', etc tag. In this
1003 case if it spans multiple lines then second and subsequent
1004 lines must be indented to match the first, in the same way as
1005 multiline argument descriptions.
1007 A 'Since: x.y.z' tagged section lists the release that introduced the
1010 An 'Example' or 'Examples' section is automatically rendered
1011 entirely as literal fixed-width text. In other sections,
1012 the text is formatted, and rST markup can be used.
1019 # Statistics of a virtual block device or a block backing device.
1021 # @device: If the stats are for a virtual block device, the name
1022 # corresponding to the virtual block device.
1024 # @node-name: The node name of the device. (since 2.3)
1026 # ... more members ...
1030 { 'struct': 'BlockStats',
1031 'data': {'*device': 'str', '*node-name': 'str',
1032 ... more members ... } }
1035 # @query-blockstats:
1037 # Query the @BlockStats for all virtual block devices.
1039 # @query-nodes: If true, the command will query all the
1040 # block nodes ... explain, explain ... (since 2.3)
1042 # Returns: A list of @BlockStats for each virtual block devices.
1048 # -> { "execute": "query-blockstats" }
1050 # ... lots of output ...
1054 { 'command': 'query-blockstats',
1055 'data': { '*query-nodes': 'bool' },
1056 'returns': ['BlockStats'] }
1059 Client JSON Protocol introspection
1060 ==================================
1062 Clients of a Client JSON Protocol commonly need to figure out what
1063 exactly the server (QEMU) supports.
1065 For this purpose, QMP provides introspection via command
1066 query-qmp-schema. QGA currently doesn't support introspection.
1068 While Client JSON Protocol wire compatibility should be maintained
1069 between qemu versions, we cannot make the same guarantees for
1070 introspection stability. For example, one version of qemu may provide
1071 a non-variant optional member of a struct, and a later version rework
1072 the member to instead be non-optional and associated with a variant.
1073 Likewise, one version of qemu may list a member with open-ended type
1074 'str', and a later version could convert it to a finite set of strings
1075 via an enum type; or a member may be converted from a specific type to
1076 an alternate that represents a choice between the original type and
1079 query-qmp-schema returns a JSON array of SchemaInfo objects. These
1080 objects together describe the wire ABI, as defined in the QAPI schema.
1081 There is no specified order to the SchemaInfo objects returned; a
1082 client must search for a particular name throughout the entire array
1083 to learn more about that name, but is at least guaranteed that there
1084 will be no collisions between type, command, and event names.
1086 However, the SchemaInfo can't reflect all the rules and restrictions
1087 that apply to QMP. It's interface introspection (figuring out what's
1088 there), not interface specification. The specification is in the QAPI
1089 schema. To understand how QMP is to be used, you need to study the
1092 Like any other command, query-qmp-schema is itself defined in the QAPI
1093 schema, along with the SchemaInfo type. This text attempts to give an
1094 overview how things work. For details you need to consult the QAPI
1097 SchemaInfo objects have common members "name", "meta-type",
1098 "features", and additional variant members depending on the value of
1101 Each SchemaInfo object describes a wire ABI entity of a certain
1102 meta-type: a command, event or one of several kinds of type.
1104 SchemaInfo for commands and events have the same name as in the QAPI
1107 Command and event names are part of the wire ABI, but type names are
1108 not. Therefore, the SchemaInfo for types have auto-generated
1109 meaningless names. For readability, the examples in this section use
1110 meaningful type names instead.
1112 Optional member "features" exposes the entity's feature strings as a
1113 JSON array of strings.
1115 To examine a type, start with a command or event using it, then follow
1118 QAPI schema definitions not reachable that way are omitted.
1120 The SchemaInfo for a command has meta-type "command", and variant
1121 members "arg-type", "ret-type" and "allow-oob". On the wire, the
1122 "arguments" member of a client's "execute" command must conform to the
1123 object type named by "arg-type". The "return" member that the server
1124 passes in a success response conforms to the type named by "ret-type".
1125 When "allow-oob" is true, it means the command supports out-of-band
1126 execution. It defaults to false.
1128 If the command takes no arguments, "arg-type" names an object type
1129 without members. Likewise, if the command returns nothing, "ret-type"
1130 names an object type without members.
1132 Example: the SchemaInfo for command query-qmp-schema ::
1134 { "name": "query-qmp-schema", "meta-type": "command",
1135 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1137 Type "q_empty" is an automatic object type without members, and type
1138 "SchemaInfoList" is the array of SchemaInfo type.
1140 The SchemaInfo for an event has meta-type "event", and variant member
1141 "arg-type". On the wire, a "data" member that the server passes in an
1142 event conforms to the object type named by "arg-type".
1144 If the event carries no additional information, "arg-type" names an
1145 object type without members. The event may not have a data member on
1148 Each command or event defined with 'data' as MEMBERS object in the
1149 QAPI schema implicitly defines an object type.
1151 Example: the SchemaInfo for EVENT_C from section Events_ ::
1153 { "name": "EVENT_C", "meta-type": "event",
1154 "arg-type": "q_obj-EVENT_C-arg" }
1156 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1157 the two members from the event's definition.
1159 The SchemaInfo for struct and union types has meta-type "object".
1161 The SchemaInfo for a struct type has variant member "members".
1163 The SchemaInfo for a union type additionally has variant members "tag"
1166 "members" is a JSON array describing the object's common members, if
1167 any. Each element is a JSON object with members "name" (the member's
1168 name), "type" (the name of its type), "features" (a JSON array of
1169 feature strings), and "default". The latter two are optional. The
1170 member is optional if "default" is present. Currently, "default" can
1171 only have value null. Other values are reserved for future
1172 extensions. The "members" array is in no particular order; clients
1173 must search the entire object when learning whether a particular
1174 member is supported.
1176 Example: the SchemaInfo for MyType from section `Struct types`_ ::
1178 { "name": "MyType", "meta-type": "object",
1180 { "name": "member1", "type": "str" },
1181 { "name": "member2", "type": "int" },
1182 { "name": "member3", "type": "str", "default": null } ] }
1184 "features" exposes the command's feature strings as a JSON array of
1187 Example: the SchemaInfo for TestType from section Features_::
1189 { "name": "TestType", "meta-type": "object",
1191 { "name": "number", "type": "int" } ],
1192 "features": ["allow-negative-numbers"] }
1194 "tag" is the name of the common member serving as type tag.
1195 "variants" is a JSON array describing the object's variant members.
1196 Each element is a JSON object with members "case" (the value of type
1197 tag this element applies to) and "type" (the name of an object type
1198 that provides the variant members for this type tag value). The
1199 "variants" array is in no particular order, and is not guaranteed to
1200 list cases in the same order as the corresponding "tag" enum type.
1202 Example: the SchemaInfo for union BlockdevOptions from section
1205 { "name": "BlockdevOptions", "meta-type": "object",
1207 { "name": "driver", "type": "BlockdevDriver" },
1208 { "name": "read-only", "type": "bool", "default": null } ],
1211 { "case": "file", "type": "BlockdevOptionsFile" },
1212 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
1214 Note that base types are "flattened": its members are included in the
1217 The SchemaInfo for an alternate type has meta-type "alternate", and
1218 variant member "members". "members" is a JSON array. Each element is
1219 a JSON object with member "type", which names a type. Values of the
1220 alternate type conform to exactly one of its member types. There is
1221 no guarantee on the order in which "members" will be listed.
1223 Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ ::
1225 { "name": "BlockdevRef", "meta-type": "alternate",
1227 { "type": "BlockdevOptions" },
1228 { "type": "str" } ] }
1230 The SchemaInfo for an array type has meta-type "array", and variant
1231 member "element-type", which names the array's element type. Array
1232 types are implicitly defined. For convenience, the array's name may
1233 resemble the element type; however, clients should examine member
1234 "element-type" instead of making assumptions based on parsing member
1237 Example: the SchemaInfo for ['str'] ::
1239 { "name": "[str]", "meta-type": "array",
1240 "element-type": "str" }
1242 The SchemaInfo for an enumeration type has meta-type "enum" and
1243 variant member "members".
1245 "members" is a JSON array describing the enumeration values. Each
1246 element is a JSON object with member "name" (the member's name), and
1247 optionally "features" (a JSON array of feature strings). The
1248 "members" array is in no particular order; clients must search the
1249 entire array when learning whether a particular value is supported.
1251 Example: the SchemaInfo for MyEnum from section `Enumeration types`_ ::
1253 { "name": "MyEnum", "meta-type": "enum",
1255 { "name": "value1" },
1256 { "name": "value2" },
1257 { "name": "value3" }
1260 The SchemaInfo for a built-in type has the same name as the type in
1261 the QAPI schema (see section `Built-in Types`_), with one exception
1262 detailed below. It has variant member "json-type" that shows how
1263 values of this type are encoded on the wire.
1265 Example: the SchemaInfo for str ::
1267 { "name": "str", "meta-type": "builtin", "json-type": "string" }
1269 The QAPI schema supports a number of integer types that only differ in
1270 how they map to C. They are identical as far as SchemaInfo is
1271 concerned. Therefore, they get all mapped to a single type "int" in
1274 As explained above, type names are not part of the wire ABI. Not even
1275 the names of built-in types. Clients should examine member
1276 "json-type" instead of hard-coding names of built-in types.
1279 Compatibility considerations
1280 ============================
1282 Maintaining backward compatibility at the Client JSON Protocol level
1283 while evolving the schema requires some care. This section is about
1284 syntactic compatibility, which is necessary, but not sufficient, for
1285 actual compatibility.
1287 Clients send commands with argument data, and receive command
1288 responses with return data and events with event data.
1290 Adding opt-in functionality to the send direction is backwards
1291 compatible: adding commands, optional arguments, enumeration values,
1292 union and alternate branches; turning an argument type into an
1293 alternate of that type; making mandatory arguments optional. Clients
1294 oblivious of the new functionality continue to work.
1296 Incompatible changes include removing commands, command arguments,
1297 enumeration values, union and alternate branches, adding mandatory
1298 command arguments, and making optional arguments mandatory.
1300 The specified behavior of an absent optional argument should remain
1301 the same. With proper documentation, this policy still allows some
1302 flexibility; for example, when an optional 'buffer-size' argument is
1303 specified to default to a sensible buffer size, the actual default
1304 value can still be changed. The specified default behavior is not the
1305 exact size of the buffer, only that the default size is sensible.
1307 Adding functionality to the receive direction is generally backwards
1308 compatible: adding events, adding return and event data members.
1309 Clients are expected to ignore the ones they don't know.
1311 Removing "unreachable" stuff like events that can't be triggered
1312 anymore, optional return or event data members that can't be sent
1313 anymore, and return or event data member (enumeration) values that
1314 can't be sent anymore makes no difference to clients, except for
1315 introspection. The latter can conceivably confuse clients, so tread
1318 Incompatible changes include removing return and event data members.
1320 Any change to a command definition's 'data' or one of the types used
1321 there (recursively) needs to consider send direction compatibility.
1323 Any change to a command definition's 'return', an event definition's
1324 'data', or one of the types used there (recursively) needs to consider
1325 receive direction compatibility.
1327 Any change to types used in both contexts need to consider both.
1329 Enumeration type values and complex and alternate type members may be
1330 reordered freely. For enumerations and alternate types, this doesn't
1331 affect the wire encoding. For complex types, this might make the
1332 implementation emit JSON object members in a different order, which
1333 the Client JSON Protocol permits.
1335 Since type names are not visible in the Client JSON Protocol, types
1336 may be freely renamed. Even certain refactorings are invisible, such
1337 as splitting members from one type into a common base type.
1343 The QAPI code generator qapi-gen.py generates code and documentation
1344 from the schema. Together with the core QAPI libraries, this code
1345 provides everything required to take JSON commands read in by a Client
1346 JSON Protocol server, unmarshal the arguments into the underlying C
1347 types, call into the corresponding C function, map the response back
1348 to a Client JSON Protocol response to be returned to the user, and
1349 introspect the commands.
1351 As an example, we'll use the following schema, which describes a
1352 single complex user-defined type, along with command which takes a
1353 list of that type as a parameter, and returns a single element of that
1354 type. The user is responsible for writing the implementation of
1355 qmp_my_command(); everything else is produced by the generator. ::
1357 $ cat example-schema.json
1358 { 'struct': 'UserDefOne',
1359 'data': { 'integer': 'int', '*string': 'str' } }
1361 { 'command': 'my-command',
1362 'data': { 'arg1': ['UserDefOne'] },
1363 'returns': 'UserDefOne' }
1365 { 'event': 'MY_EVENT' }
1367 We run qapi-gen.py like this::
1369 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1370 --prefix="example-" example-schema.json
1372 For a more thorough look at generated code, the testsuite includes
1373 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1374 what the generator will accept, and compiles the resulting C code as
1375 part of 'make check-unit'.
1378 Code generated for QAPI types
1379 -----------------------------
1381 The following files are created:
1383 ``$(prefix)qapi-types.h``
1384 C types corresponding to types defined in the schema
1386 ``$(prefix)qapi-types.c``
1387 Cleanup functions for the above C types
1389 The $(prefix) is an optional parameter used as a namespace to keep the
1390 generated code from one schema/code-generation separated from others so code
1391 can be generated/used from multiple schemas without clobbering previously
1396 $ cat qapi-generated/example-qapi-types.h
1397 [Uninteresting stuff omitted...]
1399 #ifndef EXAMPLE_QAPI_TYPES_H
1400 #define EXAMPLE_QAPI_TYPES_H
1402 #include "qapi/qapi-builtin-types.h"
1404 typedef struct UserDefOne UserDefOne;
1406 typedef struct UserDefOneList UserDefOneList;
1408 typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1416 void qapi_free_UserDefOne(UserDefOne *obj);
1417 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne)
1419 struct UserDefOneList {
1420 UserDefOneList *next;
1424 void qapi_free_UserDefOneList(UserDefOneList *obj);
1425 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList)
1427 struct q_obj_my_command_arg {
1428 UserDefOneList *arg1;
1431 #endif /* EXAMPLE_QAPI_TYPES_H */
1432 $ cat qapi-generated/example-qapi-types.c
1433 [Uninteresting stuff omitted...]
1435 void qapi_free_UserDefOne(UserDefOne *obj)
1443 v = qapi_dealloc_visitor_new();
1444 visit_type_UserDefOne(v, NULL, &obj, NULL);
1448 void qapi_free_UserDefOneList(UserDefOneList *obj)
1456 v = qapi_dealloc_visitor_new();
1457 visit_type_UserDefOneList(v, NULL, &obj, NULL);
1461 [Uninteresting stuff omitted...]
1463 For a modular QAPI schema (see section `Include directives`_), code for
1464 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1466 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1467 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1469 If qapi-gen.py is run with option --builtins, additional files are
1472 ``qapi-builtin-types.h``
1473 C types corresponding to built-in types
1475 ``qapi-builtin-types.c``
1476 Cleanup functions for the above C types
1479 Code generated for visiting QAPI types
1480 --------------------------------------
1482 These are the visitor functions used to walk through and convert
1483 between a native QAPI C data structure and some other format (such as
1484 QObject); the generated functions are named visit_type_FOO() and
1485 visit_type_FOO_members().
1487 The following files are generated:
1489 ``$(prefix)qapi-visit.c``
1490 Visitor function for a particular C type, used to automagically
1491 convert QObjects into the corresponding C type and vice-versa, as
1492 well as for deallocating memory for an existing C type
1494 ``$(prefix)qapi-visit.h``
1495 Declarations for previously mentioned visitor functions
1499 $ cat qapi-generated/example-qapi-visit.h
1500 [Uninteresting stuff omitted...]
1502 #ifndef EXAMPLE_QAPI_VISIT_H
1503 #define EXAMPLE_QAPI_VISIT_H
1505 #include "qapi/qapi-builtin-visit.h"
1506 #include "example-qapi-types.h"
1509 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1511 bool visit_type_UserDefOne(Visitor *v, const char *name,
1512 UserDefOne **obj, Error **errp);
1514 bool visit_type_UserDefOneList(Visitor *v, const char *name,
1515 UserDefOneList **obj, Error **errp);
1517 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1519 #endif /* EXAMPLE_QAPI_VISIT_H */
1520 $ cat qapi-generated/example-qapi-visit.c
1521 [Uninteresting stuff omitted...]
1523 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1525 if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1528 if (visit_optional(v, "string", &obj->has_string)) {
1529 if (!visit_type_str(v, "string", &obj->string, errp)) {
1536 bool visit_type_UserDefOne(Visitor *v, const char *name,
1537 UserDefOne **obj, Error **errp)
1541 if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) {
1546 assert(visit_is_dealloc(v));
1550 if (!visit_type_UserDefOne_members(v, *obj, errp)) {
1553 ok = visit_check_struct(v, errp);
1555 visit_end_struct(v, (void **)obj);
1556 if (!ok && visit_is_input(v)) {
1557 qapi_free_UserDefOne(*obj);
1563 bool visit_type_UserDefOneList(Visitor *v, const char *name,
1564 UserDefOneList **obj, Error **errp)
1567 UserDefOneList *tail;
1568 size_t size = sizeof(**obj);
1570 if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) {
1574 for (tail = *obj; tail;
1575 tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1576 if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
1581 ok = visit_check_list(v, errp);
1583 visit_end_list(v, (void **)obj);
1584 if (!ok && visit_is_input(v)) {
1585 qapi_free_UserDefOneList(*obj);
1591 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1593 if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1599 [Uninteresting stuff omitted...]
1601 For a modular QAPI schema (see section `Include directives`_), code for
1602 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1604 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1605 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1607 If qapi-gen.py is run with option --builtins, additional files are
1610 ``qapi-builtin-visit.h``
1611 Visitor functions for built-in types
1613 ``qapi-builtin-visit.c``
1614 Declarations for these visitor functions
1617 Code generated for commands
1618 ---------------------------
1620 These are the marshaling/dispatch functions for the commands defined
1621 in the schema. The generated code provides qmp_marshal_COMMAND(), and
1622 declares qmp_COMMAND() that the user must implement.
1624 The following files are generated:
1626 ``$(prefix)qapi-commands.c``
1627 Command marshal/dispatch functions for each QMP command defined in
1630 ``$(prefix)qapi-commands.h``
1631 Function prototypes for the QMP commands specified in the schema
1633 ``$(prefix)qapi-commands.trace-events``
1634 Trace event declarations, see :ref:`tracing`.
1636 ``$(prefix)qapi-init-commands.h``
1637 Command initialization prototype
1639 ``$(prefix)qapi-init-commands.c``
1640 Command initialization code
1644 $ cat qapi-generated/example-qapi-commands.h
1645 [Uninteresting stuff omitted...]
1647 #ifndef EXAMPLE_QAPI_COMMANDS_H
1648 #define EXAMPLE_QAPI_COMMANDS_H
1650 #include "example-qapi-types.h"
1652 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1653 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1655 #endif /* EXAMPLE_QAPI_COMMANDS_H */
1657 $ cat qapi-generated/example-qapi-commands.trace-events
1658 # AUTOMATICALLY GENERATED, DO NOT MODIFY
1660 qmp_enter_my_command(const char *json) "%s"
1661 qmp_exit_my_command(const char *result, bool succeeded) "%s %d"
1663 $ cat qapi-generated/example-qapi-commands.c
1664 [Uninteresting stuff omitted...]
1667 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in,
1668 QObject **ret_out, Error **errp)
1672 v = qobject_output_visitor_new_qmp(ret_out);
1673 if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) {
1674 visit_complete(v, ret_out);
1677 v = qapi_dealloc_visitor_new();
1678 visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1682 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1688 q_obj_my_command_arg arg = {0};
1690 v = qobject_input_visitor_new_qmp(QOBJECT(args));
1691 if (!visit_start_struct(v, NULL, NULL, 0, errp)) {
1694 if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) {
1695 ok = visit_check_struct(v, errp);
1697 visit_end_struct(v, NULL);
1702 if (trace_event_get_state_backends(TRACE_QMP_ENTER_MY_COMMAND)) {
1703 g_autoptr(GString) req_json = qobject_to_json(QOBJECT(args));
1705 trace_qmp_enter_my_command(req_json->str);
1708 retval = qmp_my_command(arg.arg1, &err);
1710 trace_qmp_exit_my_command(error_get_pretty(err), false);
1711 error_propagate(errp, err);
1715 qmp_marshal_output_UserDefOne(retval, ret, errp);
1717 if (trace_event_get_state_backends(TRACE_QMP_EXIT_MY_COMMAND)) {
1718 g_autoptr(GString) ret_json = qobject_to_json(*ret);
1720 trace_qmp_exit_my_command(ret_json->str, true);
1725 v = qapi_dealloc_visitor_new();
1726 visit_start_struct(v, NULL, NULL, 0, NULL);
1727 visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1728 visit_end_struct(v, NULL);
1732 [Uninteresting stuff omitted...]
1733 $ cat qapi-generated/example-qapi-init-commands.h
1734 [Uninteresting stuff omitted...]
1735 #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H
1736 #define EXAMPLE_QAPI_INIT_COMMANDS_H
1738 #include "qapi/qmp/dispatch.h"
1740 void example_qmp_init_marshal(QmpCommandList *cmds);
1742 #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */
1743 $ cat qapi-generated/example-qapi-init-commands.c
1744 [Uninteresting stuff omitted...]
1745 void example_qmp_init_marshal(QmpCommandList *cmds)
1749 qmp_register_command(cmds, "my-command",
1750 qmp_marshal_my_command, QCO_NO_OPTIONS);
1752 [Uninteresting stuff omitted...]
1754 For a modular QAPI schema (see section `Include directives`_), code for
1755 each sub-module SUBDIR/SUBMODULE.json is actually generated into::
1757 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1758 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1761 Code generated for events
1762 -------------------------
1764 This is the code related to events defined in the schema, providing
1765 qapi_event_send_EVENT().
1767 The following files are created:
1769 ``$(prefix)qapi-events.h``
1770 Function prototypes for each event type
1772 ``$(prefix)qapi-events.c``
1773 Implementation of functions to send an event
1775 ``$(prefix)qapi-emit-events.h``
1776 Enumeration of all event names, and common event code declarations
1778 ``$(prefix)qapi-emit-events.c``
1779 Common event code definitions
1783 $ cat qapi-generated/example-qapi-events.h
1784 [Uninteresting stuff omitted...]
1786 #ifndef EXAMPLE_QAPI_EVENTS_H
1787 #define EXAMPLE_QAPI_EVENTS_H
1789 #include "qapi/util.h"
1790 #include "example-qapi-types.h"
1792 void qapi_event_send_my_event(void);
1794 #endif /* EXAMPLE_QAPI_EVENTS_H */
1795 $ cat qapi-generated/example-qapi-events.c
1796 [Uninteresting stuff omitted...]
1798 void qapi_event_send_my_event(void)
1802 qmp = qmp_event_build_dict("MY_EVENT");
1804 example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
1809 [Uninteresting stuff omitted...]
1810 $ cat qapi-generated/example-qapi-emit-events.h
1811 [Uninteresting stuff omitted...]
1813 #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
1814 #define EXAMPLE_QAPI_EMIT_EVENTS_H
1816 #include "qapi/util.h"
1818 typedef enum example_QAPIEvent {
1819 EXAMPLE_QAPI_EVENT_MY_EVENT,
1820 EXAMPLE_QAPI_EVENT__MAX,
1821 } example_QAPIEvent;
1823 #define example_QAPIEvent_str(val) \
1824 qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
1826 extern const QEnumLookup example_QAPIEvent_lookup;
1828 void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
1830 #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
1831 $ cat qapi-generated/example-qapi-emit-events.c
1832 [Uninteresting stuff omitted...]
1834 const QEnumLookup example_QAPIEvent_lookup = {
1835 .array = (const char *const[]) {
1836 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1838 .size = EXAMPLE_QAPI_EVENT__MAX
1841 [Uninteresting stuff omitted...]
1843 For a modular QAPI schema (see section `Include directives`_), code for
1844 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1846 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1847 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1850 Code generated for introspection
1851 --------------------------------
1853 The following files are created:
1855 ``$(prefix)qapi-introspect.c``
1856 Defines a string holding a JSON description of the schema
1858 ``$(prefix)qapi-introspect.h``
1859 Declares the above string
1863 $ cat qapi-generated/example-qapi-introspect.h
1864 [Uninteresting stuff omitted...]
1866 #ifndef EXAMPLE_QAPI_INTROSPECT_H
1867 #define EXAMPLE_QAPI_INTROSPECT_H
1869 #include "qapi/qmp/qlit.h"
1871 extern const QLitObject example_qmp_schema_qlit;
1873 #endif /* EXAMPLE_QAPI_INTROSPECT_H */
1874 $ cat qapi-generated/example-qapi-introspect.c
1875 [Uninteresting stuff omitted...]
1877 const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
1878 QLIT_QDICT(((QLitDictEntry[]) {
1879 { "arg-type", QLIT_QSTR("0"), },
1880 { "meta-type", QLIT_QSTR("command"), },
1881 { "name", QLIT_QSTR("my-command"), },
1882 { "ret-type", QLIT_QSTR("1"), },
1885 QLIT_QDICT(((QLitDictEntry[]) {
1886 { "arg-type", QLIT_QSTR("2"), },
1887 { "meta-type", QLIT_QSTR("event"), },
1888 { "name", QLIT_QSTR("MY_EVENT"), },
1891 /* "0" = q_obj_my-command-arg */
1892 QLIT_QDICT(((QLitDictEntry[]) {
1893 { "members", QLIT_QLIST(((QLitObject[]) {
1894 QLIT_QDICT(((QLitDictEntry[]) {
1895 { "name", QLIT_QSTR("arg1"), },
1896 { "type", QLIT_QSTR("[1]"), },
1901 { "meta-type", QLIT_QSTR("object"), },
1902 { "name", QLIT_QSTR("0"), },
1905 /* "1" = UserDefOne */
1906 QLIT_QDICT(((QLitDictEntry[]) {
1907 { "members", QLIT_QLIST(((QLitObject[]) {
1908 QLIT_QDICT(((QLitDictEntry[]) {
1909 { "name", QLIT_QSTR("integer"), },
1910 { "type", QLIT_QSTR("int"), },
1913 QLIT_QDICT(((QLitDictEntry[]) {
1914 { "default", QLIT_QNULL, },
1915 { "name", QLIT_QSTR("string"), },
1916 { "type", QLIT_QSTR("str"), },
1921 { "meta-type", QLIT_QSTR("object"), },
1922 { "name", QLIT_QSTR("1"), },
1926 QLIT_QDICT(((QLitDictEntry[]) {
1927 { "members", QLIT_QLIST(((QLitObject[]) {
1930 { "meta-type", QLIT_QSTR("object"), },
1931 { "name", QLIT_QSTR("2"), },
1934 QLIT_QDICT(((QLitDictEntry[]) {
1935 { "element-type", QLIT_QSTR("1"), },
1936 { "meta-type", QLIT_QSTR("array"), },
1937 { "name", QLIT_QSTR("[1]"), },
1940 QLIT_QDICT(((QLitDictEntry[]) {
1941 { "json-type", QLIT_QSTR("int"), },
1942 { "meta-type", QLIT_QSTR("builtin"), },
1943 { "name", QLIT_QSTR("int"), },
1946 QLIT_QDICT(((QLitDictEntry[]) {
1947 { "json-type", QLIT_QSTR("string"), },
1948 { "meta-type", QLIT_QSTR("builtin"), },
1949 { "name", QLIT_QSTR("str"), },
1955 [Uninteresting stuff omitted...]