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