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 uses key
653 "exec-oob" instead of "execute". Example:
655 => { "exec-oob": "migrate-recover",
656 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
659 Without it, even the commands that support out-of-band execution will
660 still be run in-band.
662 Under normal QMP command execution, the following apply to each
665 - They are executed in order,
666 - They run only in main thread of QEMU,
667 - They run with the BQL held.
669 When a command is executed with OOB, the following changes occur:
671 - They can be completed before a pending in-band command,
672 - They run in a dedicated monitor thread,
673 - They run with the BQL not held.
675 OOB command handlers must satisfy the following conditions:
677 - It terminates quickly,
678 - It does not invoke system calls that may block,
679 - It does not access guest RAM that may block when userfaultfd is
680 enabled for postcopy live migration,
681 - It takes only "fast" locks, i.e. all critical sections protected by
682 any lock it takes also satisfy the conditions for OOB command
685 The restrictions on locking limit access to shared state. Such access
686 requires synchronization, but OOB commands can't take the BQL or any
689 If in doubt, do not implement OOB execution support.
691 A command may use the optional 'allow-preconfig' key to permit its execution
692 at early runtime configuration stage (preconfig runstate).
693 If not specified then a command defaults to 'allow-preconfig': false.
695 An example of declaring a command that is enabled during preconfig:
696 { 'command': 'qmp_capabilities',
697 'data': { '*enable': [ 'QMPCapability' ] },
698 'allow-preconfig': true }
702 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
705 Events are defined with the keyword 'event'. It is not allowed to
706 name an event 'MAX', since the generator also produces a C enumeration
707 of all event names with a generated _MAX value at the end. When
708 'data' is also specified, additional info will be included in the
709 event, with similar semantics to a 'struct' expression. Finally there
710 will be C API generated in qapi-events.h; when called by QEMU code, a
711 message with timestamp will be emitted on the wire.
715 { 'event': 'EVENT_C',
716 'data': { '*a': 'int', 'b': 'str' } }
718 Resulting in this JSON object:
720 { "event": "EVENT_C",
721 "data": { "b": "test string" },
722 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
724 The generator emits a function to send the event. Normally, 'data' is
725 a dictionary for an anonymous type, or names a struct type (possibly
726 empty, but not a union), and its members are passed as separate
727 arguments to this function. If the event definition includes a key
728 'boxed' with the boolean value true, then 'data' is instead the name of
729 any non-empty complex type (struct, union, or alternate), and a
730 pointer to that QAPI type is passed as a single argument.
733 === Downstream extensions ===
735 QAPI schema names that are externally visible, say in the Client JSON
736 Protocol, need to be managed with care. Names starting with a
737 downstream prefix of the form __RFQDN_ are reserved for the downstream
738 who controls the valid, reverse fully qualified domain name RFQDN.
739 RFQDN may only contain ASCII letters, digits, hyphen and period.
741 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
742 downstream command __com.redhat_drive-mirror.
745 == Client JSON Protocol introspection ==
747 Clients of a Client JSON Protocol commonly need to figure out what
748 exactly the server (QEMU) supports.
750 For this purpose, QMP provides introspection via command
751 query-qmp-schema. QGA currently doesn't support introspection.
753 While Client JSON Protocol wire compatibility should be maintained
754 between qemu versions, we cannot make the same guarantees for
755 introspection stability. For example, one version of qemu may provide
756 a non-variant optional member of a struct, and a later version rework
757 the member to instead be non-optional and associated with a variant.
758 Likewise, one version of qemu may list a member with open-ended type
759 'str', and a later version could convert it to a finite set of strings
760 via an enum type; or a member may be converted from a specific type to
761 an alternate that represents a choice between the original type and
764 query-qmp-schema returns a JSON array of SchemaInfo objects. These
765 objects together describe the wire ABI, as defined in the QAPI schema.
766 There is no specified order to the SchemaInfo objects returned; a
767 client must search for a particular name throughout the entire array
768 to learn more about that name, but is at least guaranteed that there
769 will be no collisions between type, command, and event names.
771 However, the SchemaInfo can't reflect all the rules and restrictions
772 that apply to QMP. It's interface introspection (figuring out what's
773 there), not interface specification. The specification is in the QAPI
774 schema. To understand how QMP is to be used, you need to study the
777 Like any other command, query-qmp-schema is itself defined in the QAPI
778 schema, along with the SchemaInfo type. This text attempts to give an
779 overview how things work. For details you need to consult the QAPI
782 SchemaInfo objects have common members "name" and "meta-type", and
783 additional variant members depending on the value of meta-type.
785 Each SchemaInfo object describes a wire ABI entity of a certain
786 meta-type: a command, event or one of several kinds of type.
788 SchemaInfo for commands and events have the same name as in the QAPI
791 Command and event names are part of the wire ABI, but type names are
792 not. Therefore, the SchemaInfo for types have auto-generated
793 meaningless names. For readability, the examples in this section use
794 meaningful type names instead.
796 To examine a type, start with a command or event using it, then follow
799 QAPI schema definitions not reachable that way are omitted.
801 The SchemaInfo for a command has meta-type "command", and variant
802 members "arg-type", "ret-type" and "allow-oob". On the wire, the
803 "arguments" member of a client's "execute" command must conform to the
804 object type named by "arg-type". The "return" member that the server
805 passes in a success response conforms to the type named by
806 "ret-type". When "allow-oob" is set, it means the command supports
807 out-of-band execution.
809 If the command takes no arguments, "arg-type" names an object type
810 without members. Likewise, if the command returns nothing, "ret-type"
811 names an object type without members.
813 Example: the SchemaInfo for command query-qmp-schema
815 { "name": "query-qmp-schema", "meta-type": "command",
816 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
818 Type "q_empty" is an automatic object type without members, and type
819 "SchemaInfoList" is the array of SchemaInfo type.
821 The SchemaInfo for an event has meta-type "event", and variant member
822 "arg-type". On the wire, a "data" member that the server passes in an
823 event conforms to the object type named by "arg-type".
825 If the event carries no additional information, "arg-type" names an
826 object type without members. The event may not have a data member on
829 Each command or event defined with dictionary-valued 'data' in the
830 QAPI schema implicitly defines an object type.
832 Example: the SchemaInfo for EVENT_C from section Events
834 { "name": "EVENT_C", "meta-type": "event",
835 "arg-type": "q_obj-EVENT_C-arg" }
837 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
838 the two members from the event's definition.
840 The SchemaInfo for struct and union types has meta-type "object".
842 The SchemaInfo for a struct type has variant member "members".
844 The SchemaInfo for a union type additionally has variant members "tag"
847 "members" is a JSON array describing the object's common members, if
848 any. Each element is a JSON object with members "name" (the member's
849 name), "type" (the name of its type), and optionally "default". The
850 member is optional if "default" is present. Currently, "default" can
851 only have value null. Other values are reserved for future
852 extensions. The "members" array is in no particular order; clients
853 must search the entire object when learning whether a particular
856 Example: the SchemaInfo for MyType from section Struct types
858 { "name": "MyType", "meta-type": "object",
860 { "name": "member1", "type": "str" },
861 { "name": "member2", "type": "int" },
862 { "name": "member3", "type": "str", "default": null } ] }
864 "tag" is the name of the common member serving as type tag.
865 "variants" is a JSON array describing the object's variant members.
866 Each element is a JSON object with members "case" (the value of type
867 tag this element applies to) and "type" (the name of an object type
868 that provides the variant members for this type tag value). The
869 "variants" array is in no particular order, and is not guaranteed to
870 list cases in the same order as the corresponding "tag" enum type.
872 Example: the SchemaInfo for flat union BlockdevOptions from section
875 { "name": "BlockdevOptions", "meta-type": "object",
877 { "name": "driver", "type": "BlockdevDriver" },
878 { "name": "read-only", "type": "bool", "default": null } ],
881 { "case": "file", "type": "BlockdevOptionsFile" },
882 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
884 Note that base types are "flattened": its members are included in the
887 A simple union implicitly defines an enumeration type for its implicit
888 discriminator (called "type" on the wire, see section Union types).
890 A simple union implicitly defines an object type for each of its
893 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
896 { "name": "BlockdevOptionsSimple", "meta-type": "object",
898 { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
901 { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
902 { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
904 Enumeration type "BlockdevOptionsSimpleKind" and the object types
905 "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
906 are implicitly defined.
908 The SchemaInfo for an alternate type has meta-type "alternate", and
909 variant member "members". "members" is a JSON array. Each element is
910 a JSON object with member "type", which names a type. Values of the
911 alternate type conform to exactly one of its member types. There is
912 no guarantee on the order in which "members" will be listed.
914 Example: the SchemaInfo for BlockdevRef from section Alternate types
916 { "name": "BlockdevRef", "meta-type": "alternate",
918 { "type": "BlockdevOptions" },
919 { "type": "str" } ] }
921 The SchemaInfo for an array type has meta-type "array", and variant
922 member "element-type", which names the array's element type. Array
923 types are implicitly defined. For convenience, the array's name may
924 resemble the element type; however, clients should examine member
925 "element-type" instead of making assumptions based on parsing member
928 Example: the SchemaInfo for ['str']
930 { "name": "[str]", "meta-type": "array",
931 "element-type": "str" }
933 The SchemaInfo for an enumeration type has meta-type "enum" and
934 variant member "values". The values are listed in no particular
935 order; clients must search the entire enum when learning whether a
936 particular value is supported.
938 Example: the SchemaInfo for MyEnum from section Enumeration types
940 { "name": "MyEnum", "meta-type": "enum",
941 "values": [ "value1", "value2", "value3" ] }
943 The SchemaInfo for a built-in type has the same name as the type in
944 the QAPI schema (see section Built-in Types), with one exception
945 detailed below. It has variant member "json-type" that shows how
946 values of this type are encoded on the wire.
948 Example: the SchemaInfo for str
950 { "name": "str", "meta-type": "builtin", "json-type": "string" }
952 The QAPI schema supports a number of integer types that only differ in
953 how they map to C. They are identical as far as SchemaInfo is
954 concerned. Therefore, they get all mapped to a single type "int" in
957 As explained above, type names are not part of the wire ABI. Not even
958 the names of built-in types. Clients should examine member
959 "json-type" instead of hard-coding names of built-in types.
962 == Code generation ==
964 The QAPI code generator qapi-gen.py generates code and documentation
965 from the schema. Together with the core QAPI libraries, this code
966 provides everything required to take JSON commands read in by a Client
967 JSON Protocol server, unmarshal the arguments into the underlying C
968 types, call into the corresponding C function, map the response back
969 to a Client JSON Protocol response to be returned to the user, and
970 introspect the commands.
972 As an example, we'll use the following schema, which describes a
973 single complex user-defined type, along with command which takes a
974 list of that type as a parameter, and returns a single element of that
975 type. The user is responsible for writing the implementation of
976 qmp_my_command(); everything else is produced by the generator.
978 $ cat example-schema.json
979 { 'struct': 'UserDefOne',
980 'data': { 'integer': 'int', '*string': 'str' } }
982 { 'command': 'my-command',
983 'data': { 'arg1': ['UserDefOne'] },
984 'returns': 'UserDefOne' }
986 { 'event': 'MY_EVENT' }
988 We run qapi-gen.py like this:
990 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
991 --prefix="example-" example-schema.json
993 For a more thorough look at generated code, the testsuite includes
994 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
995 what the generator will accept, and compiles the resulting C code as
996 part of 'make check-unit'.
998 === Code generated for QAPI types ===
1000 The following files are created:
1002 $(prefix)qapi-types.h - C types corresponding to types defined in
1005 $(prefix)qapi-types.c - Cleanup functions for the above C types
1007 The $(prefix) is an optional parameter used as a namespace to keep the
1008 generated code from one schema/code-generation separated from others so code
1009 can be generated/used from multiple schemas without clobbering previously
1014 $ cat qapi-generated/example-qapi-types.h
1015 [Uninteresting stuff omitted...]
1017 #ifndef EXAMPLE_QAPI_TYPES_H
1018 #define EXAMPLE_QAPI_TYPES_H
1020 [Built-in types omitted...]
1022 typedef struct UserDefOne UserDefOne;
1024 typedef struct UserDefOneList UserDefOneList;
1026 typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1034 void qapi_free_UserDefOne(UserDefOne *obj);
1036 struct UserDefOneList {
1037 UserDefOneList *next;
1041 void qapi_free_UserDefOneList(UserDefOneList *obj);
1043 struct q_obj_my_command_arg {
1044 UserDefOneList *arg1;
1048 $ cat qapi-generated/example-qapi-types.c
1049 [Uninteresting stuff omitted...]
1051 void qapi_free_UserDefOne(UserDefOne *obj)
1059 v = qapi_dealloc_visitor_new();
1060 visit_type_UserDefOne(v, NULL, &obj, NULL);
1064 void qapi_free_UserDefOneList(UserDefOneList *obj)
1072 v = qapi_dealloc_visitor_new();
1073 visit_type_UserDefOneList(v, NULL, &obj, NULL);
1077 === Code generated for visiting QAPI types ===
1079 These are the visitor functions used to walk through and convert
1080 between a native QAPI C data structure and some other format (such as
1081 QObject); the generated functions are named visit_type_FOO() and
1082 visit_type_FOO_members().
1084 The following files are generated:
1086 $(prefix)qapi-visit.c: Visitor function for a particular C type, used
1087 to automagically convert QObjects into the
1088 corresponding C type and vice-versa, as well
1089 as for deallocating memory for an existing C
1092 $(prefix)qapi-visit.h: Declarations for previously mentioned visitor
1097 $ cat qapi-generated/example-qapi-visit.h
1098 [Uninteresting stuff omitted...]
1100 #ifndef EXAMPLE_QAPI_VISIT_H
1101 #define EXAMPLE_QAPI_VISIT_H
1103 [Visitors for built-in types omitted...]
1105 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1106 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1107 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1109 void visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp);
1112 $ cat qapi-generated/example-qapi-visit.c
1113 [Uninteresting stuff omitted...]
1115 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1119 visit_type_int(v, "integer", &obj->integer, &err);
1123 if (visit_optional(v, "string", &obj->has_string)) {
1124 visit_type_str(v, "string", &obj->string, &err);
1131 error_propagate(errp, err);
1134 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1138 visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err);
1145 visit_type_UserDefOne_members(v, *obj, &err);
1149 visit_check_struct(v, &err);
1151 visit_end_struct(v, (void **)obj);
1152 if (err && visit_is_input(v)) {
1153 qapi_free_UserDefOne(*obj);
1157 error_propagate(errp, err);
1160 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1163 UserDefOneList *tail;
1164 size_t size = sizeof(**obj);
1166 visit_start_list(v, name, (GenericList **)obj, size, &err);
1171 for (tail = *obj; tail;
1172 tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1173 visit_type_UserDefOne(v, NULL, &tail->value, &err);
1180 visit_check_list(v, &err);
1182 visit_end_list(v, (void **)obj);
1183 if (err && visit_is_input(v)) {
1184 qapi_free_UserDefOneList(*obj);
1188 error_propagate(errp, err);
1191 void visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp)
1195 visit_type_UserDefOneList(v, "arg1", &obj->arg1, &err);
1201 error_propagate(errp, err);
1204 === Code generated for commands ===
1206 These are the marshaling/dispatch functions for the commands defined
1207 in the schema. The generated code provides qmp_marshal_COMMAND(), and
1208 declares qmp_COMMAND() that the user must implement.
1210 The following files are generated:
1212 $(prefix)qapi-commands.c: Command marshal/dispatch functions for each
1213 QMP command defined in the schema
1215 $(prefix)qapi-commands.h: Function prototypes for the QMP commands
1216 specified in the schema
1220 $ cat qapi-generated/example-qapi-commands.h
1221 [Uninteresting stuff omitted...]
1223 #ifndef EXAMPLE_QMP_COMMANDS_H
1224 #define EXAMPLE_QMP_COMMANDS_H
1226 #include "example-qapi-types.h"
1227 #include "qapi/qmp/qdict.h"
1228 #include "qapi/qmp/dispatch.h"
1230 void example_qmp_init_marshal(QmpCommandList *cmds);
1231 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1232 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp);
1235 $ cat qapi-generated/example-qapi-commands.c
1236 [Uninteresting stuff omitted...]
1238 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1243 v = qobject_output_visitor_new(ret_out);
1244 visit_type_UserDefOne(v, "unused", &ret_in, &err);
1246 visit_complete(v, ret_out);
1248 error_propagate(errp, err);
1250 v = qapi_dealloc_visitor_new();
1251 visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1255 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1260 q_obj_my_command_arg arg = {0};
1262 v = qobject_input_visitor_new(QOBJECT(args));
1263 visit_start_struct(v, NULL, NULL, 0, &err);
1267 visit_type_q_obj_my_command_arg_members(v, &arg, &err);
1269 visit_check_struct(v, &err);
1271 visit_end_struct(v, NULL);
1276 retval = qmp_my_command(arg.arg1, &err);
1281 qmp_marshal_output_UserDefOne(retval, ret, &err);
1284 error_propagate(errp, err);
1286 v = qapi_dealloc_visitor_new();
1287 visit_start_struct(v, NULL, NULL, 0, NULL);
1288 visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1289 visit_end_struct(v, NULL);
1293 void example_qmp_init_marshal(QmpCommandList *cmds)
1297 qmp_register_command(cmds, "my-command",
1298 qmp_marshal_my_command, QCO_NO_OPTIONS);
1301 === Code generated for events ===
1303 This is the code related to events defined in the schema, providing
1304 qapi_event_send_EVENT().
1306 The following files are created:
1308 $(prefix)qapi-events.h - Function prototypes for each event type, plus an
1309 enumeration of all event names
1311 $(prefix)qapi-events.c - Implementation of functions to send an event
1315 $ cat qapi-generated/example-qapi-events.h
1316 [Uninteresting stuff omitted...]
1318 #ifndef EXAMPLE_QAPI_EVENT_H
1319 #define EXAMPLE_QAPI_EVENT_H
1321 #include "qapi/qmp/qdict.h"
1322 #include "example-qapi-types.h"
1325 void qapi_event_send_my_event(Error **errp);
1327 typedef enum example_QAPIEvent {
1328 EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
1329 EXAMPLE_QAPI_EVENT__MAX = 1,
1330 } example_QAPIEvent;
1332 #define example_QAPIEvent_str(val) \
1333 qapi_enum_lookup(example_QAPIEvent_lookup, (val))
1335 extern const char *const example_QAPIEvent_lookup[];
1338 $ cat qapi-generated/example-qapi-events.c
1339 [Uninteresting stuff omitted...]
1341 void qapi_event_send_my_event(Error **errp)
1345 QMPEventFuncEmit emit;
1347 emit = qmp_event_get_func_emit();
1352 qmp = qmp_event_build_dict("MY_EVENT");
1354 emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err);
1356 error_propagate(errp, err);
1360 const QEnumLookup example_QAPIEvent_lookup = {
1361 .array = (const char *const[]) {
1362 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1364 .size = EXAMPLE_QAPI_EVENT__MAX
1367 === Code generated for introspection ===
1369 The following files are created:
1371 $(prefix)qapi-introspect.c - Defines a string holding a JSON
1372 description of the schema
1374 $(prefix)qapi-introspect.h - Declares the above string
1378 $ cat qapi-generated/example-qapi-introspect.h
1379 [Uninteresting stuff omitted...]
1381 #ifndef EXAMPLE_QMP_INTROSPECT_H
1382 #define EXAMPLE_QMP_INTROSPECT_H
1384 extern const QLitObject qmp_schema_qlit;
1387 $ cat qapi-generated/example-qapi-introspect.c
1388 [Uninteresting stuff omitted...]
1390 const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
1391 QLIT_QDICT(((QLitDictEntry[]) {
1392 { "arg-type", QLIT_QSTR("0") },
1393 { "meta-type", QLIT_QSTR("event") },
1394 { "name", QLIT_QSTR("Event") },
1397 QLIT_QDICT(((QLitDictEntry[]) {
1398 { "members", QLIT_QLIST(((QLitObject[]) {
1401 { "meta-type", QLIT_QSTR("object") },
1402 { "name", QLIT_QSTR("0") },