docs/qapi-code-gen.txt: Clarify naming rules
[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
48 === Comments ===
49
50 Comments are allowed; anything between an unquoted # and the following
51 newline is ignored.
52
53 A multi-line comment that starts and ends with a '##' line is a
54 documentation comment.  These are parsed by the documentation
55 generator, which recognizes certain markup detailed below.
56
57
58 ==== Documentation markup ====
59
60 Comment text starting with '=' is a section title:
61
62     # = Section title
63
64 Double the '=' for a subsection title:
65
66     # == Subection title
67
68 '|' denotes examples:
69
70     # | Text of the example, may span
71     # | multiple lines
72
73 '*' starts an itemized list:
74
75     # * First item, may span
76     #   multiple lines
77     # * Second item
78
79 You can also use '-' instead of '*'.
80
81 A decimal number followed by '.' starts a numbered list:
82
83     # 1. First item, may span
84     #    multiple lines
85     # 2. Second item
86
87 The actual number doesn't matter.  You could even use '*' instead of
88 '2.' for the second item.
89
90 Lists can't be nested.  Blank lines are currently not supported within
91 lists.
92
93 Additional whitespace between the initial '#' and the comment text is
94 permitted.
95
96 *foo* and _foo_ are for strong and emphasis styles respectively (they
97 do not work over multiple lines). @foo is used to reference a name in
98 the schema.
99
100 Example:
101
102 ##
103 # = Section
104 # == Subsection
105 #
106 # Some text foo with *strong* and _emphasis_
107 # 1. with a list
108 # 2. like that
109 #
110 # And some code:
111 # | $ echo foo
112 # | -> do this
113 # | <- get that
114 #
115 ##
116
117
118 ==== Expression documentation ====
119
120 Each expression that isn't an include directive must be preceded by a
121 documentation block.  Such blocks are called expression documentation
122 blocks.
123
124 The documentation block consists of a first line naming the
125 expression, an optional overview, a description of each argument (for
126 commands and events) or member (for structs, unions and alternates),
127 and optional tagged sections.
128
129 FIXME: the parser accepts these things in almost any order.
130
131 Optional arguments / members are tagged with the phrase '#optional',
132 often with their default value; and extensions added after the
133 expression was first released are also given a '(since x.y.z)'
134 comment.
135
136 A tagged section starts with one of the following words:
137 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
138 The section ends with the start of a new section.
139
140 A 'Since: x.y.z' tagged section lists the release that introduced the
141 expression.
142
143 For example:
144
145 ##
146 # @BlockStats:
147 #
148 # Statistics of a virtual block device or a block backing device.
149 #
150 # @device: #optional If the stats are for a virtual block device, the name
151 #          corresponding to the virtual block device.
152 #
153 # @node-name: #optional The node name of the device. (since 2.3)
154 #
155 # ... more members ...
156 #
157 # Since: 0.14.0
158 ##
159 { 'struct': 'BlockStats',
160   'data': {'*device': 'str', '*node-name': 'str',
161            ... more members ... } }
162
163 ##
164 # @query-blockstats:
165 #
166 # Query the @BlockStats for all virtual block devices.
167 #
168 # @query-nodes: #optional If true, the command will query all the
169 #               block nodes ... explain, explain ...  (since 2.3)
170 #
171 # Returns: A list of @BlockStats for each virtual block devices.
172 #
173 # Since: 0.14.0
174 #
175 # Example:
176 #
177 # -> { "execute": "query-blockstats" }
178 # <- {
179 #      ... lots of output ...
180 #    }
181 #
182 ##
183 { 'command': 'query-blockstats',
184   'data': { '*query-nodes': 'bool' },
185   'returns': ['BlockStats'] }
186
187 ==== Free-form documentation ====
188
189 A documentation block that isn't an expression documentation block is
190 a free-form documentation block.  These may be used to provide
191 additional text and structuring content.
192
193
194 === Schema overview ===
195
196 The schema sets up a series of types, as well as commands and events
197 that will use those types.  Forward references are allowed: the parser
198 scans in two passes, where the first pass learns all type names, and
199 the second validates the schema and generates the code.  This allows
200 the definition of complex structs that can have mutually recursive
201 types, and allows for indefinite nesting of Client JSON Protocol that
202 satisfies the schema.  A type name should not be defined more than
203 once.  It is permissible for the schema to contain additional types
204 not used by any commands or events in the Client JSON Protocol, for
205 the side effect of generated C code used internally.
206
207 There are seven top-level expressions recognized by the parser:
208 'include', 'command', 'struct', 'enum', 'union', 'alternate', and
209 'event'.  There are several groups of types: simple types (a number of
210 built-in types, such as 'int' and 'str'; as well as enumerations),
211 complex types (structs and two flavors of unions), and alternate types
212 (a choice between other types).  The 'command' and 'event' expressions
213 can refer to existing types by name, or list an anonymous type as a
214 dictionary. Listing a type name inside an array refers to a
215 single-dimension array of that type; multi-dimension arrays are not
216 directly supported (although an array of a complex struct that
217 contains an array member is possible).
218
219 All names must begin with a letter, and contain only ASCII letters,
220 digits, hyphen, and underscore.  There are two exceptions: enum values
221 may start with a digit, and names that are downstream extensions (see
222 section Downstream extensions) start with underscore.
223
224 Names beginning with 'q_' are reserved for the generator, which uses
225 them for munging QMP names that resemble C keywords or other
226 problematic strings.  For example, a member named "default" in qapi
227 becomes "q_default" in the generated C code.
228
229 Types, commands, and events share a common namespace.  Therefore,
230 generally speaking, type definitions should always use CamelCase for
231 user-defined type names, while built-in types are lowercase.
232
233 Type names ending with 'Kind' or 'List' are reserved for the
234 generator, which uses them for implicit union enums and array types,
235 respectively.
236
237 Command names, and member names within a type, should be all lower
238 case with words separated by a hyphen.  However, some existing older
239 commands and complex types use underscore; when extending such
240 expressions, consistency is preferred over blindly avoiding
241 underscore.
242
243 Event names should be ALL_CAPS with words separated by underscore.
244
245 Member names starting with 'has-' or 'has_' are reserved for the
246 generator, which uses them for tracking optional members.
247
248 Any name (command, event, type, member, or enum value) beginning with
249 "x-" is marked experimental, and may be withdrawn or changed
250 incompatibly in a future release.
251
252 In the rest of this document, usage lines are given for each
253 expression type, with literal strings written in lower case and
254 placeholders written in capitals.  If a literal string includes a
255 prefix of '*', that key/value pair can be omitted from the expression.
256 For example, a usage statement that includes '*base':STRUCT-NAME
257 means that an expression has an optional key 'base', which if present
258 must have a value that forms a struct name.
259
260
261 === Built-in Types ===
262
263 The following types are predefined, and map to C as follows:
264
265   Schema    C          JSON
266   str       char *     any JSON string, UTF-8
267   number    double     any JSON number
268   int       int64_t    a JSON number without fractional part
269                        that fits into the C integer type
270   int8      int8_t     likewise
271   int16     int16_t    likewise
272   int32     int32_t    likewise
273   int64     int64_t    likewise
274   uint8     uint8_t    likewise
275   uint16    uint16_t   likewise
276   uint32    uint32_t   likewise
277   uint64    uint64_t   likewise
278   size      uint64_t   like uint64_t, except StringInputVisitor
279                        accepts size suffixes
280   bool      bool       JSON true or false
281   any       QObject *  any JSON value
282   QType     QType      JSON string matching enum QType values
283
284
285 === Includes ===
286
287 Usage: { 'include': STRING }
288
289 The QAPI schema definitions can be modularized using the 'include' directive:
290
291  { 'include': 'path/to/file.json' }
292
293 The directive is evaluated recursively, and include paths are relative to the
294 file using the directive. Multiple includes of the same file are
295 idempotent.  No other keys should appear in the expression, and the include
296 value should be a string.
297
298 As a matter of style, it is a good idea to have all files be
299 self-contained, but at the moment, nothing prevents an included file
300 from making a forward reference to a type that is only introduced by
301 an outer file.  The parser may be made stricter in the future to
302 prevent incomplete include files.
303
304
305 === Struct types ===
306
307 Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
308
309 A struct is a dictionary containing a single 'data' key whose value is
310 a dictionary; the dictionary may be empty.  This corresponds to a
311 struct in C or an Object in JSON. Each value of the 'data' dictionary
312 must be the name of a type, or a one-element array containing a type
313 name.  An example of a struct is:
314
315  { 'struct': 'MyType',
316    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
317
318 The use of '*' as a prefix to the name means the member is optional in
319 the corresponding JSON protocol usage.
320
321 The default initialization value of an optional argument should not be changed
322 between versions of QEMU unless the new default maintains backward
323 compatibility to the user-visible behavior of the old default.
324
325 With proper documentation, this policy still allows some flexibility; for
326 example, documenting that a default of 0 picks an optimal buffer size allows
327 one release to declare the optimal size at 512 while another release declares
328 the optimal size at 4096 - the user-visible behavior is not the bytes used by
329 the buffer, but the fact that the buffer was optimal size.
330
331 On input structures (only mentioned in the 'data' side of a command), changing
332 from mandatory to optional is safe (older clients will supply the option, and
333 newer clients can benefit from the default); changing from optional to
334 mandatory is backwards incompatible (older clients may be omitting the option,
335 and must continue to work).
336
337 On output structures (only mentioned in the 'returns' side of a command),
338 changing from mandatory to optional is in general unsafe (older clients may be
339 expecting the member, and could crash if it is missing), although it
340 can be done if the only way that the optional argument will be omitted
341 is when it is triggered by the presence of a new input flag to the
342 command that older clients don't know to send.  Changing from optional
343 to mandatory is safe.
344
345 A structure that is used in both input and output of various commands
346 must consider the backwards compatibility constraints of both directions
347 of use.
348
349 A struct definition can specify another struct as its base.
350 In this case, the members of the base type are included as top-level members
351 of the new struct's dictionary in the Client JSON Protocol wire
352 format. An example definition is:
353
354  { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
355  { 'struct': 'BlockdevOptionsGenericCOWFormat',
356    'base': 'BlockdevOptionsGenericFormat',
357    'data': { '*backing': 'str' } }
358
359 An example BlockdevOptionsGenericCOWFormat object on the wire could use
360 both members like this:
361
362  { "file": "/some/place/my-image",
363    "backing": "/some/place/my-backing-file" }
364
365
366 === Enumeration types ===
367
368 Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
369        { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
370
371 An enumeration type is a dictionary containing a single 'data' key
372 whose value is a list of strings.  An example enumeration is:
373
374  { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
375
376 Nothing prevents an empty enumeration, although it is probably not
377 useful.  The list of strings should be lower case; if an enum name
378 represents multiple words, use '-' between words.  The string 'max' is
379 not allowed as an enum value, and values should not be repeated.
380
381 The enum constants will be named by using a heuristic to turn the
382 type name into a set of underscore separated words. For the example
383 above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
384 of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
385 does not result in a desirable name, the optional 'prefix' member
386 can be used when defining the enum.
387
388 The enumeration values are passed as strings over the Client JSON
389 Protocol, but are encoded as C enum integral values in generated code.
390 While the C code starts numbering at 0, it is better to use explicit
391 comparisons to enum values than implicit comparisons to 0; the C code
392 will also include a generated enum member ending in _MAX for tracking
393 the size of the enum, useful when using common functions for
394 converting between strings and enum values.  Since the wire format
395 always passes by name, it is acceptable to reorder or add new
396 enumeration members in any location without breaking clients of Client
397 JSON Protocol; however, removing enum values would break
398 compatibility.  For any struct that has a member that will only contain
399 a finite set of string values, using an enum type for that member is
400 better than open-coding the member to be type 'str'.
401
402
403 === Union types ===
404
405 Usage: { 'union': STRING, 'data': DICT }
406 or:    { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME-OR-DICT,
407          'discriminator': ENUM-MEMBER-OF-BASE }
408
409 Union types are used to let the user choose between several different
410 variants for an object.  There are two flavors: simple (no
411 discriminator or base), and flat (both discriminator and base).  A union
412 type is defined using a data dictionary as explained in the following
413 paragraphs.  The data dictionary for either type of union must not
414 be empty.
415
416 A simple union type defines a mapping from automatic discriminator
417 values to data types like in this example:
418
419  { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
420  { 'struct': 'BlockdevOptionsQcow2',
421    'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
422
423  { 'union': 'BlockdevOptionsSimple',
424    'data': { 'file': 'BlockdevOptionsFile',
425              'qcow2': 'BlockdevOptionsQcow2' } }
426
427 In the Client JSON Protocol, a simple union is represented by a
428 dictionary that contains the 'type' member as a discriminator, and a
429 'data' member that is of the specified data type corresponding to the
430 discriminator value, as in these examples:
431
432  { "type": "file", "data": { "filename": "/some/place/my-image" } }
433  { "type": "qcow2", "data": { "backing": "/some/place/my-image",
434                               "lazy-refcounts": true } }
435
436 The generated C code uses a struct containing a union. Additionally,
437 an implicit C enum 'NameKind' is created, corresponding to the union
438 'Name', for accessing the various branches of the union.  No branch of
439 the union can be named 'max', as this would collide with the implicit
440 enum.  The value for each branch can be of any type.
441
442 A flat union definition avoids nesting on the wire, and specifies a
443 set of common members that occur in all variants of the union.  The
444 'base' key must specify either a type name (the type must be a
445 struct, not a union), or a dictionary representing an anonymous type.
446 All branches of the union must be complex types, and the top-level
447 members of the union dictionary on the wire will be combination of
448 members from both the base type and the appropriate branch type (when
449 merging two dictionaries, there must be no keys in common).  The
450 'discriminator' member must be the name of a non-optional enum-typed
451 member of the base struct.
452
453 The following example enhances the above simple union example by
454 adding an optional common member 'read-only', renaming the
455 discriminator to something more applicable than the simple union's
456 default of 'type', and reducing the number of {} required on the wire:
457
458  { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
459  { 'union': 'BlockdevOptions',
460    'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
461    'discriminator': 'driver',
462    'data': { 'file': 'BlockdevOptionsFile',
463              'qcow2': 'BlockdevOptionsQcow2' } }
464
465 Resulting in these JSON objects:
466
467  { "driver": "file", "read-only": true,
468    "filename": "/some/place/my-image" }
469  { "driver": "qcow2", "read-only": false,
470    "backing": "/some/place/my-image", "lazy-refcounts": true }
471
472 Notice that in a flat union, the discriminator name is controlled by
473 the user, but because it must map to a base member with enum type, the
474 code generator can ensure that branches exist for all values of the
475 enum (although the order of the keys need not match the declaration of
476 the enum).  In the resulting generated C data types, a flat union is
477 represented as a struct with the base members included directly, and
478 then a union of structures for each branch of the struct.
479
480 A simple union can always be re-written as a flat union where the base
481 class has a single member named 'type', and where each branch of the
482 union has a struct with a single member named 'data'.  That is,
483
484  { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
485
486 is identical on the wire to:
487
488  { 'enum': 'Enum', 'data': ['one', 'two'] }
489  { 'struct': 'Branch1', 'data': { 'data': 'str' } }
490  { 'struct': 'Branch2', 'data': { 'data': 'int' } }
491  { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type',
492    'data': { 'one': 'Branch1', 'two': 'Branch2' } }
493
494
495 === Alternate types ===
496
497 Usage: { 'alternate': STRING, 'data': DICT }
498
499 An alternate type is one that allows a choice between two or more JSON
500 data types (string, integer, number, or object, but currently not
501 array) on the wire.  The definition is similar to a simple union type,
502 where each branch of the union names a QAPI type.  For example:
503
504  { 'alternate': 'BlockdevRef',
505    'data': { 'definition': 'BlockdevOptions',
506              'reference': 'str' } }
507
508 Unlike a union, the discriminator string is never passed on the wire
509 for the Client JSON Protocol.  Instead, the value's JSON type serves
510 as an implicit discriminator, which in turn means that an alternate
511 can only express a choice between types represented differently in
512 JSON.  If a branch is typed as the 'bool' built-in, the alternate
513 accepts true and false; if it is typed as any of the various numeric
514 built-ins, it accepts a JSON number; if it is typed as a 'str'
515 built-in or named enum type, it accepts a JSON string; and if it is
516 typed as a complex type (struct or union), it accepts a JSON object.
517 Two different complex types, for instance, aren't permitted, because
518 both are represented as a JSON object.
519
520 The example alternate declaration above allows using both of the
521 following example objects:
522
523  { "file": "my_existing_block_device_id" }
524  { "file": { "driver": "file",
525              "read-only": false,
526              "filename": "/tmp/mydisk.qcow2" } }
527
528
529 === Commands ===
530
531 Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
532          '*returns': TYPE-NAME, '*boxed': true,
533          '*gen': false, '*success-response': false }
534
535 Commands are defined by using a dictionary containing several members,
536 where three members are most common.  The 'command' member is a
537 mandatory string, and determines the "execute" value passed in a
538 Client JSON Protocol command exchange.
539
540 The 'data' argument maps to the "arguments" dictionary passed in as
541 part of a Client JSON Protocol command.  The 'data' member is optional
542 and defaults to {} (an empty dictionary).  If present, it must be the
543 string name of a complex type, or a dictionary that declares an
544 anonymous type with the same semantics as a 'struct' expression, with
545 one exception noted below when 'gen' is used.
546
547 The 'returns' member describes what will appear in the "return" member
548 of a Client JSON Protocol reply on successful completion of a command.
549 The member is optional from the command declaration; if absent, the
550 "return" member will be an empty dictionary.  If 'returns' is present,
551 it must be the string name of a complex or built-in type, a
552 one-element array containing the name of a complex or built-in type,
553 with one exception noted below when 'gen' is used.  Although it is
554 permitted to have the 'returns' member name a built-in type or an
555 array of built-in types, any command that does this cannot be extended
556 to return additional information in the future; thus, new commands
557 should strongly consider returning a dictionary-based type or an array
558 of dictionaries, even if the dictionary only contains one member at the
559 present.
560
561 All commands in Client JSON Protocol use a dictionary to report
562 failure, with no way to specify that in QAPI.  Where the error return
563 is different than the usual GenericError class in order to help the
564 client react differently to certain error conditions, it is worth
565 documenting this in the comments before the command declaration.
566
567 Some example commands:
568
569  { 'command': 'my-first-command',
570    'data': { 'arg1': 'str', '*arg2': 'str' } }
571  { 'struct': 'MyType', 'data': { '*value': 'str' } }
572  { 'command': 'my-second-command',
573    'returns': [ 'MyType' ] }
574
575 which would validate this Client JSON Protocol transaction:
576
577  => { "execute": "my-first-command",
578       "arguments": { "arg1": "hello" } }
579  <= { "return": { } }
580  => { "execute": "my-second-command" }
581  <= { "return": [ { "value": "one" }, { } ] }
582
583 The generator emits a prototype for the user's function implementing
584 the command.  Normally, 'data' is a dictionary for an anonymous type,
585 or names a struct type (possibly empty, but not a union), and its
586 members are passed as separate arguments to this function.  If the
587 command definition includes a key 'boxed' with the boolean value true,
588 then 'data' is instead the name of any non-empty complex type
589 (struct, union, or alternate), and a pointer to that QAPI type is
590 passed as a single argument.
591
592 The generator also emits a marshalling function that extracts
593 arguments for the user's function out of an input QDict, calls the
594 user's function, and if it succeeded, builds an output QObject from
595 its return value.
596
597 In rare cases, QAPI cannot express a type-safe representation of a
598 corresponding Client JSON Protocol command.  You then have to suppress
599 generation of a marshalling function by including a key 'gen' with
600 boolean value false, and instead write your own function.  Please try
601 to avoid adding new commands that rely on this, and instead use
602 type-safe unions.  For an example of this usage:
603
604  { 'command': 'netdev_add',
605    'data': {'type': 'str', 'id': 'str'},
606    'gen': false }
607
608 Normally, the QAPI schema is used to describe synchronous exchanges,
609 where a response is expected.  But in some cases, the action of a
610 command is expected to change state in a way that a successful
611 response is not possible (although the command will still return a
612 normal dictionary error on failure).  When a successful reply is not
613 possible, the command expression should include the optional key
614 'success-response' with boolean value false.  So far, only QGA makes
615 use of this member.
616
617
618 === Events ===
619
620 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
621          '*boxed': true }
622
623 Events are defined with the keyword 'event'.  It is not allowed to
624 name an event 'MAX', since the generator also produces a C enumeration
625 of all event names with a generated _MAX value at the end.  When
626 'data' is also specified, additional info will be included in the
627 event, with similar semantics to a 'struct' expression.  Finally there
628 will be C API generated in qapi-event.h; when called by QEMU code, a
629 message with timestamp will be emitted on the wire.
630
631 An example event is:
632
633 { 'event': 'EVENT_C',
634   'data': { '*a': 'int', 'b': 'str' } }
635
636 Resulting in this JSON object:
637
638 { "event": "EVENT_C",
639   "data": { "b": "test string" },
640   "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
641
642 The generator emits a function to send the event.  Normally, 'data' is
643 a dictionary for an anonymous type, or names a struct type (possibly
644 empty, but not a union), and its members are passed as separate
645 arguments to this function.  If the event definition includes a key
646 'boxed' with the boolean value true, then 'data' is instead the name of
647 any non-empty complex type (struct, union, or alternate), and a
648 pointer to that QAPI type is passed as a single argument.
649
650
651 === Downstream extensions ===
652
653 QAPI schema names that are externally visible, say in the Client JSON
654 Protocol, need to be managed with care.  Names starting with a
655 downstream prefix of the form __RFQDN_ are reserved for the downstream
656 who controls the valid, reverse fully qualified domain name RFQDN.
657 RFQDN may only contain ASCII letters, digits, hyphen and period.
658
659 Example: Red Hat, Inc. controls redhat.com, and may therefore add a
660 downstream command __com.redhat_drive-mirror.
661
662
663 == Client JSON Protocol introspection ==
664
665 Clients of a Client JSON Protocol commonly need to figure out what
666 exactly the server (QEMU) supports.
667
668 For this purpose, QMP provides introspection via command
669 query-qmp-schema.  QGA currently doesn't support introspection.
670
671 While Client JSON Protocol wire compatibility should be maintained
672 between qemu versions, we cannot make the same guarantees for
673 introspection stability.  For example, one version of qemu may provide
674 a non-variant optional member of a struct, and a later version rework
675 the member to instead be non-optional and associated with a variant.
676 Likewise, one version of qemu may list a member with open-ended type
677 'str', and a later version could convert it to a finite set of strings
678 via an enum type; or a member may be converted from a specific type to
679 an alternate that represents a choice between the original type and
680 something else.
681
682 query-qmp-schema returns a JSON array of SchemaInfo objects.  These
683 objects together describe the wire ABI, as defined in the QAPI schema.
684 There is no specified order to the SchemaInfo objects returned; a
685 client must search for a particular name throughout the entire array
686 to learn more about that name, but is at least guaranteed that there
687 will be no collisions between type, command, and event names.
688
689 However, the SchemaInfo can't reflect all the rules and restrictions
690 that apply to QMP.  It's interface introspection (figuring out what's
691 there), not interface specification.  The specification is in the QAPI
692 schema.  To understand how QMP is to be used, you need to study the
693 QAPI schema.
694
695 Like any other command, query-qmp-schema is itself defined in the QAPI
696 schema, along with the SchemaInfo type.  This text attempts to give an
697 overview how things work.  For details you need to consult the QAPI
698 schema.
699
700 SchemaInfo objects have common members "name" and "meta-type", and
701 additional variant members depending on the value of meta-type.
702
703 Each SchemaInfo object describes a wire ABI entity of a certain
704 meta-type: a command, event or one of several kinds of type.
705
706 SchemaInfo for commands and events have the same name as in the QAPI
707 schema.
708
709 Command and event names are part of the wire ABI, but type names are
710 not.  Therefore, the SchemaInfo for types have auto-generated
711 meaningless names.  For readability, the examples in this section use
712 meaningful type names instead.
713
714 To examine a type, start with a command or event using it, then follow
715 references by name.
716
717 QAPI schema definitions not reachable that way are omitted.
718
719 The SchemaInfo for a command has meta-type "command", and variant
720 members "arg-type" and "ret-type".  On the wire, the "arguments"
721 member of a client's "execute" command must conform to the object type
722 named by "arg-type".  The "return" member that the server passes in a
723 success response conforms to the type named by "ret-type".
724
725 If the command takes no arguments, "arg-type" names an object type
726 without members.  Likewise, if the command returns nothing, "ret-type"
727 names an object type without members.
728
729 Example: the SchemaInfo for command query-qmp-schema
730
731     { "name": "query-qmp-schema", "meta-type": "command",
732       "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
733
734     Type "q_empty" is an automatic object type without members, and type
735     "SchemaInfoList" is the array of SchemaInfo type.
736
737 The SchemaInfo for an event has meta-type "event", and variant member
738 "arg-type".  On the wire, a "data" member that the server passes in an
739 event conforms to the object type named by "arg-type".
740
741 If the event carries no additional information, "arg-type" names an
742 object type without members.  The event may not have a data member on
743 the wire then.
744
745 Each command or event defined with dictionary-valued 'data' in the
746 QAPI schema implicitly defines an object type.
747
748 Example: the SchemaInfo for EVENT_C from section Events
749
750     { "name": "EVENT_C", "meta-type": "event",
751       "arg-type": "q_obj-EVENT_C-arg" }
752
753     Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
754     the two members from the event's definition.
755
756 The SchemaInfo for struct and union types has meta-type "object".
757
758 The SchemaInfo for a struct type has variant member "members".
759
760 The SchemaInfo for a union type additionally has variant members "tag"
761 and "variants".
762
763 "members" is a JSON array describing the object's common members, if
764 any.  Each element is a JSON object with members "name" (the member's
765 name), "type" (the name of its type), and optionally "default".  The
766 member is optional if "default" is present.  Currently, "default" can
767 only have value null.  Other values are reserved for future
768 extensions.  The "members" array is in no particular order; clients
769 must search the entire object when learning whether a particular
770 member is supported.
771
772 Example: the SchemaInfo for MyType from section Struct types
773
774     { "name": "MyType", "meta-type": "object",
775       "members": [
776           { "name": "member1", "type": "str" },
777           { "name": "member2", "type": "int" },
778           { "name": "member3", "type": "str", "default": null } ] }
779
780 "tag" is the name of the common member serving as type tag.
781 "variants" is a JSON array describing the object's variant members.
782 Each element is a JSON object with members "case" (the value of type
783 tag this element applies to) and "type" (the name of an object type
784 that provides the variant members for this type tag value).  The
785 "variants" array is in no particular order, and is not guaranteed to
786 list cases in the same order as the corresponding "tag" enum type.
787
788 Example: the SchemaInfo for flat union BlockdevOptions from section
789 Union types
790
791     { "name": "BlockdevOptions", "meta-type": "object",
792       "members": [
793           { "name": "driver", "type": "BlockdevDriver" },
794           { "name": "read-only", "type": "bool", "default": null } ],
795       "tag": "driver",
796       "variants": [
797           { "case": "file", "type": "BlockdevOptionsFile" },
798           { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
799
800 Note that base types are "flattened": its members are included in the
801 "members" array.
802
803 A simple union implicitly defines an enumeration type for its implicit
804 discriminator (called "type" on the wire, see section Union types).
805
806 A simple union implicitly defines an object type for each of its
807 variants.
808
809 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
810 Union types
811
812     { "name": "BlockdevOptionsSimple", "meta-type": "object",
813       "members": [
814           { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
815       "tag": "type",
816       "variants": [
817           { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
818           { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
819
820     Enumeration type "BlockdevOptionsSimpleKind" and the object types
821     "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
822     are implicitly defined.
823
824 The SchemaInfo for an alternate type has meta-type "alternate", and
825 variant member "members".  "members" is a JSON array.  Each element is
826 a JSON object with member "type", which names a type.  Values of the
827 alternate type conform to exactly one of its member types.  There is
828 no guarantee on the order in which "members" will be listed.
829
830 Example: the SchemaInfo for BlockdevRef from section Alternate types
831
832     { "name": "BlockdevRef", "meta-type": "alternate",
833       "members": [
834           { "type": "BlockdevOptions" },
835           { "type": "str" } ] }
836
837 The SchemaInfo for an array type has meta-type "array", and variant
838 member "element-type", which names the array's element type.  Array
839 types are implicitly defined.  For convenience, the array's name may
840 resemble the element type; however, clients should examine member
841 "element-type" instead of making assumptions based on parsing member
842 "name".
843
844 Example: the SchemaInfo for ['str']
845
846     { "name": "[str]", "meta-type": "array",
847       "element-type": "str" }
848
849 The SchemaInfo for an enumeration type has meta-type "enum" and
850 variant member "values".  The values are listed in no particular
851 order; clients must search the entire enum when learning whether a
852 particular value is supported.
853
854 Example: the SchemaInfo for MyEnum from section Enumeration types
855
856     { "name": "MyEnum", "meta-type": "enum",
857       "values": [ "value1", "value2", "value3" ] }
858
859 The SchemaInfo for a built-in type has the same name as the type in
860 the QAPI schema (see section Built-in Types), with one exception
861 detailed below.  It has variant member "json-type" that shows how
862 values of this type are encoded on the wire.
863
864 Example: the SchemaInfo for str
865
866     { "name": "str", "meta-type": "builtin", "json-type": "string" }
867
868 The QAPI schema supports a number of integer types that only differ in
869 how they map to C.  They are identical as far as SchemaInfo is
870 concerned.  Therefore, they get all mapped to a single type "int" in
871 SchemaInfo.
872
873 As explained above, type names are not part of the wire ABI.  Not even
874 the names of built-in types.  Clients should examine member
875 "json-type" instead of hard-coding names of built-in types.
876
877
878 == Code generation ==
879
880 Schemas are fed into five scripts to generate all the code/files that,
881 paired with the core QAPI libraries, comprise everything required to
882 take JSON commands read in by a Client JSON Protocol server, unmarshal
883 the arguments into the underlying C types, call into the corresponding
884 C function, map the response back to a Client JSON Protocol response
885 to be returned to the user, and introspect the commands.
886
887 As an example, we'll use the following schema, which describes a
888 single complex user-defined type, along with command which takes a
889 list of that type as a parameter, and returns a single element of that
890 type.  The user is responsible for writing the implementation of
891 qmp_my_command(); everything else is produced by the generator.
892
893     $ cat example-schema.json
894     { 'struct': 'UserDefOne',
895       'data': { 'integer': 'int', '*string': 'str' } }
896
897     { 'command': 'my-command',
898       'data': { 'arg1': ['UserDefOne'] },
899       'returns': 'UserDefOne' }
900
901     { 'event': 'MY_EVENT' }
902
903 For a more thorough look at generated code, the testsuite includes
904 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
905 what the generator will accept, and compiles the resulting C code as
906 part of 'make check-unit'.
907
908 === scripts/qapi-types.py ===
909
910 Used to generate the C types defined by a schema, along with
911 supporting code. The following files are created:
912
913 $(prefix)qapi-types.h - C types corresponding to types defined in
914                         the schema you pass in
915 $(prefix)qapi-types.c - Cleanup functions for the above C types
916
917 The $(prefix) is an optional parameter used as a namespace to keep the
918 generated code from one schema/code-generation separated from others so code
919 can be generated/used from multiple schemas without clobbering previously
920 created code.
921
922 Example:
923
924     $ python scripts/qapi-types.py --output-dir="qapi-generated" \
925     --prefix="example-" example-schema.json
926     $ cat qapi-generated/example-qapi-types.h
927 [Uninteresting stuff omitted...]
928
929     #ifndef EXAMPLE_QAPI_TYPES_H
930     #define EXAMPLE_QAPI_TYPES_H
931
932 [Built-in types omitted...]
933
934     typedef struct UserDefOne UserDefOne;
935
936     typedef struct UserDefOneList UserDefOneList;
937
938     struct UserDefOne {
939         int64_t integer;
940         bool has_string;
941         char *string;
942     };
943
944     void qapi_free_UserDefOne(UserDefOne *obj);
945
946     struct UserDefOneList {
947         UserDefOneList *next;
948         UserDefOne *value;
949     };
950
951     void qapi_free_UserDefOneList(UserDefOneList *obj);
952
953     #endif
954     $ cat qapi-generated/example-qapi-types.c
955 [Uninteresting stuff omitted...]
956
957     void qapi_free_UserDefOne(UserDefOne *obj)
958     {
959         Visitor *v;
960
961         if (!obj) {
962             return;
963         }
964
965         v = qapi_dealloc_visitor_new();
966         visit_type_UserDefOne(v, NULL, &obj, NULL);
967         visit_free(v);
968     }
969
970     void qapi_free_UserDefOneList(UserDefOneList *obj)
971     {
972         Visitor *v;
973
974         if (!obj) {
975             return;
976         }
977
978         v = qapi_dealloc_visitor_new();
979         visit_type_UserDefOneList(v, NULL, &obj, NULL);
980         visit_free(v);
981     }
982
983 === scripts/qapi-visit.py ===
984
985 Used to generate the visitor functions used to walk through and
986 convert between a native QAPI C data structure and some other format
987 (such as QObject); the generated functions are named visit_type_FOO()
988 and visit_type_FOO_members().
989
990 The following files are generated:
991
992 $(prefix)qapi-visit.c: visitor function for a particular C type, used
993                        to automagically convert QObjects into the
994                        corresponding C type and vice-versa, as well
995                        as for deallocating memory for an existing C
996                        type
997
998 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
999                        functions
1000
1001 Example:
1002
1003     $ python scripts/qapi-visit.py --output-dir="qapi-generated"
1004     --prefix="example-" example-schema.json
1005     $ cat qapi-generated/example-qapi-visit.h
1006 [Uninteresting stuff omitted...]
1007
1008     #ifndef EXAMPLE_QAPI_VISIT_H
1009     #define EXAMPLE_QAPI_VISIT_H
1010
1011 [Visitors for built-in types omitted...]
1012
1013     void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp);
1014     void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp);
1015     void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp);
1016
1017     #endif
1018     $ cat qapi-generated/example-qapi-visit.c
1019 [Uninteresting stuff omitted...]
1020
1021     void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp)
1022     {
1023         Error *err = NULL;
1024
1025         visit_type_int(v, "integer", &obj->integer, &err);
1026         if (err) {
1027             goto out;
1028         }
1029         if (visit_optional(v, "string", &obj->has_string)) {
1030             visit_type_str(v, "string", &obj->string, &err);
1031             if (err) {
1032                 goto out;
1033             }
1034         }
1035
1036     out:
1037         error_propagate(errp, err);
1038     }
1039
1040     void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp)
1041     {
1042         Error *err = NULL;
1043
1044         visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err);
1045         if (err) {
1046             goto out;
1047         }
1048         if (!*obj) {
1049             goto out_obj;
1050         }
1051         visit_type_UserDefOne_members(v, *obj, &err);
1052         if (err) {
1053             goto out_obj;
1054         }
1055         visit_check_struct(v, &err);
1056     out_obj:
1057         visit_end_struct(v, (void **)obj);
1058         if (err && visit_is_input(v)) {
1059             qapi_free_UserDefOne(*obj);
1060             *obj = NULL;
1061         }
1062     out:
1063         error_propagate(errp, err);
1064     }
1065
1066     void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp)
1067     {
1068         Error *err = NULL;
1069         UserDefOneList *tail;
1070         size_t size = sizeof(**obj);
1071
1072         visit_start_list(v, name, (GenericList **)obj, size, &err);
1073         if (err) {
1074             goto out;
1075         }
1076
1077         for (tail = *obj; tail;
1078              tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) {
1079             visit_type_UserDefOne(v, NULL, &tail->value, &err);
1080             if (err) {
1081                 break;
1082             }
1083         }
1084
1085         visit_end_list(v, (void **)obj);
1086         if (err && visit_is_input(v)) {
1087             qapi_free_UserDefOneList(*obj);
1088             *obj = NULL;
1089         }
1090     out:
1091         error_propagate(errp, err);
1092     }
1093
1094 === scripts/qapi-commands.py ===
1095
1096 Used to generate the marshaling/dispatch functions for the commands
1097 defined in the schema. The generated code implements
1098 qmp_marshal_COMMAND() (registered automatically), and declares
1099 qmp_COMMAND() that the user must implement.  The following files are
1100 generated:
1101
1102 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
1103                         QMP command defined in the schema. Functions
1104                         generated by qapi-visit.py are used to
1105                         convert QObjects received from the wire into
1106                         function parameters, and uses the same
1107                         visitor functions to convert native C return
1108                         values to QObjects from transmission back
1109                         over the wire.
1110
1111 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
1112                          specified in the schema.
1113
1114 Example:
1115
1116     $ python scripts/qapi-commands.py --output-dir="qapi-generated"
1117     --prefix="example-" example-schema.json
1118     $ cat qapi-generated/example-qmp-commands.h
1119 [Uninteresting stuff omitted...]
1120
1121     #ifndef EXAMPLE_QMP_COMMANDS_H
1122     #define EXAMPLE_QMP_COMMANDS_H
1123
1124     #include "example-qapi-types.h"
1125     #include "qapi/qmp/qdict.h"
1126     #include "qapi/error.h"
1127
1128     UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp);
1129
1130     #endif
1131     $ cat qapi-generated/example-qmp-marshal.c
1132 [Uninteresting stuff omitted...]
1133
1134     static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp)
1135     {
1136         Error *err = NULL;
1137         Visitor *v;
1138
1139         v = qobject_output_visitor_new(ret_out);
1140         visit_type_UserDefOne(v, "unused", &ret_in, &err);
1141         if (!err) {
1142             visit_complete(v, ret_out);
1143         }
1144         error_propagate(errp, err);
1145         visit_free(v);
1146         v = qapi_dealloc_visitor_new();
1147         visit_type_UserDefOne(v, "unused", &ret_in, NULL);
1148         visit_free(v);
1149     }
1150
1151     static void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
1152     {
1153         Error *err = NULL;
1154         UserDefOne *retval;
1155         Visitor *v;
1156         UserDefOneList *arg1 = NULL;
1157
1158         v = qobject_input_visitor_new(QOBJECT(args));
1159         visit_start_struct(v, NULL, NULL, 0, &err);
1160         if (err) {
1161             goto out;
1162         }
1163         visit_type_UserDefOneList(v, "arg1", &arg1, &err);
1164         if (!err) {
1165             visit_check_struct(v, &err);
1166         }
1167         visit_end_struct(v, NULL);
1168         if (err) {
1169             goto out;
1170         }
1171
1172         retval = qmp_my_command(arg1, &err);
1173         if (err) {
1174             goto out;
1175         }
1176
1177         qmp_marshal_output_UserDefOne(retval, ret, &err);
1178
1179     out:
1180         error_propagate(errp, err);
1181         visit_free(v);
1182         v = qapi_dealloc_visitor_new();
1183         visit_start_struct(v, NULL, NULL, 0, NULL);
1184         visit_type_UserDefOneList(v, "arg1", &arg1, NULL);
1185         visit_end_struct(v, NULL);
1186         visit_free(v);
1187     }
1188
1189     static void qmp_init_marshal(void)
1190     {
1191         qmp_register_command("my-command", qmp_marshal_my_command, QCO_NO_OPTIONS);
1192     }
1193
1194     qapi_init(qmp_init_marshal);
1195
1196 === scripts/qapi-event.py ===
1197
1198 Used to generate the event-related C code defined by a schema, with
1199 implementations for qapi_event_send_FOO(). The following files are
1200 created:
1201
1202 $(prefix)qapi-event.h - Function prototypes for each event type, plus an
1203                         enumeration of all event names
1204 $(prefix)qapi-event.c - Implementation of functions to send an event
1205
1206 Example:
1207
1208     $ python scripts/qapi-event.py --output-dir="qapi-generated"
1209     --prefix="example-" example-schema.json
1210     $ cat qapi-generated/example-qapi-event.h
1211 [Uninteresting stuff omitted...]
1212
1213     #ifndef EXAMPLE_QAPI_EVENT_H
1214     #define EXAMPLE_QAPI_EVENT_H
1215
1216     #include "qapi/error.h"
1217     #include "qapi/qmp/qdict.h"
1218     #include "example-qapi-types.h"
1219
1220
1221     void qapi_event_send_my_event(Error **errp);
1222
1223     typedef enum example_QAPIEvent {
1224         EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
1225         EXAMPLE_QAPI_EVENT__MAX = 1,
1226     } example_QAPIEvent;
1227
1228     extern const char *const example_QAPIEvent_lookup[];
1229
1230     #endif
1231     $ cat qapi-generated/example-qapi-event.c
1232 [Uninteresting stuff omitted...]
1233
1234     void qapi_event_send_my_event(Error **errp)
1235     {
1236         QDict *qmp;
1237         Error *err = NULL;
1238         QMPEventFuncEmit emit;
1239         emit = qmp_event_get_func_emit();
1240         if (!emit) {
1241             return;
1242         }
1243
1244         qmp = qmp_event_build_dict("MY_EVENT");
1245
1246         emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err);
1247
1248         error_propagate(errp, err);
1249         QDECREF(qmp);
1250     }
1251
1252     const char *const example_QAPIEvent_lookup[] = {
1253         [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1254         [EXAMPLE_QAPI_EVENT__MAX] = NULL,
1255     };
1256
1257 === scripts/qapi-introspect.py ===
1258
1259 Used to generate the introspection C code for a schema. The following
1260 files are created:
1261
1262 $(prefix)qmp-introspect.c - Defines a string holding a JSON
1263                             description of the schema.
1264 $(prefix)qmp-introspect.h - Declares the above string.
1265
1266 Example:
1267
1268     $ python scripts/qapi-introspect.py --output-dir="qapi-generated"
1269     --prefix="example-" example-schema.json
1270     $ cat qapi-generated/example-qmp-introspect.h
1271 [Uninteresting stuff omitted...]
1272
1273     #ifndef EXAMPLE_QMP_INTROSPECT_H
1274     #define EXAMPLE_QMP_INTROSPECT_H
1275
1276     extern const char example_qmp_schema_json[];
1277
1278     #endif
1279     $ cat qapi-generated/example-qmp-introspect.c
1280 [Uninteresting stuff omitted...]
1281
1282     const char example_qmp_schema_json[] = "["
1283         "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, "
1284         "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, "
1285         "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, "
1286         "{\"members\": [{\"name\": \"arg1\", \"type\": \"[2]\"}], \"meta-type\": \"object\", \"name\": \"1\"}, "
1287         "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"default\": null, \"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, "
1288         "{\"element-type\": \"2\", \"meta-type\": \"array\", \"name\": \"[2]\"}, "
1289         "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, "
1290         "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]";