1 = How to use the QAPI code generator =
3 Copyright IBM Corp. 2011
4 Copyright (C) 2012-2015 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.
47 Comments are allowed; anything between an unquoted # and the following
48 newline is ignored. Although there is not yet a documentation
49 generator, a form of stylized comments has developed for consistently
50 documenting details about an expression and when it was added to the
51 schema. The documentation is delimited between two lines of ##, then
52 the first line names the expression, an optional overview is provided,
53 then individual documentation about each member of 'data' is provided,
54 and finally, a 'Since: x.y.z' tag lists the release that introduced
55 the expression. Optional fields are tagged with the phrase
56 '#optional', often with their default value; and extensions added
57 after the expression was first released are also given a '(since
58 x.y.z)' comment. For example:
63 # Statistics of a virtual block device or a block backing device.
65 # @device: #optional If the stats are for a virtual block device, the name
66 # corresponding to the virtual block device.
68 # @stats: A @BlockDeviceStats for the device.
70 # @parent: #optional This describes the file block device if it has one.
72 # @backing: #optional This describes the backing block device if it has one.
77 { 'struct': 'BlockStats',
78 'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
79 '*parent': 'BlockStats',
80 '*backing': 'BlockStats'} }
82 The schema sets up a series of types, as well as commands and events
83 that will use those types. Forward references are allowed: the parser
84 scans in two passes, where the first pass learns all type names, and
85 the second validates the schema and generates the code. This allows
86 the definition of complex structs that can have mutually recursive
87 types, and allows for indefinite nesting of Client JSON Protocol that
88 satisfies the schema. A type name should not be defined more than
89 once. It is permissible for the schema to contain additional types
90 not used by any commands or events in the Client JSON Protocol, for
91 the side effect of generated C code used internally.
93 There are seven top-level expressions recognized by the parser:
94 'include', 'command', 'struct', 'enum', 'union', 'alternate', and
95 'event'. There are several groups of types: simple types (a number of
96 built-in types, such as 'int' and 'str'; as well as enumerations),
97 complex types (structs and two flavors of unions), and alternate types
98 (a choice between other types). The 'command' and 'event' expressions
99 can refer to existing types by name, or list an anonymous type as a
100 dictionary. Listing a type name inside an array refers to a
101 single-dimension array of that type; multi-dimension arrays are not
102 directly supported (although an array of a complex struct that
103 contains an array member is possible).
105 Types, commands, and events share a common namespace. Therefore,
106 generally speaking, type definitions should always use CamelCase for
107 user-defined type names, while built-in types are lowercase. Type
108 definitions should not end in 'Kind', as this namespace is used for
109 creating implicit C enums for visiting union types, or in 'List', as
110 this namespace is used for creating array types. Command names,
111 and field names within a type, should be all lower case with words
112 separated by a hyphen. However, some existing older commands and
113 complex types use underscore; when extending such expressions,
114 consistency is preferred over blindly avoiding underscore. Event
115 names should be ALL_CAPS with words separated by underscore. Field
116 names cannot start with 'has-' or 'has_', as this is reserved for
117 tracking optional fields.
119 Any name (command, event, type, field, or enum value) beginning with
120 "x-" is marked experimental, and may be withdrawn or changed
121 incompatibly in a future release. All names must begin with a letter,
122 and contain only ASCII letters, digits, dash, and underscore. There
123 are two exceptions: enum values may start with a digit, and any
124 extensions added by downstream vendors should start with a prefix
125 matching "__RFQDN_" (for the reverse-fully-qualified-domain-name of
126 the vendor), even if the rest of the name uses dash (example:
127 __com.redhat_drive-mirror). Names beginning with 'q_' are reserved
128 for the generator: QMP names that resemble C keywords or other
129 problematic strings will be munged in C to use this prefix. For
130 example, a field named "default" in qapi becomes "q_default" in the
133 In the rest of this document, usage lines are given for each
134 expression type, with literal strings written in lower case and
135 placeholders written in capitals. If a literal string includes a
136 prefix of '*', that key/value pair can be omitted from the expression.
137 For example, a usage statement that includes '*base':STRUCT-NAME
138 means that an expression has an optional key 'base', which if present
139 must have a value that forms a struct name.
142 === Built-in Types ===
144 The following types are predefined, and map to C as follows:
147 str char * any JSON string, UTF-8
148 number double any JSON number
149 int int64_t a JSON number without fractional part
150 that fits into the C integer type
152 int16 int16_t likewise
153 int32 int32_t likewise
154 int64 int64_t likewise
155 uint8 uint8_t likewise
156 uint16 uint16_t likewise
157 uint32 uint32_t likewise
158 uint64 uint64_t likewise
159 size uint64_t like uint64_t, except StringInputVisitor
160 accepts size suffixes
161 bool bool JSON true or false
162 any QObject * any JSON value
163 QType QType JSON string matching enum QType values
168 Usage: { 'include': STRING }
170 The QAPI schema definitions can be modularized using the 'include' directive:
172 { 'include': 'path/to/file.json' }
174 The directive is evaluated recursively, and include paths are relative to the
175 file using the directive. Multiple includes of the same file are
176 idempotent. No other keys should appear in the expression, and the include
177 value should be a string.
179 As a matter of style, it is a good idea to have all files be
180 self-contained, but at the moment, nothing prevents an included file
181 from making a forward reference to a type that is only introduced by
182 an outer file. The parser may be made stricter in the future to
183 prevent incomplete include files.
188 Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
190 A struct is a dictionary containing a single 'data' key whose value is
191 a dictionary; the dictionary may be empty. This corresponds to a
192 struct in C or an Object in JSON. Each value of the 'data' dictionary
193 must be the name of a type, or a one-element array containing a type
194 name. An example of a struct is:
196 { 'struct': 'MyType',
197 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
199 The use of '*' as a prefix to the name means the member is optional in
200 the corresponding JSON protocol usage.
202 The default initialization value of an optional argument should not be changed
203 between versions of QEMU unless the new default maintains backward
204 compatibility to the user-visible behavior of the old default.
206 With proper documentation, this policy still allows some flexibility; for
207 example, documenting that a default of 0 picks an optimal buffer size allows
208 one release to declare the optimal size at 512 while another release declares
209 the optimal size at 4096 - the user-visible behavior is not the bytes used by
210 the buffer, but the fact that the buffer was optimal size.
212 On input structures (only mentioned in the 'data' side of a command), changing
213 from mandatory to optional is safe (older clients will supply the option, and
214 newer clients can benefit from the default); changing from optional to
215 mandatory is backwards incompatible (older clients may be omitting the option,
216 and must continue to work).
218 On output structures (only mentioned in the 'returns' side of a command),
219 changing from mandatory to optional is in general unsafe (older clients may be
220 expecting the field, and could crash if it is missing), although it can be done
221 if the only way that the optional argument will be omitted is when it is
222 triggered by the presence of a new input flag to the command that older clients
223 don't know to send. Changing from optional to mandatory is safe.
225 A structure that is used in both input and output of various commands
226 must consider the backwards compatibility constraints of both directions
229 A struct definition can specify another struct as its base.
230 In this case, the fields of the base type are included as top-level fields
231 of the new struct's dictionary in the Client JSON Protocol wire
232 format. An example definition is:
234 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
235 { 'struct': 'BlockdevOptionsGenericCOWFormat',
236 'base': 'BlockdevOptionsGenericFormat',
237 'data': { '*backing': 'str' } }
239 An example BlockdevOptionsGenericCOWFormat object on the wire could use
240 both fields like this:
242 { "file": "/some/place/my-image",
243 "backing": "/some/place/my-backing-file" }
246 === Enumeration types ===
248 Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
249 { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
251 An enumeration type is a dictionary containing a single 'data' key
252 whose value is a list of strings. An example enumeration is:
254 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
256 Nothing prevents an empty enumeration, although it is probably not
257 useful. The list of strings should be lower case; if an enum name
258 represents multiple words, use '-' between words. The string 'max' is
259 not allowed as an enum value, and values should not be repeated.
261 The enum constants will be named by using a heuristic to turn the
262 type name into a set of underscore separated words. For the example
263 above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
264 of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
265 does not result in a desirable name, the optional 'prefix' field
266 can be used when defining the enum.
268 The enumeration values are passed as strings over the Client JSON
269 Protocol, but are encoded as C enum integral values in generated code.
270 While the C code starts numbering at 0, it is better to use explicit
271 comparisons to enum values than implicit comparisons to 0; the C code
272 will also include a generated enum member ending in _MAX for tracking
273 the size of the enum, useful when using common functions for
274 converting between strings and enum values. Since the wire format
275 always passes by name, it is acceptable to reorder or add new
276 enumeration members in any location without breaking clients of Client
277 JSON Protocol; however, removing enum values would break
278 compatibility. For any struct that has a field that will only contain
279 a finite set of string values, using an enum type for that field is
280 better than open-coding the field to be type 'str'.
285 Usage: { 'union': STRING, 'data': DICT }
286 or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME,
287 'discriminator': ENUM-MEMBER-OF-BASE }
289 Union types are used to let the user choose between several different
290 variants for an object. There are two flavors: simple (no
291 discriminator or base), and flat (both discriminator and base). A union
292 type is defined using a data dictionary as explained in the following
293 paragraphs. The data dictionary for either type of union must not
296 A simple union type defines a mapping from automatic discriminator
297 values to data types like in this example:
299 { 'struct': 'FileOptions', 'data': { 'filename': 'str' } }
300 { 'struct': 'Qcow2Options',
301 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
303 { 'union': 'BlockdevOptions',
304 'data': { 'file': 'FileOptions',
305 'qcow2': 'Qcow2Options' } }
307 In the Client JSON Protocol, a simple union is represented by a
308 dictionary that contains the 'type' field as a discriminator, and a
309 'data' field that is of the specified data type corresponding to the
310 discriminator value, as in these examples:
312 { "type": "file", "data" : { "filename": "/some/place/my-image" } }
313 { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
314 "lazy-refcounts": true } }
316 The generated C code uses a struct containing a union. Additionally,
317 an implicit C enum 'NameKind' is created, corresponding to the union
318 'Name', for accessing the various branches of the union. No branch of
319 the union can be named 'max', as this would collide with the implicit
320 enum. The value for each branch can be of any type.
322 A flat union definition specifies a struct as its base, and
323 avoids nesting on the wire. All branches of the union must be
324 complex types, and the top-level fields of the union dictionary on
325 the wire will be combination of fields from both the base type and the
326 appropriate branch type (when merging two dictionaries, there must be
327 no keys in common). The 'discriminator' field must be the name of an
328 enum-typed member of the base struct.
330 The following example enhances the above simple union example by
331 adding a common field 'readonly', renaming the discriminator to
332 something more applicable, and reducing the number of {} required on
335 { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
336 { 'struct': 'BlockdevCommonOptions',
337 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } }
338 { 'union': 'BlockdevOptions',
339 'base': 'BlockdevCommonOptions',
340 'discriminator': 'driver',
341 'data': { 'file': 'FileOptions',
342 'qcow2': 'Qcow2Options' } }
344 Resulting in these JSON objects:
346 { "driver": "file", "readonly": true,
347 "filename": "/some/place/my-image" }
348 { "driver": "qcow2", "readonly": false,
349 "backing-file": "/some/place/my-image", "lazy-refcounts": true }
351 Notice that in a flat union, the discriminator name is controlled by
352 the user, but because it must map to a base member with enum type, the
353 code generator can ensure that branches exist for all values of the
354 enum (although the order of the keys need not match the declaration of
355 the enum). In the resulting generated C data types, a flat union is
356 represented as a struct with the base member fields included directly,
357 and then a union of structures for each branch of the struct.
359 A simple union can always be re-written as a flat union where the base
360 class has a single member named 'type', and where each branch of the
361 union has a struct with a single member named 'data'. That is,
363 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
365 is identical on the wire to:
367 { 'enum': 'Enum', 'data': ['one', 'two'] }
368 { 'struct': 'Base', 'data': { 'type': 'Enum' } }
369 { 'struct': 'Branch1', 'data': { 'data': 'str' } }
370 { 'struct': 'Branch2', 'data': { 'data': 'int' } }
371 { 'union': 'Flat', 'base': 'Base', 'discriminator': 'type',
372 'data': { 'one': 'Branch1', 'two': 'Branch2' } }
375 === Alternate types ===
377 Usage: { 'alternate': STRING, 'data': DICT }
379 An alternate type is one that allows a choice between two or more JSON
380 data types (string, integer, number, or object, but currently not
381 array) on the wire. The definition is similar to a simple union type,
382 where each branch of the union names a QAPI type. For example:
384 { 'alternate': 'BlockRef',
385 'data': { 'definition': 'BlockdevOptions',
386 'reference': 'str' } }
388 Unlike a union, the discriminator string is never passed on the wire
389 for the Client JSON Protocol. Instead, the value's JSON type serves
390 as an implicit discriminator, which in turn means that an alternate
391 can only express a choice between types represented differently in
392 JSON. If a branch is typed as the 'bool' built-in, the alternate
393 accepts true and false; if it is typed as any of the various numeric
394 built-ins, it accepts a JSON number; if it is typed as a 'str'
395 built-in or named enum type, it accepts a JSON string; and if it is
396 typed as a complex type (struct or union), it accepts a JSON object.
397 Two different complex types, for instance, aren't permitted, because
398 both are represented as a JSON object.
400 The example alternate declaration above allows using both of the
401 following example objects:
403 { "file": "my_existing_block_device_id" }
404 { "file": { "driver": "file",
406 "filename": "/tmp/mydisk.qcow2" } }
411 Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
412 '*returns': TYPE-NAME,
413 '*gen': false, '*success-response': false }
415 Commands are defined by using a dictionary containing several members,
416 where three members are most common. The 'command' member is a
417 mandatory string, and determines the "execute" value passed in a
418 Client JSON Protocol command exchange.
420 The 'data' argument maps to the "arguments" dictionary passed in as
421 part of a Client JSON Protocol command. The 'data' member is optional
422 and defaults to {} (an empty dictionary). If present, it must be the
423 string name of a complex type, or a dictionary that declares an
424 anonymous type with the same semantics as a 'struct' expression, with
425 one exception noted below when 'gen' is used.
427 The 'returns' member describes what will appear in the "return" field
428 of a Client JSON Protocol reply on successful completion of a command.
429 The member is optional from the command declaration; if absent, the
430 "return" field will be an empty dictionary. If 'returns' is present,
431 it must be the string name of a complex or built-in type, a
432 one-element array containing the name of a complex or built-in type,
433 with one exception noted below when 'gen' is used. Although it is
434 permitted to have the 'returns' member name a built-in type or an
435 array of built-in types, any command that does this cannot be extended
436 to return additional information in the future; thus, new commands
437 should strongly consider returning a dictionary-based type or an array
438 of dictionaries, even if the dictionary only contains one field at the
441 All commands in Client JSON Protocol use a dictionary to report
442 failure, with no way to specify that in QAPI. Where the error return
443 is different than the usual GenericError class in order to help the
444 client react differently to certain error conditions, it is worth
445 documenting this in the comments before the command declaration.
447 Some example commands:
449 { 'command': 'my-first-command',
450 'data': { 'arg1': 'str', '*arg2': 'str' } }
451 { 'struct': 'MyType', 'data': { '*value': 'str' } }
452 { 'command': 'my-second-command',
453 'returns': [ 'MyType' ] }
455 which would validate this Client JSON Protocol transaction:
457 => { "execute": "my-first-command",
458 "arguments": { "arg1": "hello" } }
460 => { "execute": "my-second-command" }
461 <= { "return": [ { "value": "one" }, { } ] }
463 In rare cases, QAPI cannot express a type-safe representation of a
464 corresponding Client JSON Protocol command. You then have to suppress
465 generation of a marshalling function by including a key 'gen' with
466 boolean value false, and instead write your own function. Please try
467 to avoid adding new commands that rely on this, and instead use
468 type-safe unions. For an example of this usage:
470 { 'command': 'netdev_add',
471 'data': {'type': 'str', 'id': 'str'},
474 Normally, the QAPI schema is used to describe synchronous exchanges,
475 where a response is expected. But in some cases, the action of a
476 command is expected to change state in a way that a successful
477 response is not possible (although the command will still return a
478 normal dictionary error on failure). When a successful reply is not
479 possible, the command expression should include the optional key
480 'success-response' with boolean value false. So far, only QGA makes
486 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT }
488 Events are defined with the keyword 'event'. It is not allowed to
489 name an event 'MAX', since the generator also produces a C enumeration
490 of all event names with a generated _MAX value at the end. When
491 'data' is also specified, additional info will be included in the
492 event, with similar semantics to a 'struct' expression. Finally there
493 will be C API generated in qapi-event.h; when called by QEMU code, a
494 message with timestamp will be emitted on the wire.
498 { 'event': 'EVENT_C',
499 'data': { '*a': 'int', 'b': 'str' } }
501 Resulting in this JSON object:
503 { "event": "EVENT_C",
504 "data": { "b": "test string" },
505 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
508 == Client JSON Protocol introspection ==
510 Clients of a Client JSON Protocol commonly need to figure out what
511 exactly the server (QEMU) supports.
513 For this purpose, QMP provides introspection via command
514 query-qmp-schema. QGA currently doesn't support introspection.
516 While Client JSON Protocol wire compatibility should be maintained
517 between qemu versions, we cannot make the same guarantees for
518 introspection stability. For example, one version of qemu may provide
519 a non-variant optional member of a struct, and a later version rework
520 the member to instead be non-optional and associated with a variant.
521 Likewise, one version of qemu may list a member with open-ended type
522 'str', and a later version could convert it to a finite set of strings
523 via an enum type; or a member may be converted from a specific type to
524 an alternate that represents a choice between the original type and
527 query-qmp-schema returns a JSON array of SchemaInfo objects. These
528 objects together describe the wire ABI, as defined in the QAPI schema.
529 There is no specified order to the SchemaInfo objects returned; a
530 client must search for a particular name throughout the entire array
531 to learn more about that name, but is at least guaranteed that there
532 will be no collisions between type, command, and event names.
534 However, the SchemaInfo can't reflect all the rules and restrictions
535 that apply to QMP. It's interface introspection (figuring out what's
536 there), not interface specification. The specification is in the QAPI
537 schema. To understand how QMP is to be used, you need to study the
540 Like any other command, query-qmp-schema is itself defined in the QAPI
541 schema, along with the SchemaInfo type. This text attempts to give an
542 overview how things work. For details you need to consult the QAPI
545 SchemaInfo objects have common members "name" and "meta-type", and
546 additional variant members depending on the value of meta-type.
548 Each SchemaInfo object describes a wire ABI entity of a certain
549 meta-type: a command, event or one of several kinds of type.
551 SchemaInfo for commands and events have the same name as in the QAPI
554 Command and event names are part of the wire ABI, but type names are
555 not. Therefore, the SchemaInfo for types have auto-generated
556 meaningless names. For readability, the examples in this section use
557 meaningful type names instead.
559 To examine a type, start with a command or event using it, then follow
562 QAPI schema definitions not reachable that way are omitted.
564 The SchemaInfo for a command has meta-type "command", and variant
565 members "arg-type" and "ret-type". On the wire, the "arguments"
566 member of a client's "execute" command must conform to the object type
567 named by "arg-type". The "return" member that the server passes in a
568 success response conforms to the type named by "ret-type".
570 If the command takes no arguments, "arg-type" names an object type
571 without members. Likewise, if the command returns nothing, "ret-type"
572 names an object type without members.
574 Example: the SchemaInfo for command query-qmp-schema
576 { "name": "query-qmp-schema", "meta-type": "command",
577 "arg-type": ":empty", "ret-type": "SchemaInfoList" }
579 Type ":empty" is an object type without members, and type
580 "SchemaInfoList" is the array of SchemaInfo type.
582 The SchemaInfo for an event has meta-type "event", and variant member
583 "arg-type". On the wire, a "data" member that the server passes in an
584 event conforms to the object type named by "arg-type".
586 If the event carries no additional information, "arg-type" names an
587 object type without members. The event may not have a data member on
590 Each command or event defined with dictionary-valued 'data' in the
591 QAPI schema implicitly defines an object type.
593 Example: the SchemaInfo for EVENT_C from section Events
595 { "name": "EVENT_C", "meta-type": "event",
596 "arg-type": ":obj-EVENT_C-arg" }
598 Type ":obj-EVENT_C-arg" is an implicitly defined object type with
599 the two members from the event's definition.
601 The SchemaInfo for struct and union types has meta-type "object".
603 The SchemaInfo for a struct type has variant member "members".
605 The SchemaInfo for a union type additionally has variant members "tag"
608 "members" is a JSON array describing the object's common members, if
609 any. Each element is a JSON object with members "name" (the member's
610 name), "type" (the name of its type), and optionally "default". The
611 member is optional if "default" is present. Currently, "default" can
612 only have value null. Other values are reserved for future
613 extensions. The "members" array is in no particular order; clients
614 must search the entire object when learning whether a particular
617 Example: the SchemaInfo for MyType from section Struct types
619 { "name": "MyType", "meta-type": "object",
621 { "name": "member1", "type": "str" },
622 { "name": "member2", "type": "int" },
623 { "name": "member3", "type": "str", "default": null } ] }
625 "tag" is the name of the common member serving as type tag.
626 "variants" is a JSON array describing the object's variant members.
627 Each element is a JSON object with members "case" (the value of type
628 tag this element applies to) and "type" (the name of an object type
629 that provides the variant members for this type tag value). The
630 "variants" array is in no particular order, and is not guaranteed to
631 list cases in the same order as the corresponding "tag" enum type.
633 Example: the SchemaInfo for flat union BlockdevOptions from section
636 { "name": "BlockdevOptions", "meta-type": "object",
638 { "name": "driver", "type": "BlockdevDriver" },
639 { "name": "readonly", "type": "bool"} ],
642 { "case": "file", "type": "FileOptions" },
643 { "case": "qcow2", "type": "Qcow2Options" } ] }
645 Note that base types are "flattened": its members are included in the
648 A simple union implicitly defines an enumeration type for its implicit
649 discriminator (called "type" on the wire, see section Union types).
651 A simple union implicitly defines an object type for each of its
654 Example: the SchemaInfo for simple union BlockdevOptions from section
657 { "name": "BlockdevOptions", "meta-type": "object",
659 { "name": "kind", "type": "BlockdevOptionsKind" } ],
662 { "case": "file", "type": ":obj-FileOptions-wrapper" },
663 { "case": "qcow2", "type": ":obj-Qcow2Options-wrapper" } ] }
665 Enumeration type "BlockdevOptionsKind" and the object types
666 ":obj-FileOptions-wrapper", ":obj-Qcow2Options-wrapper" are
669 The SchemaInfo for an alternate type has meta-type "alternate", and
670 variant member "members". "members" is a JSON array. Each element is
671 a JSON object with member "type", which names a type. Values of the
672 alternate type conform to exactly one of its member types. There is
673 no guarantee on the order in which "members" will be listed.
675 Example: the SchemaInfo for BlockRef from section Alternate types
677 { "name": "BlockRef", "meta-type": "alternate",
679 { "type": "BlockdevOptions" },
680 { "type": "str" } ] }
682 The SchemaInfo for an array type has meta-type "array", and variant
683 member "element-type", which names the array's element type. Array
684 types are implicitly defined. For convenience, the array's name may
685 resemble the element type; however, clients should examine member
686 "element-type" instead of making assumptions based on parsing member
689 Example: the SchemaInfo for ['str']
691 { "name": "[str]", "meta-type": "array",
692 "element-type": "str" }
694 The SchemaInfo for an enumeration type has meta-type "enum" and
695 variant member "values". The values are listed in no particular
696 order; clients must search the entire enum when learning whether a
697 particular value is supported.
699 Example: the SchemaInfo for MyEnum from section Enumeration types
701 { "name": "MyEnum", "meta-type": "enum",
702 "values": [ "value1", "value2", "value3" ] }
704 The SchemaInfo for a built-in type has the same name as the type in
705 the QAPI schema (see section Built-in Types), with one exception
706 detailed below. It has variant member "json-type" that shows how
707 values of this type are encoded on the wire.
709 Example: the SchemaInfo for str
711 { "name": "str", "meta-type": "builtin", "json-type": "string" }
713 The QAPI schema supports a number of integer types that only differ in
714 how they map to C. They are identical as far as SchemaInfo is
715 concerned. Therefore, they get all mapped to a single type "int" in
718 As explained above, type names are not part of the wire ABI. Not even
719 the names of built-in types. Clients should examine member
720 "json-type" instead of hard-coding names of built-in types.
723 == Code generation ==
725 Schemas are fed into four scripts to generate all the code/files that,
726 paired with the core QAPI libraries, comprise everything required to
727 take JSON commands read in by a Client JSON Protocol server, unmarshal
728 the arguments into the underlying C types, call into the corresponding
729 C function, and map the response back to a Client JSON Protocol
730 response to be returned to the user.
732 As an example, we'll use the following schema, which describes a single
733 complex user-defined type (which will produce a C struct, along with a list
734 node structure that can be used to chain together a list of such types in
735 case we want to accept/return a list of this type with a command), and a
736 command which takes that type as a parameter and returns the same type:
738 $ cat example-schema.json
739 { 'struct': 'UserDefOne',
740 'data': { 'integer': 'int', 'string': 'str' } }
742 { 'command': 'my-command',
743 'data': {'arg1': 'UserDefOne'},
744 'returns': 'UserDefOne' }
746 { 'event': 'MY_EVENT' }
748 === scripts/qapi-types.py ===
750 Used to generate the C types defined by a schema. The following files are
753 $(prefix)qapi-types.h - C types corresponding to types defined in
754 the schema you pass in
755 $(prefix)qapi-types.c - Cleanup functions for the above C types
757 The $(prefix) is an optional parameter used as a namespace to keep the
758 generated code from one schema/code-generation separated from others so code
759 can be generated/used from multiple schemas without clobbering previously
764 $ python scripts/qapi-types.py --output-dir="qapi-generated" \
765 --prefix="example-" example-schema.json
766 $ cat qapi-generated/example-qapi-types.c
767 [Uninteresting stuff omitted...]
769 void qapi_free_UserDefOne(UserDefOne *obj)
771 QapiDeallocVisitor *qdv;
778 qdv = qapi_dealloc_visitor_new();
779 v = qapi_dealloc_get_visitor(qdv);
780 visit_type_UserDefOne(v, &obj, NULL, NULL);
781 qapi_dealloc_visitor_cleanup(qdv);
784 void qapi_free_UserDefOneList(UserDefOneList *obj)
786 QapiDeallocVisitor *qdv;
793 qdv = qapi_dealloc_visitor_new();
794 v = qapi_dealloc_get_visitor(qdv);
795 visit_type_UserDefOneList(v, &obj, NULL, NULL);
796 qapi_dealloc_visitor_cleanup(qdv);
798 $ cat qapi-generated/example-qapi-types.h
799 [Uninteresting stuff omitted...]
801 #ifndef EXAMPLE_QAPI_TYPES_H
802 #define EXAMPLE_QAPI_TYPES_H
804 [Built-in types omitted...]
806 typedef struct UserDefOne UserDefOne;
808 typedef struct UserDefOneList UserDefOneList;
815 void qapi_free_UserDefOne(UserDefOne *obj);
817 struct UserDefOneList {
822 UserDefOneList *next;
825 void qapi_free_UserDefOneList(UserDefOneList *obj);
829 === scripts/qapi-visit.py ===
831 Used to generate the visitor functions used to walk through and convert
832 a QObject (as provided by QMP) to a native C data structure and
833 vice-versa, as well as the visitor function used to dealloc a complex
834 schema-defined C type.
836 The following files are generated:
838 $(prefix)qapi-visit.c: visitor function for a particular C type, used
839 to automagically convert QObjects into the
840 corresponding C type and vice-versa, as well
841 as for deallocating memory for an existing C
844 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
849 $ python scripts/qapi-visit.py --output-dir="qapi-generated"
850 --prefix="example-" example-schema.json
851 $ cat qapi-generated/example-qapi-visit.c
852 [Uninteresting stuff omitted...]
854 static void visit_type_UserDefOne_fields(Visitor *v, UserDefOne **obj, Error **errp)
858 visit_type_int(v, &(*obj)->integer, "integer", &err);
862 visit_type_str(v, &(*obj)->string, "string", &err);
868 error_propagate(errp, err);
871 void visit_type_UserDefOne(Visitor *v, UserDefOne **obj, const char *name, Error **errp)
875 visit_start_struct(v, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), &err);
878 visit_type_UserDefOne_fields(v, obj, errp);
880 visit_end_struct(v, &err);
882 error_propagate(errp, err);
885 void visit_type_UserDefOneList(Visitor *v, UserDefOneList **obj, const char *name, Error **errp)
888 GenericList *i, **prev;
890 visit_start_list(v, name, &err);
895 for (prev = (GenericList **)obj;
896 !err && (i = visit_next_list(v, prev, &err)) != NULL;
898 UserDefOneList *native_i = (UserDefOneList *)i;
899 visit_type_UserDefOne(v, &native_i->value, NULL, &err);
902 error_propagate(errp, err);
904 visit_end_list(v, &err);
906 error_propagate(errp, err);
908 $ cat qapi-generated/example-qapi-visit.h
909 [Uninteresting stuff omitted...]
911 #ifndef EXAMPLE_QAPI_VISIT_H
912 #define EXAMPLE_QAPI_VISIT_H
914 [Visitors for built-in types omitted...]
916 void visit_type_UserDefOne(Visitor *v, UserDefOne **obj, const char *name, Error **errp);
917 void visit_type_UserDefOneList(Visitor *v, UserDefOneList **obj, const char *name, Error **errp);
921 === scripts/qapi-commands.py ===
923 Used to generate the marshaling/dispatch functions for the commands defined
924 in the schema. The following files are generated:
926 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
927 QMP command defined in the schema. Functions
928 generated by qapi-visit.py are used to
929 convert QObjects received from the wire into
930 function parameters, and uses the same
931 visitor functions to convert native C return
932 values to QObjects from transmission back
935 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
936 specified in the schema.
940 $ python scripts/qapi-commands.py --output-dir="qapi-generated"
941 --prefix="example-" example-schema.json
942 $ cat qapi-generated/example-qmp-marshal.c
943 [Uninteresting stuff omitted...]
945 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
948 QmpOutputVisitor *qov = qmp_output_visitor_new();
949 QapiDeallocVisitor *qdv;
952 v = qmp_output_get_visitor(qov);
953 visit_type_UserDefOne(v, &ret_in, "unused", &err);
957 *ret_out = qmp_output_get_qobject(qov);
960 error_propagate(errp, err);
961 qmp_output_visitor_cleanup(qov);
962 qdv = qapi_dealloc_visitor_new();
963 v = qapi_dealloc_get_visitor(qdv);
964 visit_type_UserDefOne(v, &ret_in, "unused", NULL);
965 qapi_dealloc_visitor_cleanup(qdv);
968 static void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
972 QmpInputVisitor *qiv = qmp_input_visitor_new_strict(QOBJECT(args));
973 QapiDeallocVisitor *qdv;
975 UserDefOne *arg1 = NULL;
977 v = qmp_input_get_visitor(qiv);
978 visit_type_UserDefOne(v, &arg1, "arg1", &err);
983 retval = qmp_my_command(arg1, &err);
988 qmp_marshal_output_UserDefOne(retval, ret, &err);
991 error_propagate(errp, err);
992 qmp_input_visitor_cleanup(qiv);
993 qdv = qapi_dealloc_visitor_new();
994 v = qapi_dealloc_get_visitor(qdv);
995 visit_type_UserDefOne(v, &arg1, "arg1", NULL);
996 qapi_dealloc_visitor_cleanup(qdv);
999 static void qmp_init_marshal(void)
1001 qmp_register_command("my-command", qmp_marshal_my_command, QCO_NO_OPTIONS);
1004 qapi_init(qmp_init_marshal);
1005 $ cat qapi-generated/example-qmp-commands.h
1006 [Uninteresting stuff omitted...]
1008 #ifndef EXAMPLE_QMP_COMMANDS_H
1009 #define EXAMPLE_QMP_COMMANDS_H
1011 #include "example-qapi-types.h"
1012 #include "qapi/qmp/qdict.h"
1013 #include "qapi/error.h"
1015 UserDefOne *qmp_my_command(UserDefOne *arg1, Error **errp);
1019 === scripts/qapi-event.py ===
1021 Used to generate the event-related C code defined by a schema. The
1022 following files are created:
1024 $(prefix)qapi-event.h - Function prototypes for each event type, plus an
1025 enumeration of all event names
1026 $(prefix)qapi-event.c - Implementation of functions to send an event
1030 $ python scripts/qapi-event.py --output-dir="qapi-generated"
1031 --prefix="example-" example-schema.json
1032 $ cat qapi-generated/example-qapi-event.c
1033 [Uninteresting stuff omitted...]
1035 void qapi_event_send_my_event(Error **errp)
1039 QMPEventFuncEmit emit;
1040 emit = qmp_event_get_func_emit();
1045 qmp = qmp_event_build_dict("MY_EVENT");
1047 emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err);
1049 error_propagate(errp, err);
1053 const char *const example_QAPIEvent_lookup[] = {
1054 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1055 [EXAMPLE_QAPI_EVENT__MAX] = NULL,
1057 $ cat qapi-generated/example-qapi-event.h
1058 [Uninteresting stuff omitted...]
1060 #ifndef EXAMPLE_QAPI_EVENT_H
1061 #define EXAMPLE_QAPI_EVENT_H
1063 #include "qapi/error.h"
1064 #include "qapi/qmp/qdict.h"
1065 #include "example-qapi-types.h"
1068 void qapi_event_send_my_event(Error **errp);
1070 typedef enum example_QAPIEvent {
1071 EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
1072 EXAMPLE_QAPI_EVENT__MAX = 1,
1073 } example_QAPIEvent;
1075 extern const char *const example_QAPIEvent_lookup[];
1079 === scripts/qapi-introspect.py ===
1081 Used to generate the introspection C code for a schema. The following
1084 $(prefix)qmp-introspect.c - Defines a string holding a JSON
1085 description of the schema.
1086 $(prefix)qmp-introspect.h - Declares the above string.
1090 $ python scripts/qapi-introspect.py --output-dir="qapi-generated"
1091 --prefix="example-" example-schema.json
1092 $ cat qapi-generated/example-qmp-introspect.c
1093 [Uninteresting stuff omitted...]
1095 const char example_qmp_schema_json[] = "["
1096 "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, "
1097 "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, "
1098 "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, "
1099 "{\"members\": [{\"name\": \"arg1\", \"type\": \"2\"}], \"meta-type\": \"object\", \"name\": \"1\"}, "
1100 "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, "
1101 "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, "
1102 "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]";
1103 $ cat qapi-generated/example-qmp-introspect.h
1104 [Uninteresting stuff omitted...]
1106 #ifndef EXAMPLE_QMP_INTROSPECT_H
1107 #define EXAMPLE_QMP_INTROSPECT_H
1109 extern const char example_qmp_schema_json[];