migration: force QEMUFile to blocking mode for outgoing migration
[qemu.git] / docs / qapi-code-gen.txt
1 = How to use the QAPI code generator =
2
3 Copyright IBM Corp. 2011
4 Copyright (C) 2012-2016 Red Hat, Inc.
5
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.
8
9 == Introduction ==
10
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.
18
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.
24
25
26 == QMP/Guest agent schema ==
27
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.
46
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 members 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:
59
60     ##
61     # @BlockStats:
62     #
63     # Statistics of a virtual block device or a block backing device.
64     #
65     # @device: #optional If the stats are for a virtual block device, the name
66     #          corresponding to the virtual block device.
67     #
68     # @stats:  A @BlockDeviceStats for the device.
69     #
70     # @parent: #optional This describes the file block device if it has one.
71     #
72     # @backing: #optional This describes the backing block device if it has one.
73     #           (Since 2.0)
74     #
75     # Since: 0.14.0
76     ##
77     { 'struct': 'BlockStats',
78       'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
79                '*parent': 'BlockStats',
80                '*backing': 'BlockStats'} }
81
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.
92
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).
104
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 member 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.  Member
116 names cannot start with 'has-' or 'has_', as this is reserved for
117 tracking optional members.
118
119 Any name (command, event, type, member, 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 member named "default" in qapi becomes "q_default" in the
131 generated C code.
132
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.
140
141
142 === Built-in Types ===
143
144 The following types are predefined, and map to C as follows:
145
146   Schema    C          JSON
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
151   int8      int8_t     likewise
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
164
165
166 === Includes ===
167
168 Usage: { 'include': STRING }
169
170 The QAPI schema definitions can be modularized using the 'include' directive:
171
172  { 'include': 'path/to/file.json' }
173
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.
178
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.
184
185
186 === Struct types ===
187
188 Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
189
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:
195
196  { 'struct': 'MyType',
197    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
198
199 The use of '*' as a prefix to the name means the member is optional in
200 the corresponding JSON protocol usage.
201
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.
205
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.
211
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).
217
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 member, and could crash if it is missing), although it
221 can be done if the only way that the optional argument will be omitted
222 is when it is triggered by the presence of a new input flag to the
223 command that older clients don't know to send.  Changing from optional
224 to mandatory is safe.
225
226 A structure that is used in both input and output of various commands
227 must consider the backwards compatibility constraints of both directions
228 of use.
229
230 A struct definition can specify another struct as its base.
231 In this case, the members of the base type are included as top-level members
232 of the new struct's dictionary in the Client JSON Protocol wire
233 format. An example definition is:
234
235  { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
236  { 'struct': 'BlockdevOptionsGenericCOWFormat',
237    'base': 'BlockdevOptionsGenericFormat',
238    'data': { '*backing': 'str' } }
239
240 An example BlockdevOptionsGenericCOWFormat object on the wire could use
241 both members like this:
242
243  { "file": "/some/place/my-image",
244    "backing": "/some/place/my-backing-file" }
245
246
247 === Enumeration types ===
248
249 Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
250        { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
251
252 An enumeration type is a dictionary containing a single 'data' key
253 whose value is a list of strings.  An example enumeration is:
254
255  { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
256
257 Nothing prevents an empty enumeration, although it is probably not
258 useful.  The list of strings should be lower case; if an enum name
259 represents multiple words, use '-' between words.  The string 'max' is
260 not allowed as an enum value, and values should not be repeated.
261
262 The enum constants will be named by using a heuristic to turn the
263 type name into a set of underscore separated words. For the example
264 above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
265 of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
266 does not result in a desirable name, the optional 'prefix' member
267 can be used when defining the enum.
268
269 The enumeration values are passed as strings over the Client JSON
270 Protocol, but are encoded as C enum integral values in generated code.
271 While the C code starts numbering at 0, it is better to use explicit
272 comparisons to enum values than implicit comparisons to 0; the C code
273 will also include a generated enum member ending in _MAX for tracking
274 the size of the enum, useful when using common functions for
275 converting between strings and enum values.  Since the wire format
276 always passes by name, it is acceptable to reorder or add new
277 enumeration members in any location without breaking clients of Client
278 JSON Protocol; however, removing enum values would break
279 compatibility.  For any struct that has a member that will only contain
280 a finite set of string values, using an enum type for that member is
281 better than open-coding the member to be type 'str'.
282
283
284 === Union types ===
285
286 Usage: { 'union': STRING, 'data': DICT }
287 or:    { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME-OR-DICT,
288          'discriminator': ENUM-MEMBER-OF-BASE }
289
290 Union types are used to let the user choose between several different
291 variants for an object.  There are two flavors: simple (no
292 discriminator or base), and flat (both discriminator and base).  A union
293 type is defined using a data dictionary as explained in the following
294 paragraphs.  The data dictionary for either type of union must not
295 be empty.
296
297 A simple union type defines a mapping from automatic discriminator
298 values to data types like in this example:
299
300  { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
301  { 'struct': 'BlockdevOptionsQcow2',
302    'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
303
304  { 'union': 'BlockdevOptionsSimple',
305    'data': { 'file': 'BlockdevOptionsFile',
306              'qcow2': 'BlockdevOptionsQcow2' } }
307
308 In the Client JSON Protocol, a simple union is represented by a
309 dictionary that contains the 'type' member as a discriminator, and a
310 'data' member that is of the specified data type corresponding to the
311 discriminator value, as in these examples:
312
313  { "type": "file", "data": { "filename": "/some/place/my-image" } }
314  { "type": "qcow2", "data": { "backing": "/some/place/my-image",
315                               "lazy-refcounts": true } }
316
317 The generated C code uses a struct containing a union. Additionally,
318 an implicit C enum 'NameKind' is created, corresponding to the union
319 'Name', for accessing the various branches of the union.  No branch of
320 the union can be named 'max', as this would collide with the implicit
321 enum.  The value for each branch can be of any type.
322
323 A flat union definition avoids nesting on the wire, and specifies a
324 set of common members that occur in all variants of the union.  The
325 'base' key must specifiy either a type name (the type must be a
326 struct, not a union), or a dictionary representing an anonymous type.
327 All branches of the union must be complex types, and the top-level
328 members of the union dictionary on the wire will be combination of
329 members from both the base type and the appropriate branch type (when
330 merging two dictionaries, there must be no keys in common).  The
331 'discriminator' member must be the name of a non-optional enum-typed
332 member of the base struct.
333
334 The following example enhances the above simple union example by
335 adding an optional common member 'read-only', renaming the
336 discriminator to something more applicable than the simple union's
337 default of 'type', and reducing the number of {} required on the wire:
338
339  { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
340  { 'union': 'BlockdevOptions',
341    'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
342    'discriminator': 'driver',
343    'data': { 'file': 'BlockdevOptionsFile',
344              'qcow2': 'BlockdevOptionsQcow2' } }
345
346 Resulting in these JSON objects:
347
348  { "driver": "file", "read-only": true,
349    "filename": "/some/place/my-image" }
350  { "driver": "qcow2", "read-only": false,
351    "backing": "/some/place/my-image", "lazy-refcounts": true }
352
353 Notice that in a flat union, the discriminator name is controlled by
354 the user, but because it must map to a base member with enum type, the
355 code generator can ensure that branches exist for all values of the
356 enum (although the order of the keys need not match the declaration of
357 the enum).  In the resulting generated C data types, a flat union is
358 represented as a struct with the base members included directly, and
359 then a union of structures for each branch of the struct.
360
361 A simple union can always be re-written as a flat union where the base
362 class has a single member named 'type', and where each branch of the
363 union has a struct with a single member named 'data'.  That is,
364
365  { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
366
367 is identical on the wire to:
368
369  { 'enum': 'Enum', 'data': ['one', 'two'] }
370  { 'struct': 'Branch1', 'data': { 'data': 'str' } }
371  { 'struct': 'Branch2', 'data': { 'data': 'int' } }
372  { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type',
373    'data': { 'one': 'Branch1', 'two': 'Branch2' } }
374
375
376 === Alternate types ===
377
378 Usage: { 'alternate': STRING, 'data': DICT }
379
380 An alternate type is one that allows a choice between two or more JSON
381 data types (string, integer, number, or object, but currently not
382 array) on the wire.  The definition is similar to a simple union type,
383 where each branch of the union names a QAPI type.  For example:
384
385  { 'alternate': 'BlockdevRef',
386    'data': { 'definition': 'BlockdevOptions',
387              'reference': 'str' } }
388
389 Unlike a union, the discriminator string is never passed on the wire
390 for the Client JSON Protocol.  Instead, the value's JSON type serves
391 as an implicit discriminator, which in turn means that an alternate
392 can only express a choice between types represented differently in
393 JSON.  If a branch is typed as the 'bool' built-in, the alternate
394 accepts true and false; if it is typed as any of the various numeric
395 built-ins, it accepts a JSON number; if it is typed as a 'str'
396 built-in or named enum type, it accepts a JSON string; and if it is
397 typed as a complex type (struct or union), it accepts a JSON object.
398 Two different complex types, for instance, aren't permitted, because
399 both are represented as a JSON object.
400
401 The example alternate declaration above allows using both of the
402 following example objects:
403
404  { "file": "my_existing_block_device_id" }
405  { "file": { "driver": "file",
406              "read-only": false,
407              "filename": "/tmp/mydisk.qcow2" } }
408
409
410 === Commands ===
411
412 Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
413          '*returns': TYPE-NAME,
414          '*gen': false, '*success-response': false }
415
416 Commands are defined by using a dictionary containing several members,
417 where three members are most common.  The 'command' member is a
418 mandatory string, and determines the "execute" value passed in a
419 Client JSON Protocol command exchange.
420
421 The 'data' argument maps to the "arguments" dictionary passed in as
422 part of a Client JSON Protocol command.  The 'data' member is optional
423 and defaults to {} (an empty dictionary).  If present, it must be the
424 string name of a complex type, or a dictionary that declares an
425 anonymous type with the same semantics as a 'struct' expression, with
426 one exception noted below when 'gen' is used.
427
428 The 'returns' member describes what will appear in the "return" member
429 of a Client JSON Protocol reply on successful completion of a command.
430 The member is optional from the command declaration; if absent, the
431 "return" member will be an empty dictionary.  If 'returns' is present,
432 it must be the string name of a complex or built-in type, a
433 one-element array containing the name of a complex or built-in type,
434 with one exception noted below when 'gen' is used.  Although it is
435 permitted to have the 'returns' member name a built-in type or an
436 array of built-in types, any command that does this cannot be extended
437 to return additional information in the future; thus, new commands
438 should strongly consider returning a dictionary-based type or an array
439 of dictionaries, even if the dictionary only contains one member at the
440 present.
441
442 All commands in Client JSON Protocol use a dictionary to report
443 failure, with no way to specify that in QAPI.  Where the error return
444 is different than the usual GenericError class in order to help the
445 client react differently to certain error conditions, it is worth
446 documenting this in the comments before the command declaration.
447
448 Some example commands:
449
450  { 'command': 'my-first-command',
451    'data': { 'arg1': 'str', '*arg2': 'str' } }
452  { 'struct': 'MyType', 'data': { '*value': 'str' } }
453  { 'command': 'my-second-command',
454    'returns': [ 'MyType' ] }
455
456 which would validate this Client JSON Protocol transaction:
457
458  => { "execute": "my-first-command",
459       "arguments": { "arg1": "hello" } }
460  <= { "return": { } }
461  => { "execute": "my-second-command" }
462  <= { "return": [ { "value": "one" }, { } ] }
463
464 In rare cases, QAPI cannot express a type-safe representation of a
465 corresponding Client JSON Protocol command.  You then have to suppress
466 generation of a marshalling function by including a key 'gen' with
467 boolean value false, and instead write your own function.  Please try
468 to avoid adding new commands that rely on this, and instead use
469 type-safe unions.  For an example of this usage:
470
471  { 'command': 'netdev_add',
472    'data': {'type': 'str', 'id': 'str'},
473    'gen': false }
474
475 Normally, the QAPI schema is used to describe synchronous exchanges,
476 where a response is expected.  But in some cases, the action of a
477 command is expected to change state in a way that a successful
478 response is not possible (although the command will still return a
479 normal dictionary error on failure).  When a successful reply is not
480 possible, the command expression should include the optional key
481 'success-response' with boolean value false.  So far, only QGA makes
482 use of this member.
483
484
485 === Events ===
486
487 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT }
488
489 Events are defined with the keyword 'event'.  It is not allowed to
490 name an event 'MAX', since the generator also produces a C enumeration
491 of all event names with a generated _MAX value at the end.  When
492 'data' is also specified, additional info will be included in the
493 event, with similar semantics to a 'struct' expression.  Finally there
494 will be C API generated in qapi-event.h; when called by QEMU code, a
495 message with timestamp will be emitted on the wire.
496
497 An example event is:
498
499 { 'event': 'EVENT_C',
500   'data': { '*a': 'int', 'b': 'str' } }
501
502 Resulting in this JSON object:
503
504 { "event": "EVENT_C",
505   "data": { "b": "test string" },
506   "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
507
508
509 == Client JSON Protocol introspection ==
510
511 Clients of a Client JSON Protocol commonly need to figure out what
512 exactly the server (QEMU) supports.
513
514 For this purpose, QMP provides introspection via command
515 query-qmp-schema.  QGA currently doesn't support introspection.
516
517 While Client JSON Protocol wire compatibility should be maintained
518 between qemu versions, we cannot make the same guarantees for
519 introspection stability.  For example, one version of qemu may provide
520 a non-variant optional member of a struct, and a later version rework
521 the member to instead be non-optional and associated with a variant.
522 Likewise, one version of qemu may list a member with open-ended type
523 'str', and a later version could convert it to a finite set of strings
524 via an enum type; or a member may be converted from a specific type to
525 an alternate that represents a choice between the original type and
526 something else.
527
528 query-qmp-schema returns a JSON array of SchemaInfo objects.  These
529 objects together describe the wire ABI, as defined in the QAPI schema.
530 There is no specified order to the SchemaInfo objects returned; a
531 client must search for a particular name throughout the entire array
532 to learn more about that name, but is at least guaranteed that there
533 will be no collisions between type, command, and event names.
534
535 However, the SchemaInfo can't reflect all the rules and restrictions
536 that apply to QMP.  It's interface introspection (figuring out what's
537 there), not interface specification.  The specification is in the QAPI
538 schema.  To understand how QMP is to be used, you need to study the
539 QAPI schema.
540
541 Like any other command, query-qmp-schema is itself defined in the QAPI
542 schema, along with the SchemaInfo type.  This text attempts to give an
543 overview how things work.  For details you need to consult the QAPI
544 schema.
545
546 SchemaInfo objects have common members "name" and "meta-type", and
547 additional variant members depending on the value of meta-type.
548
549 Each SchemaInfo object describes a wire ABI entity of a certain
550 meta-type: a command, event or one of several kinds of type.
551
552 SchemaInfo for commands and events have the same name as in the QAPI
553 schema.
554
555 Command and event names are part of the wire ABI, but type names are
556 not.  Therefore, the SchemaInfo for types have auto-generated
557 meaningless names.  For readability, the examples in this section use
558 meaningful type names instead.
559
560 To examine a type, start with a command or event using it, then follow
561 references by name.
562
563 QAPI schema definitions not reachable that way are omitted.
564
565 The SchemaInfo for a command has meta-type "command", and variant
566 members "arg-type" and "ret-type".  On the wire, the "arguments"
567 member of a client's "execute" command must conform to the object type
568 named by "arg-type".  The "return" member that the server passes in a
569 success response conforms to the type named by "ret-type".
570
571 If the command takes no arguments, "arg-type" names an object type
572 without members.  Likewise, if the command returns nothing, "ret-type"
573 names an object type without members.
574
575 Example: the SchemaInfo for command query-qmp-schema
576
577     { "name": "query-qmp-schema", "meta-type": "command",
578       "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
579
580     Type "q_empty" is an automatic object type without members, and type
581     "SchemaInfoList" is the array of SchemaInfo type.
582
583 The SchemaInfo for an event has meta-type "event", and variant member
584 "arg-type".  On the wire, a "data" member that the server passes in an
585 event conforms to the object type named by "arg-type".
586
587 If the event carries no additional information, "arg-type" names an
588 object type without members.  The event may not have a data member on
589 the wire then.
590
591 Each command or event defined with dictionary-valued 'data' in the
592 QAPI schema implicitly defines an object type.
593
594 Example: the SchemaInfo for EVENT_C from section Events
595
596     { "name": "EVENT_C", "meta-type": "event",
597       "arg-type": "q_obj-EVENT_C-arg" }
598
599     Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
600     the two members from the event's definition.
601
602 The SchemaInfo for struct and union types has meta-type "object".
603
604 The SchemaInfo for a struct type has variant member "members".
605
606 The SchemaInfo for a union type additionally has variant members "tag"
607 and "variants".
608
609 "members" is a JSON array describing the object's common members, if
610 any.  Each element is a JSON object with members "name" (the member's
611 name), "type" (the name of its type), and optionally "default".  The
612 member is optional if "default" is present.  Currently, "default" can
613 only have value null.  Other values are reserved for future
614 extensions.  The "members" array is in no particular order; clients
615 must search the entire object when learning whether a particular
616 member is supported.
617
618 Example: the SchemaInfo for MyType from section Struct types
619
620     { "name": "MyType", "meta-type": "object",
621       "members": [
622           { "name": "member1", "type": "str" },
623           { "name": "member2", "type": "int" },
624           { "name": "member3", "type": "str", "default": null } ] }
625
626 "tag" is the name of the common member serving as type tag.
627 "variants" is a JSON array describing the object's variant members.
628 Each element is a JSON object with members "case" (the value of type
629 tag this element applies to) and "type" (the name of an object type
630 that provides the variant members for this type tag value).  The
631 "variants" array is in no particular order, and is not guaranteed to
632 list cases in the same order as the corresponding "tag" enum type.
633
634 Example: the SchemaInfo for flat union BlockdevOptions from section
635 Union types
636
637     { "name": "BlockdevOptions", "meta-type": "object",
638       "members": [
639           { "name": "driver", "type": "BlockdevDriver" },
640           { "name": "read-only", "type": "bool", "default": null } ],
641       "tag": "driver",
642       "variants": [
643           { "case": "file", "type": "BlockdevOptionsFile" },
644           { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
645
646 Note that base types are "flattened": its members are included in the
647 "members" array.
648
649 A simple union implicitly defines an enumeration type for its implicit
650 discriminator (called "type" on the wire, see section Union types).
651
652 A simple union implicitly defines an object type for each of its
653 variants.
654
655 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
656 Union types
657
658     { "name": "BlockdevOptionsSimple", "meta-type": "object",
659       "members": [
660           { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
661       "tag": "type",
662       "variants": [
663           { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
664           { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
665
666     Enumeration type "BlockdevOptionsSimpleKind" and the object types
667     "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
668     are implicitly defined.
669
670 The SchemaInfo for an alternate type has meta-type "alternate", and
671 variant member "members".  "members" is a JSON array.  Each element is
672 a JSON object with member "type", which names a type.  Values of the
673 alternate type conform to exactly one of its member types.  There is
674 no guarantee on the order in which "members" will be listed.
675
676 Example: the SchemaInfo for BlockdevRef from section Alternate types
677
678     { "name": "BlockdevRef", "meta-type": "alternate",
679       "members": [
680           { "type": "BlockdevOptions" },
681           { "type": "str" } ] }
682
683 The SchemaInfo for an array type has meta-type "array", and variant
684 member "element-type", which names the array's element type.  Array
685 types are implicitly defined.  For convenience, the array's name may
686 resemble the element type; however, clients should examine member
687 "element-type" instead of making assumptions based on parsing member
688 "name".
689
690 Example: the SchemaInfo for ['str']
691
692     { "name": "[str]", "meta-type": "array",
693       "element-type": "str" }
694
695 The SchemaInfo for an enumeration type has meta-type "enum" and
696 variant member "values".  The values are listed in no particular
697 order; clients must search the entire enum when learning whether a
698 particular value is supported.
699
700 Example: the SchemaInfo for MyEnum from section Enumeration types
701
702     { "name": "MyEnum", "meta-type": "enum",
703       "values": [ "value1", "value2", "value3" ] }
704
705 The SchemaInfo for a built-in type has the same name as the type in
706 the QAPI schema (see section Built-in Types), with one exception
707 detailed below.  It has variant member "json-type" that shows how
708 values of this type are encoded on the wire.
709
710 Example: the SchemaInfo for str
711
712     { "name": "str", "meta-type": "builtin", "json-type": "string" }
713
714 The QAPI schema supports a number of integer types that only differ in
715 how they map to C.  They are identical as far as SchemaInfo is
716 concerned.  Therefore, they get all mapped to a single type "int" in
717 SchemaInfo.
718
719 As explained above, type names are not part of the wire ABI.  Not even
720 the names of built-in types.  Clients should examine member
721 "json-type" instead of hard-coding names of built-in types.
722
723
724 == Code generation ==
725
726 Schemas are fed into five scripts to generate all the code/files that,
727 paired with the core QAPI libraries, comprise everything required to
728 take JSON commands read in by a Client JSON Protocol server, unmarshal
729 the arguments into the underlying C types, call into the corresponding
730 C function, map the response back to a Client JSON Protocol response
731 to be returned to the user, and introspect the commands.
732
733 As an example, we'll use the following schema, which describes a
734 single complex user-defined type, along with command which takes a
735 list of that type as a parameter, and returns a single element of that
736 type.  The user is responsible for writing the implementation of
737 qmp_my_command(); everything else is produced by the generator.
738
739     $ cat example-schema.json
740     { 'struct': 'UserDefOne',
741       'data': { 'integer': 'int', '*string': 'str' } }
742
743     { 'command': 'my-command',
744       'data': { 'arg1': ['UserDefOne'] },
745       'returns': 'UserDefOne' }
746
747     { 'event': 'MY_EVENT' }
748
749 For a more thorough look at generated code, the testsuite includes
750 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
751 what the generator will accept, and compiles the resulting C code as
752 part of 'make check-unit'.
753
754 === scripts/qapi-types.py ===
755
756 Used to generate the C types defined by a schema, along with
757 supporting code. The following files are created:
758
759 $(prefix)qapi-types.h - C types corresponding to types defined in
760                         the schema you pass in
761 $(prefix)qapi-types.c - Cleanup functions for the above C types
762
763 The $(prefix) is an optional parameter used as a namespace to keep the
764 generated code from one schema/code-generation separated from others so code
765 can be generated/used from multiple schemas without clobbering previously
766 created code.
767
768 Example:
769
770     $ python scripts/qapi-types.py --output-dir="qapi-generated" \
771     --prefix="example-" example-schema.json
772     $ cat qapi-generated/example-qapi-types.h
773 [Uninteresting stuff omitted...]
774
775     #ifndef EXAMPLE_QAPI_TYPES_H
776     #define EXAMPLE_QAPI_TYPES_H
777
778 [Built-in types omitted...]
779
780     typedef struct UserDefOne UserDefOne;
781
782     typedef struct UserDefOneList UserDefOneList;
783
784     struct UserDefOne {
785         int64_t integer;
786         bool has_string;
787         char *string;
788     };
789
790     void qapi_free_UserDefOne(UserDefOne *obj);
791
792     struct UserDefOneList {
793         UserDefOneList *next;
794         UserDefOne *value;
795     };
796
797     void qapi_free_UserDefOneList(UserDefOneList *obj);
798
799     #endif
800     $ cat qapi-generated/example-qapi-types.c
801 [Uninteresting stuff omitted...]
802
803     void qapi_free_UserDefOne(UserDefOne *obj)
804     {
805         QapiDeallocVisitor *qdv;
806         Visitor *v;
807
808         if (!obj) {
809             return;
810         }
811
812         qdv = qapi_dealloc_visitor_new();
813         v = qapi_dealloc_get_visitor(qdv);
814         visit_type_UserDefOne(v, NULL, &obj, NULL);
815         qapi_dealloc_visitor_cleanup(qdv);
816     }
817
818     void qapi_free_UserDefOneList(UserDefOneList *obj)
819     {
820         QapiDeallocVisitor *qdv;
821         Visitor *v;
822
823         if (!obj) {
824             return;
825         }
826
827         qdv = qapi_dealloc_visitor_new();
828         v = qapi_dealloc_get_visitor(qdv);
829         visit_type_UserDefOneList(v, NULL, &obj, NULL);
830         qapi_dealloc_visitor_cleanup(qdv);
831     }
832
833 === scripts/qapi-visit.py ===
834
835 Used to generate the visitor functions used to walk through and
836 convert between a native QAPI C data structure and some other format
837 (such as QObject); the generated functions are named visit_type_FOO()
838 and visit_type_FOO_members().
839
840 The following files are generated:
841
842 $(prefix)qapi-visit.c: visitor function for a particular C type, used
843                        to automagically convert QObjects into the
844                        corresponding C type and vice-versa, as well
845                        as for deallocating memory for an existing C
846                        type
847
848 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
849                        functions
850
851 Example:
852
853     $ python scripts/qapi-visit.py --output-dir="qapi-generated"
854     --prefix="example-" example-schema.json
855     $ cat qapi-generated/example-qapi-visit.h
856 [Uninteresting stuff omitted...]
857
858     #ifndef EXAMPLE_QAPI_VISIT_H
859     #define EXAMPLE_QAPI_VISIT_H
860
861 [Visitors for built-in types omitted...]
862
863     void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
864     void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
865     void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
866
867     #endif
868     $ cat qapi-generated/example-qapi-visit.c
869 [Uninteresting stuff omitted...]
870
871     void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
872     {
873         Error *err = NULL;
874
875         visit_type_int(v, "integer", &obj->integer, &err);
876         if (err) {
877             goto out;
878         }
879         if (visit_optional(v, "string", &obj->has_string)) {
880             visit_type_str(v, "string", &obj->string, &err);
881             if (err) {
882                 goto out;
883             }
884         }
885
886     out:
887         error_propagate(errp, err);
888     }
889
890     void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
891     {
892         Error *err = NULL;
893
894         visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err);
895         if (err) {
896             goto out;
897         }
898         if (!*obj) {
899             goto out_obj;
900         }
901         visit_type_UserDefOne_members(v, *obj, &err);
902         if (err) {
903             goto out_obj;
904         }
905         visit_check_struct(v, &err);
906     out_obj:
907         visit_end_struct(v);
908         if (err && visit_is_input(v)) {
909             qapi_free_UserDefOne(*obj);
910             *obj = NULL;
911         }
912     out:
913         error_propagate(errp, err);
914     }
915
916     void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
917     {
918         Error *err = NULL;
919         UserDefOneList *tail;
920         size_t size = sizeof(**obj);
921
922         visit_start_list(v, name, (GenericList **)obj, size, &err);
923         if (err) {
924             goto out;
925         }
926
927         for (tail = *obj; tail;
928              tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
929             visit_type_UserDefOne(v, NULL, &tail->value, &err);
930             if (err) {
931                 break;
932             }
933         }
934
935         visit_end_list(v);
936         if (err && visit_is_input(v)) {
937             qapi_free_UserDefOneList(*obj);
938             *obj = NULL;
939         }
940     out:
941         error_propagate(errp, err);
942     }
943
944 === scripts/qapi-commands.py ===
945
946 Used to generate the marshaling/dispatch functions for the commands
947 defined in the schema. The generated code implements
948 qmp_marshal_COMMAND() (mentioned in qmp-commands.hx, and registered
949 automatically), and declares qmp_COMMAND() that the user must
950 implement.  The following files are generated:
951
952 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
953                         QMP command defined in the schema. Functions
954                         generated by qapi-visit.py are used to
955                         convert QObjects received from the wire into
956                         function parameters, and uses the same
957                         visitor functions to convert native C return
958                         values to QObjects from transmission back
959                         over the wire.
960
961 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
962                          specified in the schema.
963
964 Example:
965
966     $ python scripts/qapi-commands.py --output-dir="qapi-generated"
967     --prefix="example-" example-schema.json
968     $ cat qapi-generated/example-qmp-commands.h
969 [Uninteresting stuff omitted...]
970
971     #ifndef EXAMPLE_QMP_COMMANDS_H
972     #define EXAMPLE_QMP_COMMANDS_H
973
974     #include "example-qapi-types.h"
975     #include "qapi/qmp/qdict.h"
976     #include "qapi/error.h"
977
978     UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
979
980     #endif
981     $ cat qapi-generated/example-qmp-marshal.c
982 [Uninteresting stuff omitted...]
983
984     static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
985     {
986         Error *err = NULL;
987         QmpOutputVisitor *qov = qmp_output_visitor_new();
988         QapiDeallocVisitor *qdv;
989         Visitor *v;
990
991         v = qmp_output_get_visitor(qov);
992         visit_type_UserDefOne(v, "unused", &ret_in, &err);
993         if (err) {
994             goto out;
995         }
996         *ret_out = qmp_output_get_qobject(qov);
997
998     out:
999         error_propagate(errp, err);
1000         qmp_output_visitor_cleanup(qov);
1001         qdv = qapi_dealloc_visitor_new();
1002         v = qapi_dealloc_get_visitor(qdv);
1003         visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1004         qapi_dealloc_visitor_cleanup(qdv);
1005     }
1006
1007     static void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1008     {
1009         Error *err = NULL;
1010         UserDefOne *retval;
1011         QmpInputVisitor *qiv = qmp_input_visitor_new(QOBJECT(args), true);
1012         QapiDeallocVisitor *qdv;
1013         Visitor *v;
1014         UserDefOneList *arg1 = NULL;
1015
1016         v = qmp_input_get_visitor(qiv);
1017         visit_start_struct(v, NULL, NULL, 0, &err);
1018         if (err) {
1019             goto out;
1020         }
1021         visit_type_UserDefOneList(v, "arg1", &arg1, &err);
1022         if (!err) {
1023             visit_check_struct(v, &err);
1024         }
1025         visit_end_struct(v);
1026         if (err) {
1027             goto out;
1028         }
1029
1030         retval = qmp_my_command(arg1, &err);
1031         if (err) {
1032             goto out;
1033         }
1034
1035         qmp_marshal_output_UserDefOne(retval, ret, &err);
1036
1037     out:
1038         error_propagate(errp, err);
1039         qmp_input_visitor_cleanup(qiv);
1040         qdv = qapi_dealloc_visitor_new();
1041         v = qapi_dealloc_get_visitor(qdv);
1042         visit_start_struct(v, NULL, NULL, 0, NULL);
1043         visit_type_UserDefOneList(v, "arg1", &arg1, NULL);
1044         visit_end_struct(v);
1045         qapi_dealloc_visitor_cleanup(qdv);
1046     }
1047
1048     static void qmp_init_marshal(void)
1049     {
1050         qmp_register_command("my-command", qmp_marshal_my_command, QCO_NO_OPTIONS);
1051     }
1052
1053     qapi_init(qmp_init_marshal);
1054
1055 === scripts/qapi-event.py ===
1056
1057 Used to generate the event-related C code defined by a schema, with
1058 implementations for qapi_event_send_FOO(). The following files are
1059 created:
1060
1061 $(prefix)qapi-event.h - Function prototypes for each event type, plus an
1062                         enumeration of all event names
1063 $(prefix)qapi-event.c - Implementation of functions to send an event
1064
1065 Example:
1066
1067     $ python scripts/qapi-event.py --output-dir="qapi-generated"
1068     --prefix="example-" example-schema.json
1069     $ cat qapi-generated/example-qapi-event.h
1070 [Uninteresting stuff omitted...]
1071
1072     #ifndef EXAMPLE_QAPI_EVENT_H
1073     #define EXAMPLE_QAPI_EVENT_H
1074
1075     #include "qapi/error.h"
1076     #include "qapi/qmp/qdict.h"
1077     #include "example-qapi-types.h"
1078
1079
1080     void qapi_event_send_my_event(Error **errp);
1081
1082     typedef enum example_QAPIEvent {
1083         EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
1084         EXAMPLE_QAPI_EVENT__MAX = 1,
1085     } example_QAPIEvent;
1086
1087     extern const char *const example_QAPIEvent_lookup[];
1088
1089     #endif
1090     $ cat qapi-generated/example-qapi-event.c
1091 [Uninteresting stuff omitted...]
1092
1093     void qapi_event_send_my_event(Error **errp)
1094     {
1095         QDict *qmp;
1096         Error *err = NULL;
1097         QMPEventFuncEmit emit;
1098         emit = qmp_event_get_func_emit();
1099         if (!emit) {
1100             return;
1101         }
1102
1103         qmp = qmp_event_build_dict("MY_EVENT");
1104
1105         emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err);
1106
1107         error_propagate(errp, err);
1108         QDECREF(qmp);
1109     }
1110
1111     const char *const example_QAPIEvent_lookup[] = {
1112         [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1113         [EXAMPLE_QAPI_EVENT__MAX] = NULL,
1114     };
1115
1116 === scripts/qapi-introspect.py ===
1117
1118 Used to generate the introspection C code for a schema. The following
1119 files are created:
1120
1121 $(prefix)qmp-introspect.c - Defines a string holding a JSON
1122                             description of the schema.
1123 $(prefix)qmp-introspect.h - Declares the above string.
1124
1125 Example:
1126
1127     $ python scripts/qapi-introspect.py --output-dir="qapi-generated"
1128     --prefix="example-" example-schema.json
1129     $ cat qapi-generated/example-qmp-introspect.h
1130 [Uninteresting stuff omitted...]
1131
1132     #ifndef EXAMPLE_QMP_INTROSPECT_H
1133     #define EXAMPLE_QMP_INTROSPECT_H
1134
1135     extern const char example_qmp_schema_json[];
1136
1137     #endif
1138     $ cat qapi-generated/example-qmp-introspect.c
1139 [Uninteresting stuff omitted...]
1140
1141     const char example_qmp_schema_json[] = "["
1142         "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, "
1143         "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, "
1144         "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, "
1145         "{\"members\": [{\"name\": \"arg1\", \"type\": \"[2]\"}], \"meta-type\": \"object\", \"name\": \"1\"}, "
1146         "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"default\": null, \"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, "
1147         "{\"element-type\": \"2\", \"meta-type\": \"array\", \"name\": \"[2]\"}, "
1148         "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, "
1149         "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]";