1 = How to use the QAPI code generator =
3 Copyright IBM Corp. 2011
4 Copyright (C) 2012-2015 Red Hat, Inc.
6 This work is licensed under the terms of the GNU GPL, version 2 or
7 later. See the COPYING file in the top-level directory.
11 QAPI is a native C API within QEMU which provides management-level
12 functionality to internal and external users. For external
13 users/processes, this interface is made available by a JSON-based wire
14 format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
15 well as the QEMU Guest Agent (QGA) for communicating with the guest.
16 The remainder of this document uses "Client JSON Protocol" when
17 referring to the wire contents of a QMP or QGA connection.
19 To map Client JSON Protocol interfaces to the native C QAPI
20 implementations, a JSON-based schema is used to define types and
21 function signatures, and a set of scripts is used to generate types,
22 signatures, and marshaling/dispatch code. This document will describe
23 how the schemas, scripts, and resulting code are used.
26 == QMP/Guest agent schema ==
28 A QAPI schema file is designed to be loosely based on JSON
29 (http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style
30 and the use of comments; a QAPI schema file is then parsed by a python
31 code generation program. A valid QAPI schema consists of a series of
32 top-level expressions, with no commas between them. Where
33 dictionaries (JSON objects) are used, they are parsed as python
34 OrderedDicts so that ordering is preserved (for predictable layout of
35 generated C structs and parameter lists). Ordering doesn't matter
36 between top-level expressions or the keys within an expression, but
37 does matter within dictionary values for 'data' and 'returns' members
38 of a single expression. QAPI schema input is written using 'single
39 quotes' instead of JSON's "double quotes" (in contrast, Client JSON
40 Protocol uses no comments, and while input accepts 'single quotes' as
41 an extension, output is strict JSON using only "double quotes"). As
42 in JSON, trailing commas are not permitted in arrays or dictionaries.
43 Input must be ASCII (although QMP supports full Unicode strings, the
44 QAPI parser does not). At present, there is no place where a QAPI
45 schema requires the use of JSON numbers or null.
47 Comments are allowed; anything between an unquoted # and the following
48 newline is ignored. Although there is not yet a documentation
49 generator, a form of stylized comments has developed for consistently
50 documenting details about an expression and when it was added to the
51 schema. The documentation is delimited between two lines of ##, then
52 the first line names the expression, an optional overview is provided,
53 then individual documentation about each member of 'data' is provided,
54 and finally, a 'Since: x.y.z' tag lists the release that introduced
55 the expression. Optional fields are tagged with the phrase
56 '#optional', often with their default value; and extensions added
57 after the expression was first released are also given a '(since
58 x.y.z)' comment. For example:
63 # Statistics of a virtual block device or a block backing device.
65 # @device: #optional If the stats are for a virtual block device, the name
66 # corresponding to the virtual block device.
68 # @stats: A @BlockDeviceStats for the device.
70 # @parent: #optional This describes the file block device if it has one.
72 # @backing: #optional This describes the backing block device if it has one.
77 { 'struct': 'BlockStats',
78 'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
79 '*parent': 'BlockStats',
80 '*backing': 'BlockStats'} }
82 The schema sets up a series of types, as well as commands and events
83 that will use those types. Forward references are allowed: the parser
84 scans in two passes, where the first pass learns all type names, and
85 the second validates the schema and generates the code. This allows
86 the definition of complex structs that can have mutually recursive
87 types, and allows for indefinite nesting of Client JSON Protocol that
88 satisfies the schema. A type name should not be defined more than
89 once. It is permissible for the schema to contain additional types
90 not used by any commands or events in the Client JSON Protocol, for
91 the side effect of generated C code used internally.
93 There are seven top-level expressions recognized by the parser:
94 'include', 'command', 'struct', 'enum', 'union', 'alternate', and
95 'event'. There are several groups of types: simple types (a number of
96 built-in types, such as 'int' and 'str'; as well as enumerations),
97 complex types (structs and two flavors of unions), and alternate types
98 (a choice between other types). The 'command' and 'event' expressions
99 can refer to existing types by name, or list an anonymous type as a
100 dictionary. Listing a type name inside an array refers to a
101 single-dimension array of that type; multi-dimension arrays are not
102 directly supported (although an array of a complex struct that
103 contains an array member is possible).
105 Types, commands, and events share a common namespace. Therefore,
106 generally speaking, type definitions should always use CamelCase for
107 user-defined type names, while built-in types are lowercase. Type
108 definitions should not end in 'Kind', as this namespace is used for
109 creating implicit C enums for visiting union types. Command names,
110 and field names within a type, should be all lower case with words
111 separated by a hyphen. However, some existing older commands and
112 complex types use underscore; when extending such expressions,
113 consistency is preferred over blindly avoiding underscore. Event
114 names should be ALL_CAPS with words separated by underscore. The
115 special string '**' appears for some commands that manually perform
116 their own type checking rather than relying on the type-safe code
117 produced by the qapi code generators.
119 Any name (command, event, type, field, or enum value) beginning with
120 "x-" is marked experimental, and may be withdrawn or changed
121 incompatibly in a future release. Downstream vendors may add
122 extensions; such extensions should begin with a prefix matching
123 "__RFQDN_" (for the reverse-fully-qualified-domain-name of the
124 vendor), even if the rest of the name uses dash (example:
125 __com.redhat_drive-mirror). Other than downstream extensions (with
126 leading underscore and the use of dots), all names should begin with a
127 letter, and contain only ASCII letters, digits, dash, and underscore.
128 It is okay to reuse names that match C keywords; the generator will
129 rename a field named "default" in the QAPI to "q_default" in the
132 In the rest of this document, usage lines are given for each
133 expression type, with literal strings written in lower case and
134 placeholders written in capitals. If a literal string includes a
135 prefix of '*', that key/value pair can be omitted from the expression.
136 For example, a usage statement that includes '*base':STRUCT-NAME
137 means that an expression has an optional key 'base', which if present
138 must have a value that forms a struct name.
141 === Built-in Types ===
143 The following types are built-in to the parser:
144 'str' - arbitrary UTF-8 string
145 'int' - 64-bit signed integer (although the C code may place further
146 restrictions on acceptable range)
147 'number' - floating point number
148 'bool' - JSON value of true or false
149 'int8', 'int16', 'int32', 'int64' - like 'int', but enforce maximum
151 'uint8', 'uint16', 'uint32', 'uint64' - unsigned counterparts
152 'size' - like 'uint64', but allows scaled suffix from command line
158 Usage: { 'include': STRING }
160 The QAPI schema definitions can be modularized using the 'include' directive:
162 { 'include': 'path/to/file.json' }
164 The directive is evaluated recursively, and include paths are relative to the
165 file using the directive. Multiple includes of the same file are
166 idempotent. No other keys should appear in the expression, and the include
167 value should be a string.
169 As a matter of style, it is a good idea to have all files be
170 self-contained, but at the moment, nothing prevents an included file
171 from making a forward reference to a type that is only introduced by
172 an outer file. The parser may be made stricter in the future to
173 prevent incomplete include files.
178 Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
180 A struct is a dictionary containing a single 'data' key whose
181 value is a dictionary. This corresponds to a struct in C or an Object
182 in JSON. Each value of the 'data' dictionary must be the name of a
183 type, or a one-element array containing a type name. An example of a
186 { 'struct': 'MyType',
187 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
189 The use of '*' as a prefix to the name means the member is optional in
190 the corresponding JSON protocol usage.
192 The default initialization value of an optional argument should not be changed
193 between versions of QEMU unless the new default maintains backward
194 compatibility to the user-visible behavior of the old default.
196 With proper documentation, this policy still allows some flexibility; for
197 example, documenting that a default of 0 picks an optimal buffer size allows
198 one release to declare the optimal size at 512 while another release declares
199 the optimal size at 4096 - the user-visible behavior is not the bytes used by
200 the buffer, but the fact that the buffer was optimal size.
202 On input structures (only mentioned in the 'data' side of a command), changing
203 from mandatory to optional is safe (older clients will supply the option, and
204 newer clients can benefit from the default); changing from optional to
205 mandatory is backwards incompatible (older clients may be omitting the option,
206 and must continue to work).
208 On output structures (only mentioned in the 'returns' side of a command),
209 changing from mandatory to optional is in general unsafe (older clients may be
210 expecting the field, and could crash if it is missing), although it can be done
211 if the only way that the optional argument will be omitted is when it is
212 triggered by the presence of a new input flag to the command that older clients
213 don't know to send. Changing from optional to mandatory is safe.
215 A structure that is used in both input and output of various commands
216 must consider the backwards compatibility constraints of both directions
219 A struct definition can specify another struct as its base.
220 In this case, the fields of the base type are included as top-level fields
221 of the new struct's dictionary in the Client JSON Protocol wire
222 format. An example definition is:
224 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
225 { 'struct': 'BlockdevOptionsGenericCOWFormat',
226 'base': 'BlockdevOptionsGenericFormat',
227 'data': { '*backing': 'str' } }
229 An example BlockdevOptionsGenericCOWFormat object on the wire could use
230 both fields like this:
232 { "file": "/some/place/my-image",
233 "backing": "/some/place/my-backing-file" }
236 === Enumeration types ===
238 Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
239 { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
241 An enumeration type is a dictionary containing a single 'data' key
242 whose value is a list of strings. An example enumeration is:
244 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
246 Nothing prevents an empty enumeration, although it is probably not
247 useful. The list of strings should be lower case; if an enum name
248 represents multiple words, use '-' between words. The string 'max' is
249 not allowed as an enum value, and values should not be repeated.
251 The enum constants will be named by using a heuristic to turn the
252 type name into a set of underscore separated words. For the example
253 above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
254 of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
255 does not result in a desirable name, the optional 'prefix' field
256 can be used when defining the enum.
258 The enumeration values are passed as strings over the Client JSON
259 Protocol, but are encoded as C enum integral values in generated code.
260 While the C code starts numbering at 0, it is better to use explicit
261 comparisons to enum values than implicit comparisons to 0; the C code
262 will also include a generated enum member ending in _MAX for tracking
263 the size of the enum, useful when using common functions for
264 converting between strings and enum values. Since the wire format
265 always passes by name, it is acceptable to reorder or add new
266 enumeration members in any location without breaking clients of Client
267 JSON Protocol; however, removing enum values would break
268 compatibility. For any struct that has a field that will only contain
269 a finite set of string values, using an enum type for that field is
270 better than open-coding the field to be type 'str'.
275 Usage: { 'union': STRING, 'data': DICT }
276 or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME,
277 'discriminator': ENUM-MEMBER-OF-BASE }
279 Union types are used to let the user choose between several different
280 variants for an object. There are two flavors: simple (no
281 discriminator or base), flat (both discriminator and base). A union
282 type is defined using a data dictionary as explained in the following
285 A simple union type defines a mapping from automatic discriminator
286 values to data types like in this example:
288 { 'struct': 'FileOptions', 'data': { 'filename': 'str' } }
289 { 'struct': 'Qcow2Options',
290 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
292 { 'union': 'BlockdevOptions',
293 'data': { 'file': 'FileOptions',
294 'qcow2': 'Qcow2Options' } }
296 In the Client JSON Protocol, a simple union is represented by a
297 dictionary that contains the 'type' field as a discriminator, and a
298 'data' field that is of the specified data type corresponding to the
299 discriminator value, as in these examples:
301 { "type": "file", "data" : { "filename": "/some/place/my-image" } }
302 { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
303 "lazy-refcounts": true } }
305 The generated C code uses a struct containing a union. Additionally,
306 an implicit C enum 'NameKind' is created, corresponding to the union
307 'Name', for accessing the various branches of the union. No branch of
308 the union can be named 'max', as this would collide with the implicit
309 enum. The value for each branch can be of any type.
311 A flat union definition specifies a struct as its base, and
312 avoids nesting on the wire. All branches of the union must be
313 complex types, and the top-level fields of the union dictionary on
314 the wire will be combination of fields from both the base type and the
315 appropriate branch type (when merging two dictionaries, there must be
316 no keys in common). The 'discriminator' field must be the name of an
317 enum-typed member of the base struct.
319 The following example enhances the above simple union example by
320 adding a common field 'readonly', renaming the discriminator to
321 something more applicable, and reducing the number of {} required on
324 { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
325 { 'struct': 'BlockdevCommonOptions',
326 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } }
327 { 'union': 'BlockdevOptions',
328 'base': 'BlockdevCommonOptions',
329 'discriminator': 'driver',
330 'data': { 'file': 'FileOptions',
331 'qcow2': 'Qcow2Options' } }
333 Resulting in these JSON objects:
335 { "driver": "file", "readonly": true,
336 "filename": "/some/place/my-image" }
337 { "driver": "qcow2", "readonly": false,
338 "backing-file": "/some/place/my-image", "lazy-refcounts": true }
340 Notice that in a flat union, the discriminator name is controlled by
341 the user, but because it must map to a base member with enum type, the
342 code generator can ensure that branches exist for all values of the
343 enum (although the order of the keys need not match the declaration of
344 the enum). In the resulting generated C data types, a flat union is
345 represented as a struct with the base member fields included directly,
346 and then a union of structures for each branch of the struct.
348 A simple union can always be re-written as a flat union where the base
349 class has a single member named 'type', and where each branch of the
350 union has a struct with a single member named 'data'. That is,
352 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
354 is identical on the wire to:
356 { 'enum': 'Enum', 'data': ['one', 'two'] }
357 { 'struct': 'Base', 'data': { 'type': 'Enum' } }
358 { 'struct': 'Branch1', 'data': { 'data': 'str' } }
359 { 'struct': 'Branch2', 'data': { 'data': 'int' } }
360 { 'union': 'Flat', 'base': 'Base', 'discriminator': 'type',
361 'data': { 'one': 'Branch1', 'two': 'Branch2' } }
364 === Alternate types ===
366 Usage: { 'alternate': STRING, 'data': DICT }
368 An alternate type is one that allows a choice between two or more JSON
369 data types (string, integer, number, or object, but currently not
370 array) on the wire. The definition is similar to a simple union type,
371 where each branch of the union names a QAPI type. For example:
373 { 'alternate': 'BlockRef',
374 'data': { 'definition': 'BlockdevOptions',
375 'reference': 'str' } }
377 Just like for a simple union, an implicit C enum 'NameKind' is created
378 to enumerate the branches for the alternate 'Name'.
380 Unlike a union, the discriminator string is never passed on the wire
381 for the Client JSON Protocol. Instead, the value's JSON type serves
382 as an implicit discriminator, which in turn means that an alternate
383 can only express a choice between types represented differently in
384 JSON. If a branch is typed as the 'bool' built-in, the alternate
385 accepts true and false; if it is typed as any of the various numeric
386 built-ins, it accepts a JSON number; if it is typed as a 'str'
387 built-in or named enum type, it accepts a JSON string; and if it is
388 typed as a complex type (struct or union), it accepts a JSON object.
389 Two different complex types, for instance, aren't permitted, because
390 both are represented as a JSON object.
392 The example alternate declaration above allows using both of the
393 following example objects:
395 { "file": "my_existing_block_device_id" }
396 { "file": { "driver": "file",
398 "filename": "/tmp/mydisk.qcow2" } }
403 Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
404 '*returns': TYPE-NAME,
405 '*gen': false, '*success-response': false }
407 Commands are defined by using a dictionary containing several members,
408 where three members are most common. The 'command' member is a
409 mandatory string, and determines the "execute" value passed in a
410 Client JSON Protocol command exchange.
412 The 'data' argument maps to the "arguments" dictionary passed in as
413 part of a Client JSON Protocol command. The 'data' member is optional
414 and defaults to {} (an empty dictionary). If present, it must be the
415 string name of a complex type, or a dictionary that declares an
416 anonymous type with the same semantics as a 'struct' expression, with
417 one exception noted below when 'gen' is used.
419 The 'returns' member describes what will appear in the "return" field
420 of a Client JSON Protocol reply on successful completion of a command.
421 The member is optional from the command declaration; if absent, the
422 "return" field will be an empty dictionary. If 'returns' is present,
423 it must be the string name of a complex or built-in type, a
424 one-element array containing the name of a complex or built-in type,
425 with one exception noted below when 'gen' is used. Although it is
426 permitted to have the 'returns' member name a built-in type or an
427 array of built-in types, any command that does this cannot be extended
428 to return additional information in the future; thus, new commands
429 should strongly consider returning a dictionary-based type or an array
430 of dictionaries, even if the dictionary only contains one field at the
433 All commands in Client JSON Protocol use a dictionary to report
434 failure, with no way to specify that in QAPI. Where the error return
435 is different than the usual GenericError class in order to help the
436 client react differently to certain error conditions, it is worth
437 documenting this in the comments before the command declaration.
439 Some example commands:
441 { 'command': 'my-first-command',
442 'data': { 'arg1': 'str', '*arg2': 'str' } }
443 { 'struct': 'MyType', 'data': { '*value': 'str' } }
444 { 'command': 'my-second-command',
445 'returns': [ 'MyType' ] }
447 which would validate this Client JSON Protocol transaction:
449 => { "execute": "my-first-command",
450 "arguments": { "arg1": "hello" } }
452 => { "execute": "my-second-command" }
453 <= { "return": [ { "value": "one" }, { } ] }
455 In rare cases, QAPI cannot express a type-safe representation of a
456 corresponding Client JSON Protocol command. In these cases, if the
457 command expression includes the key 'gen' with boolean value false,
458 then the 'data' or 'returns' member that intends to bypass generated
459 type-safety and do its own manual validation should use an inline
460 dictionary definition, with a value of '**' rather than a valid type
461 name for the keys that the generated code will not validate. Please
462 try to avoid adding new commands that rely on this, and instead use
463 type-safe unions. For an example of bypass usage:
465 { 'command': 'netdev_add',
466 'data': {'type': 'str', 'id': 'str', '*props': '**'},
469 Normally, the QAPI schema is used to describe synchronous exchanges,
470 where a response is expected. But in some cases, the action of a
471 command is expected to change state in a way that a successful
472 response is not possible (although the command will still return a
473 normal dictionary error on failure). When a successful reply is not
474 possible, the command expression should include the optional key
475 'success-response' with boolean value false. So far, only QGA makes
481 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT }
483 Events are defined with the keyword 'event'. It is not allowed to
484 name an event 'MAX', since the generator also produces a C enumeration
485 of all event names with a generated _MAX value at the end. When
486 'data' is also specified, additional info will be included in the
487 event, with similar semantics to a 'struct' expression. Finally there
488 will be C API generated in qapi-event.h; when called by QEMU code, a
489 message with timestamp will be emitted on the wire.
493 { 'event': 'EVENT_C',
494 'data': { '*a': 'int', 'b': 'str' } }
496 Resulting in this JSON object:
498 { "event": "EVENT_C",
499 "data": { "b": "test string" },
500 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
503 == Code generation ==
505 Schemas are fed into 3 scripts to generate all the code/files that, paired
506 with the core QAPI libraries, comprise everything required to take JSON
507 commands read in by a Client JSON Protocol server, unmarshal the arguments into
508 the underlying C types, call into the corresponding C function, and map the
509 response back to a Client JSON Protocol response to be returned to the user.
511 As an example, we'll use the following schema, which describes a single
512 complex user-defined type (which will produce a C struct, along with a list
513 node structure that can be used to chain together a list of such types in
514 case we want to accept/return a list of this type with a command), and a
515 command which takes that type as a parameter and returns the same type:
517 $ cat example-schema.json
518 { 'struct': 'UserDefOne',
519 'data': { 'integer': 'int', 'string': 'str' } }
521 { 'command': 'my-command',
522 'data': {'arg1': 'UserDefOne'},
523 'returns': 'UserDefOne' }
525 { 'event': 'MY_EVENT' }
527 === scripts/qapi-types.py ===
529 Used to generate the C types defined by a schema. The following files are
532 $(prefix)qapi-types.h - C types corresponding to types defined in
533 the schema you pass in
534 $(prefix)qapi-types.c - Cleanup functions for the above C types
536 The $(prefix) is an optional parameter used as a namespace to keep the
537 generated code from one schema/code-generation separated from others so code
538 can be generated/used from multiple schemas without clobbering previously
543 $ python scripts/qapi-types.py --output-dir="qapi-generated" \
544 --prefix="example-" example-schema.json
545 $ cat qapi-generated/example-qapi-types.c
546 [Uninteresting stuff omitted...]
548 void qapi_free_UserDefOneList(UserDefOneList *obj)
550 QapiDeallocVisitor *md;
557 md = qapi_dealloc_visitor_new();
558 v = qapi_dealloc_get_visitor(md);
559 visit_type_UserDefOneList(v, &obj, NULL, NULL);
560 qapi_dealloc_visitor_cleanup(md);
564 void qapi_free_UserDefOne(UserDefOne *obj)
566 QapiDeallocVisitor *md;
573 md = qapi_dealloc_visitor_new();
574 v = qapi_dealloc_get_visitor(md);
575 visit_type_UserDefOne(v, &obj, NULL, NULL);
576 qapi_dealloc_visitor_cleanup(md);
578 $ cat qapi-generated/example-qapi-types.h
579 [Uninteresting stuff omitted...]
581 #ifndef EXAMPLE_QAPI_TYPES_H
582 #define EXAMPLE_QAPI_TYPES_H
584 [Built-in types omitted...]
586 typedef struct UserDefOne UserDefOne;
588 typedef struct UserDefOneList {
593 struct UserDefOneList *next;
597 [Functions on built-in types omitted...]
604 void qapi_free_UserDefOneList(UserDefOneList *obj);
605 void qapi_free_UserDefOne(UserDefOne *obj);
609 === scripts/qapi-visit.py ===
611 Used to generate the visitor functions used to walk through and convert
612 a QObject (as provided by QMP) to a native C data structure and
613 vice-versa, as well as the visitor function used to dealloc a complex
614 schema-defined C type.
616 The following files are generated:
618 $(prefix)qapi-visit.c: visitor function for a particular C type, used
619 to automagically convert QObjects into the
620 corresponding C type and vice-versa, as well
621 as for deallocating memory for an existing C
624 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
629 $ python scripts/qapi-visit.py --output-dir="qapi-generated"
630 --prefix="example-" example-schema.json
631 $ cat qapi-generated/example-qapi-visit.c
632 [Uninteresting stuff omitted...]
634 static void visit_type_UserDefOne_fields(Visitor *m, UserDefOne **obj, Error **errp)
638 visit_type_int(m, &(*obj)->integer, "integer", &err);
642 visit_type_str(m, &(*obj)->string, "string", &err);
648 error_propagate(errp, err);
651 void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp)
655 visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), &err);
658 visit_type_UserDefOne_fields(m, obj, errp);
660 visit_end_struct(m, &err);
662 error_propagate(errp, err);
665 void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp)
668 GenericList *i, **prev;
670 visit_start_list(m, name, &err);
675 for (prev = (GenericList **)obj;
676 !err && (i = visit_next_list(m, prev, &err)) != NULL;
678 UserDefOneList *native_i = (UserDefOneList *)i;
679 visit_type_UserDefOne(m, &native_i->value, NULL, &err);
682 error_propagate(errp, err);
684 visit_end_list(m, &err);
686 error_propagate(errp, err);
688 $ cat qapi-generated/example-qapi-visit.h
689 [Uninteresting stuff omitted...]
691 #ifndef EXAMPLE_QAPI_VISIT_H
692 #define EXAMPLE_QAPI_VISIT_H
694 [Visitors for built-in types omitted...]
696 void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp);
697 void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp);
701 === scripts/qapi-commands.py ===
703 Used to generate the marshaling/dispatch functions for the commands defined
704 in the schema. The following files are generated:
706 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
707 QMP command defined in the schema. Functions
708 generated by qapi-visit.py are used to
709 convert QObjects received from the wire into
710 function parameters, and uses the same
711 visitor functions to convert native C return
712 values to QObjects from transmission back
715 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
716 specified in the schema.
720 $ python scripts/qapi-commands.py --output-dir="qapi-generated"
721 --prefix="example-" example-schema.json
722 $ cat qapi-generated/example-qmp-marshal.c
723 [Uninteresting stuff omitted...]
725 static void qmp_marshal_output_my_command(UserDefOne *ret_in, QObject **ret_out, Error **errp)
727 Error *local_err = NULL;
728 QmpOutputVisitor *mo = qmp_output_visitor_new();
729 QapiDeallocVisitor *md;
732 v = qmp_output_get_visitor(mo);
733 visit_type_UserDefOne(v, &ret_in, "unused", &local_err);
737 *ret_out = qmp_output_get_qobject(mo);
740 error_propagate(errp, local_err);
741 qmp_output_visitor_cleanup(mo);
742 md = qapi_dealloc_visitor_new();
743 v = qapi_dealloc_get_visitor(md);
744 visit_type_UserDefOne(v, &ret_in, "unused", NULL);
745 qapi_dealloc_visitor_cleanup(md);
748 static void qmp_marshal_input_my_command(QDict *args, QObject **ret, Error **errp)
750 Error *local_err = NULL;
752 QmpInputVisitor *mi = qmp_input_visitor_new_strict(QOBJECT(args));
753 QapiDeallocVisitor *md;
755 UserDefOne *arg1 = NULL;
757 v = qmp_input_get_visitor(mi);
758 visit_type_UserDefOne(v, &arg1, "arg1", &local_err);
763 retval = qmp_my_command(arg1, &local_err);
768 qmp_marshal_output_my_command(retval, ret, &local_err);
771 error_propagate(errp, local_err);
772 qmp_input_visitor_cleanup(mi);
773 md = qapi_dealloc_visitor_new();
774 v = qapi_dealloc_get_visitor(md);
775 visit_type_UserDefOne(v, &arg1, "arg1", NULL);
776 qapi_dealloc_visitor_cleanup(md);
779 static void qmp_init_marshal(void)
781 qmp_register_command("my-command", qmp_marshal_input_my_command, QCO_NO_OPTIONS);
784 qapi_init(qmp_init_marshal);
785 $ cat qapi-generated/example-qmp-commands.h
786 [Uninteresting stuff omitted...]
788 #ifndef EXAMPLE_QMP_COMMANDS_H
789 #define EXAMPLE_QMP_COMMANDS_H
791 #include "example-qapi-types.h"
792 #include "qapi/qmp/qdict.h"
793 #include "qapi/error.h"
795 UserDefOne *qmp_my_command(UserDefOne *arg1, Error **errp);
799 === scripts/qapi-event.py ===
801 Used to generate the event-related C code defined by a schema. The
802 following files are created:
804 $(prefix)qapi-event.h - Function prototypes for each event type, plus an
805 enumeration of all event names
806 $(prefix)qapi-event.c - Implementation of functions to send an event
810 $ python scripts/qapi-event.py --output-dir="qapi-generated"
811 --prefix="example-" example-schema.json
812 $ cat qapi-generated/example-qapi-event.c
813 [Uninteresting stuff omitted...]
815 void qapi_event_send_my_event(Error **errp)
818 Error *local_err = NULL;
819 QMPEventFuncEmit emit;
820 emit = qmp_event_get_func_emit();
825 qmp = qmp_event_build_dict("MY_EVENT");
827 emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &local_err);
829 error_propagate(errp, local_err);
833 const char *example_QAPIEvent_lookup[] = {
837 $ cat qapi-generated/example-qapi-event.h
838 [Uninteresting stuff omitted...]
840 #ifndef EXAMPLE_QAPI_EVENT_H
841 #define EXAMPLE_QAPI_EVENT_H
843 #include "qapi/error.h"
844 #include "qapi/qmp/qdict.h"
845 #include "example-qapi-types.h"
848 void qapi_event_send_my_event(Error **errp);
850 extern const char *example_QAPIEvent_lookup[];
851 typedef enum example_QAPIEvent {
852 EXAMPLE_QAPI_EVENT_MY_EVENT = 0,
853 EXAMPLE_QAPI_EVENT_MAX = 1,