]>
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 | ||
43 | === Complex types === | |
44 | ||
45 | A complex type is a dictionary containing a single key whose value is a | |
b84da831 MR |
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', | |
acf8394e | 50 | 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } |
b84da831 MR |
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 | ||
51631493 KW |
56 | === Enumeration types === |
57 | ||
58 | An enumeration type is a dictionary containing a single key whose value is a | |
b84da831 MR |
59 | list of strings. An example enumeration is: |
60 | ||
61 | { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } | |
62 | ||
51631493 KW |
63 | === Union types === |
64 | ||
65 | Union types are used to let the user choose between several different data | |
66 | types. A union type is defined using a dictionary as explained in the | |
67 | following paragraphs. | |
68 | ||
69 | ||
70 | A simple union type defines a mapping from discriminator values to data types | |
71 | like in this example: | |
72 | ||
73 | { 'type': 'FileOptions', 'data': { 'filename': 'str' } } | |
74 | { 'type': 'Qcow2Options', | |
75 | 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } } | |
76 | ||
77 | { 'union': 'BlockdevOptions', | |
78 | 'data': { 'file': 'FileOptions', | |
79 | 'qcow2': 'Qcow2Options' } } | |
80 | ||
81 | In the QMP wire format, a simple union is represented by a dictionary that | |
82 | contains the 'type' field as a discriminator, and a 'data' field that is of the | |
83 | specified data type corresponding to the discriminator value: | |
84 | ||
85 | { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image", | |
86 | "lazy-refcounts": true } } | |
87 | ||
88 | ||
89 | A union definition can specify a complex type as its base. In this case, the | |
90 | fields of the complex type are included as top-level fields of the union | |
91 | dictionary in the QMP wire format. An example definition is: | |
92 | ||
93 | { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } } | |
94 | { 'union': 'BlockdevOptions', | |
95 | 'base': 'BlockdevCommonOptions', | |
96 | 'data': { 'raw': 'RawOptions', | |
97 | 'qcow2': 'Qcow2Options' } } | |
98 | ||
99 | And it looks like this on the wire: | |
100 | ||
101 | { "type": "qcow2", | |
102 | "readonly": false, | |
103 | "data" : { "backing-file": "/some/place/my-image", | |
104 | "lazy-refcounts": true } } | |
105 | ||
106 | === Commands === | |
b84da831 MR |
107 | |
108 | Commands are defined by using a list containing three members. The first | |
109 | member is the command name, the second member is a dictionary containing | |
110 | arguments, and the third member is the return type. | |
111 | ||
112 | An example command is: | |
113 | ||
114 | { 'command': 'my-command', | |
115 | 'data': { 'arg1': 'str', '*arg2': 'str' }, | |
acf8394e | 116 | 'returns': 'str' } |
b84da831 | 117 | |
b84da831 MR |
118 | |
119 | == Code generation == | |
120 | ||
121 | Schemas are fed into 3 scripts to generate all the code/files that, paired | |
122 | with the core QAPI libraries, comprise everything required to take JSON | |
123 | commands read in by a QMP/guest agent server, unmarshal the arguments into | |
124 | the underlying C types, call into the corresponding C function, and map the | |
125 | response back to a QMP/guest agent response to be returned to the user. | |
126 | ||
127 | As an example, we'll use the following schema, which describes a single | |
128 | complex user-defined type (which will produce a C struct, along with a list | |
129 | node structure that can be used to chain together a list of such types in | |
130 | case we want to accept/return a list of this type with a command), and a | |
131 | command which takes that type as a parameter and returns the same type: | |
132 | ||
133 | mdroth@illuin:~/w/qemu2.git$ cat example-schema.json | |
134 | { 'type': 'UserDefOne', | |
135 | 'data': { 'integer': 'int', 'string': 'str' } } | |
136 | ||
137 | { 'command': 'my-command', | |
138 | 'data': {'arg1': 'UserDefOne'}, | |
139 | 'returns': 'UserDefOne' } | |
140 | mdroth@illuin:~/w/qemu2.git$ | |
141 | ||
142 | === scripts/qapi-types.py === | |
143 | ||
144 | Used to generate the C types defined by a schema. The following files are | |
145 | created: | |
146 | ||
147 | $(prefix)qapi-types.h - C types corresponding to types defined in | |
148 | the schema you pass in | |
149 | $(prefix)qapi-types.c - Cleanup functions for the above C types | |
150 | ||
151 | The $(prefix) is an optional parameter used as a namespace to keep the | |
152 | generated code from one schema/code-generation separated from others so code | |
153 | can be generated/used from multiple schemas without clobbering previously | |
154 | created code. | |
155 | ||
156 | Example: | |
157 | ||
158 | mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \ | |
159 | --output-dir="qapi-generated" --prefix="example-" < example-schema.json | |
160 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c | |
161 | /* AUTOMATICALLY GENERATED, DO NOT MODIFY */ | |
162 | ||
163 | #include "qapi/qapi-dealloc-visitor.h" | |
164 | #include "example-qapi-types.h" | |
165 | #include "example-qapi-visit.h" | |
166 | ||
167 | void qapi_free_UserDefOne(UserDefOne * obj) | |
168 | { | |
169 | QapiDeallocVisitor *md; | |
170 | Visitor *v; | |
171 | ||
172 | if (!obj) { | |
173 | return; | |
174 | } | |
175 | ||
176 | md = qapi_dealloc_visitor_new(); | |
177 | v = qapi_dealloc_get_visitor(md); | |
178 | visit_type_UserDefOne(v, &obj, NULL, NULL); | |
179 | qapi_dealloc_visitor_cleanup(md); | |
180 | } | |
181 | ||
182 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.h | |
183 | /* AUTOMATICALLY GENERATED, DO NOT MODIFY */ | |
184 | #ifndef QAPI_GENERATED_EXAMPLE_QAPI_TYPES | |
185 | #define QAPI_GENERATED_EXAMPLE_QAPI_TYPES | |
186 | ||
187 | #include "qapi/qapi-types-core.h" | |
188 | ||
189 | typedef struct UserDefOne UserDefOne; | |
190 | ||
191 | typedef struct UserDefOneList | |
192 | { | |
193 | UserDefOne *value; | |
194 | struct UserDefOneList *next; | |
195 | } UserDefOneList; | |
196 | ||
197 | struct UserDefOne | |
198 | { | |
199 | int64_t integer; | |
200 | char * string; | |
201 | }; | |
202 | ||
203 | void qapi_free_UserDefOne(UserDefOne * obj); | |
204 | ||
205 | #endif | |
206 | ||
207 | ||
208 | === scripts/qapi-visit.py === | |
209 | ||
210 | Used to generate the visitor functions used to walk through and convert | |
211 | a QObject (as provided by QMP) to a native C data structure and | |
212 | vice-versa, as well as the visitor function used to dealloc a complex | |
213 | schema-defined C type. | |
214 | ||
215 | The following files are generated: | |
216 | ||
217 | $(prefix)qapi-visit.c: visitor function for a particular C type, used | |
218 | to automagically convert QObjects into the | |
219 | corresponding C type and vice-versa, as well | |
220 | as for deallocating memory for an existing C | |
221 | type | |
222 | ||
223 | $(prefix)qapi-visit.h: declarations for previously mentioned visitor | |
224 | functions | |
225 | ||
226 | Example: | |
227 | ||
228 | mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \ | |
229 | --output-dir="qapi-generated" --prefix="example-" < example-schema.json | |
230 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c | |
231 | /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */ | |
232 | ||
233 | #include "example-qapi-visit.h" | |
234 | ||
235 | void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp) | |
236 | { | |
237 | visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), errp); | |
238 | visit_type_int(m, (obj && *obj) ? &(*obj)->integer : NULL, "integer", errp); | |
239 | visit_type_str(m, (obj && *obj) ? &(*obj)->string : NULL, "string", errp); | |
240 | visit_end_struct(m, errp); | |
241 | } | |
242 | ||
243 | void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp) | |
244 | { | |
3a86a0fa | 245 | GenericList *i, **prev = (GenericList **)obj; |
b84da831 MR |
246 | |
247 | visit_start_list(m, name, errp); | |
248 | ||
3a86a0fa | 249 | for (; (i = visit_next_list(m, prev, errp)) != NULL; prev = &i) { |
b84da831 MR |
250 | UserDefOneList *native_i = (UserDefOneList *)i; |
251 | visit_type_UserDefOne(m, &native_i->value, NULL, errp); | |
252 | } | |
253 | ||
254 | visit_end_list(m, errp); | |
255 | } | |
256 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.h | |
257 | /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */ | |
258 | ||
259 | #ifndef QAPI_GENERATED_EXAMPLE_QAPI_VISIT | |
260 | #define QAPI_GENERATED_EXAMPLE_QAPI_VISIT | |
261 | ||
262 | #include "qapi/qapi-visit-core.h" | |
263 | #include "example-qapi-types.h" | |
264 | ||
265 | void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp); | |
266 | void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp); | |
267 | ||
268 | #endif | |
269 | mdroth@illuin:~/w/qemu2.git$ | |
270 | ||
d195325b PB |
271 | (The actual structure of the visit_type_* functions is a bit more complex |
272 | in order to propagate errors correctly and avoid leaking memory). | |
b84da831 MR |
273 | |
274 | === scripts/qapi-commands.py === | |
275 | ||
276 | Used to generate the marshaling/dispatch functions for the commands defined | |
277 | in the schema. The following files are generated: | |
278 | ||
279 | $(prefix)qmp-marshal.c: command marshal/dispatch functions for each | |
280 | QMP command defined in the schema. Functions | |
281 | generated by qapi-visit.py are used to | |
2542bfd5 | 282 | convert QObjects received from the wire into |
b84da831 MR |
283 | function parameters, and uses the same |
284 | visitor functions to convert native C return | |
285 | values to QObjects from transmission back | |
286 | over the wire. | |
287 | ||
288 | $(prefix)qmp-commands.h: Function prototypes for the QMP commands | |
289 | specified in the schema. | |
290 | ||
291 | Example: | |
292 | ||
293 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-marshal.c | |
294 | /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */ | |
295 | ||
296 | #include "qemu-objects.h" | |
297 | #include "qapi/qmp-core.h" | |
298 | #include "qapi/qapi-visit-core.h" | |
299 | #include "qapi/qmp-output-visitor.h" | |
300 | #include "qapi/qmp-input-visitor.h" | |
301 | #include "qapi/qapi-dealloc-visitor.h" | |
302 | #include "example-qapi-types.h" | |
303 | #include "example-qapi-visit.h" | |
304 | ||
305 | #include "example-qmp-commands.h" | |
306 | static void qmp_marshal_output_my_command(UserDefOne * ret_in, QObject **ret_out, Error **errp) | |
307 | { | |
308 | QapiDeallocVisitor *md = qapi_dealloc_visitor_new(); | |
309 | QmpOutputVisitor *mo = qmp_output_visitor_new(); | |
310 | Visitor *v; | |
311 | ||
312 | v = qmp_output_get_visitor(mo); | |
313 | visit_type_UserDefOne(v, &ret_in, "unused", errp); | |
314 | v = qapi_dealloc_get_visitor(md); | |
315 | visit_type_UserDefOne(v, &ret_in, "unused", errp); | |
316 | qapi_dealloc_visitor_cleanup(md); | |
317 | ||
318 | ||
319 | *ret_out = qmp_output_get_qobject(mo); | |
320 | } | |
321 | ||
322 | static void qmp_marshal_input_my_command(QmpState *qmp__sess, QDict *args, QObject **ret, Error **errp) | |
323 | { | |
324 | UserDefOne * retval = NULL; | |
325 | QmpInputVisitor *mi; | |
326 | QapiDeallocVisitor *md; | |
327 | Visitor *v; | |
328 | UserDefOne * arg1 = NULL; | |
329 | ||
330 | mi = qmp_input_visitor_new(QOBJECT(args)); | |
331 | v = qmp_input_get_visitor(mi); | |
332 | visit_type_UserDefOne(v, &arg1, "arg1", errp); | |
333 | ||
334 | if (error_is_set(errp)) { | |
335 | goto out; | |
336 | } | |
337 | retval = qmp_my_command(arg1, errp); | |
338 | qmp_marshal_output_my_command(retval, ret, errp); | |
339 | ||
340 | out: | |
341 | md = qapi_dealloc_visitor_new(); | |
342 | v = qapi_dealloc_get_visitor(md); | |
343 | visit_type_UserDefOne(v, &arg1, "arg1", errp); | |
344 | qapi_dealloc_visitor_cleanup(md); | |
345 | return; | |
346 | } | |
347 | ||
348 | static void qmp_init_marshal(void) | |
349 | { | |
350 | qmp_register_command("my-command", qmp_marshal_input_my_command); | |
351 | } | |
352 | ||
353 | qapi_init(qmp_init_marshal); | |
354 | mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-commands.h | |
355 | /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */ | |
356 | ||
357 | #ifndef QAPI_GENERATED_EXAMPLE_QMP_COMMANDS | |
358 | #define QAPI_GENERATED_EXAMPLE_QMP_COMMANDS | |
359 | ||
360 | #include "example-qapi-types.h" | |
361 | #include "error.h" | |
362 | ||
363 | UserDefOne * qmp_my_command(UserDefOne * arg1, Error **errp); | |
364 | ||
365 | #endif | |
366 | mdroth@illuin:~/w/qemu2.git$ |