summaryrefslogtreecommitdiff
path: root/docs/qapi-code-gen.txt
blob: 61b5be47fbe48ea1cf26c2e3de0cfcd50083f881 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
= How to use the QAPI code generator =

Copyright IBM Corp. 2011
Copyright (C) 2012-2015 Red Hat, Inc.

This work is licensed under the terms of the GNU GPL, version 2 or
later. See the COPYING file in the top-level directory.

== Introduction ==

QAPI is a native C API within QEMU which provides management-level
functionality to internal and external users. For external
users/processes, this interface is made available by a JSON-based wire
format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
well as the QEMU Guest Agent (QGA) for communicating with the guest.
The remainder of this document uses "Client JSON Protocol" when
referring to the wire contents of a QMP or QGA connection.

To map Client JSON Protocol interfaces to the native C QAPI
implementations, a JSON-based schema is used to define types and
function signatures, and a set of scripts is used to generate types,
signatures, and marshaling/dispatch code. This document will describe
how the schemas, scripts, and resulting code are used.


== QMP/Guest agent schema ==

A QAPI schema file is designed to be loosely based on JSON
(http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style
and the use of comments; a QAPI schema file is then parsed by a python
code generation program.  A valid QAPI schema consists of a series of
top-level expressions, with no commas between them.  Where
dictionaries (JSON objects) are used, they are parsed as python
OrderedDicts so that ordering is preserved (for predictable layout of
generated C structs and parameter lists).  Ordering doesn't matter
between top-level expressions or the keys within an expression, but
does matter within dictionary values for 'data' and 'returns' members
of a single expression.  QAPI schema input is written using 'single
quotes' instead of JSON's "double quotes" (in contrast, Client JSON
Protocol uses no comments, and while input accepts 'single quotes' as
an extension, output is strict JSON using only "double quotes").  As
in JSON, trailing commas are not permitted in arrays or dictionaries.
Input must be ASCII (although QMP supports full Unicode strings, the
QAPI parser does not).  At present, there is no place where a QAPI
schema requires the use of JSON numbers or null.

Comments are allowed; anything between an unquoted # and the following
newline is ignored.  Although there is not yet a documentation
generator, a form of stylized comments has developed for consistently
documenting details about an expression and when it was added to the
schema.  The documentation is delimited between two lines of ##, then
the first line names the expression, an optional overview is provided,
then individual documentation about each member of 'data' is provided,
and finally, a 'Since: x.y.z' tag lists the release that introduced
the expression.  Optional fields are tagged with the phrase
'#optional', often with their default value; and extensions added
after the expression was first released are also given a '(since
x.y.z)' comment.  For example:

    ##
    # @BlockStats:
    #
    # Statistics of a virtual block device or a block backing device.
    #
    # @device: #optional If the stats are for a virtual block device, the name
    #          corresponding to the virtual block device.
    #
    # @stats:  A @BlockDeviceStats for the device.
    #
    # @parent: #optional This describes the file block device if it has one.
    #
    # @backing: #optional This describes the backing block device if it has one.
    #           (Since 2.0)
    #
    # Since: 0.14.0
    ##
    { 'struct': 'BlockStats',
      'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
               '*parent': 'BlockStats',
               '*backing': 'BlockStats'} }

The schema sets up a series of types, as well as commands and events
that will use those types.  Forward references are allowed: the parser
scans in two passes, where the first pass learns all type names, and
the second validates the schema and generates the code.  This allows
the definition of complex structs that can have mutually recursive
types, and allows for indefinite nesting of Client JSON Protocol that
satisfies the schema.  A type name should not be defined more than
once.  It is permissible for the schema to contain additional types
not used by any commands or events in the Client JSON Protocol, for
the side effect of generated C code used internally.

There are seven top-level expressions recognized by the parser:
'include', 'command', 'struct', 'enum', 'union', 'alternate', and
'event'.  There are several groups of types: simple types (a number of
built-in types, such as 'int' and 'str'; as well as enumerations),
complex types (structs and two flavors of unions), and alternate types
(a choice between other types).  The 'command' and 'event' expressions
can refer to existing types by name, or list an anonymous type as a
dictionary. Listing a type name inside an array refers to a
single-dimension array of that type; multi-dimension arrays are not
directly supported (although an array of a complex struct that
contains an array member is possible).

Types, commands, and events share a common namespace.  Therefore,
generally speaking, type definitions should always use CamelCase for
user-defined type names, while built-in types are lowercase. Type
definitions should not end in 'Kind', as this namespace is used for
creating implicit C enums for visiting union types.  Command names,
and field names within a type, should be all lower case with words
separated by a hyphen.  However, some existing older commands and
complex types use underscore; when extending such expressions,
consistency is preferred over blindly avoiding underscore.  Event
names should be ALL_CAPS with words separated by underscore.  The
special string '**' appears for some commands that manually perform
their own type checking rather than relying on the type-safe code
produced by the qapi code generators.

Any name (command, event, type, field, or enum value) beginning with
"x-" is marked experimental, and may be withdrawn or changed
incompatibly in a future release.  Downstream vendors may add
extensions; such extensions should begin with a prefix matching
"__RFQDN_" (for the reverse-fully-qualified-domain-name of the
vendor), even if the rest of the name uses dash (example:
__com.redhat_drive-mirror).  Other than downstream extensions (with
leading underscore and the use of dots), all names should begin with a
letter, and contain only ASCII letters, digits, dash, and underscore.
It is okay to reuse names that match C keywords; the generator will
rename a field named "default" in the QAPI to "q_default" in the
generated C code.

In the rest of this document, usage lines are given for each
expression type, with literal strings written in lower case and
placeholders written in capitals.  If a literal string includes a
prefix of '*', that key/value pair can be omitted from the expression.
For example, a usage statement that includes '*base':STRUCT-NAME
means that an expression has an optional key 'base', which if present
must have a value that forms a struct name.


=== Built-in Types ===

The following types are built-in to the parser:
  'str' - arbitrary UTF-8 string
  'int' - 64-bit signed integer (although the C code may place further
          restrictions on acceptable range)
  'number' - floating point number
  'bool' - JSON value of true or false
  'int8', 'int16', 'int32', 'int64' - like 'int', but enforce maximum
                                      bit size
  'uint8', 'uint16', 'uint32', 'uint64' - unsigned counterparts
  'size' - like 'uint64', but allows scaled suffix from command line
           visitor


=== Includes ===

Usage: { 'include': STRING }

The QAPI schema definitions can be modularized using the 'include' directive:

 { 'include': 'path/to/file.json' }

The directive is evaluated recursively, and include paths are relative to the
file using the directive. Multiple includes of the same file are
safe.  No other keys should appear in the expression, and the include
value should be a string.

As a matter of style, it is a good idea to have all files be
self-contained, but at the moment, nothing prevents an included file
from making a forward reference to a type that is only introduced by
an outer file.  The parser may be made stricter in the future to
prevent incomplete include files.


=== Struct types ===

Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }

A struct is a dictionary containing a single 'data' key whose
value is a dictionary.  This corresponds to a struct in C or an Object
in JSON. Each value of the 'data' dictionary must be the name of a
type, or a one-element array containing a type name.  An example of a
struct is:

 { 'struct': 'MyType',
   'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }

The use of '*' as a prefix to the name means the member is optional in
the corresponding JSON protocol usage.

The default initialization value of an optional argument should not be changed
between versions of QEMU unless the new default maintains backward
compatibility to the user-visible behavior of the old default.

With proper documentation, this policy still allows some flexibility; for
example, documenting that a default of 0 picks an optimal buffer size allows
one release to declare the optimal size at 512 while another release declares
the optimal size at 4096 - the user-visible behavior is not the bytes used by
the buffer, but the fact that the buffer was optimal size.

On input structures (only mentioned in the 'data' side of a command), changing
from mandatory to optional is safe (older clients will supply the option, and
newer clients can benefit from the default); changing from optional to
mandatory is backwards incompatible (older clients may be omitting the option,
and must continue to work).

On output structures (only mentioned in the 'returns' side of a command),
changing from mandatory to optional is in general unsafe (older clients may be
expecting the field, and could crash if it is missing), although it can be done
if the only way that the optional argument will be omitted is when it is
triggered by the presence of a new input flag to the command that older clients
don't know to send.  Changing from optional to mandatory is safe.

A structure that is used in both input and output of various commands
must consider the backwards compatibility constraints of both directions
of use.

A struct definition can specify another struct as its base.
In this case, the fields of the base type are included as top-level fields
of the new struct's dictionary in the Client JSON Protocol wire
format. An example definition is:

 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
 { 'struct': 'BlockdevOptionsGenericCOWFormat',
   'base': 'BlockdevOptionsGenericFormat',
   'data': { '*backing': 'str' } }

An example BlockdevOptionsGenericCOWFormat object on the wire could use
both fields like this:

 { "file": "/some/place/my-image",
   "backing": "/some/place/my-backing-file" }


=== Enumeration types ===

Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }

An enumeration type is a dictionary containing a single 'data' key
whose value is a list of strings.  An example enumeration is:

 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }

Nothing prevents an empty enumeration, although it is probably not
useful.  The list of strings should be lower case; if an enum name
represents multiple words, use '-' between words.  The string 'max' is
not allowed as an enum value, and values should not be repeated.

The enumeration values are passed as strings over the Client JSON
Protocol, but are encoded as C enum integral values in generated code.
While the C code starts numbering at 0, it is better to use explicit
comparisons to enum values than implicit comparisons to 0; the C code
will also include a generated enum member ending in _MAX for tracking
the size of the enum, useful when using common functions for
converting between strings and enum values.  Since the wire format
always passes by name, it is acceptable to reorder or add new
enumeration members in any location without breaking clients of Client
JSON Protocol; however, removing enum values would break
compatibility.  For any struct that has a field that will only contain
a finite set of string values, using an enum type for that field is
better than open-coding the field to be type 'str'.


=== Union types ===

Usage: { 'union': STRING, 'data': DICT }
or:    { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME,
         'discriminator': ENUM-MEMBER-OF-BASE }

Union types are used to let the user choose between several different
variants for an object.  There are two flavors: simple (no
discriminator or base), flat (both discriminator and base).  A union
type is defined using a data dictionary as explained in the following
paragraphs.

A simple union type defines a mapping from automatic discriminator
values to data types like in this example:

 { 'struct': 'FileOptions', 'data': { 'filename': 'str' } }
 { 'struct': 'Qcow2Options',
   'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }

 { 'union': 'BlockdevOptions',
   'data': { 'file': 'FileOptions',
             'qcow2': 'Qcow2Options' } }

In the Client JSON Protocol, a simple union is represented by a
dictionary that contains the 'type' field as a discriminator, and a
'data' field that is of the specified data type corresponding to the
discriminator value, as in these examples:

 { "type": "file", "data" : { "filename": "/some/place/my-image" } }
 { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
                               "lazy-refcounts": true } }

The generated C code uses a struct containing a union. Additionally,
an implicit C enum 'NameKind' is created, corresponding to the union
'Name', for accessing the various branches of the union.  No branch of
the union can be named 'max', as this would collide with the implicit
enum.  The value for each branch can be of any type.


A flat union definition specifies a struct as its base, and
avoids nesting on the wire.  All branches of the union must be
complex types, and the top-level fields of the union dictionary on
the wire will be combination of fields from both the base type and the
appropriate branch type (when merging two dictionaries, there must be
no keys in common).  The 'discriminator' field must be the name of an
enum-typed member of the base struct.

The following example enhances the above simple union example by
adding a common field 'readonly', renaming the discriminator to
something more applicable, and reducing the number of {} required on
the wire:

 { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] }
 { 'struct': 'BlockdevCommonOptions',
   'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } }
 { 'union': 'BlockdevOptions',
   'base': 'BlockdevCommonOptions',
   'discriminator': 'driver',
   'data': { 'file': 'FileOptions',
             'qcow2': 'Qcow2Options' } }

Resulting in these JSON objects:

 { "driver": "file", "readonly": true,
   "filename": "/some/place/my-image" }
 { "driver": "qcow2", "readonly": false,
   "backing-file": "/some/place/my-image", "lazy-refcounts": true }

Notice that in a flat union, the discriminator name is controlled by
the user, but because it must map to a base member with enum type, the
code generator can ensure that branches exist for all values of the
enum (although the order of the keys need not match the declaration of
the enum).  In the resulting generated C data types, a flat union is
represented as a struct with the base member fields included directly,
and then a union of structures for each branch of the struct.

A simple union can always be re-written as a flat union where the base
class has a single member named 'type', and where each branch of the
union has a struct with a single member named 'data'.  That is,

 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }

is identical on the wire to:

 { 'enum': 'Enum', 'data': ['one', 'two'] }
 { 'struct': 'Base', 'data': { 'type': 'Enum' } }
 { 'struct': 'Branch1', 'data': { 'data': 'str' } }
 { 'struct': 'Branch2', 'data': { 'data': 'int' } }
 { 'union': 'Flat': 'base': 'Base', 'discriminator': 'type',
   'data': { 'one': 'Branch1', 'two': 'Branch2' } }


=== Alternate types ===

Usage: { 'alternate': STRING, 'data': DICT }

An alternate type is one that allows a choice between two or more JSON
data types (string, integer, number, or object, but currently not
array) on the wire.  The definition is similar to a simple union type,
where each branch of the union names a QAPI type.  For example:

 { 'alternate': 'BlockRef',
   'data': { 'definition': 'BlockdevOptions',
             'reference': 'str' } }

Just like for a simple union, an implicit C enum 'NameKind' is created
to enumerate the branches for the alternate 'Name'.

Unlike a union, the discriminator string is never passed on the wire
for the Client JSON Protocol.  Instead, the value's JSON type serves
as an implicit discriminator, which in turn means that an alternate
can only express a choice between types represented differently in
JSON.  If a branch is typed as the 'bool' built-in, the alternate
accepts true and false; if it is typed as any of the various numeric
built-ins, it accepts a JSON number; if it is typed as a 'str'
built-in or named enum type, it accepts a JSON string; and if it is
typed as a complex type (struct or union), it accepts a JSON object.
Two different complex types, for instance, aren't permitted, because
both are represented as a JSON object.

The example alternate declaration above allows using both of the
following example objects:

 { "file": "my_existing_block_device_id" }
 { "file": { "driver": "file",
             "readonly": false,
             "filename": "/tmp/mydisk.qcow2" } }


=== Commands ===

Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
         '*returns': TYPE-NAME-OR-DICT,
         '*gen': false, '*success-response': false }

Commands are defined by using a dictionary containing several members,
where three members are most common.  The 'command' member is a
mandatory string, and determines the "execute" value passed in a
Client JSON Protocol command exchange.

The 'data' argument maps to the "arguments" dictionary passed in as
part of a Client JSON Protocol command.  The 'data' member is optional
and defaults to {} (an empty dictionary).  If present, it must be the
string name of a complex type, a one-element array containing the name
of a complex type, or a dictionary that declares an anonymous type
with the same semantics as a 'struct' expression, with one exception
noted below when 'gen' is used.

The 'returns' member describes what will appear in the "return" field
of a Client JSON Protocol reply on successful completion of a command.
The member is optional from the command declaration; if absent, the
"return" field will be an empty dictionary.  If 'returns' is present,
it must be the string name of a complex or built-in type, a
one-element array containing the name of a complex or built-in type,
or a dictionary that declares an anonymous type with the same
semantics as a 'struct' expression, with one exception noted below
when 'gen' is used.  Although it is permitted to have the 'returns'
member name a built-in type or an array of built-in types, any command
that does this cannot be extended to return additional information in
the future; thus, new commands should strongly consider returning a
dictionary-based type or an array of dictionaries, even if the
dictionary only contains one field at the present.

All commands in Client JSON Protocol use a dictionary to report
failure, with no way to specify that in QAPI.  Where the error return
is different than the usual GenericError class in order to help the
client react differently to certain error conditions, it is worth
documenting this in the comments before the command declaration.

Some example commands:

 { 'command': 'my-first-command',
   'data': { 'arg1': 'str', '*arg2': 'str' } }
 { 'struct': 'MyType', 'data': { '*value': 'str' } }
 { 'command': 'my-second-command',
   'returns': [ 'MyType' ] }

which would validate this Client JSON Protocol transaction:

 => { "execute": "my-first-command",
      "arguments": { "arg1": "hello" } }
 <= { "return": { } }
 => { "execute": "my-second-command" }
 <= { "return": [ { "value": "one" }, { } ] }

In rare cases, QAPI cannot express a type-safe representation of a
corresponding Client JSON Protocol command.  In these cases, if the
command expression includes the key 'gen' with boolean value false,
then the 'data' or 'returns' member that intends to bypass generated
type-safety and do its own manual validation should use an inline
dictionary definition, with a value of '**' rather than a valid type
name for the keys that the generated code will not validate.  Please
try to avoid adding new commands that rely on this, and instead use
type-safe unions.  For an example of bypass usage:

 { 'command': 'netdev_add',
   'data': {'type': 'str', 'id': 'str', '*props': '**'},
   'gen': false }

Normally, the QAPI schema is used to describe synchronous exchanges,
where a response is expected.  But in some cases, the action of a
command is expected to change state in a way that a successful
response is not possible (although the command will still return a
normal dictionary error on failure).  When a successful reply is not
possible, the command expression should include the optional key
'success-response' with boolean value false.  So far, only QGA makes
use of this field.


=== Events ===

Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT }

Events are defined with the keyword 'event'.  It is not allowed to
name an event 'MAX', since the generator also produces a C enumeration
of all event names with a generated _MAX value at the end.  When
'data' is also specified, additional info will be included in the
event, with similar semantics to a 'struct' expression.  Finally there
will be C API generated in qapi-event.h; when called by QEMU code, a
message with timestamp will be emitted on the wire.

An example event is:

{ 'event': 'EVENT_C',
  'data': { '*a': 'int', 'b': 'str' } }

Resulting in this JSON object:

{ "event": "EVENT_C",
  "data": { "b": "test string" },
  "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }


== Code generation ==

Schemas are fed into 3 scripts to generate all the code/files that, paired
with the core QAPI libraries, comprise everything required to take JSON
commands read in by a Client JSON Protocol server, unmarshal the arguments into
the underlying C types, call into the corresponding C function, and map the
response back to a Client JSON Protocol response to be returned to the user.

As an example, we'll use the following schema, which describes a single
complex user-defined type (which will produce a C struct, along with a list
node structure that can be used to chain together a list of such types in
case we want to accept/return a list of this type with a command), and a
command which takes that type as a parameter and returns the same type:

    $ cat example-schema.json
    { 'struct': 'UserDefOne',
      'data': { 'integer': 'int', 'string': 'str' } }

    { 'command': 'my-command',
      'data':    {'arg1': 'UserDefOne'},
      'returns': 'UserDefOne' }

    { 'event': 'MY_EVENT' }

=== scripts/qapi-types.py ===

Used to generate the C types defined by a schema. The following files are
created:

$(prefix)qapi-types.h - C types corresponding to types defined in
                        the schema you pass in
$(prefix)qapi-types.c - Cleanup functions for the above C types

The $(prefix) is an optional parameter used as a namespace to keep the
generated code from one schema/code-generation separated from others so code
can be generated/used from multiple schemas without clobbering previously
created code.

Example:

    $ python scripts/qapi-types.py --output-dir="qapi-generated" \
    --prefix="example-" example-schema.json
    $ cat qapi-generated/example-qapi-types.c
[Uninteresting stuff omitted...]

    void qapi_free_UserDefOneList(UserDefOneList *obj)
    {
        QapiDeallocVisitor *md;
        Visitor *v;

        if (!obj) {
            return;
        }

        md = qapi_dealloc_visitor_new();
        v = qapi_dealloc_get_visitor(md);
        visit_type_UserDefOneList(v, &obj, NULL, NULL);
        qapi_dealloc_visitor_cleanup(md);
    }

    void qapi_free_UserDefOne(UserDefOne *obj)
    {
        QapiDeallocVisitor *md;
        Visitor *v;

        if (!obj) {
            return;
        }

        md = qapi_dealloc_visitor_new();
        v = qapi_dealloc_get_visitor(md);
        visit_type_UserDefOne(v, &obj, NULL, NULL);
        qapi_dealloc_visitor_cleanup(md);
    }

    $ cat qapi-generated/example-qapi-types.h
[Uninteresting stuff omitted...]

    #ifndef EXAMPLE_QAPI_TYPES_H
    #define EXAMPLE_QAPI_TYPES_H

[Built-in types omitted...]

    typedef struct UserDefOne UserDefOne;

    typedef struct UserDefOneList
    {
        union {
            UserDefOne *value;
            uint64_t padding;
        };
        struct UserDefOneList *next;
    } UserDefOneList;

[Functions on built-in types omitted...]

    struct UserDefOne
    {
        int64_t integer;
        char *string;
    };

    void qapi_free_UserDefOneList(UserDefOneList *obj);
    void qapi_free_UserDefOne(UserDefOne *obj);

    #endif

=== scripts/qapi-visit.py ===

Used to generate the visitor functions used to walk through and convert
a QObject (as provided by QMP) to a native C data structure and
vice-versa, as well as the visitor function used to dealloc a complex
schema-defined C type.

The following files are generated:

$(prefix)qapi-visit.c: visitor function for a particular C type, used
                       to automagically convert QObjects into the
                       corresponding C type and vice-versa, as well
                       as for deallocating memory for an existing C
                       type

$(prefix)qapi-visit.h: declarations for previously mentioned visitor
                       functions

Example:

    $ python scripts/qapi-visit.py --output-dir="qapi-generated"
    --prefix="example-" example-schema.json
    $ cat qapi-generated/example-qapi-visit.c
[Uninteresting stuff omitted...]

    static void visit_type_UserDefOne_fields(Visitor *m, UserDefOne **obj, Error **errp)
    {
        Error *err = NULL;
        visit_type_int(m, &(*obj)->integer, "integer", &err);
        if (err) {
            goto out;
        }
        visit_type_str(m, &(*obj)->string, "string", &err);
        if (err) {
            goto out;
        }

    out:
        error_propagate(errp, err);
    }

    void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp)
    {
        Error *err = NULL;

        visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), &err);
        if (!err) {
            if (*obj) {
                visit_type_UserDefOne_fields(m, obj, errp);
            }
            visit_end_struct(m, &err);
        }
        error_propagate(errp, err);
    }

    void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp)
    {
        Error *err = NULL;
        GenericList *i, **prev;

        visit_start_list(m, name, &err);
        if (err) {
            goto out;
        }

        for (prev = (GenericList **)obj;
             !err && (i = visit_next_list(m, prev, &err)) != NULL;
             prev = &i) {
            UserDefOneList *native_i = (UserDefOneList *)i;
            visit_type_UserDefOne(m, &native_i->value, NULL, &err);
        }

        error_propagate(errp, err);
        err = NULL;
        visit_end_list(m, &err);
    out:
        error_propagate(errp, err);
    }
    $ cat qapi-generated/example-qapi-visit.h
[Uninteresting stuff omitted...]

    #ifndef EXAMPLE_QAPI_VISIT_H
    #define EXAMPLE_QAPI_VISIT_H

[Visitors for built-in types omitted...]

    void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp);
    void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp);

    #endif

=== scripts/qapi-commands.py ===

Used to generate the marshaling/dispatch functions for the commands defined
in the schema. The following files are generated:

$(prefix)qmp-marshal.c: command marshal/dispatch functions for each
                        QMP command defined in the schema. Functions
                        generated by qapi-visit.py are used to
                        convert QObjects received from the wire into
                        function parameters, and uses the same
                        visitor functions to convert native C return
                        values to QObjects from transmission back
                        over the wire.

$(prefix)qmp-commands.h: Function prototypes for the QMP commands
                         specified in the schema.

Example:

    $ python scripts/qapi-commands.py --output-dir="qapi-generated"
    --prefix="example-" example-schema.json
    $ cat qapi-generated/example-qmp-marshal.c
[Uninteresting stuff omitted...]

    static void qmp_marshal_output_my_command(UserDefOne *ret_in, QObject **ret_out, Error **errp)
    {
        Error *local_err = NULL;
        QmpOutputVisitor *mo = qmp_output_visitor_new();
        QapiDeallocVisitor *md;
        Visitor *v;

        v = qmp_output_get_visitor(mo);
        visit_type_UserDefOne(v, &ret_in, "unused", &local_err);
        if (local_err) {
            goto out;
        }
        *ret_out = qmp_output_get_qobject(mo);

    out:
        error_propagate(errp, local_err);
        qmp_output_visitor_cleanup(mo);
        md = qapi_dealloc_visitor_new();
        v = qapi_dealloc_get_visitor(md);
        visit_type_UserDefOne(v, &ret_in, "unused", NULL);
        qapi_dealloc_visitor_cleanup(md);
    }

    static void qmp_marshal_input_my_command(QDict *args, QObject **ret, Error **errp)
    {
        Error *local_err = NULL;
        UserDefOne *retval = NULL;
        QmpInputVisitor *mi = qmp_input_visitor_new_strict(QOBJECT(args));
        QapiDeallocVisitor *md;
        Visitor *v;
        UserDefOne *arg1 = NULL;

        v = qmp_input_get_visitor(mi);
        visit_type_UserDefOne(v, &arg1, "arg1", &local_err);
        if (local_err) {
            goto out;
        }

        retval = qmp_my_command(arg1, &local_err);
        if (local_err) {
            goto out;
        }

        qmp_marshal_output_my_command(retval, ret, &local_err);

    out:
        error_propagate(errp, local_err);
        qmp_input_visitor_cleanup(mi);
        md = qapi_dealloc_visitor_new();
        v = qapi_dealloc_get_visitor(md);
        visit_type_UserDefOne(v, &arg1, "arg1", NULL);
        qapi_dealloc_visitor_cleanup(md);
        return;
    }

    static void qmp_init_marshal(void)
    {
        qmp_register_command("my-command", qmp_marshal_input_my_command, QCO_NO_OPTIONS);
    }

    qapi_init(qmp_init_marshal);
    $ cat qapi-generated/example-qmp-commands.h
[Uninteresting stuff omitted...]

    #ifndef EXAMPLE_QMP_COMMANDS_H
    #define EXAMPLE_QMP_COMMANDS_H

    #include "example-qapi-types.h"
    #include "qapi/qmp/qdict.h"
    #include "qapi/error.h"

    UserDefOne *qmp_my_command(UserDefOne *arg1, Error **errp);

    #endif

=== scripts/qapi-event.py ===

Used to generate the event-related C code defined by a schema. The
following files are created:

$(prefix)qapi-event.h - Function prototypes for each event type, plus an
                        enumeration of all event names
$(prefix)qapi-event.c - Implementation of functions to send an event

Example:

    $ python scripts/qapi-event.py --output-dir="qapi-generated"
    --prefix="example-" example-schema.json
    $ cat qapi-generated/example-qapi-event.c
[Uninteresting stuff omitted...]

    void qapi_event_send_my_event(Error **errp)
    {
        QDict *qmp;
        Error *local_err = NULL;
        QMPEventFuncEmit emit;
        emit = qmp_event_get_func_emit();
        if (!emit) {
            return;
        }

        qmp = qmp_event_build_dict("MY_EVENT");

        emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &local_err);

        error_propagate(errp, local_err);
        QDECREF(qmp);
    }

    const char *EXAMPLE_QAPIEvent_lookup[] = {
        "MY_EVENT",
        NULL,
    };
    $ cat qapi-generated/example-qapi-event.h
[Uninteresting stuff omitted...]

    #ifndef EXAMPLE_QAPI_EVENT_H
    #define EXAMPLE_QAPI_EVENT_H

    #include "qapi/error.h"
    #include "qapi/qmp/qdict.h"
    #include "example-qapi-types.h"


    void qapi_event_send_my_event(Error **errp);

    extern const char *EXAMPLE_QAPIEvent_lookup[];
    typedef enum EXAMPLE_QAPIEvent
    {
        EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
        EXAMPLE_QAPI_EVENT_MAX = 1,
    } EXAMPLE_QAPIEvent;

    #endif