softfloat: Add float16 <=> float64 conversion functions
[qemu/ar7.git] / docs / qapi-code-gen.txt
blob0728f36c6522b576a469d7405d9fca8d81bad0b1
1 = How to use the QAPI code generator =
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.
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.
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.
21 This document will describe how the schemas, scripts, and resulting
22 code is used.
25 == QMP/Guest agent schema ==
27 This file defines the types, commands, and events used by QMP.  It should
28 fully describe the interface used by QMP.
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.
34 There are two basic syntaxes used, type definitions and command definitions.
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.
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.
43 === Complex types ===
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:
49  { 'type': 'MyType',
50    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
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.
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:
62  { 'type': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
63  { 'type': 'BlockdevOptionsGenericCOWFormat',
64    'base': 'BlockdevOptionsGenericFormat',
65    'data': { '*backing': 'str' } }
67 An example BlockdevOptionsGenericCOWFormat object on the wire could use
68 both fields like this:
70  { "file": "/some/place/my-image",
71    "backing": "/some/place/my-backing-file" }
73 === Enumeration types ===
75 An enumeration type is a dictionary containing a single key whose value is a
76 list of strings.  An example enumeration is:
78  { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
80 === Union types ===
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.
87 A simple union type defines a mapping from discriminator values to data types
88 like in this example:
90  { 'type': 'FileOptions', 'data': { 'filename': 'str' } }
91  { 'type': 'Qcow2Options',
92    'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
94  { 'union': 'BlockdevOptions',
95    'data': { 'file': 'FileOptions',
96              'qcow2': 'Qcow2Options' } }
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:
102  { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
103                                "lazy-refcounts": true } }
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:
110  { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
111  { 'union': 'BlockdevOptions',
112    'base': 'BlockdevCommonOptions',
113    'data': { 'raw': 'RawOptions',
114              'qcow2': 'Qcow2Options' } }
116 And it looks like this on the wire:
118  { "type": "qcow2",
119    "readonly": false,
120    "data" : { "backing-file": "/some/place/my-image",
121               "lazy-refcounts": true } }
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 always be a string field.
127 The above example can then be modified as follows:
129  { 'type': 'BlockdevCommonOptions',
130    'data': { 'driver': 'str', 'readonly': 'bool' } }
131  { 'union': 'BlockdevOptions',
132    'base': 'BlockdevCommonOptions',
133    'discriminator': 'driver',
134    'data': { 'raw': 'RawOptions',
135              'qcow2': 'Qcow2Options' } }
137 Resulting in this JSON object:
139  { "driver": "qcow2",
140    "readonly": false,
141    "backing-file": "/some/place/my-image",
142    "lazy-refcounts": true }
145 A special type of unions are anonymous unions. They don't form a dictionary in
146 the wire format but allow the direct use of different types in their place. As
147 they aren't structured, they don't have any explicit discriminator but use
148 the (QObject) data type of their value as an implicit discriminator. This means
149 that they are restricted to using only one discriminator value per QObject
150 type. For example, you cannot have two different complex types in an anonymous
151 union, or two different integer types.
153 Anonymous unions are declared using an empty dictionary as their discriminator.
154 The discriminator values never appear on the wire, they are only used in the
155 generated C code. Anonymous unions cannot have a base type.
157  { 'union': 'BlockRef',
158    'discriminator': {},
159    'data': { 'definition': 'BlockdevOptions',
160              'reference': 'str' } }
162 This example allows using both of the following example objects:
164  { "file": "my_existing_block_device_id" }
165  { "file": { "driver": "file",
166              "readonly": false,
167              "filename": "/tmp/mydisk.qcow2" } }
170 === Commands ===
172 Commands are defined by using a list containing three members.  The first
173 member is the command name, the second member is a dictionary containing
174 arguments, and the third member is the return type.
176 An example command is:
178  { 'command': 'my-command',
179    'data': { 'arg1': 'str', '*arg2': 'str' },
180    'returns': 'str' }
183 == Code generation ==
185 Schemas are fed into 3 scripts to generate all the code/files that, paired
186 with the core QAPI libraries, comprise everything required to take JSON
187 commands read in by a QMP/guest agent server, unmarshal the arguments into
188 the underlying C types, call into the corresponding C function, and map the
189 response back to a QMP/guest agent response to be returned to the user.
191 As an example, we'll use the following schema, which describes a single
192 complex user-defined type (which will produce a C struct, along with a list
193 node structure that can be used to chain together a list of such types in
194 case we want to accept/return a list of this type with a command), and a
195 command which takes that type as a parameter and returns the same type:
197     mdroth@illuin:~/w/qemu2.git$ cat example-schema.json
198     { 'type': 'UserDefOne',
199       'data': { 'integer': 'int', 'string': 'str' } }
201     { 'command': 'my-command',
202       'data':    {'arg1': 'UserDefOne'},
203       'returns': 'UserDefOne' }
204     mdroth@illuin:~/w/qemu2.git$
206 === scripts/qapi-types.py ===
208 Used to generate the C types defined by a schema. The following files are
209 created:
211 $(prefix)qapi-types.h - C types corresponding to types defined in
212                         the schema you pass in
213 $(prefix)qapi-types.c - Cleanup functions for the above C types
215 The $(prefix) is an optional parameter used as a namespace to keep the
216 generated code from one schema/code-generation separated from others so code
217 can be generated/used from multiple schemas without clobbering previously
218 created code.
220 Example:
222     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \
223       --output-dir="qapi-generated" --prefix="example-" < example-schema.json
224     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c
225     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
227     #include "qapi/qapi-dealloc-visitor.h"
228     #include "example-qapi-types.h"
229     #include "example-qapi-visit.h"
231     void qapi_free_UserDefOne(UserDefOne * obj)
232     {
233         QapiDeallocVisitor *md;
234         Visitor *v;
236         if (!obj) {
237             return;
238         }
240         md = qapi_dealloc_visitor_new();
241         v = qapi_dealloc_get_visitor(md);
242         visit_type_UserDefOne(v, &obj, NULL, NULL);
243         qapi_dealloc_visitor_cleanup(md);
244     }
246     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.h
247     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
248     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_TYPES
249     #define QAPI_GENERATED_EXAMPLE_QAPI_TYPES
251     #include "qapi/qapi-types-core.h"
253     typedef struct UserDefOne UserDefOne;
255     typedef struct UserDefOneList
256     {
257         UserDefOne *value;
258         struct UserDefOneList *next;
259     } UserDefOneList;
261     struct UserDefOne
262     {
263         int64_t integer;
264         char * string;
265     };
267     void qapi_free_UserDefOne(UserDefOne * obj);
269     #endif
272 === scripts/qapi-visit.py ===
274 Used to generate the visitor functions used to walk through and convert
275 a QObject (as provided by QMP) to a native C data structure and
276 vice-versa, as well as the visitor function used to dealloc a complex
277 schema-defined C type.
279 The following files are generated:
281 $(prefix)qapi-visit.c: visitor function for a particular C type, used
282                        to automagically convert QObjects into the
283                        corresponding C type and vice-versa, as well
284                        as for deallocating memory for an existing C
285                        type
287 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
288                        functions
290 Example:
292     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \
293         --output-dir="qapi-generated" --prefix="example-" < example-schema.json
294     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c
295     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
297     #include "example-qapi-visit.h"
299     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp)
300     {
301         visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), errp);
302         visit_type_int(m, (obj && *obj) ? &(*obj)->integer : NULL, "integer", errp);
303         visit_type_str(m, (obj && *obj) ? &(*obj)->string : NULL, "string", errp);
304         visit_end_struct(m, errp);
305     }
307     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp)
308     {
309         GenericList *i, **prev = (GenericList **)obj;
311         visit_start_list(m, name, errp);
313         for (; (i = visit_next_list(m, prev, errp)) != NULL; prev = &i) {
314             UserDefOneList *native_i = (UserDefOneList *)i;
315             visit_type_UserDefOne(m, &native_i->value, NULL, errp);
316         }
318         visit_end_list(m, errp);
319     }
320     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.h
321     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
323     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_VISIT
324     #define QAPI_GENERATED_EXAMPLE_QAPI_VISIT
326     #include "qapi/qapi-visit-core.h"
327     #include "example-qapi-types.h"
329     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp);
330     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp);
332     #endif
333     mdroth@illuin:~/w/qemu2.git$
335 (The actual structure of the visit_type_* functions is a bit more complex
336 in order to propagate errors correctly and avoid leaking memory).
338 === scripts/qapi-commands.py ===
340 Used to generate the marshaling/dispatch functions for the commands defined
341 in the schema. The following files are generated:
343 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
344                         QMP command defined in the schema. Functions
345                         generated by qapi-visit.py are used to
346                         convert QObjects received from the wire into
347                         function parameters, and uses the same
348                         visitor functions to convert native C return
349                         values to QObjects from transmission back
350                         over the wire.
352 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
353                          specified in the schema.
355 Example:
357     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-marshal.c
358     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
360     #include "qemu-objects.h"
361     #include "qapi/qmp-core.h"
362     #include "qapi/qapi-visit-core.h"
363     #include "qapi/qmp-output-visitor.h"
364     #include "qapi/qmp-input-visitor.h"
365     #include "qapi/qapi-dealloc-visitor.h"
366     #include "example-qapi-types.h"
367     #include "example-qapi-visit.h"
369     #include "example-qmp-commands.h"
370     static void qmp_marshal_output_my_command(UserDefOne * ret_in, QObject **ret_out, Error **errp)
371     {
372         QapiDeallocVisitor *md = qapi_dealloc_visitor_new();
373         QmpOutputVisitor *mo = qmp_output_visitor_new();
374         Visitor *v;
376         v = qmp_output_get_visitor(mo);
377         visit_type_UserDefOne(v, &ret_in, "unused", errp);
378         v = qapi_dealloc_get_visitor(md);
379         visit_type_UserDefOne(v, &ret_in, "unused", errp);
380         qapi_dealloc_visitor_cleanup(md);
383         *ret_out = qmp_output_get_qobject(mo);
384     }
386     static void qmp_marshal_input_my_command(QmpState *qmp__sess, QDict *args, QObject **ret, Error **errp)
387     {
388         UserDefOne * retval = NULL;
389         QmpInputVisitor *mi;
390         QapiDeallocVisitor *md;
391         Visitor *v;
392         UserDefOne * arg1 = NULL;
394         mi = qmp_input_visitor_new(QOBJECT(args));
395         v = qmp_input_get_visitor(mi);
396         visit_type_UserDefOne(v, &arg1, "arg1", errp);
398         if (error_is_set(errp)) {
399             goto out;
400         }
401         retval = qmp_my_command(arg1, errp);
402         qmp_marshal_output_my_command(retval, ret, errp);
404     out:
405         md = qapi_dealloc_visitor_new();
406         v = qapi_dealloc_get_visitor(md);
407         visit_type_UserDefOne(v, &arg1, "arg1", errp);
408         qapi_dealloc_visitor_cleanup(md);
409         return;
410     }
412     static void qmp_init_marshal(void)
413     {
414         qmp_register_command("my-command", qmp_marshal_input_my_command);
415     }
417     qapi_init(qmp_init_marshal);
418     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-commands.h
419     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
421     #ifndef QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
422     #define QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
424     #include "example-qapi-types.h"
425     #include "error.h"
427     UserDefOne * qmp_my_command(UserDefOne * arg1, Error **errp);
429     #endif
430     mdroth@illuin:~/w/qemu2.git$