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 Client JSON Protocol interfaces to the native C QAPI
20 implementations, a JSON-based schema is used to define types and
21 function signatures, and a set of scripts is used to generate types,
22 signatures, and marshaling/dispatch code. This document will describe
23 how the schemas, scripts, and resulting code are used.
26 == QMP/Guest agent schema ==
28 A QAPI schema file is designed to be loosely based on JSON
29 (http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style
30 and the use of comments; a QAPI schema file is then parsed by a python
31 code generation program. A valid QAPI schema consists of a series of
32 top-level expressions, with no commas between them. Where
33 dictionaries (JSON objects) are used, they are parsed as python
34 OrderedDicts so that ordering is preserved (for predictable layout of
35 generated C structs and parameter lists). Ordering doesn't matter
36 between top-level expressions or the keys within an expression, but
37 does matter within dictionary values for 'data' and 'returns' members
38 of a single expression. QAPI schema input is written using 'single
39 quotes' instead of JSON's "double quotes" (in contrast, Client JSON
40 Protocol uses no comments, and while input accepts 'single quotes' as
41 an extension, output is strict JSON using only "double quotes"). As
42 in JSON, trailing commas are not permitted in arrays or dictionaries.
43 Input must be ASCII (although QMP supports full Unicode strings, the
44 QAPI parser does not). At present, there is no place where a QAPI
45 schema requires the use of JSON numbers or null.
50 Comments are allowed; anything between an unquoted # and the following
53 A multi-line comment that starts and ends with a '##' line is a
54 documentation comment. These are parsed by the documentation
55 generator, which recognizes certain markup detailed below.
58 ==== Documentation markup ====
60 Comment text starting with '=' is a section title:
64 Double the '=' for a subsection title:
70 # | Text of the example, may span
73 '*' starts an itemized list:
75 # * First item, may span
79 You can also use '-' instead of '*'.
81 A decimal number followed by '.' starts a numbered list:
83 # 1. First item, may span
87 The actual number doesn't matter. You could even use '*' instead of
88 '2.' for the second item.
90 Lists can't be nested. Blank lines are currently not supported within
93 Additional whitespace between the initial '#' and the comment text is
96 *foo* and _foo_ are for strong and emphasis styles respectively (they
97 do not work over multiple lines). @foo is used to reference a name in
106 # Some text foo with *strong* and _emphasis_
118 ==== Expression documentation ====
120 Each expression that isn't an include directive may be preceded by a
121 documentation block. Such blocks are called expression documentation
124 When documentation is required (see pragma 'doc-required'), expression
125 documentation blocks are mandatory.
127 The documentation block consists of a first line naming the
128 expression, an optional overview, a description of each argument (for
129 commands and events) or member (for structs, unions and alternates),
130 and optional tagged sections.
132 FIXME: the parser accepts these things in almost any order.
134 Extensions added after the expression was first released carry a
135 '(since x.y.z)' comment.
137 A tagged section starts with one of the following words:
138 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
139 The section ends with the start of a new section.
141 A 'Since: x.y.z' tagged section lists the release that introduced the
149 # Statistics of a virtual block device or a block backing device.
151 # @device: If the stats are for a virtual block device, the name
152 # corresponding to the virtual block device.
154 # @node-name: The node name of the device. (since 2.3)
156 # ... more members ...
160 { 'struct': 'BlockStats',
161 'data': {'*device': 'str', '*node-name': 'str',
162 ... more members ... } }
167 # Query the @BlockStats for all virtual block devices.
169 # @query-nodes: If true, the command will query all the
170 # block nodes ... explain, explain ... (since 2.3)
172 # Returns: A list of @BlockStats for each virtual block devices.
178 # -> { "execute": "query-blockstats" }
180 # ... lots of output ...
184 { 'command': 'query-blockstats',
185 'data': { '*query-nodes': 'bool' },
186 'returns': ['BlockStats'] }
188 ==== Free-form documentation ====
190 A documentation block that isn't an expression documentation block is
191 a free-form documentation block. These may be used to provide
192 additional text and structuring content.
195 === Schema overview ===
197 The schema sets up a series of types, as well as commands and events
198 that will use those types. Forward references are allowed: the parser
199 scans in two passes, where the first pass learns all type names, and
200 the second validates the schema and generates the code. This allows
201 the definition of complex structs that can have mutually recursive
202 types, and allows for indefinite nesting of Client JSON Protocol that
203 satisfies the schema. A type name should not be defined more than
204 once. It is permissible for the schema to contain additional types
205 not used by any commands or events in the Client JSON Protocol, for
206 the side effect of generated C code used internally.
208 There are eight top-level expressions recognized by the parser:
209 'include', 'pragma', 'command', 'struct', 'enum', 'union',
210 'alternate', and 'event'. There are several groups of types: simple
211 types (a number of built-in types, such as 'int' and 'str'; as well as
212 enumerations), complex types (structs and two flavors of unions), and
213 alternate types (a choice between other types). The 'command' and
214 'event' expressions can refer to existing types by name, or list an
215 anonymous type as a dictionary. Listing a type name inside an array
216 refers to a single-dimension array of that type; multi-dimension
217 arrays are not directly supported (although an array of a complex
218 struct that contains an array member is possible).
220 All names must begin with a letter, and contain only ASCII letters,
221 digits, hyphen, and underscore. There are two exceptions: enum values
222 may start with a digit, and names that are downstream extensions (see
223 section Downstream extensions) start with underscore.
225 Names beginning with 'q_' are reserved for the generator, which uses
226 them for munging QMP names that resemble C keywords or other
227 problematic strings. For example, a member named "default" in qapi
228 becomes "q_default" in the generated C code.
230 Types, commands, and events share a common namespace. Therefore,
231 generally speaking, type definitions should always use CamelCase for
232 user-defined type names, while built-in types are lowercase.
234 Type names ending with 'Kind' or 'List' are reserved for the
235 generator, which uses them for implicit union enums and array types,
238 Command names, and member names within a type, should be all lower
239 case with words separated by a hyphen. However, some existing older
240 commands and complex types use underscore; when extending such
241 expressions, consistency is preferred over blindly avoiding
244 Event names should be ALL_CAPS with words separated by underscore.
246 Member names starting with 'has-' or 'has_' are reserved for the
247 generator, which uses them for tracking optional members.
249 Any name (command, event, type, member, or enum value) beginning with
250 "x-" is marked experimental, and may be withdrawn or changed
251 incompatibly in a future release.
253 Pragma 'name-case-whitelist' lets you violate the rules on use of
254 upper and lower case. Use for new code is strongly discouraged.
256 In the rest of this document, usage lines are given for each
257 expression type, with literal strings written in lower case and
258 placeholders written in capitals. If a literal string includes a
259 prefix of '*', that key/value pair can be omitted from the expression.
260 For example, a usage statement that includes '*base':STRUCT-NAME
261 means that an expression has an optional key 'base', which if present
262 must have a value that forms a struct name.
265 === Built-in Types ===
267 The following types are predefined, and map to C as follows:
270 str char * any JSON string, UTF-8
271 number double any JSON number
272 int int64_t a JSON number without fractional part
273 that fits into the C integer type
275 int16 int16_t likewise
276 int32 int32_t likewise
277 int64 int64_t likewise
278 uint8 uint8_t likewise
279 uint16 uint16_t likewise
280 uint32 uint32_t likewise
281 uint64 uint64_t likewise
282 size uint64_t like uint64_t, except StringInputVisitor
283 accepts size suffixes
284 bool bool JSON true or false
285 null QNull * JSON null
286 any QObject * any JSON value
287 QType QType JSON string matching enum QType values
290 === Include directives ===
292 Usage: { 'include': STRING }
294 The QAPI schema definitions can be modularized using the 'include' directive:
296 { 'include': 'path/to/file.json' }
298 The directive is evaluated recursively, and include paths are relative to the
299 file using the directive. Multiple includes of the same file are
300 idempotent. No other keys should appear in the expression, and the include
301 value should be a string.
303 As a matter of style, it is a good idea to have all files be
304 self-contained, but at the moment, nothing prevents an included file
305 from making a forward reference to a type that is only introduced by
306 an outer file. The parser may be made stricter in the future to
307 prevent incomplete include files.
310 === Pragma directives ===
312 Usage: { 'pragma': DICT }
314 The pragma directive lets you control optional generator behavior.
315 The dictionary's entries are pragma names and values.
317 Pragma's scope is currently the complete schema. Setting the same
318 pragma to different values in parts of the schema doesn't work.
320 Pragma 'doc-required' takes a boolean value. If true, documentation
321 is required. Default is false.
323 Pragma 'returns-whitelist' takes a list of command names that may
324 violate the rules on permitted return types. Default is none.
326 Pragma 'name-case-whitelist' takes a list of names that may violate
327 rules on use of upper- vs. lower-case letters. Default is none.
332 Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
334 A struct is a dictionary containing a single 'data' key whose value is
335 a dictionary; the dictionary may be empty. This corresponds to a
336 struct in C or an Object in JSON. Each value of the 'data' dictionary
337 must be the name of a type, or a one-element array containing a type
338 name. An example of a struct is:
340 { 'struct': 'MyType',
341 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
343 The use of '*' as a prefix to the name means the member is optional in
344 the corresponding JSON protocol usage.
346 The default initialization value of an optional argument should not be changed
347 between versions of QEMU unless the new default maintains backward
348 compatibility to the user-visible behavior of the old default.
350 With proper documentation, this policy still allows some flexibility; for
351 example, documenting that a default of 0 picks an optimal buffer size allows
352 one release to declare the optimal size at 512 while another release declares
353 the optimal size at 4096 - the user-visible behavior is not the bytes used by
354 the buffer, but the fact that the buffer was optimal size.
356 On input structures (only mentioned in the 'data' side of a command), changing
357 from mandatory to optional is safe (older clients will supply the option, and
358 newer clients can benefit from the default); changing from optional to
359 mandatory is backwards incompatible (older clients may be omitting the option,
360 and must continue to work).
362 On output structures (only mentioned in the 'returns' side of a command),
363 changing from mandatory to optional is in general unsafe (older clients may be
364 expecting the member, and could crash if it is missing), although it
365 can be done if the only way that the optional argument will be omitted
366 is when it is triggered by the presence of a new input flag to the
367 command that older clients don't know to send. Changing from optional
368 to mandatory is safe.
370 A structure that is used in both input and output of various commands
371 must consider the backwards compatibility constraints of both directions
374 A struct definition can specify another struct as its base.
375 In this case, the members of the base type are included as top-level members
376 of the new struct's dictionary in the Client JSON Protocol wire
377 format. An example definition is:
379 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
380 { 'struct': 'BlockdevOptionsGenericCOWFormat',
381 'base': 'BlockdevOptionsGenericFormat',
382 'data': { '*backing': 'str' } }
384 An example BlockdevOptionsGenericCOWFormat object on the wire could use
385 both members like this:
387 { "file": "/some/place/my-image",
388 "backing": "/some/place/my-backing-file" }
391 === Enumeration types ===
393 Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
394 { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
396 An enumeration type is a dictionary containing a single 'data' key
397 whose value is a list of strings. An example enumeration is:
399 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
401 Nothing prevents an empty enumeration, although it is probably not
402 useful. The list of strings should be lower case; if an enum name
403 represents multiple words, use '-' between words. The string 'max' is
404 not allowed as an enum value, and values should not be repeated.
406 The enum constants will be named by using a heuristic to turn the
407 type name into a set of underscore separated words. For the example
408 above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
409 of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
410 does not result in a desirable name, the optional 'prefix' member
411 can be used when defining the enum.
413 The enumeration values are passed as strings over the Client JSON
414 Protocol, but are encoded as C enum integral values in generated code.
415 While the C code starts numbering at 0, it is better to use explicit
416 comparisons to enum values than implicit comparisons to 0; the C code
417 will also include a generated enum member ending in _MAX for tracking
418 the size of the enum, useful when using common functions for
419 converting between strings and enum values. Since the wire format
420 always passes by name, it is acceptable to reorder or add new
421 enumeration members in any location without breaking clients of Client
422 JSON Protocol; however, removing enum values would break
423 compatibility. For any struct that has a member that will only contain
424 a finite set of string values, using an enum type for that member is
425 better than open-coding the member to be type 'str'.
430 Usage: { 'union': STRING, 'data': DICT }
431 or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME-OR-DICT,
432 'discriminator': ENUM-MEMBER-OF-BASE }
434 Union types are used to let the user choose between several different
435 variants for an object. There are two flavors: simple (no
436 discriminator or base), and flat (both discriminator and base). A union
437 type is defined using a data dictionary as explained in the following
438 paragraphs. The data dictionary for either type of union must not
441 A simple union type defines a mapping from automatic discriminator
442 values to data types like in this example:
444 { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
445 { 'struct': 'BlockdevOptionsQcow2',
446 'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
448 { 'union': 'BlockdevOptionsSimple',
449 'data': { 'file': 'BlockdevOptionsFile',
450 'qcow2': 'BlockdevOptionsQcow2' } }
452 In the Client JSON Protocol, a simple union is represented by a
453 dictionary that contains the 'type' member as a discriminator, and a
454 'data' member that is of the specified data type corresponding to the
455 discriminator value, as in these examples:
457 { "type": "file", "data": { "filename": "/some/place/my-image" } }
458 { "type": "qcow2", "data": { "backing": "/some/place/my-image",
459 "lazy-refcounts": true } }
461 The generated C code uses a struct containing a union. Additionally,
462 an implicit C enum 'NameKind' is created, corresponding to the union
463 'Name', for accessing the various branches of the union. No branch of
464 the union can be named 'max', as this would collide with the implicit
465 enum. The value for each branch can be of any type.
467 A flat union definition avoids nesting on the wire, and specifies a
468 set of common members that occur in all variants of the union. The
469 'base' key must specify either a type name (the type must be a
470 struct, not a union), or a dictionary representing an anonymous type.
471 All branches of the union must be complex types, and the top-level
472 members of the union dictionary on the wire will be combination of
473 members from both the base type and the appropriate branch type (when
474 merging two dictionaries, there must be no keys in common). The
475 'discriminator' member must be the name of a non-optional enum-typed
476 member of the base struct.
478 The following example enhances the above simple union example by
479 adding an optional common member 'read-only', renaming the
480 discriminator to something more applicable than the simple union's
481 default of 'type', and reducing the number of {} required on the wire:
483 { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
484 { 'union': 'BlockdevOptions',
485 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
486 'discriminator': 'driver',
487 'data': { 'file': 'BlockdevOptionsFile',
488 'qcow2': 'BlockdevOptionsQcow2' } }
490 Resulting in these JSON objects:
492 { "driver": "file", "read-only": true,
493 "filename": "/some/place/my-image" }
494 { "driver": "qcow2", "read-only": false,
495 "backing": "/some/place/my-image", "lazy-refcounts": true }
497 Notice that in a flat union, the discriminator name is controlled by
498 the user, but because it must map to a base member with enum type, the
499 code generator ensures that branches match the existing values of the
500 enum. The order of the keys need not match the declaration of the enum.
501 The keys need not cover all possible enum values. Omitted enum values
502 are still valid branches that add no additional members to the data type.
503 In the resulting generated C data types, a flat union is
504 represented as a struct with the base members included directly, and
505 then a union of structures for each branch of the struct.
507 A simple union can always be re-written as a flat union where the base
508 class has a single member named 'type', and where each branch of the
509 union has a struct with a single member named 'data'. That is,
511 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
513 is identical on the wire to:
515 { 'enum': 'Enum', 'data': ['one', 'two'] }
516 { 'struct': 'Branch1', 'data': { 'data': 'str' } }
517 { 'struct': 'Branch2', 'data': { 'data': 'int' } }
518 { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type',
519 'data': { 'one': 'Branch1', 'two': 'Branch2' } }
522 === Alternate types ===
524 Usage: { 'alternate': STRING, 'data': DICT }
526 An alternate type is one that allows a choice between two or more JSON
527 data types (string, integer, number, or object, but currently not
528 array) on the wire. The definition is similar to a simple union type,
529 where each branch of the union names a QAPI type. For example:
531 { 'alternate': 'BlockdevRef',
532 'data': { 'definition': 'BlockdevOptions',
533 'reference': 'str' } }
535 Unlike a union, the discriminator string is never passed on the wire
536 for the Client JSON Protocol. Instead, the value's JSON type serves
537 as an implicit discriminator, which in turn means that an alternate
538 can only express a choice between types represented differently in
539 JSON. If a branch is typed as the 'bool' built-in, the alternate
540 accepts true and false; if it is typed as any of the various numeric
541 built-ins, it accepts a JSON number; if it is typed as a 'str'
542 built-in or named enum type, it accepts a JSON string; if it is typed
543 as the 'null' built-in, it accepts JSON null; and if it is typed as a
544 complex type (struct or union), it accepts a JSON object. Two
545 different complex types, for instance, aren't permitted, because both
546 are represented as a JSON object.
548 The example alternate declaration above allows using both of the
549 following example objects:
551 { "file": "my_existing_block_device_id" }
552 { "file": { "driver": "file",
554 "filename": "/tmp/mydisk.qcow2" } }
559 --- General Command Layout ---
561 Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
562 '*returns': TYPE-NAME, '*boxed': true,
563 '*gen': false, '*success-response': false,
564 '*allow-oob': true, '*allow-preconfig': true }
566 Commands are defined by using a dictionary containing several members,
567 where three members are most common. The 'command' member is a
568 mandatory string, and determines the "execute" value passed in a
569 Client JSON Protocol command exchange.
571 The 'data' argument maps to the "arguments" dictionary passed in as
572 part of a Client JSON Protocol command. The 'data' member is optional
573 and defaults to {} (an empty dictionary). If present, it must be the
574 string name of a complex type, or a dictionary that declares an
575 anonymous type with the same semantics as a 'struct' expression.
577 The 'returns' member describes what will appear in the "return" member
578 of a Client JSON Protocol reply on successful completion of a command.
579 The member is optional from the command declaration; if absent, the
580 "return" member will be an empty dictionary. If 'returns' is present,
581 it must be the string name of a complex or built-in type, a
582 one-element array containing the name of a complex or built-in type.
583 To return anything else, you have to list the command in pragma
584 'returns-whitelist'. If you do this, the command cannot be extended
585 to return additional information in the future. Use of
586 'returns-whitelist' for new commands is strongly discouraged.
588 All commands in Client JSON Protocol use a dictionary to report
589 failure, with no way to specify that in QAPI. Where the error return
590 is different than the usual GenericError class in order to help the
591 client react differently to certain error conditions, it is worth
592 documenting this in the comments before the command declaration.
594 Some example commands:
596 { 'command': 'my-first-command',
597 'data': { 'arg1': 'str', '*arg2': 'str' } }
598 { 'struct': 'MyType', 'data': { '*value': 'str' } }
599 { 'command': 'my-second-command',
600 'returns': [ 'MyType' ] }
602 which would validate this Client JSON Protocol transaction:
604 => { "execute": "my-first-command",
605 "arguments": { "arg1": "hello" } }
607 => { "execute": "my-second-command" }
608 <= { "return": [ { "value": "one" }, { } ] }
610 The generator emits a prototype for the user's function implementing
611 the command. Normally, 'data' is a dictionary for an anonymous type,
612 or names a struct type (possibly empty, but not a union), and its
613 members are passed as separate arguments to this function. If the
614 command definition includes a key 'boxed' with the boolean value true,
615 then 'data' is instead the name of any non-empty complex type
616 (struct, union, or alternate), and a pointer to that QAPI type is
617 passed as a single argument.
619 The generator also emits a marshalling function that extracts
620 arguments for the user's function out of an input QDict, calls the
621 user's function, and if it succeeded, builds an output QObject from
624 In rare cases, QAPI cannot express a type-safe representation of a
625 corresponding Client JSON Protocol command. You then have to suppress
626 generation of a marshalling function by including a key 'gen' with
627 boolean value false, and instead write your own function. Please try
628 to avoid adding new commands that rely on this, and instead use
629 type-safe unions. For an example of this usage:
631 { 'command': 'netdev_add',
632 'data': {'type': 'str', 'id': 'str'},
635 Normally, the QAPI schema is used to describe synchronous exchanges,
636 where a response is expected. But in some cases, the action of a
637 command is expected to change state in a way that a successful
638 response is not possible (although the command will still return a
639 normal dictionary error on failure). When a successful reply is not
640 possible, the command expression should include the optional key
641 'success-response' with boolean value false. So far, only QGA makes
644 A command can be declared to support Out-Of-Band (OOB) execution. By
645 default, commands do not support OOB. To declare a command that
646 supports it, the schema includes an extra 'allow-oob' field. For
649 { 'command': 'migrate_recover',
650 'data': { 'uri': 'str' }, 'allow-oob': true }
652 To execute a command with out-of-band priority, the client specifies
653 the "control" field in the request, with "run-oob" set to
656 => { "execute": "command-support-oob",
657 "arguments": { ... },
658 "control": { "run-oob": true } }
661 Without it, even the commands that support out-of-band execution will
662 still be run in-band.
664 Under normal QMP command execution, the following apply to each
667 - They are executed in order,
668 - They run only in main thread of QEMU,
669 - They run with the BQL held.
671 When a command is executed with OOB, the following changes occur:
673 - They can be completed before a pending in-band command,
674 - They run in a dedicated monitor thread,
675 - They run with the BQL not held.
677 OOB command handlers must satisfy the following conditions:
679 - It terminates quickly,
680 - It does not invoke system calls that may block,
681 - It does not access guest RAM that may block when userfaultfd is
682 enabled for postcopy live migration,
683 - It takes only "fast" locks, i.e. all critical sections protected by
684 any lock it takes also satisfy the conditions for OOB command
687 The restrictions on locking limit access to shared state. Such access
688 requires synchronization, but OOB commands can't take the BQL or any
691 If in doubt, do not implement OOB execution support.
693 A command may use the optional 'allow-preconfig' key to permit its execution
694 at early runtime configuration stage (preconfig runstate).
695 If not specified then a command defaults to 'allow-preconfig': false.
697 An example of declaring a command that is enabled during preconfig:
698 { 'command': 'qmp_capabilities',
699 'data': { '*enable': [ 'QMPCapability' ] },
700 'allow-preconfig': true }
704 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
707 Events are defined with the keyword 'event'. It is not allowed to
708 name an event 'MAX', since the generator also produces a C enumeration
709 of all event names with a generated _MAX value at the end. When
710 'data' is also specified, additional info will be included in the
711 event, with similar semantics to a 'struct' expression. Finally there
712 will be C API generated in qapi-events.h; when called by QEMU code, a
713 message with timestamp will be emitted on the wire.
717 { 'event': 'EVENT_C',
718 'data': { '*a': 'int', 'b': 'str' } }
720 Resulting in this JSON object:
722 { "event": "EVENT_C",
723 "data": { "b": "test string" },
724 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
726 The generator emits a function to send the event. Normally, 'data' is
727 a dictionary for an anonymous type, or names a struct type (possibly
728 empty, but not a union), and its members are passed as separate
729 arguments to this function. If the event definition includes a key
730 'boxed' with the boolean value true, then 'data' is instead the name of
731 any non-empty complex type (struct, union, or alternate), and a
732 pointer to that QAPI type is passed as a single argument.
735 === Downstream extensions ===
737 QAPI schema names that are externally visible, say in the Client JSON
738 Protocol, need to be managed with care. Names starting with a
739 downstream prefix of the form __RFQDN_ are reserved for the downstream
740 who controls the valid, reverse fully qualified domain name RFQDN.
741 RFQDN may only contain ASCII letters, digits, hyphen and period.
743 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
744 downstream command __com.redhat_drive-mirror.
747 == Client JSON Protocol introspection ==
749 Clients of a Client JSON Protocol commonly need to figure out what
750 exactly the server (QEMU) supports.
752 For this purpose, QMP provides introspection via command
753 query-qmp-schema. QGA currently doesn't support introspection.
755 While Client JSON Protocol wire compatibility should be maintained
756 between qemu versions, we cannot make the same guarantees for
757 introspection stability. For example, one version of qemu may provide
758 a non-variant optional member of a struct, and a later version rework
759 the member to instead be non-optional and associated with a variant.
760 Likewise, one version of qemu may list a member with open-ended type
761 'str', and a later version could convert it to a finite set of strings
762 via an enum type; or a member may be converted from a specific type to
763 an alternate that represents a choice between the original type and
766 query-qmp-schema returns a JSON array of SchemaInfo objects. These
767 objects together describe the wire ABI, as defined in the QAPI schema.
768 There is no specified order to the SchemaInfo objects returned; a
769 client must search for a particular name throughout the entire array
770 to learn more about that name, but is at least guaranteed that there
771 will be no collisions between type, command, and event names.
773 However, the SchemaInfo can't reflect all the rules and restrictions
774 that apply to QMP. It's interface introspection (figuring out what's
775 there), not interface specification. The specification is in the QAPI
776 schema. To understand how QMP is to be used, you need to study the
779 Like any other command, query-qmp-schema is itself defined in the QAPI
780 schema, along with the SchemaInfo type. This text attempts to give an
781 overview how things work. For details you need to consult the QAPI
784 SchemaInfo objects have common members "name" and "meta-type", and
785 additional variant members depending on the value of meta-type.
787 Each SchemaInfo object describes a wire ABI entity of a certain
788 meta-type: a command, event or one of several kinds of type.
790 SchemaInfo for commands and events have the same name as in the QAPI
793 Command and event names are part of the wire ABI, but type names are
794 not. Therefore, the SchemaInfo for types have auto-generated
795 meaningless names. For readability, the examples in this section use
796 meaningful type names instead.
798 To examine a type, start with a command or event using it, then follow
801 QAPI schema definitions not reachable that way are omitted.
803 The SchemaInfo for a command has meta-type "command", and variant
804 members "arg-type", "ret-type" and "allow-oob". On the wire, the
805 "arguments" member of a client's "execute" command must conform to the
806 object type named by "arg-type". The "return" member that the server
807 passes in a success response conforms to the type named by
808 "ret-type". When "allow-oob" is set, it means the command supports
809 out-of-band execution.
811 If the command takes no arguments, "arg-type" names an object type
812 without members. Likewise, if the command returns nothing, "ret-type"
813 names an object type without members.
815 Example: the SchemaInfo for command query-qmp-schema
817 { "name": "query-qmp-schema", "meta-type": "command",
818 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
820 Type "q_empty" is an automatic object type without members, and type
821 "SchemaInfoList" is the array of SchemaInfo type.
823 The SchemaInfo for an event has meta-type "event", and variant member
824 "arg-type". On the wire, a "data" member that the server passes in an
825 event conforms to the object type named by "arg-type".
827 If the event carries no additional information, "arg-type" names an
828 object type without members. The event may not have a data member on
831 Each command or event defined with dictionary-valued 'data' in the
832 QAPI schema implicitly defines an object type.
834 Example: the SchemaInfo for EVENT_C from section Events
836 { "name": "EVENT_C", "meta-type": "event",
837 "arg-type": "q_obj-EVENT_C-arg" }
839 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
840 the two members from the event's definition.
842 The SchemaInfo for struct and union types has meta-type "object".
844 The SchemaInfo for a struct type has variant member "members".
846 The SchemaInfo for a union type additionally has variant members "tag"
849 "members" is a JSON array describing the object's common members, if
850 any. Each element is a JSON object with members "name" (the member's
851 name), "type" (the name of its type), and optionally "default". The
852 member is optional if "default" is present. Currently, "default" can
853 only have value null. Other values are reserved for future
854 extensions. The "members" array is in no particular order; clients
855 must search the entire object when learning whether a particular
858 Example: the SchemaInfo for MyType from section Struct types
860 { "name": "MyType", "meta-type": "object",
862 { "name": "member1", "type": "str" },
863 { "name": "member2", "type": "int" },
864 { "name": "member3", "type": "str", "default": null } ] }
866 "tag" is the name of the common member serving as type tag.
867 "variants" is a JSON array describing the object's variant members.
868 Each element is a JSON object with members "case" (the value of type
869 tag this element applies to) and "type" (the name of an object type
870 that provides the variant members for this type tag value). The
871 "variants" array is in no particular order, and is not guaranteed to
872 list cases in the same order as the corresponding "tag" enum type.
874 Example: the SchemaInfo for flat union BlockdevOptions from section
877 { "name": "BlockdevOptions", "meta-type": "object",
879 { "name": "driver", "type": "BlockdevDriver" },
880 { "name": "read-only", "type": "bool", "default": null } ],
883 { "case": "file", "type": "BlockdevOptionsFile" },
884 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
886 Note that base types are "flattened": its members are included in the
889 A simple union implicitly defines an enumeration type for its implicit
890 discriminator (called "type" on the wire, see section Union types).
892 A simple union implicitly defines an object type for each of its
895 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
898 { "name": "BlockdevOptionsSimple", "meta-type": "object",
900 { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
903 { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
904 { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
906 Enumeration type "BlockdevOptionsSimpleKind" and the object types
907 "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
908 are implicitly defined.
910 The SchemaInfo for an alternate type has meta-type "alternate", and
911 variant member "members". "members" is a JSON array. Each element is
912 a JSON object with member "type", which names a type. Values of the
913 alternate type conform to exactly one of its member types. There is
914 no guarantee on the order in which "members" will be listed.
916 Example: the SchemaInfo for BlockdevRef from section Alternate types
918 { "name": "BlockdevRef", "meta-type": "alternate",
920 { "type": "BlockdevOptions" },
921 { "type": "str" } ] }
923 The SchemaInfo for an array type has meta-type "array", and variant
924 member "element-type", which names the array's element type. Array
925 types are implicitly defined. For convenience, the array's name may
926 resemble the element type; however, clients should examine member
927 "element-type" instead of making assumptions based on parsing member
930 Example: the SchemaInfo for ['str']
932 { "name": "[str]", "meta-type": "array",
933 "element-type": "str" }
935 The SchemaInfo for an enumeration type has meta-type "enum" and
936 variant member "values". The values are listed in no particular
937 order; clients must search the entire enum when learning whether a
938 particular value is supported.
940 Example: the SchemaInfo for MyEnum from section Enumeration types
942 { "name": "MyEnum", "meta-type": "enum",
943 "values": [ "value1", "value2", "value3" ] }
945 The SchemaInfo for a built-in type has the same name as the type in
946 the QAPI schema (see section Built-in Types), with one exception
947 detailed below. It has variant member "json-type" that shows how
948 values of this type are encoded on the wire.
950 Example: the SchemaInfo for str
952 { "name": "str", "meta-type": "builtin", "json-type": "string" }
954 The QAPI schema supports a number of integer types that only differ in
955 how they map to C. They are identical as far as SchemaInfo is
956 concerned. Therefore, they get all mapped to a single type "int" in
959 As explained above, type names are not part of the wire ABI. Not even
960 the names of built-in types. Clients should examine member
961 "json-type" instead of hard-coding names of built-in types.
964 == Code generation ==
966 The QAPI code generator qapi-gen.py generates code and documentation
967 from the schema. Together with the core QAPI libraries, this code
968 provides everything required to take JSON commands read in by a Client
969 JSON Protocol server, unmarshal the arguments into the underlying C
970 types, call into the corresponding C function, map the response back
971 to a Client JSON Protocol response to be returned to the user, and
972 introspect the commands.
974 As an example, we'll use the following schema, which describes a
975 single complex user-defined type, along with command which takes a
976 list of that type as a parameter, and returns a single element of that
977 type. The user is responsible for writing the implementation of
978 qmp_my_command(); everything else is produced by the generator.
980 $ cat example-schema.json
981 { 'struct': 'UserDefOne',
982 'data': { 'integer': 'int', '*string': 'str' } }
984 { 'command': 'my-command',
985 'data': { 'arg1': ['UserDefOne'] },
986 'returns': 'UserDefOne' }
988 { 'event': 'MY_EVENT' }
990 We run qapi-gen.py like this:
992 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
993 --prefix="example-" example-schema.json
995 For a more thorough look at generated code, the testsuite includes
996 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
997 what the generator will accept, and compiles the resulting C code as
998 part of 'make check-unit'.
1000 === Code generated for QAPI types ===
1002 The following files are created:
1004 $(prefix)qapi-types.h - C types corresponding to types defined in
1007 $(prefix)qapi-types.c - Cleanup functions for the above C types
1009 The $(prefix) is an optional parameter used as a namespace to keep the
1010 generated code from one schema/code-generation separated from others so code
1011 can be generated/used from multiple schemas without clobbering previously
1016 $ cat qapi-generated/example-qapi-types.h
1017 [Uninteresting stuff omitted...]
1019 #ifndef EXAMPLE_QAPI_TYPES_H
1020 #define EXAMPLE_QAPI_TYPES_H
1022 [Built-in types omitted...]
1024 typedef struct UserDefOne UserDefOne;
1026 typedef struct UserDefOneList UserDefOneList;
1028 typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1036 void qapi_free_UserDefOne(UserDefOne *obj);
1038 struct UserDefOneList {
1039 UserDefOneList *next;
1043 void qapi_free_UserDefOneList(UserDefOneList *obj);
1045 struct q_obj_my_command_arg {
1046 UserDefOneList *arg1;
1050 $ cat qapi-generated/example-qapi-types.c
1051 [Uninteresting stuff omitted...]
1053 void qapi_free_UserDefOne(UserDefOne *obj)
1061 v = qapi_dealloc_visitor_new();
1062 visit_type_UserDefOne(v, NULL, &obj, NULL);
1066 void qapi_free_UserDefOneList(UserDefOneList *obj)
1074 v = qapi_dealloc_visitor_new();
1075 visit_type_UserDefOneList(v, NULL, &obj, NULL);
1079 === Code generated for visiting QAPI types ===
1081 These are the visitor functions used to walk through and convert
1082 between a native QAPI C data structure and some other format (such as
1083 QObject); the generated functions are named visit_type_FOO() and
1084 visit_type_FOO_members().
1086 The following files are generated:
1088 $(prefix)qapi-visit.c: Visitor function for a particular C type, used
1089 to automagically convert QObjects into the
1090 corresponding C type and vice-versa, as well
1091 as for deallocating memory for an existing C
1094 $(prefix)qapi-visit.h: Declarations for previously mentioned visitor
1099 $ cat qapi-generated/example-qapi-visit.h
1100 [Uninteresting stuff omitted...]
1102 #ifndef EXAMPLE_QAPI_VISIT_H
1103 #define EXAMPLE_QAPI_VISIT_H
1105 [Visitors for built-in types omitted...]
1107 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1108 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1109 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1111 void visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1114 $ cat qapi-generated/example-qapi-visit.c
1115 [Uninteresting stuff omitted...]
1117 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1121 visit_type_int(v, "integer", &obj->integer, &err);
1125 if (visit_optional(v, "string", &obj->has_string)) {
1126 visit_type_str(v, "string", &obj->string, &err);
1133 error_propagate(errp, err);
1136 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1140 visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err);
1147 visit_type_UserDefOne_members(v, *obj, &err);
1151 visit_check_struct(v, &err);
1153 visit_end_struct(v, (void **)obj);
1154 if (err && visit_is_input(v)) {
1155 qapi_free_UserDefOne(*obj);
1159 error_propagate(errp, err);
1162 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1165 UserDefOneList *tail;
1166 size_t size = sizeof(**obj);
1168 visit_start_list(v, name, (GenericList **)obj, size, &err);
1173 for (tail = *obj; tail;
1174 tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1175 visit_type_UserDefOne(v, NULL, &tail->value, &err);
1182 visit_check_list(v, &err);
1184 visit_end_list(v, (void **)obj);
1185 if (err && visit_is_input(v)) {
1186 qapi_free_UserDefOneList(*obj);
1190 error_propagate(errp, err);
1193 void visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1197 visit_type_UserDefOneList(v, "arg1", &obj->arg1, &err);
1203 error_propagate(errp, err);
1206 === Code generated for commands ===
1208 These are the marshaling/dispatch functions for the commands defined
1209 in the schema. The generated code provides qmp_marshal_COMMAND(), and
1210 declares qmp_COMMAND() that the user must implement.
1212 The following files are generated:
1214 $(prefix)qapi-commands.c: Command marshal/dispatch functions for each
1215 QMP command defined in the schema
1217 $(prefix)qapi-commands.h: Function prototypes for the QMP commands
1218 specified in the schema
1222 $ cat qapi-generated/example-qapi-commands.h
1223 [Uninteresting stuff omitted...]
1225 #ifndef EXAMPLE_QMP_COMMANDS_H
1226 #define EXAMPLE_QMP_COMMANDS_H
1228 #include "example-qapi-types.h"
1229 #include "qapi/qmp/qdict.h"
1230 #include "qapi/qmp/dispatch.h"
1232 void example_qmp_init_marshal(QmpCommandList *cmds);
1233 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1234 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1237 $ cat qapi-generated/example-qapi-commands.c
1238 [Uninteresting stuff omitted...]
1240 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1245 v = qobject_output_visitor_new(ret_out);
1246 visit_type_UserDefOne(v, "unused", &ret_in, &err);
1248 visit_complete(v, ret_out);
1250 error_propagate(errp, err);
1252 v = qapi_dealloc_visitor_new();
1253 visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1257 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1262 q_obj_my_command_arg arg = {0};
1264 v = qobject_input_visitor_new(QOBJECT(args));
1265 visit_start_struct(v, NULL, NULL, 0, &err);
1269 visit_type_q_obj_my_command_arg_members(v, &arg, &err);
1271 visit_check_struct(v, &err);
1273 visit_end_struct(v, NULL);
1278 retval = qmp_my_command(arg.arg1, &err);
1283 qmp_marshal_output_UserDefOne(retval, ret, &err);
1286 error_propagate(errp, err);
1288 v = qapi_dealloc_visitor_new();
1289 visit_start_struct(v, NULL, NULL, 0, NULL);
1290 visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1291 visit_end_struct(v, NULL);
1295 void example_qmp_init_marshal(QmpCommandList *cmds)
1299 qmp_register_command(cmds, "my-command",
1300 qmp_marshal_my_command, QCO_NO_OPTIONS);
1303 === Code generated for events ===
1305 This is the code related to events defined in the schema, providing
1306 qapi_event_send_EVENT().
1308 The following files are created:
1310 $(prefix)qapi-events.h - Function prototypes for each event type, plus an
1311 enumeration of all event names
1313 $(prefix)qapi-events.c - Implementation of functions to send an event
1317 $ cat qapi-generated/example-qapi-events.h
1318 [Uninteresting stuff omitted...]
1320 #ifndef EXAMPLE_QAPI_EVENT_H
1321 #define EXAMPLE_QAPI_EVENT_H
1323 #include "qapi/qmp/qdict.h"
1324 #include "example-qapi-types.h"
1327 void qapi_event_send_my_event(Error **errp);
1329 typedef enum example_QAPIEvent {
1330 EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
1331 EXAMPLE_QAPI_EVENT__MAX = 1,
1332 } example_QAPIEvent;
1334 #define example_QAPIEvent_str(val) \
1335 qapi_enum_lookup(example_QAPIEvent_lookup, (val))
1337 extern const char *const example_QAPIEvent_lookup[];
1340 $ cat qapi-generated/example-qapi-events.c
1341 [Uninteresting stuff omitted...]
1343 void qapi_event_send_my_event(Error **errp)
1347 QMPEventFuncEmit emit;
1349 emit = qmp_event_get_func_emit();
1354 qmp = qmp_event_build_dict("MY_EVENT");
1356 emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err);
1358 error_propagate(errp, err);
1362 const QEnumLookup example_QAPIEvent_lookup = {
1363 .array = (const char *const[]) {
1364 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1366 .size = EXAMPLE_QAPI_EVENT__MAX
1369 === Code generated for introspection ===
1371 The following files are created:
1373 $(prefix)qapi-introspect.c - Defines a string holding a JSON
1374 description of the schema
1376 $(prefix)qapi-introspect.h - Declares the above string
1380 $ cat qapi-generated/example-qapi-introspect.h
1381 [Uninteresting stuff omitted...]
1383 #ifndef EXAMPLE_QMP_INTROSPECT_H
1384 #define EXAMPLE_QMP_INTROSPECT_H
1386 extern const QLitObject qmp_schema_qlit;
1389 $ cat qapi-generated/example-qapi-introspect.c
1390 [Uninteresting stuff omitted...]
1392 const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
1393 QLIT_QDICT(((QLitDictEntry[]) {
1394 { "arg-type", QLIT_QSTR("0") },
1395 { "meta-type", QLIT_QSTR("event") },
1396 { "name", QLIT_QSTR("Event") },
1399 QLIT_QDICT(((QLitDictEntry[]) {
1400 { "members", QLIT_QLIST(((QLitObject[]) {
1403 { "meta-type", QLIT_QSTR("object") },
1404 { "name", QLIT_QSTR("0") },