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 Optional arguments / members are tagged with the phrase '#optional',
135 often with their default value; and extensions added after the
136 expression was first released are also given a '(since x.y.z)'
139 A tagged section starts with one of the following words:
140 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
141 The section ends with the start of a new section.
143 A 'Since: x.y.z' tagged section lists the release that introduced the
151 # Statistics of a virtual block device or a block backing device.
153 # @device: #optional If the stats are for a virtual block device, the name
154 # corresponding to the virtual block device.
156 # @node-name: #optional The node name of the device. (since 2.3)
158 # ... more members ...
162 { 'struct': 'BlockStats',
163 'data': {'*device': 'str', '*node-name': 'str',
164 ... more members ... } }
169 # Query the @BlockStats for all virtual block devices.
171 # @query-nodes: #optional If true, the command will query all the
172 # block nodes ... explain, explain ... (since 2.3)
174 # Returns: A list of @BlockStats for each virtual block devices.
180 # -> { "execute": "query-blockstats" }
182 # ... lots of output ...
186 { 'command': 'query-blockstats',
187 'data': { '*query-nodes': 'bool' },
188 'returns': ['BlockStats'] }
190 ==== Free-form documentation ====
192 A documentation block that isn't an expression documentation block is
193 a free-form documentation block. These may be used to provide
194 additional text and structuring content.
197 === Schema overview ===
199 The schema sets up a series of types, as well as commands and events
200 that will use those types. Forward references are allowed: the parser
201 scans in two passes, where the first pass learns all type names, and
202 the second validates the schema and generates the code. This allows
203 the definition of complex structs that can have mutually recursive
204 types, and allows for indefinite nesting of Client JSON Protocol that
205 satisfies the schema. A type name should not be defined more than
206 once. It is permissible for the schema to contain additional types
207 not used by any commands or events in the Client JSON Protocol, for
208 the side effect of generated C code used internally.
210 There are eight top-level expressions recognized by the parser:
211 'include', 'pragma', 'command', 'struct', 'enum', 'union',
212 'alternate', and 'event'. There are several groups of types: simple
213 types (a number of built-in types, such as 'int' and 'str'; as well as
214 enumerations), complex types (structs and two flavors of unions), and
215 alternate types (a choice between other types). The 'command' and
216 'event' expressions can refer to existing types by name, or list an
217 anonymous type as a dictionary. Listing a type name inside an array
218 refers to a single-dimension array of that type; multi-dimension
219 arrays are not directly supported (although an array of a complex
220 struct that contains an array member is possible).
222 All names must begin with a letter, and contain only ASCII letters,
223 digits, hyphen, and underscore. There are two exceptions: enum values
224 may start with a digit, and names that are downstream extensions (see
225 section Downstream extensions) start with underscore.
227 Names beginning with 'q_' are reserved for the generator, which uses
228 them for munging QMP names that resemble C keywords or other
229 problematic strings. For example, a member named "default" in qapi
230 becomes "q_default" in the generated C code.
232 Types, commands, and events share a common namespace. Therefore,
233 generally speaking, type definitions should always use CamelCase for
234 user-defined type names, while built-in types are lowercase.
236 Type names ending with 'Kind' or 'List' are reserved for the
237 generator, which uses them for implicit union enums and array types,
240 Command names, and member names within a type, should be all lower
241 case with words separated by a hyphen. However, some existing older
242 commands and complex types use underscore; when extending such
243 expressions, consistency is preferred over blindly avoiding
246 Event names should be ALL_CAPS with words separated by underscore.
248 Member names starting with 'has-' or 'has_' are reserved for the
249 generator, which uses them for tracking optional members.
251 Any name (command, event, type, member, or enum value) beginning with
252 "x-" is marked experimental, and may be withdrawn or changed
253 incompatibly in a future release.
255 In the rest of this document, usage lines are given for each
256 expression type, with literal strings written in lower case and
257 placeholders written in capitals. If a literal string includes a
258 prefix of '*', that key/value pair can be omitted from the expression.
259 For example, a usage statement that includes '*base':STRUCT-NAME
260 means that an expression has an optional key 'base', which if present
261 must have a value that forms a struct name.
264 === Built-in Types ===
266 The following types are predefined, and map to C as follows:
269 str char * any JSON string, UTF-8
270 number double any JSON number
271 int int64_t a JSON number without fractional part
272 that fits into the C integer type
274 int16 int16_t likewise
275 int32 int32_t likewise
276 int64 int64_t likewise
277 uint8 uint8_t likewise
278 uint16 uint16_t likewise
279 uint32 uint32_t likewise
280 uint64 uint64_t likewise
281 size uint64_t like uint64_t, except StringInputVisitor
282 accepts size suffixes
283 bool bool JSON true or false
284 any QObject * any JSON value
285 QType QType JSON string matching enum QType values
288 === Include directives ===
290 Usage: { 'include': STRING }
292 The QAPI schema definitions can be modularized using the 'include' directive:
294 { 'include': 'path/to/file.json' }
296 The directive is evaluated recursively, and include paths are relative to the
297 file using the directive. Multiple includes of the same file are
298 idempotent. No other keys should appear in the expression, and the include
299 value should be a string.
301 As a matter of style, it is a good idea to have all files be
302 self-contained, but at the moment, nothing prevents an included file
303 from making a forward reference to a type that is only introduced by
304 an outer file. The parser may be made stricter in the future to
305 prevent incomplete include files.
308 === Pragma directives ===
310 Usage: { 'pragma': DICT }
312 The pragma directive lets you control optional generator behavior.
313 The dictionary's entries are pragma names and values.
315 Pragma's scope is currently the complete schema. Setting the same
316 pragma to different values in parts of the schema doesn't work.
318 Pragma 'doc-required' takes a boolean value. If true, documentation
319 is required. Default is false.
324 Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
326 A struct is a dictionary containing a single 'data' key whose value is
327 a dictionary; the dictionary may be empty. This corresponds to a
328 struct in C or an Object in JSON. Each value of the 'data' dictionary
329 must be the name of a type, or a one-element array containing a type
330 name. An example of a struct is:
332 { 'struct': 'MyType',
333 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
335 The use of '*' as a prefix to the name means the member is optional in
336 the corresponding JSON protocol usage.
338 The default initialization value of an optional argument should not be changed
339 between versions of QEMU unless the new default maintains backward
340 compatibility to the user-visible behavior of the old default.
342 With proper documentation, this policy still allows some flexibility; for
343 example, documenting that a default of 0 picks an optimal buffer size allows
344 one release to declare the optimal size at 512 while another release declares
345 the optimal size at 4096 - the user-visible behavior is not the bytes used by
346 the buffer, but the fact that the buffer was optimal size.
348 On input structures (only mentioned in the 'data' side of a command), changing
349 from mandatory to optional is safe (older clients will supply the option, and
350 newer clients can benefit from the default); changing from optional to
351 mandatory is backwards incompatible (older clients may be omitting the option,
352 and must continue to work).
354 On output structures (only mentioned in the 'returns' side of a command),
355 changing from mandatory to optional is in general unsafe (older clients may be
356 expecting the member, and could crash if it is missing), although it
357 can be done if the only way that the optional argument will be omitted
358 is when it is triggered by the presence of a new input flag to the
359 command that older clients don't know to send. Changing from optional
360 to mandatory is safe.
362 A structure that is used in both input and output of various commands
363 must consider the backwards compatibility constraints of both directions
366 A struct definition can specify another struct as its base.
367 In this case, the members of the base type are included as top-level members
368 of the new struct's dictionary in the Client JSON Protocol wire
369 format. An example definition is:
371 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
372 { 'struct': 'BlockdevOptionsGenericCOWFormat',
373 'base': 'BlockdevOptionsGenericFormat',
374 'data': { '*backing': 'str' } }
376 An example BlockdevOptionsGenericCOWFormat object on the wire could use
377 both members like this:
379 { "file": "/some/place/my-image",
380 "backing": "/some/place/my-backing-file" }
383 === Enumeration types ===
385 Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
386 { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
388 An enumeration type is a dictionary containing a single 'data' key
389 whose value is a list of strings. An example enumeration is:
391 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
393 Nothing prevents an empty enumeration, although it is probably not
394 useful. The list of strings should be lower case; if an enum name
395 represents multiple words, use '-' between words. The string 'max' is
396 not allowed as an enum value, and values should not be repeated.
398 The enum constants will be named by using a heuristic to turn the
399 type name into a set of underscore separated words. For the example
400 above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
401 of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
402 does not result in a desirable name, the optional 'prefix' member
403 can be used when defining the enum.
405 The enumeration values are passed as strings over the Client JSON
406 Protocol, but are encoded as C enum integral values in generated code.
407 While the C code starts numbering at 0, it is better to use explicit
408 comparisons to enum values than implicit comparisons to 0; the C code
409 will also include a generated enum member ending in _MAX for tracking
410 the size of the enum, useful when using common functions for
411 converting between strings and enum values. Since the wire format
412 always passes by name, it is acceptable to reorder or add new
413 enumeration members in any location without breaking clients of Client
414 JSON Protocol; however, removing enum values would break
415 compatibility. For any struct that has a member that will only contain
416 a finite set of string values, using an enum type for that member is
417 better than open-coding the member to be type 'str'.
422 Usage: { 'union': STRING, 'data': DICT }
423 or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME-OR-DICT,
424 'discriminator': ENUM-MEMBER-OF-BASE }
426 Union types are used to let the user choose between several different
427 variants for an object. There are two flavors: simple (no
428 discriminator or base), and flat (both discriminator and base). A union
429 type is defined using a data dictionary as explained in the following
430 paragraphs. The data dictionary for either type of union must not
433 A simple union type defines a mapping from automatic discriminator
434 values to data types like in this example:
436 { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
437 { 'struct': 'BlockdevOptionsQcow2',
438 'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
440 { 'union': 'BlockdevOptionsSimple',
441 'data': { 'file': 'BlockdevOptionsFile',
442 'qcow2': 'BlockdevOptionsQcow2' } }
444 In the Client JSON Protocol, a simple union is represented by a
445 dictionary that contains the 'type' member as a discriminator, and a
446 'data' member that is of the specified data type corresponding to the
447 discriminator value, as in these examples:
449 { "type": "file", "data": { "filename": "/some/place/my-image" } }
450 { "type": "qcow2", "data": { "backing": "/some/place/my-image",
451 "lazy-refcounts": true } }
453 The generated C code uses a struct containing a union. Additionally,
454 an implicit C enum 'NameKind' is created, corresponding to the union
455 'Name', for accessing the various branches of the union. No branch of
456 the union can be named 'max', as this would collide with the implicit
457 enum. The value for each branch can be of any type.
459 A flat union definition avoids nesting on the wire, and specifies a
460 set of common members that occur in all variants of the union. The
461 'base' key must specify either a type name (the type must be a
462 struct, not a union), or a dictionary representing an anonymous type.
463 All branches of the union must be complex types, and the top-level
464 members of the union dictionary on the wire will be combination of
465 members from both the base type and the appropriate branch type (when
466 merging two dictionaries, there must be no keys in common). The
467 'discriminator' member must be the name of a non-optional enum-typed
468 member of the base struct.
470 The following example enhances the above simple union example by
471 adding an optional common member 'read-only', renaming the
472 discriminator to something more applicable than the simple union's
473 default of 'type', and reducing the number of {} required on the wire:
475 { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
476 { 'union': 'BlockdevOptions',
477 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
478 'discriminator': 'driver',
479 'data': { 'file': 'BlockdevOptionsFile',
480 'qcow2': 'BlockdevOptionsQcow2' } }
482 Resulting in these JSON objects:
484 { "driver": "file", "read-only": true,
485 "filename": "/some/place/my-image" }
486 { "driver": "qcow2", "read-only": false,
487 "backing": "/some/place/my-image", "lazy-refcounts": true }
489 Notice that in a flat union, the discriminator name is controlled by
490 the user, but because it must map to a base member with enum type, the
491 code generator can ensure that branches exist for all values of the
492 enum (although the order of the keys need not match the declaration of
493 the enum). In the resulting generated C data types, a flat union is
494 represented as a struct with the base members included directly, and
495 then a union of structures for each branch of the struct.
497 A simple union can always be re-written as a flat union where the base
498 class has a single member named 'type', and where each branch of the
499 union has a struct with a single member named 'data'. That is,
501 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
503 is identical on the wire to:
505 { 'enum': 'Enum', 'data': ['one', 'two'] }
506 { 'struct': 'Branch1', 'data': { 'data': 'str' } }
507 { 'struct': 'Branch2', 'data': { 'data': 'int' } }
508 { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type',
509 'data': { 'one': 'Branch1', 'two': 'Branch2' } }
512 === Alternate types ===
514 Usage: { 'alternate': STRING, 'data': DICT }
516 An alternate type is one that allows a choice between two or more JSON
517 data types (string, integer, number, or object, but currently not
518 array) on the wire. The definition is similar to a simple union type,
519 where each branch of the union names a QAPI type. For example:
521 { 'alternate': 'BlockdevRef',
522 'data': { 'definition': 'BlockdevOptions',
523 'reference': 'str' } }
525 Unlike a union, the discriminator string is never passed on the wire
526 for the Client JSON Protocol. Instead, the value's JSON type serves
527 as an implicit discriminator, which in turn means that an alternate
528 can only express a choice between types represented differently in
529 JSON. If a branch is typed as the 'bool' built-in, the alternate
530 accepts true and false; if it is typed as any of the various numeric
531 built-ins, it accepts a JSON number; if it is typed as a 'str'
532 built-in or named enum type, it accepts a JSON string; and if it is
533 typed as a complex type (struct or union), it accepts a JSON object.
534 Two different complex types, for instance, aren't permitted, because
535 both are represented as a JSON object.
537 The example alternate declaration above allows using both of the
538 following example objects:
540 { "file": "my_existing_block_device_id" }
541 { "file": { "driver": "file",
543 "filename": "/tmp/mydisk.qcow2" } }
548 Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
549 '*returns': TYPE-NAME, '*boxed': true,
550 '*gen': false, '*success-response': false }
552 Commands are defined by using a dictionary containing several members,
553 where three members are most common. The 'command' member is a
554 mandatory string, and determines the "execute" value passed in a
555 Client JSON Protocol command exchange.
557 The 'data' argument maps to the "arguments" dictionary passed in as
558 part of a Client JSON Protocol command. The 'data' member is optional
559 and defaults to {} (an empty dictionary). If present, it must be the
560 string name of a complex type, or a dictionary that declares an
561 anonymous type with the same semantics as a 'struct' expression, with
562 one exception noted below when 'gen' is used.
564 The 'returns' member describes what will appear in the "return" member
565 of a Client JSON Protocol reply on successful completion of a command.
566 The member is optional from the command declaration; if absent, the
567 "return" member will be an empty dictionary. If 'returns' is present,
568 it must be the string name of a complex or built-in type, a
569 one-element array containing the name of a complex or built-in type,
570 with one exception noted below when 'gen' is used. Although it is
571 permitted to have the 'returns' member name a built-in type or an
572 array of built-in types, any command that does this cannot be extended
573 to return additional information in the future; thus, new commands
574 should strongly consider returning a dictionary-based type or an array
575 of dictionaries, even if the dictionary only contains one member at the
578 All commands in Client JSON Protocol use a dictionary to report
579 failure, with no way to specify that in QAPI. Where the error return
580 is different than the usual GenericError class in order to help the
581 client react differently to certain error conditions, it is worth
582 documenting this in the comments before the command declaration.
584 Some example commands:
586 { 'command': 'my-first-command',
587 'data': { 'arg1': 'str', '*arg2': 'str' } }
588 { 'struct': 'MyType', 'data': { '*value': 'str' } }
589 { 'command': 'my-second-command',
590 'returns': [ 'MyType' ] }
592 which would validate this Client JSON Protocol transaction:
594 => { "execute": "my-first-command",
595 "arguments": { "arg1": "hello" } }
597 => { "execute": "my-second-command" }
598 <= { "return": [ { "value": "one" }, { } ] }
600 The generator emits a prototype for the user's function implementing
601 the command. Normally, 'data' is a dictionary for an anonymous type,
602 or names a struct type (possibly empty, but not a union), and its
603 members are passed as separate arguments to this function. If the
604 command definition includes a key 'boxed' with the boolean value true,
605 then 'data' is instead the name of any non-empty complex type
606 (struct, union, or alternate), and a pointer to that QAPI type is
607 passed as a single argument.
609 The generator also emits a marshalling function that extracts
610 arguments for the user's function out of an input QDict, calls the
611 user's function, and if it succeeded, builds an output QObject from
614 In rare cases, QAPI cannot express a type-safe representation of a
615 corresponding Client JSON Protocol command. You then have to suppress
616 generation of a marshalling function by including a key 'gen' with
617 boolean value false, and instead write your own function. Please try
618 to avoid adding new commands that rely on this, and instead use
619 type-safe unions. For an example of this usage:
621 { 'command': 'netdev_add',
622 'data': {'type': 'str', 'id': 'str'},
625 Normally, the QAPI schema is used to describe synchronous exchanges,
626 where a response is expected. But in some cases, the action of a
627 command is expected to change state in a way that a successful
628 response is not possible (although the command will still return a
629 normal dictionary error on failure). When a successful reply is not
630 possible, the command expression should include the optional key
631 'success-response' with boolean value false. So far, only QGA makes
637 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
640 Events are defined with the keyword 'event'. It is not allowed to
641 name an event 'MAX', since the generator also produces a C enumeration
642 of all event names with a generated _MAX value at the end. When
643 'data' is also specified, additional info will be included in the
644 event, with similar semantics to a 'struct' expression. Finally there
645 will be C API generated in qapi-event.h; when called by QEMU code, a
646 message with timestamp will be emitted on the wire.
650 { 'event': 'EVENT_C',
651 'data': { '*a': 'int', 'b': 'str' } }
653 Resulting in this JSON object:
655 { "event": "EVENT_C",
656 "data": { "b": "test string" },
657 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
659 The generator emits a function to send the event. Normally, 'data' is
660 a dictionary for an anonymous type, or names a struct type (possibly
661 empty, but not a union), and its members are passed as separate
662 arguments to this function. If the event definition includes a key
663 'boxed' with the boolean value true, then 'data' is instead the name of
664 any non-empty complex type (struct, union, or alternate), and a
665 pointer to that QAPI type is passed as a single argument.
668 === Downstream extensions ===
670 QAPI schema names that are externally visible, say in the Client JSON
671 Protocol, need to be managed with care. Names starting with a
672 downstream prefix of the form __RFQDN_ are reserved for the downstream
673 who controls the valid, reverse fully qualified domain name RFQDN.
674 RFQDN may only contain ASCII letters, digits, hyphen and period.
676 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
677 downstream command __com.redhat_drive-mirror.
680 == Client JSON Protocol introspection ==
682 Clients of a Client JSON Protocol commonly need to figure out what
683 exactly the server (QEMU) supports.
685 For this purpose, QMP provides introspection via command
686 query-qmp-schema. QGA currently doesn't support introspection.
688 While Client JSON Protocol wire compatibility should be maintained
689 between qemu versions, we cannot make the same guarantees for
690 introspection stability. For example, one version of qemu may provide
691 a non-variant optional member of a struct, and a later version rework
692 the member to instead be non-optional and associated with a variant.
693 Likewise, one version of qemu may list a member with open-ended type
694 'str', and a later version could convert it to a finite set of strings
695 via an enum type; or a member may be converted from a specific type to
696 an alternate that represents a choice between the original type and
699 query-qmp-schema returns a JSON array of SchemaInfo objects. These
700 objects together describe the wire ABI, as defined in the QAPI schema.
701 There is no specified order to the SchemaInfo objects returned; a
702 client must search for a particular name throughout the entire array
703 to learn more about that name, but is at least guaranteed that there
704 will be no collisions between type, command, and event names.
706 However, the SchemaInfo can't reflect all the rules and restrictions
707 that apply to QMP. It's interface introspection (figuring out what's
708 there), not interface specification. The specification is in the QAPI
709 schema. To understand how QMP is to be used, you need to study the
712 Like any other command, query-qmp-schema is itself defined in the QAPI
713 schema, along with the SchemaInfo type. This text attempts to give an
714 overview how things work. For details you need to consult the QAPI
717 SchemaInfo objects have common members "name" and "meta-type", and
718 additional variant members depending on the value of meta-type.
720 Each SchemaInfo object describes a wire ABI entity of a certain
721 meta-type: a command, event or one of several kinds of type.
723 SchemaInfo for commands and events have the same name as in the QAPI
726 Command and event names are part of the wire ABI, but type names are
727 not. Therefore, the SchemaInfo for types have auto-generated
728 meaningless names. For readability, the examples in this section use
729 meaningful type names instead.
731 To examine a type, start with a command or event using it, then follow
734 QAPI schema definitions not reachable that way are omitted.
736 The SchemaInfo for a command has meta-type "command", and variant
737 members "arg-type" and "ret-type". On the wire, the "arguments"
738 member of a client's "execute" command must conform to the object type
739 named by "arg-type". The "return" member that the server passes in a
740 success response conforms to the type named by "ret-type".
742 If the command takes no arguments, "arg-type" names an object type
743 without members. Likewise, if the command returns nothing, "ret-type"
744 names an object type without members.
746 Example: the SchemaInfo for command query-qmp-schema
748 { "name": "query-qmp-schema", "meta-type": "command",
749 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
751 Type "q_empty" is an automatic object type without members, and type
752 "SchemaInfoList" is the array of SchemaInfo type.
754 The SchemaInfo for an event has meta-type "event", and variant member
755 "arg-type". On the wire, a "data" member that the server passes in an
756 event conforms to the object type named by "arg-type".
758 If the event carries no additional information, "arg-type" names an
759 object type without members. The event may not have a data member on
762 Each command or event defined with dictionary-valued 'data' in the
763 QAPI schema implicitly defines an object type.
765 Example: the SchemaInfo for EVENT_C from section Events
767 { "name": "EVENT_C", "meta-type": "event",
768 "arg-type": "q_obj-EVENT_C-arg" }
770 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
771 the two members from the event's definition.
773 The SchemaInfo for struct and union types has meta-type "object".
775 The SchemaInfo for a struct type has variant member "members".
777 The SchemaInfo for a union type additionally has variant members "tag"
780 "members" is a JSON array describing the object's common members, if
781 any. Each element is a JSON object with members "name" (the member's
782 name), "type" (the name of its type), and optionally "default". The
783 member is optional if "default" is present. Currently, "default" can
784 only have value null. Other values are reserved for future
785 extensions. The "members" array is in no particular order; clients
786 must search the entire object when learning whether a particular
789 Example: the SchemaInfo for MyType from section Struct types
791 { "name": "MyType", "meta-type": "object",
793 { "name": "member1", "type": "str" },
794 { "name": "member2", "type": "int" },
795 { "name": "member3", "type": "str", "default": null } ] }
797 "tag" is the name of the common member serving as type tag.
798 "variants" is a JSON array describing the object's variant members.
799 Each element is a JSON object with members "case" (the value of type
800 tag this element applies to) and "type" (the name of an object type
801 that provides the variant members for this type tag value). The
802 "variants" array is in no particular order, and is not guaranteed to
803 list cases in the same order as the corresponding "tag" enum type.
805 Example: the SchemaInfo for flat union BlockdevOptions from section
808 { "name": "BlockdevOptions", "meta-type": "object",
810 { "name": "driver", "type": "BlockdevDriver" },
811 { "name": "read-only", "type": "bool", "default": null } ],
814 { "case": "file", "type": "BlockdevOptionsFile" },
815 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
817 Note that base types are "flattened": its members are included in the
820 A simple union implicitly defines an enumeration type for its implicit
821 discriminator (called "type" on the wire, see section Union types).
823 A simple union implicitly defines an object type for each of its
826 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
829 { "name": "BlockdevOptionsSimple", "meta-type": "object",
831 { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
834 { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
835 { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
837 Enumeration type "BlockdevOptionsSimpleKind" and the object types
838 "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
839 are implicitly defined.
841 The SchemaInfo for an alternate type has meta-type "alternate", and
842 variant member "members". "members" is a JSON array. Each element is
843 a JSON object with member "type", which names a type. Values of the
844 alternate type conform to exactly one of its member types. There is
845 no guarantee on the order in which "members" will be listed.
847 Example: the SchemaInfo for BlockdevRef from section Alternate types
849 { "name": "BlockdevRef", "meta-type": "alternate",
851 { "type": "BlockdevOptions" },
852 { "type": "str" } ] }
854 The SchemaInfo for an array type has meta-type "array", and variant
855 member "element-type", which names the array's element type. Array
856 types are implicitly defined. For convenience, the array's name may
857 resemble the element type; however, clients should examine member
858 "element-type" instead of making assumptions based on parsing member
861 Example: the SchemaInfo for ['str']
863 { "name": "[str]", "meta-type": "array",
864 "element-type": "str" }
866 The SchemaInfo for an enumeration type has meta-type "enum" and
867 variant member "values". The values are listed in no particular
868 order; clients must search the entire enum when learning whether a
869 particular value is supported.
871 Example: the SchemaInfo for MyEnum from section Enumeration types
873 { "name": "MyEnum", "meta-type": "enum",
874 "values": [ "value1", "value2", "value3" ] }
876 The SchemaInfo for a built-in type has the same name as the type in
877 the QAPI schema (see section Built-in Types), with one exception
878 detailed below. It has variant member "json-type" that shows how
879 values of this type are encoded on the wire.
881 Example: the SchemaInfo for str
883 { "name": "str", "meta-type": "builtin", "json-type": "string" }
885 The QAPI schema supports a number of integer types that only differ in
886 how they map to C. They are identical as far as SchemaInfo is
887 concerned. Therefore, they get all mapped to a single type "int" in
890 As explained above, type names are not part of the wire ABI. Not even
891 the names of built-in types. Clients should examine member
892 "json-type" instead of hard-coding names of built-in types.
895 == Code generation ==
897 Schemas are fed into five scripts to generate all the code/files that,
898 paired with the core QAPI libraries, comprise everything required to
899 take JSON commands read in by a Client JSON Protocol server, unmarshal
900 the arguments into the underlying C types, call into the corresponding
901 C function, map the response back to a Client JSON Protocol response
902 to be returned to the user, and introspect the commands.
904 As an example, we'll use the following schema, which describes a
905 single complex user-defined type, along with command which takes a
906 list of that type as a parameter, and returns a single element of that
907 type. The user is responsible for writing the implementation of
908 qmp_my_command(); everything else is produced by the generator.
910 $ cat example-schema.json
911 { 'struct': 'UserDefOne',
912 'data': { 'integer': 'int', '*string': 'str' } }
914 { 'command': 'my-command',
915 'data': { 'arg1': ['UserDefOne'] },
916 'returns': 'UserDefOne' }
918 { 'event': 'MY_EVENT' }
920 For a more thorough look at generated code, the testsuite includes
921 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
922 what the generator will accept, and compiles the resulting C code as
923 part of 'make check-unit'.
925 === scripts/qapi-types.py ===
927 Used to generate the C types defined by a schema, along with
928 supporting code. The following files are created:
930 $(prefix)qapi-types.h - C types corresponding to types defined in
931 the schema you pass in
932 $(prefix)qapi-types.c - Cleanup functions for the above C types
934 The $(prefix) is an optional parameter used as a namespace to keep the
935 generated code from one schema/code-generation separated from others so code
936 can be generated/used from multiple schemas without clobbering previously
941 $ python scripts/qapi-types.py --output-dir="qapi-generated" \
942 --prefix="example-" example-schema.json
943 $ cat qapi-generated/example-qapi-types.h
944 [Uninteresting stuff omitted...]
946 #ifndef EXAMPLE_QAPI_TYPES_H
947 #define EXAMPLE_QAPI_TYPES_H
949 [Built-in types omitted...]
951 typedef struct UserDefOne UserDefOne;
953 typedef struct UserDefOneList UserDefOneList;
961 void qapi_free_UserDefOne(UserDefOne *obj);
963 struct UserDefOneList {
964 UserDefOneList *next;
968 void qapi_free_UserDefOneList(UserDefOneList *obj);
971 $ cat qapi-generated/example-qapi-types.c
972 [Uninteresting stuff omitted...]
974 void qapi_free_UserDefOne(UserDefOne *obj)
982 v = qapi_dealloc_visitor_new();
983 visit_type_UserDefOne(v, NULL, &obj, NULL);
987 void qapi_free_UserDefOneList(UserDefOneList *obj)
995 v = qapi_dealloc_visitor_new();
996 visit_type_UserDefOneList(v, NULL, &obj, NULL);
1000 === scripts/qapi-visit.py ===
1002 Used to generate the visitor functions used to walk through and
1003 convert between a native QAPI C data structure and some other format
1004 (such as QObject); the generated functions are named visit_type_FOO()
1005 and visit_type_FOO_members().
1007 The following files are generated:
1009 $(prefix)qapi-visit.c: visitor function for a particular C type, used
1010 to automagically convert QObjects into the
1011 corresponding C type and vice-versa, as well
1012 as for deallocating memory for an existing C
1015 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
1020 $ python scripts/qapi-visit.py --output-dir="qapi-generated"
1021 --prefix="example-" example-schema.json
1022 $ cat qapi-generated/example-qapi-visit.h
1023 [Uninteresting stuff omitted...]
1025 #ifndef EXAMPLE_QAPI_VISIT_H
1026 #define EXAMPLE_QAPI_VISIT_H
1028 [Visitors for built-in types omitted...]
1030 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1031 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1032 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1035 $ cat qapi-generated/example-qapi-visit.c
1036 [Uninteresting stuff omitted...]
1038 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1042 visit_type_int(v, "integer", &obj->integer, &err);
1046 if (visit_optional(v, "string", &obj->has_string)) {
1047 visit_type_str(v, "string", &obj->string, &err);
1054 error_propagate(errp, err);
1057 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1061 visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err);
1068 visit_type_UserDefOne_members(v, *obj, &err);
1072 visit_check_struct(v, &err);
1074 visit_end_struct(v, (void **)obj);
1075 if (err && visit_is_input(v)) {
1076 qapi_free_UserDefOne(*obj);
1080 error_propagate(errp, err);
1083 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1086 UserDefOneList *tail;
1087 size_t size = sizeof(**obj);
1089 visit_start_list(v, name, (GenericList **)obj, size, &err);
1094 for (tail = *obj; tail;
1095 tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1096 visit_type_UserDefOne(v, NULL, &tail->value, &err);
1102 visit_end_list(v, (void **)obj);
1103 if (err && visit_is_input(v)) {
1104 qapi_free_UserDefOneList(*obj);
1108 error_propagate(errp, err);
1111 === scripts/qapi-commands.py ===
1113 Used to generate the marshaling/dispatch functions for the commands
1114 defined in the schema. The generated code implements
1115 qmp_marshal_COMMAND() (registered automatically), and declares
1116 qmp_COMMAND() that the user must implement. The following files are
1119 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
1120 QMP command defined in the schema. Functions
1121 generated by qapi-visit.py are used to
1122 convert QObjects received from the wire into
1123 function parameters, and uses the same
1124 visitor functions to convert native C return
1125 values to QObjects from transmission back
1128 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
1129 specified in the schema.
1133 $ python scripts/qapi-commands.py --output-dir="qapi-generated"
1134 --prefix="example-" example-schema.json
1135 $ cat qapi-generated/example-qmp-commands.h
1136 [Uninteresting stuff omitted...]
1138 #ifndef EXAMPLE_QMP_COMMANDS_H
1139 #define EXAMPLE_QMP_COMMANDS_H
1141 #include "example-qapi-types.h"
1142 #include "qapi/qmp/qdict.h"
1143 #include "qapi/error.h"
1145 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1148 $ cat qapi-generated/example-qmp-marshal.c
1149 [Uninteresting stuff omitted...]
1151 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1156 v = qobject_output_visitor_new(ret_out);
1157 visit_type_UserDefOne(v, "unused", &ret_in, &err);
1159 visit_complete(v, ret_out);
1161 error_propagate(errp, err);
1163 v = qapi_dealloc_visitor_new();
1164 visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1168 static void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1173 UserDefOneList *arg1 = NULL;
1175 v = qobject_input_visitor_new(QOBJECT(args));
1176 visit_start_struct(v, NULL, NULL, 0, &err);
1180 visit_type_UserDefOneList(v, "arg1", &arg1, &err);
1182 visit_check_struct(v, &err);
1184 visit_end_struct(v, NULL);
1189 retval = qmp_my_command(arg1, &err);
1194 qmp_marshal_output_UserDefOne(retval, ret, &err);
1197 error_propagate(errp, err);
1199 v = qapi_dealloc_visitor_new();
1200 visit_start_struct(v, NULL, NULL, 0, NULL);
1201 visit_type_UserDefOneList(v, "arg1", &arg1, NULL);
1202 visit_end_struct(v, NULL);
1206 static void qmp_init_marshal(void)
1208 qmp_register_command("my-command", qmp_marshal_my_command, QCO_NO_OPTIONS);
1211 qapi_init(qmp_init_marshal);
1213 === scripts/qapi-event.py ===
1215 Used to generate the event-related C code defined by a schema, with
1216 implementations for qapi_event_send_FOO(). The following files are
1219 $(prefix)qapi-event.h - Function prototypes for each event type, plus an
1220 enumeration of all event names
1221 $(prefix)qapi-event.c - Implementation of functions to send an event
1225 $ python scripts/qapi-event.py --output-dir="qapi-generated"
1226 --prefix="example-" example-schema.json
1227 $ cat qapi-generated/example-qapi-event.h
1228 [Uninteresting stuff omitted...]
1230 #ifndef EXAMPLE_QAPI_EVENT_H
1231 #define EXAMPLE_QAPI_EVENT_H
1233 #include "qapi/error.h"
1234 #include "qapi/qmp/qdict.h"
1235 #include "example-qapi-types.h"
1238 void qapi_event_send_my_event(Error **errp);
1240 typedef enum example_QAPIEvent {
1241 EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
1242 EXAMPLE_QAPI_EVENT__MAX = 1,
1243 } example_QAPIEvent;
1245 extern const char *const example_QAPIEvent_lookup[];
1248 $ cat qapi-generated/example-qapi-event.c
1249 [Uninteresting stuff omitted...]
1251 void qapi_event_send_my_event(Error **errp)
1255 QMPEventFuncEmit emit;
1256 emit = qmp_event_get_func_emit();
1261 qmp = qmp_event_build_dict("MY_EVENT");
1263 emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err);
1265 error_propagate(errp, err);
1269 const char *const example_QAPIEvent_lookup[] = {
1270 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1271 [EXAMPLE_QAPI_EVENT__MAX] = NULL,
1274 === scripts/qapi-introspect.py ===
1276 Used to generate the introspection C code for a schema. The following
1279 $(prefix)qmp-introspect.c - Defines a string holding a JSON
1280 description of the schema.
1281 $(prefix)qmp-introspect.h - Declares the above string.
1285 $ python scripts/qapi-introspect.py --output-dir="qapi-generated"
1286 --prefix="example-" example-schema.json
1287 $ cat qapi-generated/example-qmp-introspect.h
1288 [Uninteresting stuff omitted...]
1290 #ifndef EXAMPLE_QMP_INTROSPECT_H
1291 #define EXAMPLE_QMP_INTROSPECT_H
1293 extern const char example_qmp_schema_json[];
1296 $ cat qapi-generated/example-qmp-introspect.c
1297 [Uninteresting stuff omitted...]
1299 const char example_qmp_schema_json[] = "["
1300 "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, "
1301 "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, "
1302 "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, "
1303 "{\"members\": [{\"name\": \"arg1\", \"type\": \"[2]\"}], \"meta-type\": \"object\", \"name\": \"1\"}, "
1304 "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"default\": null, \"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, "
1305 "{\"element-type\": \"2\", \"meta-type\": \"array\", \"name\": \"[2]\"}, "
1306 "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, "
1307 "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]";