]>
Commit | Line | Data |
---|---|---|
b84da831 MR |
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 | |
4238e264 | 17 | scripts, paired with a separate schema, to generate |
b84da831 MR |
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 | |
51631493 KW |
37 | three kinds of user-defined types that are supported: complex types, |
38 | enumeration types and union types. | |
b84da831 | 39 | |
51631493 KW |
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 | ||
a719a27c LV |
43 | |
44 | === Includes === | |
45 | ||
46 | The QAPI schema definitions can be modularized using the 'include' directive: | |
47 | ||
48 | { 'include': 'path/to/file.json'} | |
49 | ||
50 | The directive is evaluated recursively, and include paths are relative to the | |
51 | file using the directive. | |
52 | ||
53 | ||
51631493 KW |
54 | === Complex types === |
55 | ||
56 | A complex type is a dictionary containing a single key whose value is a | |
b84da831 MR |
57 | dictionary. This corresponds to a struct in C or an Object in JSON. An |
58 | example of a complex type is: | |
59 | ||
60 | { 'type': 'MyType', | |
acf8394e | 61 | 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } |
b84da831 | 62 | |
cc162655 EB |
63 | The use of '*' as a prefix to the name means the member is optional. |
64 | ||
65 | The default initialization value of an optional argument should not be changed | |
66 | between versions of QEMU unless the new default maintains backward | |
67 | compatibility to the user-visible behavior of the old default. | |
68 | ||
69 | With proper documentation, this policy still allows some flexibility; for | |
70 | example, documenting that a default of 0 picks an optimal buffer size allows | |
71 | one release to declare the optimal size at 512 while another release declares | |
72 | the optimal size at 4096 - the user-visible behavior is not the bytes used by | |
73 | the buffer, but the fact that the buffer was optimal size. | |
74 | ||
75 | On input structures (only mentioned in the 'data' side of a command), changing | |
76 | from mandatory to optional is safe (older clients will supply the option, and | |
77 | newer clients can benefit from the default); changing from optional to | |
78 | mandatory is backwards incompatible (older clients may be omitting the option, | |
79 | and must continue to work). | |
80 | ||
81 | On output structures (only mentioned in the 'returns' side of a command), | |
82 | changing from mandatory to optional is in general unsafe (older clients may be | |
83 | expecting the field, and could crash if it is missing), although it can be done | |
84 | if the only way that the optional argument will be omitted is when it is | |
85 | triggered by the presence of a new input flag to the command that older clients | |
86 | don't know to send. Changing from optional to mandatory is safe. | |
87 | ||
88 | A structure that is used in both input and output of various commands | |
89 | must consider the backwards compatibility constraints of both directions | |
90 | of use. | |
622f557f KW |
91 | |
92 | A complex type definition can specify another complex type as its base. | |
93 | In this case, the fields of the base type are included as top-level fields | |
94 | of the new complex type's dictionary in the QMP wire format. An example | |
95 | definition is: | |
96 | ||
97 | { 'type': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } | |
98 | { 'type': 'BlockdevOptionsGenericCOWFormat', | |
99 | 'base': 'BlockdevOptionsGenericFormat', | |
100 | 'data': { '*backing': 'str' } } | |
101 | ||
102 | An example BlockdevOptionsGenericCOWFormat object on the wire could use | |
103 | both fields like this: | |
104 | ||
105 | { "file": "/some/place/my-image", | |
106 | "backing": "/some/place/my-backing-file" } | |
107 | ||
51631493 KW |
108 | === Enumeration types === |
109 | ||
110 | An enumeration type is a dictionary containing a single key whose value is a | |
b84da831 MR |
111 | list of strings. An example enumeration is: |
112 | ||
113 | { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } | |
114 | ||
51631493 KW |
115 | === Union types === |
116 | ||
117 | Union types are used to let the user choose between several different data | |
118 | types. A union type is defined using a dictionary as explained in the | |
119 | following paragraphs. | |
120 | ||
121 | ||
122 | A simple union type defines a mapping from discriminator values to data types | |
123 | like in this example: | |
124 | ||
125 | { 'type': 'FileOptions', 'data': { 'filename': 'str' } } | |
126 | { 'type': 'Qcow2Options', | |
127 | 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } } | |
128 | ||
129 | { 'union': 'BlockdevOptions', | |
130 | 'data': { 'file': 'FileOptions', | |
131 | 'qcow2': 'Qcow2Options' } } | |
132 | ||
133 | In the QMP wire format, a simple union is represented by a dictionary that | |
134 | contains the 'type' field as a discriminator, and a 'data' field that is of the | |
135 | specified data type corresponding to the discriminator value: | |
136 | ||
137 | { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image", | |
138 | "lazy-refcounts": true } } | |
139 | ||
140 | ||
141 | A union definition can specify a complex type as its base. In this case, the | |
142 | fields of the complex type are included as top-level fields of the union | |
143 | dictionary in the QMP wire format. An example definition is: | |
144 | ||
145 | { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } } | |
146 | { 'union': 'BlockdevOptions', | |
147 | 'base': 'BlockdevCommonOptions', | |
148 | 'data': { 'raw': 'RawOptions', | |
149 | 'qcow2': 'Qcow2Options' } } | |
150 | ||
151 | And it looks like this on the wire: | |
152 | ||
153 | { "type": "qcow2", | |
154 | "readonly": false, | |
155 | "data" : { "backing-file": "/some/place/my-image", | |
156 | "lazy-refcounts": true } } | |
157 | ||
50f2bdc7 KW |
158 | |
159 | Flat union types avoid the nesting on the wire. They are used whenever a | |
160 | specific field of the base type is declared as the discriminator ('type' is | |
5223070c | 161 | then no longer generated). The discriminator must be of enumeration type. |
50f2bdc7 KW |
162 | The above example can then be modified as follows: |
163 | ||
bceae769 | 164 | { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] } |
50f2bdc7 | 165 | { 'type': 'BlockdevCommonOptions', |
bceae769 | 166 | 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } } |
50f2bdc7 KW |
167 | { 'union': 'BlockdevOptions', |
168 | 'base': 'BlockdevCommonOptions', | |
169 | 'discriminator': 'driver', | |
170 | 'data': { 'raw': 'RawOptions', | |
171 | 'qcow2': 'Qcow2Options' } } | |
172 | ||
173 | Resulting in this JSON object: | |
174 | ||
175 | { "driver": "qcow2", | |
176 | "readonly": false, | |
177 | "backing-file": "/some/place/my-image", | |
178 | "lazy-refcounts": true } | |
179 | ||
180 | ||
69dd62df KW |
181 | A special type of unions are anonymous unions. They don't form a dictionary in |
182 | the wire format but allow the direct use of different types in their place. As | |
183 | they aren't structured, they don't have any explicit discriminator but use | |
184 | the (QObject) data type of their value as an implicit discriminator. This means | |
185 | that they are restricted to using only one discriminator value per QObject | |
186 | type. For example, you cannot have two different complex types in an anonymous | |
187 | union, or two different integer types. | |
188 | ||
189 | Anonymous unions are declared using an empty dictionary as their discriminator. | |
190 | The discriminator values never appear on the wire, they are only used in the | |
191 | generated C code. Anonymous unions cannot have a base type. | |
192 | ||
193 | { 'union': 'BlockRef', | |
194 | 'discriminator': {}, | |
195 | 'data': { 'definition': 'BlockdevOptions', | |
196 | 'reference': 'str' } } | |
197 | ||
198 | This example allows using both of the following example objects: | |
199 | ||
200 | { "file": "my_existing_block_device_id" } | |
201 | { "file": { "driver": "file", | |
202 | "readonly": false, | |
63922c64 | 203 | "filename": "/tmp/mydisk.qcow2" } } |
69dd62df KW |
204 | |
205 | ||
51631493 | 206 | === Commands === |
b84da831 MR |
207 | |
208 | Commands are defined by using a list containing three members. The first | |
209 | member is the command name, the second member is a dictionary containing | |
210 | arguments, and the third member is the return type. | |
211 | ||
212 | An example command is: | |
213 | ||
214 | { 'command': 'my-command', | |
215 | 'data': { 'arg1': 'str', '*arg2': 'str' }, | |
acf8394e | 216 | 'returns': 'str' } |
b84da831 | 217 | |
b84da831 MR |
218 | |
219 | == Code generation == | |
220 | ||
221 | Schemas are fed into 3 scripts to generate all the code/files that, paired | |
222 | with the core QAPI libraries, comprise everything required to take JSON | |
223 | commands read in by a QMP/guest agent server, unmarshal the arguments into | |
224 | the underlying C types, call into the corresponding C function, and map the | |
225 | response back to a QMP/guest agent response to be returned to the user. | |
226 | ||
227 | As an example, we'll use the following schema, which describes a single | |
228 | complex user-defined type (which will produce a C struct, along with a list | |
229 | node structure that can be used to chain together a list of such types in | |
230 | case we want to accept/return a list of this type with a command), and a | |
231 | command which takes that type as a parameter and returns the same type: | |
232 | ||
233 | mdroth@illuin:~/w/qemu2.git$ cat example-schema.json | |
234 | { 'type': 'UserDefOne', | |
235 | 'data': { 'integer': 'int', 'string': 'str' } } | |
236 | ||
237 | { 'command': 'my-command', | |
238 | 'data': {'arg1': 'UserDefOne'}, | |
239 | 'returns': 'UserDefOne' } | |
240 | mdroth@illuin:~/w/qemu2.git$ | |
241 | ||
242 | === scripts/qapi-types.py === | |
243 | ||
244 | Used to generate the C types defined by a schema. The following files are | |
245 | created: | |
246 | ||
247 | $(prefix)qapi-types.h - C types corresponding to types defined in | |
248 | the schema you pass in | |
249 | $(prefix)qapi-types.c - Cleanup functions for the above C types | |
250 | ||
251 | The $(prefix) is an optional parameter used as a namespace to keep the | |
252 | generated code from one schema/code-generation separated from others so code | |
253 | can be generated/used from multiple schemas without clobbering previously | |
254 | created code. | |
255 | ||
256 | Example: | |
257 | ||
258 | mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \ | |
33aaad52 | 259 | --output-dir="qapi-generated" --prefix="example-" --input-file=example-schema.json |
b84da831 | 260 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c |
6e2bb3ec MA |
261 | [Uninteresting stuff omitted...] |
262 | ||
263 | void qapi_free_UserDefOneList(UserDefOneList * obj) | |
264 | { | |
265 | QapiDeallocVisitor *md; | |
266 | Visitor *v; | |
267 | ||
268 | if (!obj) { | |
269 | return; | |
270 | } | |
271 | ||
272 | md = qapi_dealloc_visitor_new(); | |
273 | v = qapi_dealloc_get_visitor(md); | |
274 | visit_type_UserDefOneList(v, &obj, NULL, NULL); | |
275 | qapi_dealloc_visitor_cleanup(md); | |
276 | } | |
b84da831 | 277 | |
b84da831 MR |
278 | |
279 | void qapi_free_UserDefOne(UserDefOne * obj) | |
280 | { | |
281 | QapiDeallocVisitor *md; | |
282 | Visitor *v; | |
283 | ||
284 | if (!obj) { | |
285 | return; | |
286 | } | |
287 | ||
288 | md = qapi_dealloc_visitor_new(); | |
289 | v = qapi_dealloc_get_visitor(md); | |
290 | visit_type_UserDefOne(v, &obj, NULL, NULL); | |
291 | qapi_dealloc_visitor_cleanup(md); | |
292 | } | |
293 | ||
294 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.h | |
6e2bb3ec MA |
295 | [Uninteresting stuff omitted...] |
296 | ||
297 | #ifndef EXAMPLE_QAPI_TYPES_H | |
298 | #define EXAMPLE_QAPI_TYPES_H | |
b84da831 | 299 | |
6e2bb3ec | 300 | [Builtin types omitted...] |
b84da831 MR |
301 | |
302 | typedef struct UserDefOne UserDefOne; | |
303 | ||
304 | typedef struct UserDefOneList | |
305 | { | |
6e2bb3ec MA |
306 | union { |
307 | UserDefOne *value; | |
308 | uint64_t padding; | |
309 | }; | |
b84da831 MR |
310 | struct UserDefOneList *next; |
311 | } UserDefOneList; | |
312 | ||
6e2bb3ec MA |
313 | [Functions on builtin types omitted...] |
314 | ||
b84da831 MR |
315 | struct UserDefOne |
316 | { | |
317 | int64_t integer; | |
318 | char * string; | |
319 | }; | |
320 | ||
6e2bb3ec | 321 | void qapi_free_UserDefOneList(UserDefOneList * obj); |
b84da831 MR |
322 | void qapi_free_UserDefOne(UserDefOne * obj); |
323 | ||
324 | #endif | |
325 | ||
b84da831 MR |
326 | === scripts/qapi-visit.py === |
327 | ||
328 | Used to generate the visitor functions used to walk through and convert | |
329 | a QObject (as provided by QMP) to a native C data structure and | |
330 | vice-versa, as well as the visitor function used to dealloc a complex | |
331 | schema-defined C type. | |
332 | ||
333 | The following files are generated: | |
334 | ||
335 | $(prefix)qapi-visit.c: visitor function for a particular C type, used | |
336 | to automagically convert QObjects into the | |
337 | corresponding C type and vice-versa, as well | |
338 | as for deallocating memory for an existing C | |
339 | type | |
340 | ||
341 | $(prefix)qapi-visit.h: declarations for previously mentioned visitor | |
342 | functions | |
343 | ||
344 | Example: | |
345 | ||
346 | mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \ | |
33aaad52 | 347 | --output-dir="qapi-generated" --prefix="example-" --input-file=example-schema.json |
b84da831 | 348 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c |
6e2bb3ec | 349 | [Uninteresting stuff omitted...] |
b84da831 | 350 | |
6e2bb3ec MA |
351 | static void visit_type_UserDefOne_fields(Visitor *m, UserDefOne ** obj, Error **errp) |
352 | { | |
353 | Error *err = NULL; | |
354 | visit_type_int(m, &(*obj)->integer, "integer", &err); | |
355 | visit_type_str(m, &(*obj)->string, "string", &err); | |
356 | ||
357 | error_propagate(errp, err); | |
358 | } | |
b84da831 MR |
359 | |
360 | void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp) | |
361 | { | |
6e2bb3ec MA |
362 | if (!error_is_set(errp)) { |
363 | Error *err = NULL; | |
364 | visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), &err); | |
365 | if (!err) { | |
366 | if (*obj) { | |
367 | visit_type_UserDefOne_fields(m, obj, &err); | |
368 | error_propagate(errp, err); | |
369 | err = NULL; | |
370 | } | |
371 | /* Always call end_struct if start_struct succeeded. */ | |
372 | visit_end_struct(m, &err); | |
373 | } | |
374 | error_propagate(errp, err); | |
375 | } | |
b84da831 MR |
376 | } |
377 | ||
378 | void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp) | |
379 | { | |
3a86a0fa | 380 | GenericList *i, **prev = (GenericList **)obj; |
6e2bb3ec MA |
381 | Error *err = NULL; |
382 | ||
383 | if (!error_is_set(errp)) { | |
384 | visit_start_list(m, name, &err); | |
385 | if (!err) { | |
386 | for (; (i = visit_next_list(m, prev, &err)) != NULL; prev = &i) { | |
387 | UserDefOneList *native_i = (UserDefOneList *)i; | |
388 | visit_type_UserDefOne(m, &native_i->value, NULL, &err); | |
389 | } | |
390 | error_propagate(errp, err); | |
391 | err = NULL; | |
392 | ||
393 | /* Always call end_list if start_list succeeded. */ | |
394 | visit_end_list(m, &err); | |
395 | } | |
396 | error_propagate(errp, err); | |
b84da831 | 397 | } |
b84da831 MR |
398 | } |
399 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.h | |
6e2bb3ec | 400 | [Uninteresting stuff omitted...] |
b84da831 | 401 | |
6e2bb3ec MA |
402 | #ifndef EXAMPLE_QAPI_VISIT_H |
403 | #define EXAMPLE_QAPI_VISIT_H | |
b84da831 | 404 | |
6e2bb3ec | 405 | [Visitors for builtin types omitted...] |
b84da831 MR |
406 | |
407 | void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp); | |
408 | void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp); | |
409 | ||
410 | #endif | |
411 | mdroth@illuin:~/w/qemu2.git$ | |
412 | ||
b84da831 MR |
413 | === scripts/qapi-commands.py === |
414 | ||
415 | Used to generate the marshaling/dispatch functions for the commands defined | |
416 | in the schema. The following files are generated: | |
417 | ||
418 | $(prefix)qmp-marshal.c: command marshal/dispatch functions for each | |
419 | QMP command defined in the schema. Functions | |
420 | generated by qapi-visit.py are used to | |
2542bfd5 | 421 | convert QObjects received from the wire into |
b84da831 MR |
422 | function parameters, and uses the same |
423 | visitor functions to convert native C return | |
424 | values to QObjects from transmission back | |
425 | over the wire. | |
426 | ||
427 | $(prefix)qmp-commands.h: Function prototypes for the QMP commands | |
428 | specified in the schema. | |
429 | ||
430 | Example: | |
431 | ||
432 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-marshal.c | |
6e2bb3ec | 433 | [Uninteresting stuff omitted...] |
b84da831 | 434 | |
b84da831 MR |
435 | static void qmp_marshal_output_my_command(UserDefOne * ret_in, QObject **ret_out, Error **errp) |
436 | { | |
b84da831 | 437 | QmpOutputVisitor *mo = qmp_output_visitor_new(); |
f9bee751 | 438 | QapiDeallocVisitor *md; |
b84da831 MR |
439 | Visitor *v; |
440 | ||
441 | v = qmp_output_get_visitor(mo); | |
442 | visit_type_UserDefOne(v, &ret_in, "unused", errp); | |
6e2bb3ec MA |
443 | if (!error_is_set(errp)) { |
444 | *ret_out = qmp_output_get_qobject(mo); | |
445 | } | |
446 | qmp_output_visitor_cleanup(mo); | |
f9bee751 | 447 | md = qapi_dealloc_visitor_new(); |
b84da831 | 448 | v = qapi_dealloc_get_visitor(md); |
6e2bb3ec | 449 | visit_type_UserDefOne(v, &ret_in, "unused", NULL); |
b84da831 | 450 | qapi_dealloc_visitor_cleanup(md); |
b84da831 MR |
451 | } |
452 | ||
6e2bb3ec | 453 | static void qmp_marshal_input_my_command(QDict *args, QObject **ret, Error **errp) |
b84da831 MR |
454 | { |
455 | UserDefOne * retval = NULL; | |
f9bee751 | 456 | QmpInputVisitor *mi = qmp_input_visitor_new_strict(QOBJECT(args)); |
b84da831 MR |
457 | QapiDeallocVisitor *md; |
458 | Visitor *v; | |
459 | UserDefOne * arg1 = NULL; | |
460 | ||
b84da831 MR |
461 | v = qmp_input_get_visitor(mi); |
462 | visit_type_UserDefOne(v, &arg1, "arg1", errp); | |
463 | ||
464 | if (error_is_set(errp)) { | |
465 | goto out; | |
466 | } | |
467 | retval = qmp_my_command(arg1, errp); | |
6e2bb3ec MA |
468 | if (!error_is_set(errp)) { |
469 | qmp_marshal_output_my_command(retval, ret, errp); | |
470 | } | |
b84da831 MR |
471 | |
472 | out: | |
f9bee751 | 473 | qmp_input_visitor_cleanup(mi); |
b84da831 MR |
474 | md = qapi_dealloc_visitor_new(); |
475 | v = qapi_dealloc_get_visitor(md); | |
6e2bb3ec | 476 | visit_type_UserDefOne(v, &arg1, "arg1", NULL); |
b84da831 MR |
477 | qapi_dealloc_visitor_cleanup(md); |
478 | return; | |
479 | } | |
480 | ||
481 | static void qmp_init_marshal(void) | |
482 | { | |
6e2bb3ec | 483 | qmp_register_command("my-command", qmp_marshal_input_my_command, QCO_NO_OPTIONS); |
b84da831 MR |
484 | } |
485 | ||
486 | qapi_init(qmp_init_marshal); | |
487 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-commands.h | |
6e2bb3ec | 488 | [Uninteresting stuff omitted...] |
b84da831 | 489 | |
6e2bb3ec MA |
490 | #ifndef EXAMPLE_QMP_COMMANDS_H |
491 | #define EXAMPLE_QMP_COMMANDS_H | |
b84da831 MR |
492 | |
493 | #include "example-qapi-types.h" | |
6e2bb3ec MA |
494 | #include "qapi/qmp/qdict.h" |
495 | #include "qapi/error.h" | |
b84da831 MR |
496 | |
497 | UserDefOne * qmp_my_command(UserDefOne * arg1, Error **errp); | |
498 | ||
499 | #endif | |
500 | mdroth@illuin:~/w/qemu2.git$ |