PPC: e500mc: add missing IVORs to bitmap
[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 two kinds of types that are supported: complex user-defined types, and enums.
38
39 A complex type is a dictionary containing a single key who's value is a
40 dictionary.  This corresponds to a struct in C or an Object in JSON.  An
41 example of a complex type is:
42
43  { 'type': 'MyType',
44    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
45
46 The use of '*' as a prefix to the name means the member is optional.  Optional
47 members should always be added to the end of the dictionary to preserve
48 backwards compatibility.
49
50 An enumeration type is a dictionary containing a single key who's value is a
51 list of strings.  An example enumeration is:
52
53  { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
54
55 Generally speaking, complex types and enums should always use CamelCase for
56 the type names.
57
58 Commands are defined by using a list containing three members.  The first
59 member is the command name, the second member is a dictionary containing
60 arguments, and the third member is the return type.
61
62 An example command is:
63
64  { 'command': 'my-command',
65    'data': { 'arg1': 'str', '*arg2': 'str' },
66    'returns': 'str' }
67
68 Command names should be all lower case with words separated by a hyphen.
69
70
71 == Code generation ==
72
73 Schemas are fed into 3 scripts to generate all the code/files that, paired
74 with the core QAPI libraries, comprise everything required to take JSON
75 commands read in by a QMP/guest agent server, unmarshal the arguments into
76 the underlying C types, call into the corresponding C function, and map the
77 response back to a QMP/guest agent response to be returned to the user.
78
79 As an example, we'll use the following schema, which describes a single
80 complex user-defined type (which will produce a C struct, along with a list
81 node structure that can be used to chain together a list of such types in
82 case we want to accept/return a list of this type with a command), and a
83 command which takes that type as a parameter and returns the same type:
84
85     mdroth@illuin:~/w/qemu2.git$ cat example-schema.json
86     { 'type': 'UserDefOne',
87       'data': { 'integer': 'int', 'string': 'str' } }
88
89     { 'command': 'my-command',
90       'data':    {'arg1': 'UserDefOne'},
91       'returns': 'UserDefOne' }
92     mdroth@illuin:~/w/qemu2.git$
93
94 === scripts/qapi-types.py ===
95
96 Used to generate the C types defined by a schema. The following files are
97 created:
98
99 $(prefix)qapi-types.h - C types corresponding to types defined in
100                         the schema you pass in
101 $(prefix)qapi-types.c - Cleanup functions for the above C types
102
103 The $(prefix) is an optional parameter used as a namespace to keep the
104 generated code from one schema/code-generation separated from others so code
105 can be generated/used from multiple schemas without clobbering previously
106 created code.
107
108 Example:
109
110     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \
111       --output-dir="qapi-generated" --prefix="example-" < example-schema.json
112     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c
113     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
114
115     #include "qapi/qapi-dealloc-visitor.h"
116     #include "example-qapi-types.h"
117     #include "example-qapi-visit.h"
118
119     void qapi_free_UserDefOne(UserDefOne * obj)
120     {
121         QapiDeallocVisitor *md;
122         Visitor *v;
123
124         if (!obj) {
125             return;
126         }
127
128         md = qapi_dealloc_visitor_new();
129         v = qapi_dealloc_get_visitor(md);
130         visit_type_UserDefOne(v, &obj, NULL, NULL);
131         qapi_dealloc_visitor_cleanup(md);
132     }
133
134     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.h
135     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
136     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_TYPES
137     #define QAPI_GENERATED_EXAMPLE_QAPI_TYPES
138
139     #include "qapi/qapi-types-core.h"
140
141     typedef struct UserDefOne UserDefOne;
142
143     typedef struct UserDefOneList
144     {
145         UserDefOne *value;
146         struct UserDefOneList *next;
147     } UserDefOneList;
148
149     struct UserDefOne
150     {
151         int64_t integer;
152         char * string;
153     };
154
155     void qapi_free_UserDefOne(UserDefOne * obj);
156
157     #endif
158
159
160 === scripts/qapi-visit.py ===
161
162 Used to generate the visitor functions used to walk through and convert
163 a QObject (as provided by QMP) to a native C data structure and
164 vice-versa, as well as the visitor function used to dealloc a complex
165 schema-defined C type.
166
167 The following files are generated:
168
169 $(prefix)qapi-visit.c: visitor function for a particular C type, used
170                        to automagically convert QObjects into the
171                        corresponding C type and vice-versa, as well
172                        as for deallocating memory for an existing C
173                        type
174
175 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
176                        functions
177
178 Example:
179
180     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \
181         --output-dir="qapi-generated" --prefix="example-" < example-schema.json
182     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c
183     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
184
185     #include "example-qapi-visit.h"
186
187     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp)
188     {
189         visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), errp);
190         visit_type_int(m, (obj && *obj) ? &(*obj)->integer : NULL, "integer", errp);
191         visit_type_str(m, (obj && *obj) ? &(*obj)->string : NULL, "string", errp);
192         visit_end_struct(m, errp);
193     }
194
195     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp)
196     {
197         GenericList *i;
198
199         visit_start_list(m, name, errp);
200
201         for (i = visit_next_list(m, (GenericList **)obj, errp); i; i = visit_next_list(m, &i, errp)) {
202             UserDefOneList *native_i = (UserDefOneList *)i;
203             visit_type_UserDefOne(m, &native_i->value, NULL, errp);
204         }
205
206         visit_end_list(m, errp);
207     }
208     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.h
209     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
210
211     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_VISIT
212     #define QAPI_GENERATED_EXAMPLE_QAPI_VISIT
213
214     #include "qapi/qapi-visit-core.h"
215     #include "example-qapi-types.h"
216
217     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp);
218     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp);
219
220     #endif
221     mdroth@illuin:~/w/qemu2.git$
222
223
224 === scripts/qapi-commands.py ===
225
226 Used to generate the marshaling/dispatch functions for the commands defined
227 in the schema. The following files are generated:
228
229 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
230                         QMP command defined in the schema. Functions
231                         generated by qapi-visit.py are used to
232                         convert QObjects received from the wire into
233                         function parameters, and uses the same
234                         visitor functions to convert native C return
235                         values to QObjects from transmission back
236                         over the wire.
237
238 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
239                          specified in the schema.
240
241 Example:
242
243     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-marshal.c
244     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
245
246     #include "qemu-objects.h"
247     #include "qapi/qmp-core.h"
248     #include "qapi/qapi-visit-core.h"
249     #include "qapi/qmp-output-visitor.h"
250     #include "qapi/qmp-input-visitor.h"
251     #include "qapi/qapi-dealloc-visitor.h"
252     #include "example-qapi-types.h"
253     #include "example-qapi-visit.h"
254
255     #include "example-qmp-commands.h"
256     static void qmp_marshal_output_my_command(UserDefOne * ret_in, QObject **ret_out, Error **errp)
257     {
258         QapiDeallocVisitor *md = qapi_dealloc_visitor_new();
259         QmpOutputVisitor *mo = qmp_output_visitor_new();
260         Visitor *v;
261
262         v = qmp_output_get_visitor(mo);
263         visit_type_UserDefOne(v, &ret_in, "unused", errp);
264         v = qapi_dealloc_get_visitor(md);
265         visit_type_UserDefOne(v, &ret_in, "unused", errp);
266         qapi_dealloc_visitor_cleanup(md);
267
268
269         *ret_out = qmp_output_get_qobject(mo);
270     }
271
272     static void qmp_marshal_input_my_command(QmpState *qmp__sess, QDict *args, QObject **ret, Error **errp)
273     {
274         UserDefOne * retval = NULL;
275         QmpInputVisitor *mi;
276         QapiDeallocVisitor *md;
277         Visitor *v;
278         UserDefOne * arg1 = NULL;
279
280         mi = qmp_input_visitor_new(QOBJECT(args));
281         v = qmp_input_get_visitor(mi);
282         visit_type_UserDefOne(v, &arg1, "arg1", errp);
283
284         if (error_is_set(errp)) {
285             goto out;
286         }
287         retval = qmp_my_command(arg1, errp);
288         qmp_marshal_output_my_command(retval, ret, errp);
289
290     out:
291         md = qapi_dealloc_visitor_new();
292         v = qapi_dealloc_get_visitor(md);
293         visit_type_UserDefOne(v, &arg1, "arg1", errp);
294         qapi_dealloc_visitor_cleanup(md);
295         return;
296     }
297
298     static void qmp_init_marshal(void)
299     {
300         qmp_register_command("my-command", qmp_marshal_input_my_command);
301     }
302
303     qapi_init(qmp_init_marshal);
304     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-commands.h
305     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
306
307     #ifndef QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
308     #define QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
309
310     #include "example-qapi-types.h"
311     #include "error.h"
312
313     UserDefOne * qmp_my_command(UserDefOne * arg1, Error **errp);
314
315     #endif
316     mdroth@illuin:~/w/qemu2.git$