1 = How to use the QAPI code generator =
3 Copyright IBM Corp. 2011
4 Copyright (C) 2012-2016 Red Hat, Inc.
6 This work is licensed under the terms of the GNU GPL, version 2 or
7 later. See the COPYING file in the top-level directory.
11 QAPI is a native C API within QEMU which provides management-level
12 functionality to internal and external users. For external
13 users/processes, this interface is made available by a JSON-based wire
14 format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
15 well as the QEMU Guest Agent (QGA) for communicating with the guest.
16 The remainder of this document uses "Client JSON Protocol" when
17 referring to the wire contents of a QMP or QGA connection.
19 To map between Client JSON Protocol interfaces and the native C API,
20 we generate C code from a QAPI schema. This document describes the
21 QAPI schema language, and how it gets mapped to the Client JSON
22 Protocol and to C. It additionally provides guidance on maintaining
23 Client JSON Protocol compatibility.
26 == The QAPI schema language ==
28 The QAPI schema defines the Client JSON Protocol's commands and
29 events, as well as types used by them. Forward references are
32 It is permissible for the schema to contain additional types not used
33 by any commands or events, for the side effect of generated C code
36 There are several kinds of types: simple types (a number of built-in
37 types, such as 'int' and 'str'; as well as enumerations), arrays,
38 complex types (structs and two flavors of unions), and alternate types
39 (a choice between other types).
44 Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt).
47 * Comments: start with a hash character (#) that is not part of a
48 string, and extend to the end of the line.
50 * Strings are enclosed in 'single quotes', not "double quotes".
52 * Strings are restricted to printable ASCII, and escape sequences to
55 * Numbers and null are not supported.
57 A second layer of syntax defines the sequences of JSON texts that are
58 a correctly structured QAPI schema. We provide a grammar for this
59 syntax in an EBNF-like notation:
61 * Production rules look like non-terminal = expression
62 * Concatenation: expression A B matches expression A, then B
63 * Alternation: expression A | B matches expression A or B
64 * Repetition: expression A... matches zero or more occurrences of
66 * Repetition: expression A, ... matches zero or more occurrences of
67 expression A separated by ,
68 * Grouping: expression ( A ) matches expression A
69 * JSON's structural characters are terminals: { } [ ] : ,
70 * JSON's literal names are terminals: false true
71 * String literals enclosed in 'single quotes' are terminal, and match
72 this JSON string, with a leading '*' stripped off
73 * When JSON object member's name starts with '*', the member is
75 * The symbol STRING is a terminal, and matches any JSON string
76 * The symbol BOOL is a terminal, and matches JSON false or true
77 * ALL-CAPS words other than STRING are non-terminals
79 The order of members within JSON objects does not matter unless
82 A QAPI schema consists of a series of top-level expressions:
84 SCHEMA = TOP-LEVEL-EXPR...
86 The top-level expressions are all JSON objects. Code and
87 documentation is generated in schema definition order. Code order
90 A top-level expressions is either a directive or a definition:
92 TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION
94 There are two kinds of directives and six kinds of definitions:
96 DIRECTIVE = INCLUDE | PRAGMA
97 DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT
99 These are discussed in detail below.
102 === Built-in Types ===
104 The following types are predefined, and map to C as follows:
107 str char * any JSON string, UTF-8
108 number double any JSON number
109 int int64_t a JSON number without fractional part
110 that fits into the C integer type
112 int16 int16_t likewise
113 int32 int32_t likewise
114 int64 int64_t likewise
115 uint8 uint8_t likewise
116 uint16 uint16_t likewise
117 uint32 uint32_t likewise
118 uint64 uint64_t likewise
119 size uint64_t like uint64_t, except StringInputVisitor
120 accepts size suffixes
121 bool bool JSON true or false
122 null QNull * JSON null
123 any QObject * any JSON value
124 QType QType JSON string matching enum QType values
127 === Include directives ===
130 INCLUDE = { 'include': STRING }
132 The QAPI schema definitions can be modularized using the 'include' directive:
134 { 'include': 'path/to/file.json' }
136 The directive is evaluated recursively, and include paths are relative
137 to the file using the directive. Multiple includes of the same file
140 As a matter of style, it is a good idea to have all files be
141 self-contained, but at the moment, nothing prevents an included file
142 from making a forward reference to a type that is only introduced by
143 an outer file. The parser may be made stricter in the future to
144 prevent incomplete include files.
147 === Pragma directives ===
150 PRAGMA = { 'pragma': { '*doc-required': BOOL,
151 '*returns-whitelist': [ STRING, ... ],
152 '*name-case-whitelist': [ STRING, ... ] } }
154 The pragma directive lets you control optional generator behavior.
156 Pragma's scope is currently the complete schema. Setting the same
157 pragma to different values in parts of the schema doesn't work.
159 Pragma 'doc-required' takes a boolean value. If true, documentation
160 is required. Default is false.
162 Pragma 'returns-whitelist' takes a list of command names that may
163 violate the rules on permitted return types. Default is none.
165 Pragma 'name-case-whitelist' takes a list of names that may violate
166 rules on use of upper- vs. lower-case letters. Default is none.
169 === Enumeration types ===
172 ENUM = { 'enum': STRING,
173 'data': [ ENUM-VALUE, ... ],
176 '*features': FEATURES }
178 | { 'name': STRING, '*if': COND }
180 Member 'enum' names the enum type.
182 Each member of the 'data' array defines a value of the enumeration
183 type. The form STRING is shorthand for { 'name': STRING }. The
184 'name' values must be be distinct.
188 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
190 Nothing prevents an empty enumeration, although it is probably not
193 On the wire, an enumeration type's value is represented by its
194 (string) name. In C, it's represented by an enumeration constant.
195 These are of the form PREFIX_NAME, where PREFIX is derived from the
196 enumeration type's name, and NAME from the value's name. For the
197 example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to
198 VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The
199 optional 'prefix' member overrides PREFIX.
201 The generated C enumeration constants have values 0, 1, ..., N-1 (in
202 QAPI schema order), where N is the number of values. There is an
203 additional enumeration constant PREFIX__MAX with value N.
205 Do not use string or an integer type when an enumeration type can do
206 the job satisfactorily.
208 The optional 'if' member specifies a conditional. See "Configuring
209 the schema" below for more on this.
211 The optional 'features' member specifies features. See "Features"
212 below for more on this.
215 === Type references and array types ===
218 TYPE-REF = STRING | ARRAY-TYPE
219 ARRAY-TYPE = [ STRING ]
221 A string denotes the type named by the string.
223 A one-element array containing a string denotes an array of the type
224 named by the string. Example: ['int'] denotes an array of 'int'.
230 STRUCT = { 'struct': STRING,
234 '*features': FEATURES }
235 MEMBERS = { MEMBER, ... }
236 MEMBER = STRING : TYPE-REF
237 | STRING : { 'type': TYPE-REF,
239 '*features': FEATURES }
241 Member 'struct' names the struct type.
243 Each MEMBER of the 'data' object defines a member of the struct type.
245 The MEMBER's STRING name consists of an optional '*' prefix and the
246 struct member name. If '*' is present, the member is optional.
248 The MEMBER's value defines its properties, in particular its type.
249 The form TYPE-REF is shorthand for { 'type': TYPE-REF }.
253 { 'struct': 'MyType',
254 'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } }
256 A struct type corresponds to a struct in C, and an object in JSON.
257 The C struct's members are generated in QAPI schema order.
259 The optional 'base' member names a struct type whose members are to be
260 included in this type. They go first in the C struct.
264 { 'struct': 'BlockdevOptionsGenericFormat',
265 'data': { 'file': 'str' } }
266 { 'struct': 'BlockdevOptionsGenericCOWFormat',
267 'base': 'BlockdevOptionsGenericFormat',
268 'data': { '*backing': 'str' } }
270 An example BlockdevOptionsGenericCOWFormat object on the wire could use
271 both members like this:
273 { "file": "/some/place/my-image",
274 "backing": "/some/place/my-backing-file" }
276 The optional 'if' member specifies a conditional. See "Configuring
277 the schema" below for more on this.
279 The optional 'features' member specifies features. See "Features"
280 below for more on this.
286 UNION = { 'union': STRING,
289 '*features': FEATURES }
292 'base': ( MEMBERS | STRING ),
293 'discriminator': STRING,
295 '*features': FEATURES }
296 BRANCHES = { BRANCH, ... }
297 BRANCH = STRING : TYPE-REF
298 | STRING : { 'type': TYPE-REF, '*if': COND }
300 Member 'union' names the union type.
302 There are two flavors of union types: simple (no discriminator or
303 base), and flat (both discriminator and base).
305 Each BRANCH of the 'data' object defines a branch of the union. A
306 union must have at least one branch.
308 The BRANCH's STRING name is the branch name.
310 The BRANCH's value defines the branch's properties, in particular its
311 type. The form TYPE-REF is shorthand for { 'type': TYPE-REF }.
313 A simple union type defines a mapping from automatic discriminator
314 values to data types like in this example:
316 { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
317 { 'struct': 'BlockdevOptionsQcow2',
318 'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
320 { 'union': 'BlockdevOptionsSimple',
321 'data': { 'file': 'BlockdevOptionsFile',
322 'qcow2': 'BlockdevOptionsQcow2' } }
324 In the Client JSON Protocol, a simple union is represented by an
325 object that contains the 'type' member as a discriminator, and a
326 'data' member that is of the specified data type corresponding to the
327 discriminator value, as in these examples:
329 { "type": "file", "data": { "filename": "/some/place/my-image" } }
330 { "type": "qcow2", "data": { "backing": "/some/place/my-image",
331 "lazy-refcounts": true } }
333 The generated C code uses a struct containing a union. Additionally,
334 an implicit C enum 'NameKind' is created, corresponding to the union
335 'Name', for accessing the various branches of the union. The value
336 for each branch can be of any type.
338 Flat unions permit arbitrary common members that occur in all variants
339 of the union, not just a discriminator. Their discriminators need not
340 be named 'type'. They also avoid nesting on the wire.
342 The 'base' member defines the common members. If it is a MEMBERS
343 object, it defines common members just like a struct type's 'data'
344 member defines struct type members. If it is a STRING, it names a
345 struct type whose members are the common members.
347 All flat union branches must be of struct type.
349 In the Client JSON Protocol, a flat union is represented by an object
350 with the common members (from the base type) and the selected branch's
351 members. The two sets of member names must be disjoint. Member
352 'discriminator' must name a non-optional enum-typed member of the base
355 The following example enhances the above simple union example by
356 adding an optional common member 'read-only', renaming the
357 discriminator to something more applicable than the simple union's
358 default of 'type', and reducing the number of {} required on the wire:
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 Notice that in a flat union, the discriminator name is controlled by
375 the user, but because it must map to a base member with enum type, the
376 code generator ensures that branches match the existing values of the
377 enum. The order of branches need not match the order of the enum
378 values. The branches need not cover all possible enum values.
379 Omitted enum values are still valid branches that add no additional
380 members to the data type. In the resulting generated C data types, a
381 flat union is represented as a struct with the base members in QAPI
382 schema order, and then a union of structures for each branch of the
385 A simple union can always be re-written as a flat union where the base
386 class has a single member named 'type', and where each branch of the
387 union has a struct with a single member named 'data'. That is,
389 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
391 is identical on the wire to:
393 { 'enum': 'Enum', 'data': ['one', 'two'] }
394 { 'struct': 'Branch1', 'data': { 'data': 'str' } }
395 { 'struct': 'Branch2', 'data': { 'data': 'int' } }
396 { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type',
397 'data': { 'one': 'Branch1', 'two': 'Branch2' } }
399 The optional 'if' member specifies a conditional. See "Configuring
400 the schema" below for more on this.
402 The optional 'features' member specifies features. See "Features"
403 below for more on this.
406 === Alternate types ===
409 ALTERNATE = { 'alternate': STRING,
410 'data': ALTERNATIVES,
412 '*features': FEATURES }
413 ALTERNATIVES = { ALTERNATIVE, ... }
414 ALTERNATIVE = STRING : STRING
415 | STRING : { 'type': STRING, '*if': COND }
417 Member 'alternate' names the alternate type.
419 Each ALTERNATIVE of the 'data' object defines a branch of the
420 alternate. An alternate must have at least one branch.
422 The ALTERNATIVE's STRING name is the branch name.
424 The ALTERNATIVE's value defines the branch's properties, in particular
425 its type. The form STRING is shorthand for { 'type': STRING }.
429 { 'alternate': 'BlockdevRef',
430 'data': { 'definition': 'BlockdevOptions',
431 'reference': 'str' } }
433 An alternate type is like a union type, except there is no
434 discriminator on the wire. Instead, the branch to use is inferred
435 from the value. An alternate can only express a choice between types
436 represented differently on the wire.
438 If a branch is typed as the 'bool' built-in, the alternate accepts
439 true and false; if it is typed as any of the various numeric
440 built-ins, it accepts a JSON number; if it is typed as a 'str'
441 built-in or named enum type, it accepts a JSON string; if it is typed
442 as the 'null' built-in, it accepts JSON null; and if it is typed as a
443 complex type (struct or union), it accepts a JSON object.
445 The example alternate declaration above allows using both of the
446 following example objects:
448 { "file": "my_existing_block_device_id" }
449 { "file": { "driver": "file",
451 "filename": "/tmp/mydisk.qcow2" } }
453 The optional 'if' member specifies a conditional. See "Configuring
454 the schema" below for more on this.
456 The optional 'features' member specifies features. See "Features"
457 below for more on this.
463 COMMAND = { 'command': STRING,
465 '*data': ( MEMBERS | STRING ),
470 '*returns': TYPE-REF,
471 '*success-response': false,
474 '*allow-preconfig': true,
476 '*features': FEATURES }
478 Member 'command' names the command.
480 Member 'data' defines the arguments. It defaults to an empty MEMBERS
483 If 'data' is a MEMBERS object, then MEMBERS defines arguments just
484 like a struct type's 'data' defines struct type members.
486 If 'data' is a STRING, then STRING names a complex type whose members
487 are the arguments. A union type requires 'boxed': true.
489 Member 'returns' defines the command's return type. It defaults to an
490 empty struct type. It must normally be a complex type or an array of
491 a complex type. To return anything else, the command must be listed
492 in pragma 'returns-whitelist'. If you do this, extending the command
493 to return additional information will be harder. Use of
494 'returns-whitelist' for new commands is strongly discouraged.
496 A command's error responses are not specified in the QAPI schema.
497 Error conditions should be documented in comments.
499 In the Client JSON Protocol, the value of the "execute" or "exec-oob"
500 member is the command name. The value of the "arguments" member then
501 has to conform to the arguments, and the value of the success
502 response's "return" member will conform to the return type.
504 Some example commands:
506 { 'command': 'my-first-command',
507 'data': { 'arg1': 'str', '*arg2': 'str' } }
508 { 'struct': 'MyType', 'data': { '*value': 'str' } }
509 { 'command': 'my-second-command',
510 'returns': [ 'MyType' ] }
512 which would validate this Client JSON Protocol transaction:
514 => { "execute": "my-first-command",
515 "arguments": { "arg1": "hello" } }
517 => { "execute": "my-second-command" }
518 <= { "return": [ { "value": "one" }, { } ] }
520 The generator emits a prototype for the C function implementing the
521 command. The function itself needs to be written by hand. See
522 section "Code generated for commands" for examples.
524 The function returns the return type. When member 'boxed' is absent,
525 it takes the command arguments as arguments one by one, in QAPI schema
526 order. Else it takes them wrapped in the C struct generated for the
527 complex argument type. It takes an additional Error ** argument in
530 The generator also emits a marshalling function that extracts
531 arguments for the user's function out of an input QDict, calls the
532 user's function, and if it succeeded, builds an output QObject from
533 its return value. This is for use by the QMP monitor core.
535 In rare cases, QAPI cannot express a type-safe representation of a
536 corresponding Client JSON Protocol command. You then have to suppress
537 generation of a marshalling function by including a member 'gen' with
538 boolean value false, and instead write your own function. For
541 { 'command': 'netdev_add',
542 'data': {'type': 'str', 'id': 'str'},
545 Please try to avoid adding new commands that rely on this, and instead
546 use type-safe unions.
548 Normally, the QAPI schema is used to describe synchronous exchanges,
549 where a response is expected. But in some cases, the action of a
550 command is expected to change state in a way that a successful
551 response is not possible (although the command will still return an
552 error object on failure). When a successful reply is not possible,
553 the command definition includes the optional member 'success-response'
554 with boolean value false. So far, only QGA makes use of this member.
556 Member 'allow-oob' declares whether the command supports out-of-band
557 (OOB) execution. It defaults to false. For example:
559 { 'command': 'migrate_recover',
560 'data': { 'uri': 'str' }, 'allow-oob': true }
562 See qmp-spec.txt for out-of-band execution syntax and semantics.
564 Commands supporting out-of-band execution can still be executed
567 When a command is executed in-band, its handler runs in the main
568 thread with the BQL held.
570 When a command is executed out-of-band, its handler runs in a
571 dedicated monitor I/O thread with the BQL *not* held.
573 An OOB-capable command handler must satisfy the following conditions:
575 - It terminates quickly.
576 - It does not invoke system calls that may block.
577 - It does not access guest RAM that may block when userfaultfd is
578 enabled for postcopy live migration.
579 - It takes only "fast" locks, i.e. all critical sections protected by
580 any lock it takes also satisfy the conditions for OOB command
583 The restrictions on locking limit access to shared state. Such access
584 requires synchronization, but OOB commands can't take the BQL or any
587 When in doubt, do not implement OOB execution support.
589 Member 'allow-preconfig' declares whether the command is available
590 before the machine is built. It defaults to false. For example:
592 { 'command': 'qmp_capabilities',
593 'data': { '*enable': [ 'QMPCapability' ] },
594 'allow-preconfig': true }
596 QMP is available before the machine is built only when QEMU was
597 started with --preconfig.
599 The optional 'if' member specifies a conditional. See "Configuring
600 the schema" below for more on this.
602 The optional 'features' member specifies features. See "Features"
603 below for more on this.
609 EVENT = { 'event': STRING,
611 '*data': ( MEMBERS | STRING ),
617 '*features': FEATURES }
619 Member 'event' names the event. This is the event name used in the
620 Client JSON Protocol.
622 Member 'data' defines the event-specific data. It defaults to an
623 empty MEMBERS object.
625 If 'data' is a MEMBERS object, then MEMBERS defines event-specific
626 data just like a struct type's 'data' defines struct type members.
628 If 'data' is a STRING, then STRING names a complex type whose members
629 are the event-specific data. A union type requires 'boxed': true.
633 { 'event': 'EVENT_C',
634 'data': { '*a': 'int', 'b': 'str' } }
636 Resulting in this JSON object:
638 { "event": "EVENT_C",
639 "data": { "b": "test string" },
640 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
642 The generator emits a function to send the event. When member 'boxed'
643 is absent, it takes event-specific data one by one, in QAPI schema
644 order. Else it takes them wrapped in the C struct generated for the
645 complex type. See section "Code generated for events" for examples.
647 The optional 'if' member specifies a conditional. See "Configuring
648 the schema" below for more on this.
650 The optional 'features' member specifies features. See "Features"
651 below for more on this.
657 FEATURES = [ FEATURE, ... ]
659 | { 'name': STRING, '*if': COND }
661 Sometimes, the behaviour of QEMU changes compatibly, but without a
662 change in the QMP syntax (usually by allowing values or operations
663 that previously resulted in an error). QMP clients may still need to
664 know whether the extension is available.
666 For this purpose, a list of features can be specified for a command or
667 struct type. Each list member can either be { 'name': STRING, '*if':
668 COND }, or STRING, which is shorthand for { 'name': STRING }.
670 The optional 'if' member specifies a conditional. See "Configuring
671 the schema" below for more on this.
675 { 'struct': 'TestType',
676 'data': { 'number': 'int' },
677 'features': [ 'allow-negative-numbers' ] }
679 The feature strings are exposed to clients in introspection, as
680 explained in section "Client JSON Protocol introspection".
682 Intended use is to have each feature string signal that this build of
683 QEMU shows a certain behaviour.
686 === Naming rules and reserved names ===
688 All names must begin with a letter, and contain only ASCII letters,
689 digits, hyphen, and underscore. There are two exceptions: enum values
690 may start with a digit, and names that are downstream extensions (see
691 section Downstream extensions) start with underscore.
693 Names beginning with 'q_' are reserved for the generator, which uses
694 them for munging QMP names that resemble C keywords or other
695 problematic strings. For example, a member named "default" in qapi
696 becomes "q_default" in the generated C code.
698 Types, commands, and events share a common namespace. Therefore,
699 generally speaking, type definitions should always use CamelCase for
700 user-defined type names, while built-in types are lowercase.
702 Type names ending with 'Kind' or 'List' are reserved for the
703 generator, which uses them for implicit union enums and array types,
706 Command names, and member names within a type, should be all lower
707 case with words separated by a hyphen. However, some existing older
708 commands and complex types use underscore; when extending them,
709 consistency is preferred over blindly avoiding underscore.
711 Event names should be ALL_CAPS with words separated by underscore.
713 Member name 'u' and names starting with 'has-' or 'has_' are reserved
714 for the generator, which uses them for unions and for tracking
717 Any name (command, event, type, member, or enum value) beginning with
718 "x-" is marked experimental, and may be withdrawn or changed
719 incompatibly in a future release.
721 Pragma 'name-case-whitelist' lets you violate the rules on use of
722 upper and lower case. Use for new code is strongly discouraged.
725 === Downstream extensions ===
727 QAPI schema names that are externally visible, say in the Client JSON
728 Protocol, need to be managed with care. Names starting with a
729 downstream prefix of the form __RFQDN_ are reserved for the downstream
730 who controls the valid, reverse fully qualified domain name RFQDN.
731 RFQDN may only contain ASCII letters, digits, hyphen and period.
733 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
734 downstream command __com.redhat_drive-mirror.
737 === Configuring the schema ===
743 All definitions take an optional 'if' member. Its value must be a
744 string or a list of strings. A string is shorthand for a list
745 containing just that string. The code generated for the definition
746 will then be guarded by #if STRING for each STRING in the COND list.
748 Example: a conditional struct
750 { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
751 'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] }
753 gets its generated code guarded like this:
755 #if defined(CONFIG_FOO)
756 #if defined(HAVE_BAR)
757 ... generated code ...
758 #endif /* defined(HAVE_BAR) */
759 #endif /* defined(CONFIG_FOO) */
761 Individual members of complex types, commands arguments, and
762 event-specific data can also be made conditional. This requires the
763 longhand form of MEMBER.
765 Example: a struct type with unconditional member 'foo' and conditional
768 { 'struct': 'IfStruct', 'data':
770 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
772 A union's discriminator may not be conditional.
774 Likewise, individual enumeration values be conditional. This requires
775 the longhand form of ENUM-VALUE.
777 Example: an enum type with unconditional value 'foo' and conditional
780 { 'enum': 'IfEnum', 'data':
782 { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
784 Likewise, features can be conditional. This requires the longhand
787 Example: a struct with conditional feature 'allow-negative-numbers'
789 { 'struct': 'TestType',
790 'data': { 'number': 'int' },
791 'features': [ { 'name': 'allow-negative-numbers',
792 'if' 'defined(IFCOND)' } ] }
794 Please note that you are responsible to ensure that the C code will
795 compile with an arbitrary combination of conditions, since the
796 generator is unable to check it at this point.
798 The conditions apply to introspection as well, i.e. introspection
799 shows a conditional entity only when the condition is satisfied in
800 this particular build.
803 === Documentation comments ===
805 A multi-line comment that starts and ends with a '##' line is a
806 documentation comment.
808 If the documentation comment starts like
813 it documents the definition if SYMBOL, else it's free-form
816 See below for more on definition documentation.
818 Free-form documentation may be used to provide additional text and
822 ==== Documentation markup ====
824 Comment text starting with '=' is a section title:
828 Double the '=' for a subsection title:
830 # == Subsection title
832 '|' denotes examples:
834 # | Text of the example, may span
837 '*' starts an itemized list:
839 # * First item, may span
843 You can also use '-' instead of '*'.
845 A decimal number followed by '.' starts a numbered list:
847 # 1. First item, may span
851 The actual number doesn't matter. You could even use '*' instead of
852 '2.' for the second item.
854 Lists can't be nested. Blank lines are currently not supported within
857 Additional whitespace between the initial '#' and the comment text is
860 *foo* and _foo_ are for strong and emphasis styles respectively (they
861 do not work over multiple lines). @foo is used to reference a name in
870 # Some text foo with *strong* and _emphasis_
882 ==== Definition documentation ====
884 Definition documentation, if present, must immediately precede the
885 definition it documents.
887 When documentation is required (see pragma 'doc-required'), every
888 definition must have documentation.
890 Definition documentation starts with a line naming the definition,
891 followed by an optional overview, a description of each argument (for
892 commands and events), member (for structs and unions), branch (for
893 alternates), or value (for enums), and finally optional tagged
896 FIXME: the parser accepts these things in almost any order.
897 FIXME: union branches should be described, too.
899 Extensions added after the definition was first released carry a
900 '(since x.y.z)' comment.
902 A tagged section starts with one of the following words:
903 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
904 The section ends with the start of a new section.
906 A 'Since: x.y.z' tagged section lists the release that introduced the
914 # Statistics of a virtual block device or a block backing device.
916 # @device: If the stats are for a virtual block device, the name
917 # corresponding to the virtual block device.
919 # @node-name: The node name of the device. (since 2.3)
921 # ... more members ...
925 { 'struct': 'BlockStats',
926 'data': {'*device': 'str', '*node-name': 'str',
927 ... more members ... } }
932 # Query the @BlockStats for all virtual block devices.
934 # @query-nodes: If true, the command will query all the
935 # block nodes ... explain, explain ... (since 2.3)
937 # Returns: A list of @BlockStats for each virtual block devices.
943 # -> { "execute": "query-blockstats" }
945 # ... lots of output ...
949 { 'command': 'query-blockstats',
950 'data': { '*query-nodes': 'bool' },
951 'returns': ['BlockStats'] }
954 == Client JSON Protocol introspection ==
956 Clients of a Client JSON Protocol commonly need to figure out what
957 exactly the server (QEMU) supports.
959 For this purpose, QMP provides introspection via command
960 query-qmp-schema. QGA currently doesn't support introspection.
962 While Client JSON Protocol wire compatibility should be maintained
963 between qemu versions, we cannot make the same guarantees for
964 introspection stability. For example, one version of qemu may provide
965 a non-variant optional member of a struct, and a later version rework
966 the member to instead be non-optional and associated with a variant.
967 Likewise, one version of qemu may list a member with open-ended type
968 'str', and a later version could convert it to a finite set of strings
969 via an enum type; or a member may be converted from a specific type to
970 an alternate that represents a choice between the original type and
973 query-qmp-schema returns a JSON array of SchemaInfo objects. These
974 objects together describe the wire ABI, as defined in the QAPI schema.
975 There is no specified order to the SchemaInfo objects returned; a
976 client must search for a particular name throughout the entire array
977 to learn more about that name, but is at least guaranteed that there
978 will be no collisions between type, command, and event names.
980 However, the SchemaInfo can't reflect all the rules and restrictions
981 that apply to QMP. It's interface introspection (figuring out what's
982 there), not interface specification. The specification is in the QAPI
983 schema. To understand how QMP is to be used, you need to study the
986 Like any other command, query-qmp-schema is itself defined in the QAPI
987 schema, along with the SchemaInfo type. This text attempts to give an
988 overview how things work. For details you need to consult the QAPI
991 SchemaInfo objects have common members "name", "meta-type",
992 "features", and additional variant members depending on the value of
995 Each SchemaInfo object describes a wire ABI entity of a certain
996 meta-type: a command, event or one of several kinds of type.
998 SchemaInfo for commands and events have the same name as in the QAPI
1001 Command and event names are part of the wire ABI, but type names are
1002 not. Therefore, the SchemaInfo for types have auto-generated
1003 meaningless names. For readability, the examples in this section use
1004 meaningful type names instead.
1006 Optional member "features" exposes the entity's feature strings as a
1007 JSON array of strings.
1009 To examine a type, start with a command or event using it, then follow
1012 QAPI schema definitions not reachable that way are omitted.
1014 The SchemaInfo for a command has meta-type "command", and variant
1015 members "arg-type", "ret-type" and "allow-oob". On the wire, the
1016 "arguments" member of a client's "execute" command must conform to the
1017 object type named by "arg-type". The "return" member that the server
1018 passes in a success response conforms to the type named by "ret-type".
1019 When "allow-oob" is true, it means the command supports out-of-band
1020 execution. It defaults to false.
1022 If the command takes no arguments, "arg-type" names an object type
1023 without members. Likewise, if the command returns nothing, "ret-type"
1024 names an object type without members.
1026 Example: the SchemaInfo for command query-qmp-schema
1028 { "name": "query-qmp-schema", "meta-type": "command",
1029 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1031 Type "q_empty" is an automatic object type without members, and type
1032 "SchemaInfoList" is the array of SchemaInfo type.
1034 The SchemaInfo for an event has meta-type "event", and variant member
1035 "arg-type". On the wire, a "data" member that the server passes in an
1036 event conforms to the object type named by "arg-type".
1038 If the event carries no additional information, "arg-type" names an
1039 object type without members. The event may not have a data member on
1042 Each command or event defined with 'data' as MEMBERS object in the
1043 QAPI schema implicitly defines an object type.
1045 Example: the SchemaInfo for EVENT_C from section Events
1047 { "name": "EVENT_C", "meta-type": "event",
1048 "arg-type": "q_obj-EVENT_C-arg" }
1050 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1051 the two members from the event's definition.
1053 The SchemaInfo for struct and union types has meta-type "object".
1055 The SchemaInfo for a struct type has variant member "members".
1057 The SchemaInfo for a union type additionally has variant members "tag"
1060 "members" is a JSON array describing the object's common members, if
1061 any. Each element is a JSON object with members "name" (the member's
1062 name), "type" (the name of its type), and optionally "default". The
1063 member is optional if "default" is present. Currently, "default" can
1064 only have value null. Other values are reserved for future
1065 extensions. The "members" array is in no particular order; clients
1066 must search the entire object when learning whether a particular
1067 member is supported.
1069 Example: the SchemaInfo for MyType from section Struct types
1071 { "name": "MyType", "meta-type": "object",
1073 { "name": "member1", "type": "str" },
1074 { "name": "member2", "type": "int" },
1075 { "name": "member3", "type": "str", "default": null } ] }
1077 "features" exposes the command's feature strings as a JSON array of
1080 Example: the SchemaInfo for TestType from section Features:
1082 { "name": "TestType", "meta-type": "object",
1084 { "name": "number", "type": "int" } ],
1085 "features": ["allow-negative-numbers"] }
1087 "tag" is the name of the common member serving as type tag.
1088 "variants" is a JSON array describing the object's variant members.
1089 Each element is a JSON object with members "case" (the value of type
1090 tag this element applies to) and "type" (the name of an object type
1091 that provides the variant members for this type tag value). The
1092 "variants" array is in no particular order, and is not guaranteed to
1093 list cases in the same order as the corresponding "tag" enum type.
1095 Example: the SchemaInfo for flat union BlockdevOptions from section
1098 { "name": "BlockdevOptions", "meta-type": "object",
1100 { "name": "driver", "type": "BlockdevDriver" },
1101 { "name": "read-only", "type": "bool", "default": null } ],
1104 { "case": "file", "type": "BlockdevOptionsFile" },
1105 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
1107 Note that base types are "flattened": its members are included in the
1110 A simple union implicitly defines an enumeration type for its implicit
1111 discriminator (called "type" on the wire, see section Union types).
1113 A simple union implicitly defines an object type for each of its
1116 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
1119 { "name": "BlockdevOptionsSimple", "meta-type": "object",
1121 { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
1124 { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
1125 { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
1127 Enumeration type "BlockdevOptionsSimpleKind" and the object types
1128 "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
1129 are implicitly defined.
1131 The SchemaInfo for an alternate type has meta-type "alternate", and
1132 variant member "members". "members" is a JSON array. Each element is
1133 a JSON object with member "type", which names a type. Values of the
1134 alternate type conform to exactly one of its member types. There is
1135 no guarantee on the order in which "members" will be listed.
1137 Example: the SchemaInfo for BlockdevRef from section Alternate types
1139 { "name": "BlockdevRef", "meta-type": "alternate",
1141 { "type": "BlockdevOptions" },
1142 { "type": "str" } ] }
1144 The SchemaInfo for an array type has meta-type "array", and variant
1145 member "element-type", which names the array's element type. Array
1146 types are implicitly defined. For convenience, the array's name may
1147 resemble the element type; however, clients should examine member
1148 "element-type" instead of making assumptions based on parsing member
1151 Example: the SchemaInfo for ['str']
1153 { "name": "[str]", "meta-type": "array",
1154 "element-type": "str" }
1156 The SchemaInfo for an enumeration type has meta-type "enum" and
1157 variant member "values". The values are listed in no particular
1158 order; clients must search the entire enum when learning whether a
1159 particular value is supported.
1161 Example: the SchemaInfo for MyEnum from section Enumeration types
1163 { "name": "MyEnum", "meta-type": "enum",
1164 "values": [ "value1", "value2", "value3" ] }
1166 The SchemaInfo for a built-in type has the same name as the type in
1167 the QAPI schema (see section Built-in Types), with one exception
1168 detailed below. It has variant member "json-type" that shows how
1169 values of this type are encoded on the wire.
1171 Example: the SchemaInfo for str
1173 { "name": "str", "meta-type": "builtin", "json-type": "string" }
1175 The QAPI schema supports a number of integer types that only differ in
1176 how they map to C. They are identical as far as SchemaInfo is
1177 concerned. Therefore, they get all mapped to a single type "int" in
1180 As explained above, type names are not part of the wire ABI. Not even
1181 the names of built-in types. Clients should examine member
1182 "json-type" instead of hard-coding names of built-in types.
1185 == Compatibility considerations ==
1187 Maintaining backward compatibility at the Client JSON Protocol level
1188 while evolving the schema requires some care. This section is about
1189 syntactic compatibility, which is necessary, but not sufficient, for
1190 actual compatibility.
1192 Clients send commands with argument data, and receive command
1193 responses with return data and events with event data.
1195 Adding opt-in functionality to the send direction is backwards
1196 compatible: adding commands, optional arguments, enumeration values,
1197 union and alternate branches; turning an argument type into an
1198 alternate of that type; making mandatory arguments optional. Clients
1199 oblivious of the new functionality continue to work.
1201 Incompatible changes include removing commands, command arguments,
1202 enumeration values, union and alternate branches, adding mandatory
1203 command arguments, and making optional arguments mandatory.
1205 The specified behavior of an absent optional argument should remain
1206 the same. With proper documentation, this policy still allows some
1207 flexibility; for example, when an optional 'buffer-size' argument is
1208 specified to default to a sensible buffer size, the actual default
1209 value can still be changed. The specified default behavior is not the
1210 exact size of the buffer, only that the default size is sensible.
1212 Adding functionality to the receive direction is generally backwards
1213 compatible: adding events, adding return and event data members.
1214 Clients are expected to ignore the ones they don't know.
1216 Removing "unreachable" stuff like events that can't be triggered
1217 anymore, optional return or event data members that can't be sent
1218 anymore, and return or event data member (enumeration) values that
1219 can't be sent anymore makes no difference to clients, except for
1220 introspection. The latter can conceivably confuse clients, so tread
1223 Incompatible changes include removing return and event data members.
1225 Any change to a command definition's 'data' or one of the types used
1226 there (recursively) needs to consider send direction compatibility.
1228 Any change to a command definition's 'return', an event definition's
1229 'data', or one of the types used there (recursively) needs to consider
1230 receive direction compatibility.
1232 Any change to types used in both contexts need to consider both.
1234 Enumeration type values and complex and alternate type members may be
1235 reordered freely. For enumerations and alternate types, this doesn't
1236 affect the wire encoding. For complex types, this might make the
1237 implementation emit JSON object members in a different order, which
1238 the Client JSON Protocol permits.
1240 Since type names are not visible in the Client JSON Protocol, types
1241 may be freely renamed. Even certain refactorings are invisible, such
1242 as splitting members from one type into a common base type.
1245 == Code generation ==
1247 The QAPI code generator qapi-gen.py generates code and documentation
1248 from the schema. Together with the core QAPI libraries, this code
1249 provides everything required to take JSON commands read in by a Client
1250 JSON Protocol server, unmarshal the arguments into the underlying C
1251 types, call into the corresponding C function, map the response back
1252 to a Client JSON Protocol response to be returned to the user, and
1253 introspect the commands.
1255 As an example, we'll use the following schema, which describes a
1256 single complex user-defined type, along with command which takes a
1257 list of that type as a parameter, and returns a single element of that
1258 type. The user is responsible for writing the implementation of
1259 qmp_my_command(); everything else is produced by the generator.
1261 $ cat example-schema.json
1262 { 'struct': 'UserDefOne',
1263 'data': { 'integer': 'int', '*string': 'str' } }
1265 { 'command': 'my-command',
1266 'data': { 'arg1': ['UserDefOne'] },
1267 'returns': 'UserDefOne' }
1269 { 'event': 'MY_EVENT' }
1271 We run qapi-gen.py like this:
1273 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1274 --prefix="example-" example-schema.json
1276 For a more thorough look at generated code, the testsuite includes
1277 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1278 what the generator will accept, and compiles the resulting C code as
1279 part of 'make check-unit'.
1281 === Code generated for QAPI types ===
1283 The following files are created:
1285 $(prefix)qapi-types.h - C types corresponding to types defined in
1288 $(prefix)qapi-types.c - Cleanup functions for the above C types
1290 The $(prefix) is an optional parameter used as a namespace to keep the
1291 generated code from one schema/code-generation separated from others so code
1292 can be generated/used from multiple schemas without clobbering previously
1297 $ cat qapi-generated/example-qapi-types.h
1298 [Uninteresting stuff omitted...]
1300 #ifndef EXAMPLE_QAPI_TYPES_H
1301 #define EXAMPLE_QAPI_TYPES_H
1303 #include "qapi/qapi-builtin-types.h"
1305 typedef struct UserDefOne UserDefOne;
1307 typedef struct UserDefOneList UserDefOneList;
1309 typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1317 void qapi_free_UserDefOne(UserDefOne *obj);
1319 struct UserDefOneList {
1320 UserDefOneList *next;
1324 void qapi_free_UserDefOneList(UserDefOneList *obj);
1326 struct q_obj_my_command_arg {
1327 UserDefOneList *arg1;
1330 #endif /* EXAMPLE_QAPI_TYPES_H */
1331 $ cat qapi-generated/example-qapi-types.c
1332 [Uninteresting stuff omitted...]
1334 void qapi_free_UserDefOne(UserDefOne *obj)
1342 v = qapi_dealloc_visitor_new();
1343 visit_type_UserDefOne(v, NULL, &obj, NULL);
1347 void qapi_free_UserDefOneList(UserDefOneList *obj)
1355 v = qapi_dealloc_visitor_new();
1356 visit_type_UserDefOneList(v, NULL, &obj, NULL);
1360 [Uninteresting stuff omitted...]
1362 For a modular QAPI schema (see section Include directives), code for
1363 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1365 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1366 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1368 If qapi-gen.py is run with option --builtins, additional files are
1371 qapi-builtin-types.h - C types corresponding to built-in types
1373 qapi-builtin-types.c - Cleanup functions for the above C types
1375 === Code generated for visiting QAPI types ===
1377 These are the visitor functions used to walk through and convert
1378 between a native QAPI C data structure and some other format (such as
1379 QObject); the generated functions are named visit_type_FOO() and
1380 visit_type_FOO_members().
1382 The following files are generated:
1384 $(prefix)qapi-visit.c: Visitor function for a particular C type, used
1385 to automagically convert QObjects into the
1386 corresponding C type and vice-versa, as well
1387 as for deallocating memory for an existing C
1390 $(prefix)qapi-visit.h: Declarations for previously mentioned visitor
1395 $ cat qapi-generated/example-qapi-visit.h
1396 [Uninteresting stuff omitted...]
1398 #ifndef EXAMPLE_QAPI_VISIT_H
1399 #define EXAMPLE_QAPI_VISIT_H
1401 #include "qapi/qapi-builtin-visit.h"
1402 #include "example-qapi-types.h"
1405 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1406 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1407 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1409 void visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1411 #endif /* EXAMPLE_QAPI_VISIT_H */
1412 $ cat qapi-generated/example-qapi-visit.c
1413 [Uninteresting stuff omitted...]
1415 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1419 visit_type_int(v, "integer", &obj->integer, &err);
1423 if (visit_optional(v, "string", &obj->has_string)) {
1424 visit_type_str(v, "string", &obj->string, &err);
1431 error_propagate(errp, err);
1434 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1438 visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err);
1445 visit_type_UserDefOne_members(v, *obj, &err);
1449 visit_check_struct(v, &err);
1451 visit_end_struct(v, (void **)obj);
1452 if (err && visit_is_input(v)) {
1453 qapi_free_UserDefOne(*obj);
1457 error_propagate(errp, err);
1460 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1463 UserDefOneList *tail;
1464 size_t size = sizeof(**obj);
1466 visit_start_list(v, name, (GenericList **)obj, size, &err);
1471 for (tail = *obj; tail;
1472 tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1473 visit_type_UserDefOne(v, NULL, &tail->value, &err);
1480 visit_check_list(v, &err);
1482 visit_end_list(v, (void **)obj);
1483 if (err && visit_is_input(v)) {
1484 qapi_free_UserDefOneList(*obj);
1488 error_propagate(errp, err);
1491 void visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1495 visit_type_UserDefOneList(v, "arg1", &obj->arg1, &err);
1501 error_propagate(errp, err);
1504 [Uninteresting stuff omitted...]
1506 For a modular QAPI schema (see section Include directives), code for
1507 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1509 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1510 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1512 If qapi-gen.py is run with option --builtins, additional files are
1515 qapi-builtin-visit.h - Visitor functions for built-in types
1517 qapi-builtin-visit.c - Declarations for these visitor functions
1519 === Code generated for commands ===
1521 These are the marshaling/dispatch functions for the commands defined
1522 in the schema. The generated code provides qmp_marshal_COMMAND(), and
1523 declares qmp_COMMAND() that the user must implement.
1525 The following files are generated:
1527 $(prefix)qapi-commands.c: Command marshal/dispatch functions for each
1528 QMP command defined in the schema
1530 $(prefix)qapi-commands.h: Function prototypes for the QMP commands
1531 specified in the schema
1533 $(prefix)qapi-init-commands.h - Command initialization prototype
1535 $(prefix)qapi-init-commands.c - Command initialization code
1539 $ cat qapi-generated/example-qapi-commands.h
1540 [Uninteresting stuff omitted...]
1542 #ifndef EXAMPLE_QAPI_COMMANDS_H
1543 #define EXAMPLE_QAPI_COMMANDS_H
1545 #include "example-qapi-types.h"
1547 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1548 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1550 #endif /* EXAMPLE_QAPI_COMMANDS_H */
1551 $ cat qapi-generated/example-qapi-commands.c
1552 [Uninteresting stuff omitted...]
1554 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1559 v = qobject_output_visitor_new(ret_out);
1560 visit_type_UserDefOne(v, "unused", &ret_in, &err);
1562 visit_complete(v, ret_out);
1564 error_propagate(errp, err);
1566 v = qapi_dealloc_visitor_new();
1567 visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1571 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1576 q_obj_my_command_arg arg = {0};
1578 v = qobject_input_visitor_new(QOBJECT(args));
1579 visit_start_struct(v, NULL, NULL, 0, &err);
1583 visit_type_q_obj_my_command_arg_members(v, &arg, &err);
1585 visit_check_struct(v, &err);
1587 visit_end_struct(v, NULL);
1592 retval = qmp_my_command(arg.arg1, &err);
1597 qmp_marshal_output_UserDefOne(retval, ret, &err);
1600 error_propagate(errp, err);
1602 v = qapi_dealloc_visitor_new();
1603 visit_start_struct(v, NULL, NULL, 0, NULL);
1604 visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1605 visit_end_struct(v, NULL);
1608 [Uninteresting stuff omitted...]
1609 $ cat qapi-generated/example-qapi-init-commands.h
1610 [Uninteresting stuff omitted...]
1611 #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H
1612 #define EXAMPLE_QAPI_INIT_COMMANDS_H
1614 #include "qapi/qmp/dispatch.h"
1616 void example_qmp_init_marshal(QmpCommandList *cmds);
1618 #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */
1619 $ cat qapi-generated/example-qapi-init-commands.c
1620 [Uninteresting stuff omitted...]
1621 void example_qmp_init_marshal(QmpCommandList *cmds)
1625 qmp_register_command(cmds, "my-command",
1626 qmp_marshal_my_command, QCO_NO_OPTIONS);
1628 [Uninteresting stuff omitted...]
1630 For a modular QAPI schema (see section Include directives), code for
1631 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1633 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1634 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1636 === Code generated for events ===
1638 This is the code related to events defined in the schema, providing
1639 qapi_event_send_EVENT().
1641 The following files are created:
1643 $(prefix)qapi-events.h - Function prototypes for each event type
1645 $(prefix)qapi-events.c - Implementation of functions to send an event
1647 $(prefix)qapi-emit-events.h - Enumeration of all event names, and
1648 common event code declarations
1650 $(prefix)qapi-emit-events.c - Common event code definitions
1654 $ cat qapi-generated/example-qapi-events.h
1655 [Uninteresting stuff omitted...]
1657 #ifndef EXAMPLE_QAPI_EVENTS_H
1658 #define EXAMPLE_QAPI_EVENTS_H
1660 #include "qapi/util.h"
1661 #include "example-qapi-types.h"
1663 void qapi_event_send_my_event(void);
1665 #endif /* EXAMPLE_QAPI_EVENTS_H */
1666 $ cat qapi-generated/example-qapi-events.c
1667 [Uninteresting stuff omitted...]
1669 void qapi_event_send_my_event(void)
1673 qmp = qmp_event_build_dict("MY_EVENT");
1675 example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
1680 [Uninteresting stuff omitted...]
1681 $ cat qapi-generated/example-qapi-emit-events.h
1682 [Uninteresting stuff omitted...]
1684 #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
1685 #define EXAMPLE_QAPI_EMIT_EVENTS_H
1687 #include "qapi/util.h"
1689 typedef enum example_QAPIEvent {
1690 EXAMPLE_QAPI_EVENT_MY_EVENT,
1691 EXAMPLE_QAPI_EVENT__MAX,
1692 } example_QAPIEvent;
1694 #define example_QAPIEvent_str(val) \
1695 qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
1697 extern const QEnumLookup example_QAPIEvent_lookup;
1699 void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
1701 #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
1702 $ cat qapi-generated/example-qapi-emit-events.c
1703 [Uninteresting stuff omitted...]
1705 const QEnumLookup example_QAPIEvent_lookup = {
1706 .array = (const char *const[]) {
1707 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1709 .size = EXAMPLE_QAPI_EVENT__MAX
1712 [Uninteresting stuff omitted...]
1714 For a modular QAPI schema (see section Include directives), code for
1715 each sub-module SUBDIR/SUBMODULE.json is actually generated into
1717 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1718 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1720 === Code generated for introspection ===
1722 The following files are created:
1724 $(prefix)qapi-introspect.c - Defines a string holding a JSON
1725 description of the schema
1727 $(prefix)qapi-introspect.h - Declares the above string
1731 $ cat qapi-generated/example-qapi-introspect.h
1732 [Uninteresting stuff omitted...]
1734 #ifndef EXAMPLE_QAPI_INTROSPECT_H
1735 #define EXAMPLE_QAPI_INTROSPECT_H
1737 #include "qapi/qmp/qlit.h"
1739 extern const QLitObject example_qmp_schema_qlit;
1741 #endif /* EXAMPLE_QAPI_INTROSPECT_H */
1742 $ cat qapi-generated/example-qapi-introspect.c
1743 [Uninteresting stuff omitted...]
1745 const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
1746 QLIT_QDICT(((QLitDictEntry[]) {
1747 { "arg-type", QLIT_QSTR("0"), },
1748 { "meta-type", QLIT_QSTR("command"), },
1749 { "name", QLIT_QSTR("my-command"), },
1750 { "ret-type", QLIT_QSTR("1"), },
1753 QLIT_QDICT(((QLitDictEntry[]) {
1754 { "arg-type", QLIT_QSTR("2"), },
1755 { "meta-type", QLIT_QSTR("event"), },
1756 { "name", QLIT_QSTR("MY_EVENT"), },
1759 /* "0" = q_obj_my-command-arg */
1760 QLIT_QDICT(((QLitDictEntry[]) {
1761 { "members", QLIT_QLIST(((QLitObject[]) {
1762 QLIT_QDICT(((QLitDictEntry[]) {
1763 { "name", QLIT_QSTR("arg1"), },
1764 { "type", QLIT_QSTR("[1]"), },
1769 { "meta-type", QLIT_QSTR("object"), },
1770 { "name", QLIT_QSTR("0"), },
1773 /* "1" = UserDefOne */
1774 QLIT_QDICT(((QLitDictEntry[]) {
1775 { "members", QLIT_QLIST(((QLitObject[]) {
1776 QLIT_QDICT(((QLitDictEntry[]) {
1777 { "name", QLIT_QSTR("integer"), },
1778 { "type", QLIT_QSTR("int"), },
1781 QLIT_QDICT(((QLitDictEntry[]) {
1782 { "default", QLIT_QNULL, },
1783 { "name", QLIT_QSTR("string"), },
1784 { "type", QLIT_QSTR("str"), },
1789 { "meta-type", QLIT_QSTR("object"), },
1790 { "name", QLIT_QSTR("1"), },
1794 QLIT_QDICT(((QLitDictEntry[]) {
1795 { "members", QLIT_QLIST(((QLitObject[]) {
1798 { "meta-type", QLIT_QSTR("object"), },
1799 { "name", QLIT_QSTR("2"), },
1802 QLIT_QDICT(((QLitDictEntry[]) {
1803 { "element-type", QLIT_QSTR("1"), },
1804 { "meta-type", QLIT_QSTR("array"), },
1805 { "name", QLIT_QSTR("[1]"), },
1808 QLIT_QDICT(((QLitDictEntry[]) {
1809 { "json-type", QLIT_QSTR("int"), },
1810 { "meta-type", QLIT_QSTR("builtin"), },
1811 { "name", QLIT_QSTR("int"), },
1814 QLIT_QDICT(((QLitDictEntry[]) {
1815 { "json-type", QLIT_QSTR("string"), },
1816 { "meta-type", QLIT_QSTR("builtin"), },
1817 { "name", QLIT_QSTR("str"), },
1823 [Uninteresting stuff omitted...]