Merge remote-tracking branch 'remotes/kevin/tags/for-upstream' into staging
[qemu.git] / docs / qapi-code-gen.txt
1 = How to use the QAPI code generator =
2
3 * Note: as of this writing, QMP does not use QAPI. Eventually QMP
4 commands will be converted to use QAPI internally. The following
5 information describes QMP/QAPI as it will exist after the
6 conversion.
7
8 QAPI is a native C API within QEMU which provides management-level
9 functionality to internal/external users. For external
10 users/processes, this interface is made available by a JSON-based
11 QEMU Monitor protocol that is provided by the QMP server.
12
13 To map QMP-defined interfaces to the native C QAPI implementations,
14 a JSON-based schema is used to define types and function
15 signatures, and a set of scripts is used to generate types/signatures,
16 and marshaling/dispatch code. The QEMU Guest Agent also uses these
17 scripts, paired with a separate schema, to generate
18 marshaling/dispatch code for the guest agent server running in the
19 guest.
20
21 This document will describe how the schemas, scripts, and resulting
22 code is used.
23
24
25 == QMP/Guest agent schema ==
26
27 This file defines the types, commands, and events used by QMP.  It should
28 fully describe the interface used by QMP.
29
30 This file is designed to be loosely based on JSON although it's technically
31 executable Python.  While dictionaries are used, they are parsed as
32 OrderedDicts so that ordering is preserved.
33
34 There are two basic syntaxes used, type definitions and command definitions.
35
36 The first syntax defines a type and is represented by a dictionary.  There are
37 three kinds of user-defined types that are supported: complex types,
38 enumeration types and union types.
39
40 Generally speaking, types definitions should always use CamelCase for the type
41 names. Command names should be all lower case with words separated by a hyphen.
42
43 === Complex types ===
44
45 A complex type is a dictionary containing a single key whose value is a
46 dictionary.  This corresponds to a struct in C or an Object in JSON.  An
47 example of a complex type is:
48
49  { 'type': 'MyType',
50    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
51
52 The use of '*' as a prefix to the name means the member is optional.  Optional
53 members should always be added to the end of the dictionary to preserve
54 backwards compatibility.
55
56
57 A complex type definition can specify another complex type as its base.
58 In this case, the fields of the base type are included as top-level fields
59 of the new complex type's dictionary in the QMP wire format. An example
60 definition is:
61
62  { 'type': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
63  { 'type': 'BlockdevOptionsGenericCOWFormat',
64    'base': 'BlockdevOptionsGenericFormat',
65    'data': { '*backing': 'str' } }
66
67 An example BlockdevOptionsGenericCOWFormat object on the wire could use
68 both fields like this:
69
70  { "file": "/some/place/my-image",
71    "backing": "/some/place/my-backing-file" }
72
73 === Enumeration types ===
74
75 An enumeration type is a dictionary containing a single key whose value is a
76 list of strings.  An example enumeration is:
77
78  { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
79
80 === Union types ===
81
82 Union types are used to let the user choose between several different data
83 types.  A union type is defined using a dictionary as explained in the
84 following paragraphs.
85
86
87 A simple union type defines a mapping from discriminator values to data types
88 like in this example:
89
90  { 'type': 'FileOptions', 'data': { 'filename': 'str' } }
91  { 'type': 'Qcow2Options',
92    'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
93
94  { 'union': 'BlockdevOptions',
95    'data': { 'file': 'FileOptions',
96              'qcow2': 'Qcow2Options' } }
97
98 In the QMP wire format, a simple union is represented by a dictionary that
99 contains the 'type' field as a discriminator, and a 'data' field that is of the
100 specified data type corresponding to the discriminator value:
101
102  { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
103                                "lazy-refcounts": true } }
104
105
106 A union definition can specify a complex type as its base. In this case, the
107 fields of the complex type are included as top-level fields of the union
108 dictionary in the QMP wire format. An example definition is:
109
110  { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
111  { 'union': 'BlockdevOptions',
112    'base': 'BlockdevCommonOptions',
113    'data': { 'raw': 'RawOptions',
114              'qcow2': 'Qcow2Options' } }
115
116 And it looks like this on the wire:
117
118  { "type": "qcow2",
119    "readonly": false,
120    "data" : { "backing-file": "/some/place/my-image",
121               "lazy-refcounts": true } }
122
123
124 Flat union types avoid the nesting on the wire. They are used whenever a
125 specific field of the base type is declared as the discriminator ('type' is
126 then no longer generated). The discriminator must be of enumeration type.
127 The above example can then be modified as follows:
128
129  { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] }
130  { 'type': 'BlockdevCommonOptions',
131    'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } }
132  { 'union': 'BlockdevOptions',
133    'base': 'BlockdevCommonOptions',
134    'discriminator': 'driver',
135    'data': { 'raw': 'RawOptions',
136              'qcow2': 'Qcow2Options' } }
137
138 Resulting in this JSON object:
139
140  { "driver": "qcow2",
141    "readonly": false,
142    "backing-file": "/some/place/my-image",
143    "lazy-refcounts": true }
144
145
146 A special type of unions are anonymous unions. They don't form a dictionary in
147 the wire format but allow the direct use of different types in their place. As
148 they aren't structured, they don't have any explicit discriminator but use
149 the (QObject) data type of their value as an implicit discriminator. This means
150 that they are restricted to using only one discriminator value per QObject
151 type. For example, you cannot have two different complex types in an anonymous
152 union, or two different integer types.
153
154 Anonymous unions are declared using an empty dictionary as their discriminator.
155 The discriminator values never appear on the wire, they are only used in the
156 generated C code. Anonymous unions cannot have a base type.
157
158  { 'union': 'BlockRef',
159    'discriminator': {},
160    'data': { 'definition': 'BlockdevOptions',
161              'reference': 'str' } }
162
163 This example allows using both of the following example objects:
164
165  { "file": "my_existing_block_device_id" }
166  { "file": { "driver": "file",
167              "readonly": false,
168              "filename": "/tmp/mydisk.qcow2" } }
169
170
171 === Commands ===
172
173 Commands are defined by using a list containing three members.  The first
174 member is the command name, the second member is a dictionary containing
175 arguments, and the third member is the return type.
176
177 An example command is:
178
179  { 'command': 'my-command',
180    'data': { 'arg1': 'str', '*arg2': 'str' },
181    'returns': 'str' }
182
183
184 == Code generation ==
185
186 Schemas are fed into 3 scripts to generate all the code/files that, paired
187 with the core QAPI libraries, comprise everything required to take JSON
188 commands read in by a QMP/guest agent server, unmarshal the arguments into
189 the underlying C types, call into the corresponding C function, and map the
190 response back to a QMP/guest agent response to be returned to the user.
191
192 As an example, we'll use the following schema, which describes a single
193 complex user-defined type (which will produce a C struct, along with a list
194 node structure that can be used to chain together a list of such types in
195 case we want to accept/return a list of this type with a command), and a
196 command which takes that type as a parameter and returns the same type:
197
198     mdroth@illuin:~/w/qemu2.git$ cat example-schema.json
199     { 'type': 'UserDefOne',
200       'data': { 'integer': 'int', 'string': 'str' } }
201
202     { 'command': 'my-command',
203       'data':    {'arg1': 'UserDefOne'},
204       'returns': 'UserDefOne' }
205     mdroth@illuin:~/w/qemu2.git$
206
207 === scripts/qapi-types.py ===
208
209 Used to generate the C types defined by a schema. The following files are
210 created:
211
212 $(prefix)qapi-types.h - C types corresponding to types defined in
213                         the schema you pass in
214 $(prefix)qapi-types.c - Cleanup functions for the above C types
215
216 The $(prefix) is an optional parameter used as a namespace to keep the
217 generated code from one schema/code-generation separated from others so code
218 can be generated/used from multiple schemas without clobbering previously
219 created code.
220
221 Example:
222
223     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \
224       --output-dir="qapi-generated" --prefix="example-" < example-schema.json
225     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c
226     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
227
228     #include "qapi/qapi-dealloc-visitor.h"
229     #include "example-qapi-types.h"
230     #include "example-qapi-visit.h"
231
232     void qapi_free_UserDefOne(UserDefOne * obj)
233     {
234         QapiDeallocVisitor *md;
235         Visitor *v;
236
237         if (!obj) {
238             return;
239         }
240
241         md = qapi_dealloc_visitor_new();
242         v = qapi_dealloc_get_visitor(md);
243         visit_type_UserDefOne(v, &obj, NULL, NULL);
244         qapi_dealloc_visitor_cleanup(md);
245     }
246
247     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.h
248     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
249     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_TYPES
250     #define QAPI_GENERATED_EXAMPLE_QAPI_TYPES
251
252     #include "qapi/qapi-types-core.h"
253
254     typedef struct UserDefOne UserDefOne;
255
256     typedef struct UserDefOneList
257     {
258         UserDefOne *value;
259         struct UserDefOneList *next;
260     } UserDefOneList;
261
262     struct UserDefOne
263     {
264         int64_t integer;
265         char * string;
266     };
267
268     void qapi_free_UserDefOne(UserDefOne * obj);
269
270     #endif
271
272
273 === scripts/qapi-visit.py ===
274
275 Used to generate the visitor functions used to walk through and convert
276 a QObject (as provided by QMP) to a native C data structure and
277 vice-versa, as well as the visitor function used to dealloc a complex
278 schema-defined C type.
279
280 The following files are generated:
281
282 $(prefix)qapi-visit.c: visitor function for a particular C type, used
283                        to automagically convert QObjects into the
284                        corresponding C type and vice-versa, as well
285                        as for deallocating memory for an existing C
286                        type
287
288 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
289                        functions
290
291 Example:
292
293     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \
294         --output-dir="qapi-generated" --prefix="example-" < example-schema.json
295     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c
296     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
297
298     #include "example-qapi-visit.h"
299
300     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp)
301     {
302         visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), errp);
303         visit_type_int(m, (obj && *obj) ? &(*obj)->integer : NULL, "integer", errp);
304         visit_type_str(m, (obj && *obj) ? &(*obj)->string : NULL, "string", errp);
305         visit_end_struct(m, errp);
306     }
307
308     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp)
309     {
310         GenericList *i, **prev = (GenericList **)obj;
311
312         visit_start_list(m, name, errp);
313
314         for (; (i = visit_next_list(m, prev, errp)) != NULL; prev = &i) {
315             UserDefOneList *native_i = (UserDefOneList *)i;
316             visit_type_UserDefOne(m, &native_i->value, NULL, errp);
317         }
318
319         visit_end_list(m, errp);
320     }
321     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.h
322     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
323
324     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_VISIT
325     #define QAPI_GENERATED_EXAMPLE_QAPI_VISIT
326
327     #include "qapi/qapi-visit-core.h"
328     #include "example-qapi-types.h"
329
330     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp);
331     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp);
332
333     #endif
334     mdroth@illuin:~/w/qemu2.git$
335
336 (The actual structure of the visit_type_* functions is a bit more complex
337 in order to propagate errors correctly and avoid leaking memory).
338
339 === scripts/qapi-commands.py ===
340
341 Used to generate the marshaling/dispatch functions for the commands defined
342 in the schema. The following files are generated:
343
344 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
345                         QMP command defined in the schema. Functions
346                         generated by qapi-visit.py are used to
347                         convert QObjects received from the wire into
348                         function parameters, and uses the same
349                         visitor functions to convert native C return
350                         values to QObjects from transmission back
351                         over the wire.
352
353 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
354                          specified in the schema.
355
356 Example:
357
358     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-marshal.c
359     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
360
361     #include "qemu-objects.h"
362     #include "qapi/qmp-core.h"
363     #include "qapi/qapi-visit-core.h"
364     #include "qapi/qmp-output-visitor.h"
365     #include "qapi/qmp-input-visitor.h"
366     #include "qapi/qapi-dealloc-visitor.h"
367     #include "example-qapi-types.h"
368     #include "example-qapi-visit.h"
369
370     #include "example-qmp-commands.h"
371     static void qmp_marshal_output_my_command(UserDefOne * ret_in, QObject **ret_out, Error **errp)
372     {
373         QapiDeallocVisitor *md = qapi_dealloc_visitor_new();
374         QmpOutputVisitor *mo = qmp_output_visitor_new();
375         Visitor *v;
376
377         v = qmp_output_get_visitor(mo);
378         visit_type_UserDefOne(v, &ret_in, "unused", errp);
379         v = qapi_dealloc_get_visitor(md);
380         visit_type_UserDefOne(v, &ret_in, "unused", errp);
381         qapi_dealloc_visitor_cleanup(md);
382
383
384         *ret_out = qmp_output_get_qobject(mo);
385     }
386
387     static void qmp_marshal_input_my_command(QmpState *qmp__sess, QDict *args, QObject **ret, Error **errp)
388     {
389         UserDefOne * retval = NULL;
390         QmpInputVisitor *mi;
391         QapiDeallocVisitor *md;
392         Visitor *v;
393         UserDefOne * arg1 = NULL;
394
395         mi = qmp_input_visitor_new(QOBJECT(args));
396         v = qmp_input_get_visitor(mi);
397         visit_type_UserDefOne(v, &arg1, "arg1", errp);
398
399         if (error_is_set(errp)) {
400             goto out;
401         }
402         retval = qmp_my_command(arg1, errp);
403         qmp_marshal_output_my_command(retval, ret, errp);
404
405     out:
406         md = qapi_dealloc_visitor_new();
407         v = qapi_dealloc_get_visitor(md);
408         visit_type_UserDefOne(v, &arg1, "arg1", errp);
409         qapi_dealloc_visitor_cleanup(md);
410         return;
411     }
412
413     static void qmp_init_marshal(void)
414     {
415         qmp_register_command("my-command", qmp_marshal_input_my_command);
416     }
417
418     qapi_init(qmp_init_marshal);
419     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-commands.h
420     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
421
422     #ifndef QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
423     #define QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
424
425     #include "example-qapi-types.h"
426     #include "error.h"
427
428     UserDefOne * qmp_my_command(UserDefOne * arg1, Error **errp);
429
430     #endif
431     mdroth@illuin:~/w/qemu2.git$