]>
Commit | Line | Data |
---|---|---|
f7aa076d JS |
1 | ================================== |
2 | How to use the QAPI code generator | |
3 | ================================== | |
b84da831 | 4 | |
f7aa076d JS |
5 | .. |
6 | Copyright IBM Corp. 2011 | |
7 | Copyright (C) 2012-2016 Red Hat, Inc. | |
6fb55451 | 8 | |
f7aa076d JS |
9 | This work is licensed under the terms of the GNU GPL, version 2 or |
10 | later. See the COPYING file in the top-level directory. | |
6fb55451 | 11 | |
f7aa076d JS |
12 | |
13 | Introduction | |
14 | ============ | |
6fb55451 | 15 | |
b84da831 | 16 | QAPI is a native C API within QEMU which provides management-level |
b6c37eba | 17 | functionality to internal and external users. For external |
e790e666 EB |
18 | users/processes, this interface is made available by a JSON-based wire |
19 | format for the QEMU Monitor Protocol (QMP) for controlling qemu, as | |
20 | well as the QEMU Guest Agent (QGA) for communicating with the guest. | |
363b4262 EB |
21 | The remainder of this document uses "Client JSON Protocol" when |
22 | referring to the wire contents of a QMP or QGA connection. | |
b84da831 | 23 | |
634c82c1 MA |
24 | To map between Client JSON Protocol interfaces and the native C API, |
25 | we generate C code from a QAPI schema. This document describes the | |
26 | QAPI schema language, and how it gets mapped to the Client JSON | |
27 | Protocol and to C. It additionally provides guidance on maintaining | |
28 | Client JSON Protocol compatibility. | |
29 | ||
30 | ||
f7aa076d JS |
31 | The QAPI schema language |
32 | ======================== | |
634c82c1 MA |
33 | |
34 | The QAPI schema defines the Client JSON Protocol's commands and | |
35 | events, as well as types used by them. Forward references are | |
36 | allowed. | |
37 | ||
38 | It is permissible for the schema to contain additional types not used | |
39 | by any commands or events, for the side effect of generated C code | |
40 | used internally. | |
41 | ||
42 | There are several kinds of types: simple types (a number of built-in | |
55927c5f | 43 | types, such as ``int`` and ``str``; as well as enumerations), arrays, |
659056b8 AB |
44 | complex types (structs and unions), and alternate types (a choice |
45 | between other types). | |
634c82c1 MA |
46 | |
47 | ||
f7aa076d JS |
48 | Schema syntax |
49 | ------------- | |
634c82c1 | 50 | |
f7aa076d | 51 | Syntax is loosely based on `JSON <http://www.ietf.org/rfc/rfc8259.txt>`_. |
634c82c1 MA |
52 | Differences: |
53 | ||
55927c5f | 54 | * Comments: start with a hash character (``#``) that is not part of a |
634c82c1 MA |
55 | string, and extend to the end of the line. |
56 | ||
55927c5f | 57 | * Strings are enclosed in ``'single quotes'``, not ``"double quotes"``. |
634c82c1 MA |
58 | |
59 | * Strings are restricted to printable ASCII, and escape sequences to | |
55927c5f | 60 | just ``\\``. |
634c82c1 | 61 | |
55927c5f | 62 | * Numbers and ``null`` are not supported. |
634c82c1 | 63 | |
b6c37eba MA |
64 | A second layer of syntax defines the sequences of JSON texts that are |
65 | a correctly structured QAPI schema. We provide a grammar for this | |
66 | syntax in an EBNF-like notation: | |
67 | ||
55927c5f JS |
68 | * Production rules look like ``non-terminal = expression`` |
69 | * Concatenation: expression ``A B`` matches expression ``A``, then ``B`` | |
70 | * Alternation: expression ``A | B`` matches expression ``A`` or ``B`` | |
71 | * Repetition: expression ``A...`` matches zero or more occurrences of | |
72 | expression ``A`` | |
73 | * Repetition: expression ``A, ...`` matches zero or more occurrences of | |
74 | expression ``A`` separated by ``,`` | |
75 | * Grouping: expression ``( A )`` matches expression ``A`` | |
76 | * JSON's structural characters are terminals: ``{ } [ ] : ,`` | |
77 | * JSON's literal names are terminals: ``false true`` | |
78 | * String literals enclosed in ``'single quotes'`` are terminal, and match | |
79 | this JSON string, with a leading ``*`` stripped off | |
80 | * When JSON object member's name starts with ``*``, the member is | |
b6c37eba | 81 | optional. |
55927c5f JS |
82 | * The symbol ``STRING`` is a terminal, and matches any JSON string |
83 | * The symbol ``BOOL`` is a terminal, and matches JSON ``false`` or ``true`` | |
84 | * ALL-CAPS words other than ``STRING`` are non-terminals | |
b6c37eba MA |
85 | |
86 | The order of members within JSON objects does not matter unless | |
634c82c1 MA |
87 | explicitly noted. |
88 | ||
f7aa076d | 89 | A QAPI schema consists of a series of top-level expressions:: |
b6c37eba MA |
90 | |
91 | SCHEMA = TOP-LEVEL-EXPR... | |
92 | ||
93 | The top-level expressions are all JSON objects. Code and | |
94 | documentation is generated in schema definition order. Code order | |
95 | should not matter. | |
96 | ||
f7aa076d | 97 | A top-level expressions is either a directive or a definition:: |
b6c37eba MA |
98 | |
99 | TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION | |
e790e666 | 100 | |
f7aa076d | 101 | There are two kinds of directives and six kinds of definitions:: |
b6c37eba MA |
102 | |
103 | DIRECTIVE = INCLUDE | PRAGMA | |
104 | DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT | |
105 | ||
106 | These are discussed in detail below. | |
e790e666 EB |
107 | |
108 | ||
f7aa076d JS |
109 | Built-in Types |
110 | -------------- | |
e790e666 | 111 | |
55927c5f JS |
112 | The following types are predefined, and map to C as follows: |
113 | ||
114 | ============= ============== ============================================ | |
115 | Schema C JSON | |
116 | ============= ============== ============================================ | |
117 | ``str`` ``char *`` any JSON string, UTF-8 | |
118 | ``number`` ``double`` any JSON number | |
119 | ``int`` ``int64_t`` a JSON number without fractional part | |
120 | that fits into the C integer type | |
121 | ``int8`` ``int8_t`` likewise | |
122 | ``int16`` ``int16_t`` likewise | |
123 | ``int32`` ``int32_t`` likewise | |
124 | ``int64`` ``int64_t`` likewise | |
125 | ``uint8`` ``uint8_t`` likewise | |
126 | ``uint16`` ``uint16_t`` likewise | |
127 | ``uint32`` ``uint32_t`` likewise | |
128 | ``uint64`` ``uint64_t`` likewise | |
129 | ``size`` ``uint64_t`` like ``uint64_t``, except | |
130 | ``StringInputVisitor`` accepts size suffixes | |
131 | ``bool`` ``bool`` JSON ``true`` or ``false`` | |
132 | ``null`` ``QNull *`` JSON ``null`` | |
133 | ``any`` ``QObject *`` any JSON value | |
134 | ``QType`` ``QType`` JSON string matching enum ``QType`` values | |
135 | ============= ============== ============================================ | |
51631493 | 136 | |
a719a27c | 137 | |
f7aa076d JS |
138 | Include directives |
139 | ------------------ | |
140 | ||
141 | Syntax:: | |
a719a27c | 142 | |
b6c37eba | 143 | INCLUDE = { 'include': STRING } |
e790e666 | 144 | |
f7aa076d | 145 | The QAPI schema definitions can be modularized using the 'include' directive:: |
a719a27c | 146 | |
e790e666 | 147 | { 'include': 'path/to/file.json' } |
a719a27c | 148 | |
b6c37eba MA |
149 | The directive is evaluated recursively, and include paths are relative |
150 | to the file using the directive. Multiple includes of the same file | |
151 | are idempotent. | |
e790e666 EB |
152 | |
153 | As a matter of style, it is a good idea to have all files be | |
154 | self-contained, but at the moment, nothing prevents an included file | |
155 | from making a forward reference to a type that is only introduced by | |
156 | an outer file. The parser may be made stricter in the future to | |
157 | prevent incomplete include files. | |
a719a27c | 158 | |
9c66762a | 159 | .. _pragma: |
a719a27c | 160 | |
f7aa076d JS |
161 | Pragma directives |
162 | ----------------- | |
163 | ||
164 | Syntax:: | |
bc52d03f | 165 | |
b86df374 MA |
166 | PRAGMA = { 'pragma': { |
167 | '*doc-required': BOOL, | |
05ebf841 | 168 | '*command-name-exceptions': [ STRING, ... ], |
b86df374 MA |
169 | '*command-returns-exceptions': [ STRING, ... ], |
170 | '*member-name-exceptions': [ STRING, ... ] } } | |
bc52d03f MA |
171 | |
172 | The pragma directive lets you control optional generator behavior. | |
bc52d03f MA |
173 | |
174 | Pragma's scope is currently the complete schema. Setting the same | |
175 | pragma to different values in parts of the schema doesn't work. | |
176 | ||
177 | Pragma 'doc-required' takes a boolean value. If true, documentation | |
178 | is required. Default is false. | |
179 | ||
05ebf841 | 180 | Pragma 'command-name-exceptions' takes a list of commands whose names |
55927c5f | 181 | may contain ``"_"`` instead of ``"-"``. Default is none. |
05ebf841 | 182 | |
b86df374 | 183 | Pragma 'command-returns-exceptions' takes a list of commands that may |
1554a8fa MA |
184 | violate the rules on permitted return types. Default is none. |
185 | ||
b86df374 | 186 | Pragma 'member-name-exceptions' takes a list of types whose member |
55927c5f JS |
187 | names may contain uppercase letters, and ``"_"`` instead of ``"-"``. |
188 | Default is none. | |
2cfbae3c | 189 | |
9c66762a | 190 | .. _ENUM-VALUE: |
bc52d03f | 191 | |
f7aa076d JS |
192 | Enumeration types |
193 | ----------------- | |
194 | ||
195 | Syntax:: | |
f5821f52 | 196 | |
b6c37eba MA |
197 | ENUM = { 'enum': STRING, |
198 | 'data': [ ENUM-VALUE, ... ], | |
199 | '*prefix': STRING, | |
013b4efc MA |
200 | '*if': COND, |
201 | '*features': FEATURES } | |
b6c37eba | 202 | ENUM-VALUE = STRING |
b6c18755 MA |
203 | | { 'name': STRING, |
204 | '*if': COND, | |
205 | '*features': FEATURES } | |
f5821f52 | 206 | |
b6c37eba MA |
207 | Member 'enum' names the enum type. |
208 | ||
209 | Each member of the 'data' array defines a value of the enumeration | |
55927c5f | 210 | type. The form STRING is shorthand for :code:`{ 'name': STRING }`. The |
b6c37eba MA |
211 | 'name' values must be be distinct. |
212 | ||
f7aa076d | 213 | Example:: |
f5821f52 MA |
214 | |
215 | { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } | |
216 | ||
217 | Nothing prevents an empty enumeration, although it is probably not | |
b6c37eba MA |
218 | useful. |
219 | ||
220 | On the wire, an enumeration type's value is represented by its | |
221 | (string) name. In C, it's represented by an enumeration constant. | |
222 | These are of the form PREFIX_NAME, where PREFIX is derived from the | |
223 | enumeration type's name, and NAME from the value's name. For the | |
224 | example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to | |
225 | VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The | |
226 | optional 'prefix' member overrides PREFIX. | |
227 | ||
228 | The generated C enumeration constants have values 0, 1, ..., N-1 (in | |
229 | QAPI schema order), where N is the number of values. There is an | |
230 | additional enumeration constant PREFIX__MAX with value N. | |
231 | ||
232 | Do not use string or an integer type when an enumeration type can do | |
233 | the job satisfactorily. | |
234 | ||
9c66762a JS |
235 | The optional 'if' member specifies a conditional. See `Configuring the |
236 | schema`_ below for more on this. | |
b6c37eba | 237 | |
9c66762a | 238 | The optional 'features' member specifies features. See Features_ |
013b4efc MA |
239 | below for more on this. |
240 | ||
b6c37eba | 241 | |
9c66762a JS |
242 | .. _TYPE-REF: |
243 | ||
f7aa076d JS |
244 | Type references and array types |
245 | ------------------------------- | |
246 | ||
247 | Syntax:: | |
b6c37eba | 248 | |
b6c37eba MA |
249 | TYPE-REF = STRING | ARRAY-TYPE |
250 | ARRAY-TYPE = [ STRING ] | |
251 | ||
252 | A string denotes the type named by the string. | |
253 | ||
254 | A one-element array containing a string denotes an array of the type | |
55927c5f | 255 | named by the string. Example: ``['int']`` denotes an array of ``int``. |
b6c37eba | 256 | |
f5821f52 | 257 | |
f7aa076d JS |
258 | Struct types |
259 | ------------ | |
260 | ||
261 | Syntax:: | |
51631493 | 262 | |
b6c37eba MA |
263 | STRUCT = { 'struct': STRING, |
264 | 'data': MEMBERS, | |
265 | '*base': STRING, | |
266 | '*if': COND, | |
267 | '*features': FEATURES } | |
268 | MEMBERS = { MEMBER, ... } | |
269 | MEMBER = STRING : TYPE-REF | |
84ab0086 MA |
270 | | STRING : { 'type': TYPE-REF, |
271 | '*if': COND, | |
272 | '*features': FEATURES } | |
b6c37eba MA |
273 | |
274 | Member 'struct' names the struct type. | |
275 | ||
276 | Each MEMBER of the 'data' object defines a member of the struct type. | |
e790e666 | 277 | |
9c66762a JS |
278 | .. _MEMBERS: |
279 | ||
55927c5f JS |
280 | The MEMBER's STRING name consists of an optional ``*`` prefix and the |
281 | struct member name. If ``*`` is present, the member is optional. | |
b6c37eba MA |
282 | |
283 | The MEMBER's value defines its properties, in particular its type. | |
9c66762a | 284 | The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`. |
b6c37eba | 285 | |
f7aa076d | 286 | Example:: |
b84da831 | 287 | |
3b2a8b85 | 288 | { 'struct': 'MyType', |
b6c37eba | 289 | 'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } } |
b84da831 | 290 | |
b6c37eba MA |
291 | A struct type corresponds to a struct in C, and an object in JSON. |
292 | The C struct's members are generated in QAPI schema order. | |
cc162655 | 293 | |
b6c37eba MA |
294 | The optional 'base' member names a struct type whose members are to be |
295 | included in this type. They go first in the C struct. | |
622f557f | 296 | |
f7aa076d | 297 | Example:: |
b6c37eba MA |
298 | |
299 | { 'struct': 'BlockdevOptionsGenericFormat', | |
300 | 'data': { 'file': 'str' } } | |
3b2a8b85 | 301 | { 'struct': 'BlockdevOptionsGenericCOWFormat', |
622f557f KW |
302 | 'base': 'BlockdevOptionsGenericFormat', |
303 | 'data': { '*backing': 'str' } } | |
304 | ||
305 | An example BlockdevOptionsGenericCOWFormat object on the wire could use | |
f7aa076d | 306 | both members like this:: |
622f557f KW |
307 | |
308 | { "file": "/some/place/my-image", | |
309 | "backing": "/some/place/my-backing-file" } | |
310 | ||
9c66762a JS |
311 | The optional 'if' member specifies a conditional. See `Configuring |
312 | the schema`_ below for more on this. | |
b6c37eba | 313 | |
9c66762a | 314 | The optional 'features' member specifies features. See Features_ |
b6c37eba MA |
315 | below for more on this. |
316 | ||
e790e666 | 317 | |
f7aa076d JS |
318 | Union types |
319 | ----------- | |
320 | ||
321 | Syntax:: | |
51631493 | 322 | |
b6c37eba | 323 | UNION = { 'union': STRING, |
b6c37eba MA |
324 | 'base': ( MEMBERS | STRING ), |
325 | 'discriminator': STRING, | |
4e99f4b1 | 326 | 'data': BRANCHES, |
013b4efc MA |
327 | '*if': COND, |
328 | '*features': FEATURES } | |
b6c37eba MA |
329 | BRANCHES = { BRANCH, ... } |
330 | BRANCH = STRING : TYPE-REF | |
331 | | STRING : { 'type': TYPE-REF, '*if': COND } | |
332 | ||
333 | Member 'union' names the union type. | |
51631493 | 334 | |
4e99f4b1 MA |
335 | The 'base' member defines the common members. If it is a MEMBERS_ |
336 | object, it defines common members just like a struct type's 'data' | |
337 | member defines struct type members. If it is a STRING, it names a | |
338 | struct type whose members are the common members. | |
339 | ||
340 | Member 'discriminator' must name a non-optional enum-typed member of | |
341 | the base struct. That member's value selects a branch by its name. | |
342 | If no such branch exists, an empty branch is assumed. | |
b6c37eba MA |
343 | |
344 | Each BRANCH of the 'data' object defines a branch of the union. A | |
345 | union must have at least one branch. | |
346 | ||
4e99f4b1 MA |
347 | The BRANCH's STRING name is the branch name. It must be a value of |
348 | the discriminator enum type. | |
b6c37eba MA |
349 | |
350 | The BRANCH's value defines the branch's properties, in particular its | |
4e99f4b1 MA |
351 | type. The type must a struct type. The form TYPE-REF_ is shorthand |
352 | for :code:`{ 'type': TYPE-REF }`. | |
b6c37eba | 353 | |
4e99f4b1 MA |
354 | In the Client JSON Protocol, a union is represented by an object with |
355 | the common members (from the base type) and the selected branch's | |
356 | members. The two sets of member names must be disjoint. | |
b6c37eba | 357 | |
4e99f4b1 | 358 | Example:: |
50f2bdc7 | 359 | |
94a3f0af | 360 | { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] } |
50f2bdc7 | 361 | { 'union': 'BlockdevOptions', |
ac4338f8 | 362 | 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' }, |
50f2bdc7 | 363 | 'discriminator': 'driver', |
bd59adce EB |
364 | 'data': { 'file': 'BlockdevOptionsFile', |
365 | 'qcow2': 'BlockdevOptionsQcow2' } } | |
50f2bdc7 | 366 | |
f7aa076d | 367 | Resulting in these JSON objects:: |
e790e666 | 368 | |
bd59adce | 369 | { "driver": "file", "read-only": true, |
e790e666 | 370 | "filename": "/some/place/my-image" } |
bd59adce EB |
371 | { "driver": "qcow2", "read-only": false, |
372 | "backing": "/some/place/my-image", "lazy-refcounts": true } | |
e790e666 | 373 | |
4e99f4b1 MA |
374 | The order of branches need not match the order of the enum values. |
375 | The branches need not cover all possible enum values. In the | |
376 | resulting generated C data types, a union is represented as a struct | |
377 | with the base members in QAPI schema order, and then a union of | |
378 | structures for each branch of the struct. | |
69dd62df | 379 | |
9c66762a JS |
380 | The optional 'if' member specifies a conditional. See `Configuring |
381 | the schema`_ below for more on this. | |
b6c37eba | 382 | |
9c66762a | 383 | The optional 'features' member specifies features. See Features_ |
013b4efc MA |
384 | below for more on this. |
385 | ||
e790e666 | 386 | |
f7aa076d JS |
387 | Alternate types |
388 | --------------- | |
389 | ||
390 | Syntax:: | |
69dd62df | 391 | |
b6c37eba MA |
392 | ALTERNATE = { 'alternate': STRING, |
393 | 'data': ALTERNATIVES, | |
013b4efc MA |
394 | '*if': COND, |
395 | '*features': FEATURES } | |
b6c37eba | 396 | ALTERNATIVES = { ALTERNATIVE, ... } |
942ab686 | 397 | ALTERNATIVE = STRING : STRING |
b6c37eba MA |
398 | | STRING : { 'type': STRING, '*if': COND } |
399 | ||
400 | Member 'alternate' names the alternate type. | |
401 | ||
402 | Each ALTERNATIVE of the 'data' object defines a branch of the | |
403 | alternate. An alternate must have at least one branch. | |
7b1b98c4 | 404 | |
b6c37eba MA |
405 | The ALTERNATIVE's STRING name is the branch name. |
406 | ||
407 | The ALTERNATIVE's value defines the branch's properties, in particular | |
55927c5f | 408 | its type. The form STRING is shorthand for :code:`{ 'type': STRING }`. |
b6c37eba | 409 | |
f7aa076d | 410 | Example:: |
7b1b98c4 | 411 | |
bd59adce | 412 | { 'alternate': 'BlockdevRef', |
69dd62df KW |
413 | 'data': { 'definition': 'BlockdevOptions', |
414 | 'reference': 'str' } } | |
415 | ||
b6c37eba MA |
416 | An alternate type is like a union type, except there is no |
417 | discriminator on the wire. Instead, the branch to use is inferred | |
418 | from the value. An alternate can only express a choice between types | |
419 | represented differently on the wire. | |
420 | ||
421 | If a branch is typed as the 'bool' built-in, the alternate accepts | |
422 | true and false; if it is typed as any of the various numeric | |
363b4262 | 423 | built-ins, it accepts a JSON number; if it is typed as a 'str' |
4d2d5c41 MA |
424 | built-in or named enum type, it accepts a JSON string; if it is typed |
425 | as the 'null' built-in, it accepts JSON null; and if it is typed as a | |
b6c37eba | 426 | complex type (struct or union), it accepts a JSON object. |
7b1b98c4 EB |
427 | |
428 | The example alternate declaration above allows using both of the | |
f7aa076d | 429 | following example objects:: |
69dd62df KW |
430 | |
431 | { "file": "my_existing_block_device_id" } | |
432 | { "file": { "driver": "file", | |
bd59adce | 433 | "read-only": false, |
63922c64 | 434 | "filename": "/tmp/mydisk.qcow2" } } |
69dd62df | 435 | |
9c66762a JS |
436 | The optional 'if' member specifies a conditional. See `Configuring |
437 | the schema`_ below for more on this. | |
b6c37eba | 438 | |
9c66762a | 439 | The optional 'features' member specifies features. See Features_ |
013b4efc MA |
440 | below for more on this. |
441 | ||
69dd62df | 442 | |
f7aa076d JS |
443 | Commands |
444 | -------- | |
445 | ||
446 | Syntax:: | |
b84da831 | 447 | |
b6c37eba MA |
448 | COMMAND = { 'command': STRING, |
449 | ( | |
450 | '*data': ( MEMBERS | STRING ), | |
451 | | | |
452 | 'data': STRING, | |
453 | 'boxed': true, | |
454 | ) | |
455 | '*returns': TYPE-REF, | |
456 | '*success-response': false, | |
457 | '*gen': false, | |
458 | '*allow-oob': true, | |
459 | '*allow-preconfig': true, | |
04f22362 | 460 | '*coroutine': true, |
23394b4c PK |
461 | '*if': COND, |
462 | '*features': FEATURES } | |
b6c37eba MA |
463 | |
464 | Member 'command' names the command. | |
465 | ||
9c66762a | 466 | Member 'data' defines the arguments. It defaults to an empty MEMBERS_ |
b6c37eba MA |
467 | object. |
468 | ||
9c66762a | 469 | If 'data' is a MEMBERS_ object, then MEMBERS defines arguments just |
b6c37eba MA |
470 | like a struct type's 'data' defines struct type members. |
471 | ||
472 | If 'data' is a STRING, then STRING names a complex type whose members | |
55927c5f | 473 | are the arguments. A union type requires ``'boxed': true``. |
b6c37eba MA |
474 | |
475 | Member 'returns' defines the command's return type. It defaults to an | |
476 | empty struct type. It must normally be a complex type or an array of | |
477 | a complex type. To return anything else, the command must be listed | |
b86df374 MA |
478 | in pragma 'commands-returns-exceptions'. If you do this, extending |
479 | the command to return additional information will be harder. Use of | |
480 | the pragma for new commands is strongly discouraged. | |
363b4262 | 481 | |
b6c37eba MA |
482 | A command's error responses are not specified in the QAPI schema. |
483 | Error conditions should be documented in comments. | |
484 | ||
485 | In the Client JSON Protocol, the value of the "execute" or "exec-oob" | |
486 | member is the command name. The value of the "arguments" member then | |
487 | has to conform to the arguments, and the value of the success | |
488 | response's "return" member will conform to the return type. | |
e790e666 | 489 | |
f7aa076d | 490 | Some example commands:: |
e790e666 EB |
491 | |
492 | { 'command': 'my-first-command', | |
493 | 'data': { 'arg1': 'str', '*arg2': 'str' } } | |
3b2a8b85 | 494 | { 'struct': 'MyType', 'data': { '*value': 'str' } } |
e790e666 EB |
495 | { 'command': 'my-second-command', |
496 | 'returns': [ 'MyType' ] } | |
497 | ||
f7aa076d | 498 | which would validate this Client JSON Protocol transaction:: |
e790e666 EB |
499 | |
500 | => { "execute": "my-first-command", | |
501 | "arguments": { "arg1": "hello" } } | |
502 | <= { "return": { } } | |
503 | => { "execute": "my-second-command" } | |
504 | <= { "return": [ { "value": "one" }, { } ] } | |
505 | ||
b6c37eba MA |
506 | The generator emits a prototype for the C function implementing the |
507 | command. The function itself needs to be written by hand. See | |
9c66762a | 508 | section `Code generated for commands`_ for examples. |
b6c37eba MA |
509 | |
510 | The function returns the return type. When member 'boxed' is absent, | |
511 | it takes the command arguments as arguments one by one, in QAPI schema | |
512 | order. Else it takes them wrapped in the C struct generated for the | |
55927c5f | 513 | complex argument type. It takes an additional ``Error **`` argument in |
b6c37eba | 514 | either case. |
c818408e EB |
515 | |
516 | The generator also emits a marshalling function that extracts | |
517 | arguments for the user's function out of an input QDict, calls the | |
518 | user's function, and if it succeeded, builds an output QObject from | |
b6c37eba | 519 | its return value. This is for use by the QMP monitor core. |
c818408e | 520 | |
e790e666 | 521 | In rare cases, QAPI cannot express a type-safe representation of a |
2d21291a | 522 | corresponding Client JSON Protocol command. You then have to suppress |
b6c37eba | 523 | generation of a marshalling function by including a member 'gen' with |
153d73f3 | 524 | boolean value false, and instead write your own function. For |
f7aa076d | 525 | example:: |
e790e666 EB |
526 | |
527 | { 'command': 'netdev_add', | |
b8a98326 | 528 | 'data': {'type': 'str', 'id': 'str'}, |
e790e666 EB |
529 | 'gen': false } |
530 | ||
153d73f3 MA |
531 | Please try to avoid adding new commands that rely on this, and instead |
532 | use type-safe unions. | |
533 | ||
e790e666 EB |
534 | Normally, the QAPI schema is used to describe synchronous exchanges, |
535 | where a response is expected. But in some cases, the action of a | |
536 | command is expected to change state in a way that a successful | |
b6c37eba MA |
537 | response is not possible (although the command will still return an |
538 | error object on failure). When a successful reply is not possible, | |
539 | the command definition includes the optional member 'success-response' | |
540 | with boolean value false. So far, only QGA makes use of this member. | |
b84da831 | 541 | |
b6c37eba | 542 | Member 'allow-oob' declares whether the command supports out-of-band |
f7aa076d | 543 | (OOB) execution. It defaults to false. For example:: |
378112b0 PX |
544 | |
545 | { 'command': 'migrate_recover', | |
546 | 'data': { 'uri': 'str' }, 'allow-oob': true } | |
547 | ||
153d73f3 | 548 | See qmp-spec.txt for out-of-band execution syntax and semantics. |
378112b0 | 549 | |
153d73f3 MA |
550 | Commands supporting out-of-band execution can still be executed |
551 | in-band. | |
378112b0 | 552 | |
153d73f3 MA |
553 | When a command is executed in-band, its handler runs in the main |
554 | thread with the BQL held. | |
378112b0 | 555 | |
153d73f3 MA |
556 | When a command is executed out-of-band, its handler runs in a |
557 | dedicated monitor I/O thread with the BQL *not* held. | |
378112b0 | 558 | |
153d73f3 | 559 | An OOB-capable command handler must satisfy the following conditions: |
378112b0 | 560 | |
153d73f3 MA |
561 | - It terminates quickly. |
562 | - It does not invoke system calls that may block. | |
378112b0 | 563 | - It does not access guest RAM that may block when userfaultfd is |
153d73f3 | 564 | enabled for postcopy live migration. |
4bfa7974 PX |
565 | - It takes only "fast" locks, i.e. all critical sections protected by |
566 | any lock it takes also satisfy the conditions for OOB command | |
567 | handler code. | |
568 | ||
569 | The restrictions on locking limit access to shared state. Such access | |
570 | requires synchronization, but OOB commands can't take the BQL or any | |
571 | other "slow" lock. | |
378112b0 | 572 | |
153d73f3 | 573 | When in doubt, do not implement OOB execution support. |
b84da831 | 574 | |
b6c37eba | 575 | Member 'allow-preconfig' declares whether the command is available |
f7aa076d | 576 | before the machine is built. It defaults to false. For example:: |
d6fe3d02 | 577 | |
c4cdf54c MA |
578 | { 'enum': 'QMPCapability', |
579 | 'data': [ 'oob' ] } | |
d6fe3d02 IM |
580 | { 'command': 'qmp_capabilities', |
581 | 'data': { '*enable': [ 'QMPCapability' ] }, | |
582 | 'allow-preconfig': true } | |
583 | ||
153d73f3 MA |
584 | QMP is available before the machine is built only when QEMU was |
585 | started with --preconfig. | |
586 | ||
04f22362 KW |
587 | Member 'coroutine' tells the QMP dispatcher whether the command handler |
588 | is safe to be run in a coroutine. It defaults to false. If it is true, | |
589 | the command handler is called from coroutine context and may yield while | |
590 | waiting for an external event (such as I/O completion) in order to avoid | |
591 | blocking the guest and other background operations. | |
592 | ||
593 | Coroutine safety can be hard to prove, similar to thread safety. Common | |
594 | pitfalls are: | |
595 | ||
55927c5f | 596 | - The global mutex isn't held across ``qemu_coroutine_yield()``, so |
04f22362 KW |
597 | operations that used to assume that they execute atomically may have |
598 | to be more careful to protect against changes in the global state. | |
599 | ||
55927c5f | 600 | - Nested event loops (``AIO_WAIT_WHILE()`` etc.) are problematic in |
04f22362 KW |
601 | coroutine context and can easily lead to deadlocks. They should be |
602 | replaced by yielding and reentering the coroutine when the condition | |
603 | becomes false. | |
604 | ||
605 | Since the command handler may assume coroutine context, any callers | |
606 | other than the QMP dispatcher must also call it in coroutine context. | |
bb4b9ead | 607 | In particular, HMP commands calling such a QMP command handler must be |
55927c5f | 608 | marked ``.coroutine = true`` in hmp-commands.hx. |
04f22362 | 609 | |
55927c5f | 610 | It is an error to specify both ``'coroutine': true`` and ``'allow-oob': true`` |
04f22362 KW |
611 | for a command. We don't currently have a use case for both together and |
612 | without a use case, it's not entirely clear what the semantics should | |
613 | be. | |
614 | ||
9c66762a JS |
615 | The optional 'if' member specifies a conditional. See `Configuring |
616 | the schema`_ below for more on this. | |
b6c37eba | 617 | |
9c66762a | 618 | The optional 'features' member specifies features. See Features_ |
013b4efc MA |
619 | below for more on this. |
620 | ||
b6c37eba | 621 | |
f7aa076d JS |
622 | Events |
623 | ------ | |
624 | ||
625 | Syntax:: | |
21cd70df | 626 | |
b6c37eba MA |
627 | EVENT = { 'event': STRING, |
628 | ( | |
629 | '*data': ( MEMBERS | STRING ), | |
630 | | | |
631 | 'data': STRING, | |
632 | 'boxed': true, | |
633 | ) | |
013b4efc MA |
634 | '*if': COND, |
635 | '*features': FEATURES } | |
b6c37eba MA |
636 | |
637 | Member 'event' names the event. This is the event name used in the | |
638 | Client JSON Protocol. | |
639 | ||
640 | Member 'data' defines the event-specific data. It defaults to an | |
641 | empty MEMBERS object. | |
642 | ||
643 | If 'data' is a MEMBERS object, then MEMBERS defines event-specific | |
644 | data just like a struct type's 'data' defines struct type members. | |
e790e666 | 645 | |
b6c37eba | 646 | If 'data' is a STRING, then STRING names a complex type whose members |
55927c5f | 647 | are the event-specific data. A union type requires ``'boxed': true``. |
21cd70df | 648 | |
f7aa076d | 649 | An example event is:: |
21cd70df | 650 | |
f7aa076d JS |
651 | { 'event': 'EVENT_C', |
652 | 'data': { '*a': 'int', 'b': 'str' } } | |
21cd70df | 653 | |
f7aa076d | 654 | Resulting in this JSON object:: |
21cd70df | 655 | |
f7aa076d JS |
656 | { "event": "EVENT_C", |
657 | "data": { "b": "test string" }, | |
658 | "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } | |
b84da831 | 659 | |
b6c37eba MA |
660 | The generator emits a function to send the event. When member 'boxed' |
661 | is absent, it takes event-specific data one by one, in QAPI schema | |
662 | order. Else it takes them wrapped in the C struct generated for the | |
9c66762a | 663 | complex type. See section `Code generated for events`_ for examples. |
b6c37eba | 664 | |
9c66762a JS |
665 | The optional 'if' member specifies a conditional. See `Configuring |
666 | the schema`_ below for more on this. | |
c818408e | 667 | |
9c66762a | 668 | The optional 'features' member specifies features. See Features_ |
013b4efc MA |
669 | below for more on this. |
670 | ||
59a2c4ce | 671 | |
9c66762a JS |
672 | .. _FEATURE: |
673 | ||
f7aa076d JS |
674 | Features |
675 | -------- | |
676 | ||
677 | Syntax:: | |
6a8c0b51 | 678 | |
b6c37eba MA |
679 | FEATURES = [ FEATURE, ... ] |
680 | FEATURE = STRING | |
681 | | { 'name': STRING, '*if': COND } | |
682 | ||
6a8c0b51 | 683 | Sometimes, the behaviour of QEMU changes compatibly, but without a |
b6c37eba MA |
684 | change in the QMP syntax (usually by allowing values or operations |
685 | that previously resulted in an error). QMP clients may still need to | |
686 | know whether the extension is available. | |
6a8c0b51 | 687 | |
23394b4c | 688 | For this purpose, a list of features can be specified for a command or |
f7aa076d JS |
689 | struct type. Each list member can either be ``{ 'name': STRING, '*if': |
690 | COND }``, or STRING, which is shorthand for ``{ 'name': STRING }``. | |
6a8c0b51 | 691 | |
9c66762a JS |
692 | The optional 'if' member specifies a conditional. See `Configuring |
693 | the schema`_ below for more on this. | |
6a8c0b51 | 694 | |
f7aa076d | 695 | Example:: |
6a8c0b51 | 696 | |
f7aa076d JS |
697 | { 'struct': 'TestType', |
698 | 'data': { 'number': 'int' }, | |
699 | 'features': [ 'allow-negative-numbers' ] } | |
6a8c0b51 | 700 | |
86014c64 | 701 | The feature strings are exposed to clients in introspection, as |
9c66762a | 702 | explained in section `Client JSON Protocol introspection`_. |
86014c64 MA |
703 | |
704 | Intended use is to have each feature string signal that this build of | |
705 | QEMU shows a certain behaviour. | |
706 | ||
6a8c0b51 | 707 | |
f7aa076d JS |
708 | Special features |
709 | ~~~~~~~~~~~~~~~~ | |
f965e8fe | 710 | |
b6c18755 MA |
711 | Feature "deprecated" marks a command, event, enum value, or struct |
712 | member as deprecated. It is not supported elsewhere so far. | |
713 | Interfaces so marked may be withdrawn in future releases in accordance | |
714 | with QEMU's deprecation policy. | |
f965e8fe | 715 | |
a3c45b3e MA |
716 | Feature "unstable" marks a command, event, enum value, or struct |
717 | member as unstable. It is not supported elsewhere so far. Interfaces | |
718 | so marked may be withdrawn or changed incompatibly in future releases. | |
719 | ||
f965e8fe | 720 | |
f7aa076d JS |
721 | Naming rules and reserved names |
722 | ------------------------------- | |
f5821f52 MA |
723 | |
724 | All names must begin with a letter, and contain only ASCII letters, | |
725 | digits, hyphen, and underscore. There are two exceptions: enum values | |
726 | may start with a digit, and names that are downstream extensions (see | |
9c66762a | 727 | section `Downstream extensions`_) start with underscore. |
f5821f52 | 728 | |
55927c5f | 729 | Names beginning with ``q_`` are reserved for the generator, which uses |
f5821f52 | 730 | them for munging QMP names that resemble C keywords or other |
55927c5f JS |
731 | problematic strings. For example, a member named ``default`` in qapi |
732 | becomes ``q_default`` in the generated C code. | |
f5821f52 MA |
733 | |
734 | Types, commands, and events share a common namespace. Therefore, | |
735 | generally speaking, type definitions should always use CamelCase for | |
736 | user-defined type names, while built-in types are lowercase. | |
737 | ||
55927c5f | 738 | Type names ending with ``Kind`` or ``List`` are reserved for the |
f5821f52 MA |
739 | generator, which uses them for implicit union enums and array types, |
740 | respectively. | |
741 | ||
742 | Command names, and member names within a type, should be all lower | |
743 | case with words separated by a hyphen. However, some existing older | |
b6c37eba MA |
744 | commands and complex types use underscore; when extending them, |
745 | consistency is preferred over blindly avoiding underscore. | |
f5821f52 MA |
746 | |
747 | Event names should be ALL_CAPS with words separated by underscore. | |
748 | ||
55927c5f | 749 | Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved |
f5821f52 MA |
750 | for the generator, which uses them for unions and for tracking |
751 | optional members. | |
752 | ||
a3c45b3e MA |
753 | Names beginning with ``x-`` used to signify "experimental". This |
754 | convention has been replaced by special feature "unstable". | |
f5821f52 | 755 | |
9c66762a JS |
756 | Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let |
757 | you violate naming rules. Use for new code is strongly discouraged. See | |
758 | `Pragma directives`_ for details. | |
f5821f52 MA |
759 | |
760 | ||
f7aa076d JS |
761 | Downstream extensions |
762 | --------------------- | |
79f75981 MA |
763 | |
764 | QAPI schema names that are externally visible, say in the Client JSON | |
765 | Protocol, need to be managed with care. Names starting with a | |
766 | downstream prefix of the form __RFQDN_ are reserved for the downstream | |
767 | who controls the valid, reverse fully qualified domain name RFQDN. | |
768 | RFQDN may only contain ASCII letters, digits, hyphen and period. | |
769 | ||
770 | Example: Red Hat, Inc. controls redhat.com, and may therefore add a | |
55927c5f | 771 | downstream command ``__com.redhat_drive-mirror``. |
79f75981 MA |
772 | |
773 | ||
f7aa076d JS |
774 | Configuring the schema |
775 | ---------------------- | |
776 | ||
777 | Syntax:: | |
967c8851 | 778 | |
b6c37eba | 779 | COND = STRING |
3248c1aa MAL |
780 | | { 'all: [ COND, ... ] } |
781 | | { 'any: [ COND, ... ] } | |
782 | | { 'not': COND } | |
b6c37eba MA |
783 | |
784 | All definitions take an optional 'if' member. Its value must be a | |
3248c1aa MAL |
785 | string, or an object with a single member 'all', 'any' or 'not'. |
786 | ||
787 | The C code generated for the definition will then be guarded by an #if | |
788 | preprocessing directive with an operand generated from that condition: | |
789 | ||
790 | * STRING will generate defined(STRING) | |
791 | * { 'all': [COND, ...] } will generate (COND && ...) | |
792 | * { 'any': [COND, ...] } will generate (COND || ...) | |
793 | * { 'not': COND } will generate !COND | |
967c8851 | 794 | |
f7aa076d | 795 | Example: a conditional struct :: |
967c8851 MAL |
796 | |
797 | { 'struct': 'IfStruct', 'data': { 'foo': 'int' }, | |
3248c1aa | 798 | 'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } } |
967c8851 | 799 | |
f7aa076d | 800 | gets its generated code guarded like this:: |
967c8851 | 801 | |
3248c1aa | 802 | #if defined(CONFIG_FOO) && defined(HAVE_BAR) |
967c8851 | 803 | ... generated code ... |
3248c1aa | 804 | #endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */ |
967c8851 | 805 | |
b6c37eba MA |
806 | Individual members of complex types, commands arguments, and |
807 | event-specific data can also be made conditional. This requires the | |
808 | longhand form of MEMBER. | |
ccadd6bc | 809 | |
b6c37eba | 810 | Example: a struct type with unconditional member 'foo' and conditional |
f7aa076d | 811 | member 'bar' :: |
ccadd6bc | 812 | |
4cfd6537 MA |
813 | { 'struct': 'IfStruct', |
814 | 'data': { 'foo': 'int', | |
815 | 'bar': { 'type': 'int', 'if': 'IFCOND'} } } | |
ccadd6bc | 816 | |
b6c37eba | 817 | A union's discriminator may not be conditional. |
6cc32b0e | 818 | |
b6c37eba | 819 | Likewise, individual enumeration values be conditional. This requires |
9c66762a | 820 | the longhand form of ENUM-VALUE_. |
b6c37eba MA |
821 | |
822 | Example: an enum type with unconditional value 'foo' and conditional | |
f7aa076d | 823 | value 'bar' :: |
6cc32b0e | 824 | |
4cfd6537 MA |
825 | { 'enum': 'IfEnum', |
826 | 'data': [ 'foo', | |
827 | { 'name' : 'bar', 'if': 'IFCOND' } ] } | |
6cc32b0e | 828 | |
b6c37eba | 829 | Likewise, features can be conditional. This requires the longhand |
9c66762a | 830 | form of FEATURE_. |
6a8c0b51 | 831 | |
f7aa076d | 832 | Example: a struct with conditional feature 'allow-negative-numbers' :: |
6a8c0b51 | 833 | |
f7aa076d JS |
834 | { 'struct': 'TestType', |
835 | 'data': { 'number': 'int' }, | |
836 | 'features': [ { 'name': 'allow-negative-numbers', | |
3248c1aa | 837 | 'if': 'IFCOND' } ] } |
6a8c0b51 | 838 | |
967c8851 MAL |
839 | Please note that you are responsible to ensure that the C code will |
840 | compile with an arbitrary combination of conditions, since the | |
b6c37eba | 841 | generator is unable to check it at this point. |
967c8851 | 842 | |
b6c37eba MA |
843 | The conditions apply to introspection as well, i.e. introspection |
844 | shows a conditional entity only when the condition is satisfied in | |
845 | this particular build. | |
967c8851 MAL |
846 | |
847 | ||
f7aa076d JS |
848 | Documentation comments |
849 | ---------------------- | |
f5821f52 | 850 | |
55927c5f | 851 | A multi-line comment that starts and ends with a ``##`` line is a |
b6c37eba MA |
852 | documentation comment. |
853 | ||
f7aa076d | 854 | If the documentation comment starts like :: |
b6c37eba MA |
855 | |
856 | ## | |
857 | # @SYMBOL: | |
858 | ||
55927c5f | 859 | it documents the definition of SYMBOL, else it's free-form |
b6c37eba MA |
860 | documentation. |
861 | ||
9c66762a | 862 | See below for more on `Definition documentation`_. |
b6c37eba MA |
863 | |
864 | Free-form documentation may be used to provide additional text and | |
865 | structuring content. | |
f5821f52 | 866 | |
f7aa076d JS |
867 | |
868 | Headings and subheadings | |
869 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
f5821f52 | 870 | |
55ec69f8 | 871 | A free-form documentation comment containing a line which starts with |
55927c5f | 872 | some ``=`` symbols and then a space defines a section heading:: |
f5821f52 | 873 | |
55ec69f8 PM |
874 | ## |
875 | # = This is a top level heading | |
876 | # | |
877 | # This is a free-form comment which will go under the | |
878 | # top level heading. | |
879 | ## | |
f5821f52 | 880 | |
55ec69f8 PM |
881 | ## |
882 | # == This is a second level heading | |
883 | ## | |
f5821f52 | 884 | |
55ec69f8 PM |
885 | A heading line must be the first line of the documentation |
886 | comment block. | |
f5821f52 | 887 | |
55ec69f8 PM |
888 | Section headings must always be correctly nested, so you can only |
889 | define a third-level heading inside a second-level heading, and so on. | |
f5821f52 | 890 | |
f7aa076d JS |
891 | |
892 | Documentation markup | |
893 | ~~~~~~~~~~~~~~~~~~~~ | |
d98884b7 | 894 | |
55ec69f8 | 895 | Documentation comments can use most rST markup. In particular, |
55927c5f | 896 | a ``::`` literal block can be used for examples:: |
f5821f52 | 897 | |
55ec69f8 PM |
898 | # :: |
899 | # | |
900 | # Text of the example, may span | |
901 | # multiple lines | |
f5821f52 | 902 | |
55927c5f | 903 | ``*`` starts an itemized list:: |
f5821f52 MA |
904 | |
905 | # * First item, may span | |
906 | # multiple lines | |
907 | # * Second item | |
908 | ||
55927c5f | 909 | You can also use ``-`` instead of ``*``. |
f5821f52 | 910 | |
55927c5f | 911 | A decimal number followed by ``.`` starts a numbered list:: |
f5821f52 MA |
912 | |
913 | # 1. First item, may span | |
914 | # multiple lines | |
915 | # 2. Second item | |
916 | ||
55ec69f8 | 917 | The actual number doesn't matter. |
f5821f52 | 918 | |
55ec69f8 PM |
919 | Lists of either kind must be preceded and followed by a blank line. |
920 | If a list item's text spans multiple lines, then the second and | |
921 | subsequent lines must be correctly indented to line up with the | |
922 | first character of the first line. | |
f5821f52 | 923 | |
55927c5f JS |
924 | The usual ****strong****, *\*emphasized\** and ````literal```` markup |
925 | should be used. If you need a single literal ``*``, you will need to | |
55ec69f8 | 926 | backslash-escape it. As an extension beyond the usual rST syntax, you |
55927c5f JS |
927 | can also use ``@foo`` to reference a name in the schema; this is rendered |
928 | the same way as ````foo````. | |
f5821f52 | 929 | |
f7aa076d | 930 | Example:: |
f5821f52 | 931 | |
f7aa076d JS |
932 | ## |
933 | # Some text foo with **bold** and *emphasis* | |
934 | # 1. with a list | |
935 | # 2. like that | |
936 | # | |
937 | # And some code: | |
938 | # | |
939 | # :: | |
940 | # | |
941 | # $ echo foo | |
942 | # -> do this | |
943 | # <- get that | |
944 | ## | |
f5821f52 MA |
945 | |
946 | ||
f7aa076d JS |
947 | Definition documentation |
948 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
f5821f52 | 949 | |
b6c37eba MA |
950 | Definition documentation, if present, must immediately precede the |
951 | definition it documents. | |
f5821f52 | 952 | |
9c66762a | 953 | When documentation is required (see pragma_ 'doc-required'), every |
b6c37eba | 954 | definition must have documentation. |
f5821f52 | 955 | |
b6c37eba MA |
956 | Definition documentation starts with a line naming the definition, |
957 | followed by an optional overview, a description of each argument (for | |
958 | commands and events), member (for structs and unions), branch (for | |
53e9e547 MA |
959 | alternates), or value (for enums), a description of each feature (if |
960 | any), and finally optional tagged sections. | |
f5821f52 | 961 | |
53e9e547 MA |
962 | The description of an argument or feature 'name' starts with |
963 | '\@name:'. The description text can start on the line following the | |
964 | '\@name:', in which case it must not be indented at all. It can also | |
965 | start on the same line as the '\@name:'. In this case if it spans | |
966 | multiple lines then second and subsequent lines must be indented to | |
967 | line up with the first character of the first line of the | |
968 | description:: | |
a69a6d4b | 969 | |
f7aa076d JS |
970 | # @argone: |
971 | # This is a two line description | |
972 | # in the first style. | |
973 | # | |
974 | # @argtwo: This is a two line description | |
975 | # in the second style. | |
a69a6d4b PM |
976 | |
977 | The number of spaces between the ':' and the text is not significant. | |
978 | ||
55927c5f JS |
979 | .. admonition:: FIXME |
980 | ||
981 | The parser accepts these things in almost any order. | |
982 | ||
983 | .. admonition:: FIXME | |
984 | ||
985 | union branches should be described, too. | |
f5821f52 | 986 | |
b6c37eba | 987 | Extensions added after the definition was first released carry a |
f5821f52 MA |
988 | '(since x.y.z)' comment. |
989 | ||
53e9e547 MA |
990 | The feature descriptions must be preceded by a line "Features:", like |
991 | this:: | |
992 | ||
993 | # Features: | |
994 | # @feature: Description text | |
995 | ||
f5821f52 MA |
996 | A tagged section starts with one of the following words: |
997 | "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". | |
998 | The section ends with the start of a new section. | |
999 | ||
a69a6d4b PM |
1000 | The text of a section can start on a new line, in |
1001 | which case it must not be indented at all. It can also start | |
1002 | on the same line as the 'Note:', 'Returns:', etc tag. In this | |
1003 | case if it spans multiple lines then second and subsequent | |
1004 | lines must be indented to match the first, in the same way as | |
1005 | multiline argument descriptions. | |
1006 | ||
f5821f52 | 1007 | A 'Since: x.y.z' tagged section lists the release that introduced the |
b6c37eba | 1008 | definition. |
f5821f52 | 1009 | |
55ec69f8 PM |
1010 | An 'Example' or 'Examples' section is automatically rendered |
1011 | entirely as literal fixed-width text. In other sections, | |
1012 | the text is formatted, and rST markup can be used. | |
1013 | ||
f7aa076d JS |
1014 | For example:: |
1015 | ||
1016 | ## | |
1017 | # @BlockStats: | |
1018 | # | |
1019 | # Statistics of a virtual block device or a block backing device. | |
1020 | # | |
1021 | # @device: If the stats are for a virtual block device, the name | |
1022 | # corresponding to the virtual block device. | |
1023 | # | |
1024 | # @node-name: The node name of the device. (since 2.3) | |
1025 | # | |
1026 | # ... more members ... | |
1027 | # | |
1028 | # Since: 0.14.0 | |
1029 | ## | |
1030 | { 'struct': 'BlockStats', | |
1031 | 'data': {'*device': 'str', '*node-name': 'str', | |
1032 | ... more members ... } } | |
1033 | ||
1034 | ## | |
1035 | # @query-blockstats: | |
1036 | # | |
1037 | # Query the @BlockStats for all virtual block devices. | |
1038 | # | |
1039 | # @query-nodes: If true, the command will query all the | |
1040 | # block nodes ... explain, explain ... (since 2.3) | |
1041 | # | |
1042 | # Returns: A list of @BlockStats for each virtual block devices. | |
1043 | # | |
1044 | # Since: 0.14.0 | |
1045 | # | |
1046 | # Example: | |
1047 | # | |
1048 | # -> { "execute": "query-blockstats" } | |
1049 | # <- { | |
1050 | # ... lots of output ... | |
1051 | # } | |
1052 | # | |
1053 | ## | |
1054 | { 'command': 'query-blockstats', | |
1055 | 'data': { '*query-nodes': 'bool' }, | |
1056 | 'returns': ['BlockStats'] } | |
1057 | ||
1058 | ||
1059 | Client JSON Protocol introspection | |
1060 | ================================== | |
39a18158 MA |
1061 | |
1062 | Clients of a Client JSON Protocol commonly need to figure out what | |
1063 | exactly the server (QEMU) supports. | |
1064 | ||
1065 | For this purpose, QMP provides introspection via command | |
1066 | query-qmp-schema. QGA currently doesn't support introspection. | |
1067 | ||
39a65e2c EB |
1068 | While Client JSON Protocol wire compatibility should be maintained |
1069 | between qemu versions, we cannot make the same guarantees for | |
1070 | introspection stability. For example, one version of qemu may provide | |
1071 | a non-variant optional member of a struct, and a later version rework | |
1072 | the member to instead be non-optional and associated with a variant. | |
1073 | Likewise, one version of qemu may list a member with open-ended type | |
1074 | 'str', and a later version could convert it to a finite set of strings | |
1075 | via an enum type; or a member may be converted from a specific type to | |
1076 | an alternate that represents a choice between the original type and | |
1077 | something else. | |
1078 | ||
39a18158 MA |
1079 | query-qmp-schema returns a JSON array of SchemaInfo objects. These |
1080 | objects together describe the wire ABI, as defined in the QAPI schema. | |
f5455044 EB |
1081 | There is no specified order to the SchemaInfo objects returned; a |
1082 | client must search for a particular name throughout the entire array | |
1083 | to learn more about that name, but is at least guaranteed that there | |
1084 | will be no collisions between type, command, and event names. | |
39a18158 MA |
1085 | |
1086 | However, the SchemaInfo can't reflect all the rules and restrictions | |
1087 | that apply to QMP. It's interface introspection (figuring out what's | |
1088 | there), not interface specification. The specification is in the QAPI | |
1089 | schema. To understand how QMP is to be used, you need to study the | |
1090 | QAPI schema. | |
1091 | ||
1092 | Like any other command, query-qmp-schema is itself defined in the QAPI | |
1093 | schema, along with the SchemaInfo type. This text attempts to give an | |
1094 | overview how things work. For details you need to consult the QAPI | |
1095 | schema. | |
1096 | ||
013b4efc MA |
1097 | SchemaInfo objects have common members "name", "meta-type", |
1098 | "features", and additional variant members depending on the value of | |
1099 | meta-type. | |
39a18158 MA |
1100 | |
1101 | Each SchemaInfo object describes a wire ABI entity of a certain | |
1102 | meta-type: a command, event or one of several kinds of type. | |
1103 | ||
1a9a507b MA |
1104 | SchemaInfo for commands and events have the same name as in the QAPI |
1105 | schema. | |
39a18158 MA |
1106 | |
1107 | Command and event names are part of the wire ABI, but type names are | |
1a9a507b MA |
1108 | not. Therefore, the SchemaInfo for types have auto-generated |
1109 | meaningless names. For readability, the examples in this section use | |
1110 | meaningful type names instead. | |
1111 | ||
013b4efc MA |
1112 | Optional member "features" exposes the entity's feature strings as a |
1113 | JSON array of strings. | |
1114 | ||
1a9a507b MA |
1115 | To examine a type, start with a command or event using it, then follow |
1116 | references by name. | |
39a18158 MA |
1117 | |
1118 | QAPI schema definitions not reachable that way are omitted. | |
1119 | ||
1120 | The SchemaInfo for a command has meta-type "command", and variant | |
013b4efc MA |
1121 | members "arg-type", "ret-type" and "allow-oob". On the wire, the |
1122 | "arguments" member of a client's "execute" command must conform to the | |
1123 | object type named by "arg-type". The "return" member that the server | |
1124 | passes in a success response conforms to the type named by "ret-type". | |
1125 | When "allow-oob" is true, it means the command supports out-of-band | |
1126 | execution. It defaults to false. | |
39a18158 MA |
1127 | |
1128 | If the command takes no arguments, "arg-type" names an object type | |
1129 | without members. Likewise, if the command returns nothing, "ret-type" | |
1130 | names an object type without members. | |
1131 | ||
f7aa076d | 1132 | Example: the SchemaInfo for command query-qmp-schema :: |
39a18158 | 1133 | |
f7aa076d JS |
1134 | { "name": "query-qmp-schema", "meta-type": "command", |
1135 | "arg-type": "q_empty", "ret-type": "SchemaInfoList" } | |
39a18158 | 1136 | |
f7aa076d JS |
1137 | Type "q_empty" is an automatic object type without members, and type |
1138 | "SchemaInfoList" is the array of SchemaInfo type. | |
39a18158 MA |
1139 | |
1140 | The SchemaInfo for an event has meta-type "event", and variant member | |
1141 | "arg-type". On the wire, a "data" member that the server passes in an | |
1142 | event conforms to the object type named by "arg-type". | |
1143 | ||
1144 | If the event carries no additional information, "arg-type" names an | |
1145 | object type without members. The event may not have a data member on | |
1146 | the wire then. | |
1147 | ||
b6c37eba | 1148 | Each command or event defined with 'data' as MEMBERS object in the |
1a9a507b | 1149 | QAPI schema implicitly defines an object type. |
39a18158 | 1150 | |
9c66762a | 1151 | Example: the SchemaInfo for EVENT_C from section Events_ :: |
39a18158 MA |
1152 | |
1153 | { "name": "EVENT_C", "meta-type": "event", | |
7599697c | 1154 | "arg-type": "q_obj-EVENT_C-arg" } |
39a18158 | 1155 | |
7599697c | 1156 | Type "q_obj-EVENT_C-arg" is an implicitly defined object type with |
39a18158 MA |
1157 | the two members from the event's definition. |
1158 | ||
1159 | The SchemaInfo for struct and union types has meta-type "object". | |
1160 | ||
013b4efc | 1161 | The SchemaInfo for a struct type has variant member "members". |
39a18158 MA |
1162 | |
1163 | The SchemaInfo for a union type additionally has variant members "tag" | |
1164 | and "variants". | |
1165 | ||
1166 | "members" is a JSON array describing the object's common members, if | |
1167 | any. Each element is a JSON object with members "name" (the member's | |
b6c18755 MA |
1168 | name), "type" (the name of its type), "features" (a JSON array of |
1169 | feature strings), and "default". The latter two are optional. The | |
39a18158 MA |
1170 | member is optional if "default" is present. Currently, "default" can |
1171 | only have value null. Other values are reserved for future | |
f5455044 EB |
1172 | extensions. The "members" array is in no particular order; clients |
1173 | must search the entire object when learning whether a particular | |
1174 | member is supported. | |
39a18158 | 1175 | |
9c66762a | 1176 | Example: the SchemaInfo for MyType from section `Struct types`_ :: |
39a18158 MA |
1177 | |
1178 | { "name": "MyType", "meta-type": "object", | |
1179 | "members": [ | |
1180 | { "name": "member1", "type": "str" }, | |
1181 | { "name": "member2", "type": "int" }, | |
1182 | { "name": "member3", "type": "str", "default": null } ] } | |
1183 | ||
86014c64 MA |
1184 | "features" exposes the command's feature strings as a JSON array of |
1185 | strings. | |
1186 | ||
9c66762a | 1187 | Example: the SchemaInfo for TestType from section Features_:: |
86014c64 MA |
1188 | |
1189 | { "name": "TestType", "meta-type": "object", | |
1190 | "members": [ | |
1191 | { "name": "number", "type": "int" } ], | |
1192 | "features": ["allow-negative-numbers"] } | |
1193 | ||
39a18158 MA |
1194 | "tag" is the name of the common member serving as type tag. |
1195 | "variants" is a JSON array describing the object's variant members. | |
1196 | Each element is a JSON object with members "case" (the value of type | |
1197 | tag this element applies to) and "type" (the name of an object type | |
f5455044 EB |
1198 | that provides the variant members for this type tag value). The |
1199 | "variants" array is in no particular order, and is not guaranteed to | |
1200 | list cases in the same order as the corresponding "tag" enum type. | |
39a18158 | 1201 | |
4e99f4b1 | 1202 | Example: the SchemaInfo for union BlockdevOptions from section |
9c66762a | 1203 | `Union types`_ :: |
39a18158 MA |
1204 | |
1205 | { "name": "BlockdevOptions", "meta-type": "object", | |
1206 | "members": [ | |
1207 | { "name": "driver", "type": "BlockdevDriver" }, | |
bd59adce | 1208 | { "name": "read-only", "type": "bool", "default": null } ], |
39a18158 MA |
1209 | "tag": "driver", |
1210 | "variants": [ | |
bd59adce EB |
1211 | { "case": "file", "type": "BlockdevOptionsFile" }, |
1212 | { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] } | |
39a18158 MA |
1213 | |
1214 | Note that base types are "flattened": its members are included in the | |
1215 | "members" array. | |
1216 | ||
39a18158 MA |
1217 | The SchemaInfo for an alternate type has meta-type "alternate", and |
1218 | variant member "members". "members" is a JSON array. Each element is | |
1219 | a JSON object with member "type", which names a type. Values of the | |
f5455044 EB |
1220 | alternate type conform to exactly one of its member types. There is |
1221 | no guarantee on the order in which "members" will be listed. | |
39a18158 | 1222 | |
9c66762a | 1223 | Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ :: |
39a18158 | 1224 | |
bd59adce | 1225 | { "name": "BlockdevRef", "meta-type": "alternate", |
39a18158 MA |
1226 | "members": [ |
1227 | { "type": "BlockdevOptions" }, | |
1228 | { "type": "str" } ] } | |
1229 | ||
1230 | The SchemaInfo for an array type has meta-type "array", and variant | |
1231 | member "element-type", which names the array's element type. Array | |
ce5fcb47 EB |
1232 | types are implicitly defined. For convenience, the array's name may |
1233 | resemble the element type; however, clients should examine member | |
1234 | "element-type" instead of making assumptions based on parsing member | |
1235 | "name". | |
39a18158 | 1236 | |
f7aa076d | 1237 | Example: the SchemaInfo for ['str'] :: |
39a18158 | 1238 | |
ce5fcb47 | 1239 | { "name": "[str]", "meta-type": "array", |
39a18158 MA |
1240 | "element-type": "str" } |
1241 | ||
1242 | The SchemaInfo for an enumeration type has meta-type "enum" and | |
75ecee72 MA |
1243 | variant member "members". |
1244 | ||
1245 | "members" is a JSON array describing the enumeration values. Each | |
b6c18755 MA |
1246 | element is a JSON object with member "name" (the member's name), and |
1247 | optionally "features" (a JSON array of feature strings). The | |
75ecee72 MA |
1248 | "members" array is in no particular order; clients must search the |
1249 | entire array when learning whether a particular value is supported. | |
39a18158 | 1250 | |
9c66762a | 1251 | Example: the SchemaInfo for MyEnum from section `Enumeration types`_ :: |
39a18158 MA |
1252 | |
1253 | { "name": "MyEnum", "meta-type": "enum", | |
75ecee72 MA |
1254 | "members": [ |
1255 | { "name": "value1" }, | |
1256 | { "name": "value2" }, | |
1257 | { "name": "value3" } | |
1258 | ] } | |
39a18158 MA |
1259 | |
1260 | The SchemaInfo for a built-in type has the same name as the type in | |
9c66762a | 1261 | the QAPI schema (see section `Built-in Types`_), with one exception |
39a18158 MA |
1262 | detailed below. It has variant member "json-type" that shows how |
1263 | values of this type are encoded on the wire. | |
1264 | ||
f7aa076d | 1265 | Example: the SchemaInfo for str :: |
39a18158 MA |
1266 | |
1267 | { "name": "str", "meta-type": "builtin", "json-type": "string" } | |
1268 | ||
1269 | The QAPI schema supports a number of integer types that only differ in | |
1270 | how they map to C. They are identical as far as SchemaInfo is | |
1271 | concerned. Therefore, they get all mapped to a single type "int" in | |
1272 | SchemaInfo. | |
1273 | ||
1274 | As explained above, type names are not part of the wire ABI. Not even | |
1275 | the names of built-in types. Clients should examine member | |
1276 | "json-type" instead of hard-coding names of built-in types. | |
1277 | ||
1278 | ||
f7aa076d JS |
1279 | Compatibility considerations |
1280 | ============================ | |
ab76bc27 MA |
1281 | |
1282 | Maintaining backward compatibility at the Client JSON Protocol level | |
1283 | while evolving the schema requires some care. This section is about | |
1284 | syntactic compatibility, which is necessary, but not sufficient, for | |
1285 | actual compatibility. | |
1286 | ||
1287 | Clients send commands with argument data, and receive command | |
1288 | responses with return data and events with event data. | |
1289 | ||
1290 | Adding opt-in functionality to the send direction is backwards | |
1291 | compatible: adding commands, optional arguments, enumeration values, | |
1292 | union and alternate branches; turning an argument type into an | |
1293 | alternate of that type; making mandatory arguments optional. Clients | |
1294 | oblivious of the new functionality continue to work. | |
1295 | ||
1296 | Incompatible changes include removing commands, command arguments, | |
1297 | enumeration values, union and alternate branches, adding mandatory | |
1298 | command arguments, and making optional arguments mandatory. | |
1299 | ||
1300 | The specified behavior of an absent optional argument should remain | |
1301 | the same. With proper documentation, this policy still allows some | |
1302 | flexibility; for example, when an optional 'buffer-size' argument is | |
1303 | specified to default to a sensible buffer size, the actual default | |
1304 | value can still be changed. The specified default behavior is not the | |
1305 | exact size of the buffer, only that the default size is sensible. | |
1306 | ||
1307 | Adding functionality to the receive direction is generally backwards | |
1308 | compatible: adding events, adding return and event data members. | |
1309 | Clients are expected to ignore the ones they don't know. | |
1310 | ||
1311 | Removing "unreachable" stuff like events that can't be triggered | |
1312 | anymore, optional return or event data members that can't be sent | |
1313 | anymore, and return or event data member (enumeration) values that | |
1314 | can't be sent anymore makes no difference to clients, except for | |
1315 | introspection. The latter can conceivably confuse clients, so tread | |
1316 | carefully. | |
1317 | ||
1318 | Incompatible changes include removing return and event data members. | |
1319 | ||
1320 | Any change to a command definition's 'data' or one of the types used | |
1321 | there (recursively) needs to consider send direction compatibility. | |
1322 | ||
1323 | Any change to a command definition's 'return', an event definition's | |
1324 | 'data', or one of the types used there (recursively) needs to consider | |
1325 | receive direction compatibility. | |
1326 | ||
1327 | Any change to types used in both contexts need to consider both. | |
1328 | ||
b6c37eba | 1329 | Enumeration type values and complex and alternate type members may be |
ab76bc27 MA |
1330 | reordered freely. For enumerations and alternate types, this doesn't |
1331 | affect the wire encoding. For complex types, this might make the | |
1332 | implementation emit JSON object members in a different order, which | |
1333 | the Client JSON Protocol permits. | |
1334 | ||
1335 | Since type names are not visible in the Client JSON Protocol, types | |
1336 | may be freely renamed. Even certain refactorings are invisible, such | |
1337 | as splitting members from one type into a common base type. | |
1338 | ||
1339 | ||
f7aa076d JS |
1340 | Code generation |
1341 | =============== | |
b84da831 | 1342 | |
fb0bc835 MA |
1343 | The QAPI code generator qapi-gen.py generates code and documentation |
1344 | from the schema. Together with the core QAPI libraries, this code | |
1345 | provides everything required to take JSON commands read in by a Client | |
1346 | JSON Protocol server, unmarshal the arguments into the underlying C | |
1347 | types, call into the corresponding C function, map the response back | |
1348 | to a Client JSON Protocol response to be returned to the user, and | |
1349 | introspect the commands. | |
b84da831 | 1350 | |
9ee86b85 EB |
1351 | As an example, we'll use the following schema, which describes a |
1352 | single complex user-defined type, along with command which takes a | |
1353 | list of that type as a parameter, and returns a single element of that | |
1354 | type. The user is responsible for writing the implementation of | |
f7aa076d | 1355 | qmp_my_command(); everything else is produced by the generator. :: |
b84da831 | 1356 | |
87a560c4 | 1357 | $ cat example-schema.json |
3b2a8b85 | 1358 | { 'struct': 'UserDefOne', |
9ee86b85 | 1359 | 'data': { 'integer': 'int', '*string': 'str' } } |
b84da831 MR |
1360 | |
1361 | { 'command': 'my-command', | |
9ee86b85 | 1362 | 'data': { 'arg1': ['UserDefOne'] }, |
b84da831 | 1363 | 'returns': 'UserDefOne' } |
b84da831 | 1364 | |
59a2c4ce EB |
1365 | { 'event': 'MY_EVENT' } |
1366 | ||
f7aa076d | 1367 | We run qapi-gen.py like this:: |
fb0bc835 MA |
1368 | |
1369 | $ python scripts/qapi-gen.py --output-dir="qapi-generated" \ | |
1370 | --prefix="example-" example-schema.json | |
1371 | ||
9ee86b85 EB |
1372 | For a more thorough look at generated code, the testsuite includes |
1373 | tests/qapi-schema/qapi-schema-tests.json that covers more examples of | |
1374 | what the generator will accept, and compiles the resulting C code as | |
1375 | part of 'make check-unit'. | |
1376 | ||
f7aa076d JS |
1377 | |
1378 | Code generated for QAPI types | |
1379 | ----------------------------- | |
b84da831 | 1380 | |
fb0bc835 | 1381 | The following files are created: |
b84da831 | 1382 | |
f7aa076d JS |
1383 | ``$(prefix)qapi-types.h`` |
1384 | C types corresponding to types defined in the schema | |
fb0bc835 | 1385 | |
f7aa076d JS |
1386 | ``$(prefix)qapi-types.c`` |
1387 | Cleanup functions for the above C types | |
b84da831 MR |
1388 | |
1389 | The $(prefix) is an optional parameter used as a namespace to keep the | |
1390 | generated code from one schema/code-generation separated from others so code | |
1391 | can be generated/used from multiple schemas without clobbering previously | |
1392 | created code. | |
1393 | ||
f7aa076d | 1394 | Example:: |
b84da831 | 1395 | |
9ee86b85 | 1396 | $ cat qapi-generated/example-qapi-types.h |
f7aa076d | 1397 | [Uninteresting stuff omitted...] |
9ee86b85 EB |
1398 | |
1399 | #ifndef EXAMPLE_QAPI_TYPES_H | |
1400 | #define EXAMPLE_QAPI_TYPES_H | |
1401 | ||
913b5e28 | 1402 | #include "qapi/qapi-builtin-types.h" |
9ee86b85 EB |
1403 | |
1404 | typedef struct UserDefOne UserDefOne; | |
1405 | ||
1406 | typedef struct UserDefOneList UserDefOneList; | |
1407 | ||
64355088 MA |
1408 | typedef struct q_obj_my_command_arg q_obj_my_command_arg; |
1409 | ||
9ee86b85 EB |
1410 | struct UserDefOne { |
1411 | int64_t integer; | |
1412 | bool has_string; | |
1413 | char *string; | |
1414 | }; | |
1415 | ||
1416 | void qapi_free_UserDefOne(UserDefOne *obj); | |
221db5da | 1417 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne) |
9ee86b85 EB |
1418 | |
1419 | struct UserDefOneList { | |
1420 | UserDefOneList *next; | |
1421 | UserDefOne *value; | |
1422 | }; | |
1423 | ||
1424 | void qapi_free_UserDefOneList(UserDefOneList *obj); | |
221db5da | 1425 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList) |
9ee86b85 | 1426 | |
64355088 MA |
1427 | struct q_obj_my_command_arg { |
1428 | UserDefOneList *arg1; | |
1429 | }; | |
1430 | ||
913b5e28 | 1431 | #endif /* EXAMPLE_QAPI_TYPES_H */ |
87a560c4 | 1432 | $ cat qapi-generated/example-qapi-types.c |
f7aa076d | 1433 | [Uninteresting stuff omitted...] |
6e2bb3ec | 1434 | |
2b162ccb | 1435 | void qapi_free_UserDefOne(UserDefOne *obj) |
6e2bb3ec | 1436 | { |
6e2bb3ec MA |
1437 | Visitor *v; |
1438 | ||
1439 | if (!obj) { | |
1440 | return; | |
1441 | } | |
1442 | ||
2c0ef9f4 | 1443 | v = qapi_dealloc_visitor_new(); |
9ee86b85 | 1444 | visit_type_UserDefOne(v, NULL, &obj, NULL); |
2c0ef9f4 | 1445 | visit_free(v); |
6e2bb3ec | 1446 | } |
b84da831 | 1447 | |
2b162ccb | 1448 | void qapi_free_UserDefOneList(UserDefOneList *obj) |
b84da831 | 1449 | { |
b84da831 MR |
1450 | Visitor *v; |
1451 | ||
1452 | if (!obj) { | |
1453 | return; | |
1454 | } | |
1455 | ||
2c0ef9f4 | 1456 | v = qapi_dealloc_visitor_new(); |
9ee86b85 | 1457 | visit_type_UserDefOneList(v, NULL, &obj, NULL); |
2c0ef9f4 | 1458 | visit_free(v); |
b84da831 | 1459 | } |
b84da831 | 1460 | |
f7aa076d | 1461 | [Uninteresting stuff omitted...] |
913b5e28 | 1462 | |
9c66762a | 1463 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d | 1464 | each sub-module SUBDIR/SUBMODULE.json is actually generated into :: |
ce32bf85 | 1465 | |
f7aa076d JS |
1466 | SUBDIR/$(prefix)qapi-types-SUBMODULE.h |
1467 | SUBDIR/$(prefix)qapi-types-SUBMODULE.c | |
ce32bf85 MA |
1468 | |
1469 | If qapi-gen.py is run with option --builtins, additional files are | |
1470 | created: | |
1471 | ||
f7aa076d JS |
1472 | ``qapi-builtin-types.h`` |
1473 | C types corresponding to built-in types | |
1474 | ||
1475 | ``qapi-builtin-types.c`` | |
1476 | Cleanup functions for the above C types | |
ce32bf85 | 1477 | |
ce32bf85 | 1478 | |
f7aa076d JS |
1479 | Code generated for visiting QAPI types |
1480 | -------------------------------------- | |
b84da831 | 1481 | |
fb0bc835 MA |
1482 | These are the visitor functions used to walk through and convert |
1483 | between a native QAPI C data structure and some other format (such as | |
1484 | QObject); the generated functions are named visit_type_FOO() and | |
1485 | visit_type_FOO_members(). | |
b84da831 MR |
1486 | |
1487 | The following files are generated: | |
1488 | ||
f7aa076d JS |
1489 | ``$(prefix)qapi-visit.c`` |
1490 | Visitor function for a particular C type, used to automagically | |
1491 | convert QObjects into the corresponding C type and vice-versa, as | |
1492 | well as for deallocating memory for an existing C type | |
b84da831 | 1493 | |
f7aa076d JS |
1494 | ``$(prefix)qapi-visit.h`` |
1495 | Declarations for previously mentioned visitor functions | |
b84da831 | 1496 | |
f7aa076d | 1497 | Example:: |
b84da831 | 1498 | |
9ee86b85 | 1499 | $ cat qapi-generated/example-qapi-visit.h |
f7aa076d | 1500 | [Uninteresting stuff omitted...] |
9ee86b85 EB |
1501 | |
1502 | #ifndef EXAMPLE_QAPI_VISIT_H | |
1503 | #define EXAMPLE_QAPI_VISIT_H | |
1504 | ||
913b5e28 MA |
1505 | #include "qapi/qapi-builtin-visit.h" |
1506 | #include "example-qapi-types.h" | |
1507 | ||
9ee86b85 | 1508 | |
012d4c96 | 1509 | bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp); |
e0366f9f MA |
1510 | |
1511 | bool visit_type_UserDefOne(Visitor *v, const char *name, | |
1512 | UserDefOne **obj, Error **errp); | |
1513 | ||
1514 | bool visit_type_UserDefOneList(Visitor *v, const char *name, | |
1515 | UserDefOneList **obj, Error **errp); | |
9ee86b85 | 1516 | |
012d4c96 | 1517 | bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp); |
64355088 | 1518 | |
913b5e28 | 1519 | #endif /* EXAMPLE_QAPI_VISIT_H */ |
87a560c4 | 1520 | $ cat qapi-generated/example-qapi-visit.c |
f7aa076d | 1521 | [Uninteresting stuff omitted...] |
b84da831 | 1522 | |
012d4c96 | 1523 | bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp) |
6e2bb3ec | 1524 | { |
012d4c96 MA |
1525 | if (!visit_type_int(v, "integer", &obj->integer, errp)) { |
1526 | return false; | |
297a3646 | 1527 | } |
9ee86b85 | 1528 | if (visit_optional(v, "string", &obj->has_string)) { |
012d4c96 MA |
1529 | if (!visit_type_str(v, "string", &obj->string, errp)) { |
1530 | return false; | |
9ee86b85 | 1531 | } |
297a3646 | 1532 | } |
cdd2b228 | 1533 | return true; |
6e2bb3ec | 1534 | } |
b84da831 | 1535 | |
e0366f9f MA |
1536 | bool visit_type_UserDefOne(Visitor *v, const char *name, |
1537 | UserDefOne **obj, Error **errp) | |
b84da831 | 1538 | { |
cdd2b228 | 1539 | bool ok = false; |
297a3646 | 1540 | |
012d4c96 MA |
1541 | if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) { |
1542 | return false; | |
9ee86b85 EB |
1543 | } |
1544 | if (!*obj) { | |
8e08bf4e MA |
1545 | /* incomplete */ |
1546 | assert(visit_is_dealloc(v)); | |
e0366f9f | 1547 | ok = true; |
9ee86b85 | 1548 | goto out_obj; |
6e2bb3ec | 1549 | } |
cdd2b228 | 1550 | if (!visit_type_UserDefOne_members(v, *obj, errp)) { |
15c2f669 EB |
1551 | goto out_obj; |
1552 | } | |
cdd2b228 | 1553 | ok = visit_check_struct(v, errp); |
9ee86b85 | 1554 | out_obj: |
1158bb2a | 1555 | visit_end_struct(v, (void **)obj); |
cdd2b228 | 1556 | if (!ok && visit_is_input(v)) { |
68ab47e4 EB |
1557 | qapi_free_UserDefOne(*obj); |
1558 | *obj = NULL; | |
1559 | } | |
cdd2b228 | 1560 | return ok; |
b84da831 MR |
1561 | } |
1562 | ||
e0366f9f MA |
1563 | bool visit_type_UserDefOneList(Visitor *v, const char *name, |
1564 | UserDefOneList **obj, Error **errp) | |
b84da831 | 1565 | { |
cdd2b228 | 1566 | bool ok = false; |
d9f62dde EB |
1567 | UserDefOneList *tail; |
1568 | size_t size = sizeof(**obj); | |
6e2bb3ec | 1569 | |
012d4c96 MA |
1570 | if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) { |
1571 | return false; | |
297a3646 MA |
1572 | } |
1573 | ||
d9f62dde EB |
1574 | for (tail = *obj; tail; |
1575 | tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) { | |
cdd2b228 MA |
1576 | if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) { |
1577 | goto out_obj; | |
d9f62dde | 1578 | } |
b84da831 | 1579 | } |
297a3646 | 1580 | |
cdd2b228 MA |
1581 | ok = visit_check_list(v, errp); |
1582 | out_obj: | |
1158bb2a | 1583 | visit_end_list(v, (void **)obj); |
cdd2b228 | 1584 | if (!ok && visit_is_input(v)) { |
68ab47e4 EB |
1585 | qapi_free_UserDefOneList(*obj); |
1586 | *obj = NULL; | |
1587 | } | |
cdd2b228 | 1588 | return ok; |
b84da831 | 1589 | } |
b84da831 | 1590 | |
012d4c96 | 1591 | bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp) |
64355088 | 1592 | { |
012d4c96 MA |
1593 | if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) { |
1594 | return false; | |
64355088 | 1595 | } |
cdd2b228 | 1596 | return true; |
64355088 MA |
1597 | } |
1598 | ||
f7aa076d | 1599 | [Uninteresting stuff omitted...] |
913b5e28 | 1600 | |
9c66762a | 1601 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d | 1602 | each sub-module SUBDIR/SUBMODULE.json is actually generated into :: |
ce32bf85 | 1603 | |
f7aa076d JS |
1604 | SUBDIR/$(prefix)qapi-visit-SUBMODULE.h |
1605 | SUBDIR/$(prefix)qapi-visit-SUBMODULE.c | |
ce32bf85 MA |
1606 | |
1607 | If qapi-gen.py is run with option --builtins, additional files are | |
1608 | created: | |
1609 | ||
f7aa076d JS |
1610 | ``qapi-builtin-visit.h`` |
1611 | Visitor functions for built-in types | |
1612 | ||
1613 | ``qapi-builtin-visit.c`` | |
1614 | Declarations for these visitor functions | |
ce32bf85 | 1615 | |
ce32bf85 | 1616 | |
f7aa076d JS |
1617 | Code generated for commands |
1618 | --------------------------- | |
fb0bc835 MA |
1619 | |
1620 | These are the marshaling/dispatch functions for the commands defined | |
1621 | in the schema. The generated code provides qmp_marshal_COMMAND(), and | |
1622 | declares qmp_COMMAND() that the user must implement. | |
b84da831 | 1623 | |
fb0bc835 | 1624 | The following files are generated: |
b84da831 | 1625 | |
f7aa076d JS |
1626 | ``$(prefix)qapi-commands.c`` |
1627 | Command marshal/dispatch functions for each QMP command defined in | |
1628 | the schema | |
b84da831 | 1629 | |
f7aa076d JS |
1630 | ``$(prefix)qapi-commands.h`` |
1631 | Function prototypes for the QMP commands specified in the schema | |
b84da831 | 1632 | |
ff8e4827 VSO |
1633 | ``$(prefix)qapi-commands.trace-events`` |
1634 | Trace event declarations, see :ref:`tracing`. | |
1635 | ||
f7aa076d JS |
1636 | ``$(prefix)qapi-init-commands.h`` |
1637 | Command initialization prototype | |
00ca24ff | 1638 | |
f7aa076d JS |
1639 | ``$(prefix)qapi-init-commands.c`` |
1640 | Command initialization code | |
00ca24ff | 1641 | |
f7aa076d | 1642 | Example:: |
b84da831 | 1643 | |
eb815e24 | 1644 | $ cat qapi-generated/example-qapi-commands.h |
f7aa076d | 1645 | [Uninteresting stuff omitted...] |
9ee86b85 | 1646 | |
913b5e28 MA |
1647 | #ifndef EXAMPLE_QAPI_COMMANDS_H |
1648 | #define EXAMPLE_QAPI_COMMANDS_H | |
9ee86b85 EB |
1649 | |
1650 | #include "example-qapi-types.h" | |
9ee86b85 EB |
1651 | |
1652 | UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp); | |
64355088 | 1653 | void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp); |
9ee86b85 | 1654 | |
913b5e28 | 1655 | #endif /* EXAMPLE_QAPI_COMMANDS_H */ |
ff8e4827 VSO |
1656 | |
1657 | $ cat qapi-generated/example-qapi-commands.trace-events | |
1658 | # AUTOMATICALLY GENERATED, DO NOT MODIFY | |
1659 | ||
1660 | qmp_enter_my_command(const char *json) "%s" | |
1661 | qmp_exit_my_command(const char *result, bool succeeded) "%s %d" | |
1662 | ||
eb815e24 | 1663 | $ cat qapi-generated/example-qapi-commands.c |
f7aa076d | 1664 | [Uninteresting stuff omitted...] |
b84da831 | 1665 | |
e0366f9f MA |
1666 | |
1667 | static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, | |
1668 | QObject **ret_out, Error **errp) | |
b84da831 | 1669 | { |
b84da831 MR |
1670 | Visitor *v; |
1671 | ||
e0366f9f | 1672 | v = qobject_output_visitor_new_qmp(ret_out); |
cdd2b228 | 1673 | if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) { |
3b098d56 | 1674 | visit_complete(v, ret_out); |
6e2bb3ec | 1675 | } |
2c0ef9f4 EB |
1676 | visit_free(v); |
1677 | v = qapi_dealloc_visitor_new(); | |
9ee86b85 | 1678 | visit_type_UserDefOne(v, "unused", &ret_in, NULL); |
2c0ef9f4 | 1679 | visit_free(v); |
b84da831 MR |
1680 | } |
1681 | ||
64355088 | 1682 | void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp) |
b84da831 | 1683 | { |
2a0f50e8 | 1684 | Error *err = NULL; |
cdd2b228 | 1685 | bool ok = false; |
b84da831 | 1686 | Visitor *v; |
2061487b | 1687 | UserDefOne *retval; |
64355088 | 1688 | q_obj_my_command_arg arg = {0}; |
b84da831 | 1689 | |
e0366f9f | 1690 | v = qobject_input_visitor_new_qmp(QOBJECT(args)); |
cdd2b228 | 1691 | if (!visit_start_struct(v, NULL, NULL, 0, errp)) { |
ed841535 EB |
1692 | goto out; |
1693 | } | |
cdd2b228 MA |
1694 | if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) { |
1695 | ok = visit_check_struct(v, errp); | |
15c2f669 | 1696 | } |
1158bb2a | 1697 | visit_end_struct(v, NULL); |
cdd2b228 | 1698 | if (!ok) { |
b84da831 MR |
1699 | goto out; |
1700 | } | |
297a3646 | 1701 | |
ff8e4827 VSO |
1702 | if (trace_event_get_state_backends(TRACE_QMP_ENTER_MY_COMMAND)) { |
1703 | g_autoptr(GString) req_json = qobject_to_json(QOBJECT(args)); | |
1704 | ||
1705 | trace_qmp_enter_my_command(req_json->str); | |
1706 | } | |
1707 | ||
64355088 | 1708 | retval = qmp_my_command(arg.arg1, &err); |
2a0f50e8 | 1709 | if (err) { |
ff8e4827 | 1710 | trace_qmp_exit_my_command(error_get_pretty(err), false); |
167d913f | 1711 | error_propagate(errp, err); |
297a3646 | 1712 | goto out; |
6e2bb3ec | 1713 | } |
b84da831 | 1714 | |
cdd2b228 | 1715 | qmp_marshal_output_UserDefOne(retval, ret, errp); |
297a3646 | 1716 | |
ff8e4827 VSO |
1717 | if (trace_event_get_state_backends(TRACE_QMP_EXIT_MY_COMMAND)) { |
1718 | g_autoptr(GString) ret_json = qobject_to_json(*ret); | |
1719 | ||
1720 | trace_qmp_exit_my_command(ret_json->str, true); | |
1721 | } | |
1722 | ||
b84da831 | 1723 | out: |
2c0ef9f4 EB |
1724 | visit_free(v); |
1725 | v = qapi_dealloc_visitor_new(); | |
ed841535 | 1726 | visit_start_struct(v, NULL, NULL, 0, NULL); |
64355088 | 1727 | visit_type_q_obj_my_command_arg_members(v, &arg, NULL); |
1158bb2a | 1728 | visit_end_struct(v, NULL); |
2c0ef9f4 | 1729 | visit_free(v); |
b84da831 | 1730 | } |
cdd2b228 | 1731 | |
f7aa076d | 1732 | [Uninteresting stuff omitted...] |
00ca24ff | 1733 | $ cat qapi-generated/example-qapi-init-commands.h |
f7aa076d | 1734 | [Uninteresting stuff omitted...] |
00ca24ff MA |
1735 | #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H |
1736 | #define EXAMPLE_QAPI_INIT_COMMANDS_H | |
b84da831 | 1737 | |
00ca24ff MA |
1738 | #include "qapi/qmp/dispatch.h" |
1739 | ||
1740 | void example_qmp_init_marshal(QmpCommandList *cmds); | |
1741 | ||
1742 | #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */ | |
1743 | $ cat qapi-generated/example-qapi-init-commands.c | |
f7aa076d | 1744 | [Uninteresting stuff omitted...] |
64355088 | 1745 | void example_qmp_init_marshal(QmpCommandList *cmds) |
b84da831 | 1746 | { |
64355088 | 1747 | QTAILQ_INIT(cmds); |
b84da831 | 1748 | |
64355088 MA |
1749 | qmp_register_command(cmds, "my-command", |
1750 | qmp_marshal_my_command, QCO_NO_OPTIONS); | |
1751 | } | |
f7aa076d | 1752 | [Uninteresting stuff omitted...] |
913b5e28 | 1753 | |
9c66762a | 1754 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d | 1755 | each sub-module SUBDIR/SUBMODULE.json is actually generated into:: |
ce32bf85 | 1756 | |
f7aa076d JS |
1757 | SUBDIR/$(prefix)qapi-commands-SUBMODULE.h |
1758 | SUBDIR/$(prefix)qapi-commands-SUBMODULE.c | |
ce32bf85 | 1759 | |
f7aa076d JS |
1760 | |
1761 | Code generated for events | |
1762 | ------------------------- | |
59a2c4ce | 1763 | |
fb0bc835 MA |
1764 | This is the code related to events defined in the schema, providing |
1765 | qapi_event_send_EVENT(). | |
1766 | ||
1767 | The following files are created: | |
59a2c4ce | 1768 | |
f7aa076d JS |
1769 | ``$(prefix)qapi-events.h`` |
1770 | Function prototypes for each event type | |
fb0bc835 | 1771 | |
f7aa076d JS |
1772 | ``$(prefix)qapi-events.c`` |
1773 | Implementation of functions to send an event | |
59a2c4ce | 1774 | |
f7aa076d JS |
1775 | ``$(prefix)qapi-emit-events.h`` |
1776 | Enumeration of all event names, and common event code declarations | |
5d75648b | 1777 | |
f7aa076d JS |
1778 | ``$(prefix)qapi-emit-events.c`` |
1779 | Common event code definitions | |
5d75648b | 1780 | |
f7aa076d | 1781 | Example:: |
59a2c4ce | 1782 | |
eb815e24 | 1783 | $ cat qapi-generated/example-qapi-events.h |
f7aa076d | 1784 | [Uninteresting stuff omitted...] |
9ee86b85 | 1785 | |
913b5e28 MA |
1786 | #ifndef EXAMPLE_QAPI_EVENTS_H |
1787 | #define EXAMPLE_QAPI_EVENTS_H | |
9ee86b85 | 1788 | |
913b5e28 | 1789 | #include "qapi/util.h" |
9ee86b85 EB |
1790 | #include "example-qapi-types.h" |
1791 | ||
3ab72385 | 1792 | void qapi_event_send_my_event(void); |
9ee86b85 | 1793 | |
913b5e28 | 1794 | #endif /* EXAMPLE_QAPI_EVENTS_H */ |
eb815e24 | 1795 | $ cat qapi-generated/example-qapi-events.c |
f7aa076d | 1796 | [Uninteresting stuff omitted...] |
59a2c4ce | 1797 | |
3ab72385 | 1798 | void qapi_event_send_my_event(void) |
59a2c4ce EB |
1799 | { |
1800 | QDict *qmp; | |
59a2c4ce EB |
1801 | |
1802 | qmp = qmp_event_build_dict("MY_EVENT"); | |
1803 | ||
a9529100 | 1804 | example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp); |
59a2c4ce | 1805 | |
cb3e7f08 | 1806 | qobject_unref(qmp); |
59a2c4ce EB |
1807 | } |
1808 | ||
f7aa076d | 1809 | [Uninteresting stuff omitted...] |
5d75648b | 1810 | $ cat qapi-generated/example-qapi-emit-events.h |
f7aa076d | 1811 | [Uninteresting stuff omitted...] |
5d75648b MA |
1812 | |
1813 | #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H | |
1814 | #define EXAMPLE_QAPI_EMIT_EVENTS_H | |
1815 | ||
1816 | #include "qapi/util.h" | |
1817 | ||
1818 | typedef enum example_QAPIEvent { | |
1819 | EXAMPLE_QAPI_EVENT_MY_EVENT, | |
1820 | EXAMPLE_QAPI_EVENT__MAX, | |
1821 | } example_QAPIEvent; | |
1822 | ||
1823 | #define example_QAPIEvent_str(val) \ | |
1824 | qapi_enum_lookup(&example_QAPIEvent_lookup, (val)) | |
1825 | ||
1826 | extern const QEnumLookup example_QAPIEvent_lookup; | |
1827 | ||
1828 | void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict); | |
1829 | ||
1830 | #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */ | |
1831 | $ cat qapi-generated/example-qapi-emit-events.c | |
f7aa076d | 1832 | [Uninteresting stuff omitted...] |
5d75648b | 1833 | |
fb0bc835 MA |
1834 | const QEnumLookup example_QAPIEvent_lookup = { |
1835 | .array = (const char *const[]) { | |
1836 | [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", | |
1837 | }, | |
1838 | .size = EXAMPLE_QAPI_EVENT__MAX | |
59a2c4ce | 1839 | }; |
39a18158 | 1840 | |
f7aa076d | 1841 | [Uninteresting stuff omitted...] |
913b5e28 | 1842 | |
9c66762a | 1843 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d JS |
1844 | each sub-module SUBDIR/SUBMODULE.json is actually generated into :: |
1845 | ||
1846 | SUBDIR/$(prefix)qapi-events-SUBMODULE.h | |
1847 | SUBDIR/$(prefix)qapi-events-SUBMODULE.c | |
ce32bf85 | 1848 | |
ce32bf85 | 1849 | |
f7aa076d JS |
1850 | Code generated for introspection |
1851 | -------------------------------- | |
39a18158 | 1852 | |
fb0bc835 | 1853 | The following files are created: |
39a18158 | 1854 | |
f7aa076d JS |
1855 | ``$(prefix)qapi-introspect.c`` |
1856 | Defines a string holding a JSON description of the schema | |
fb0bc835 | 1857 | |
f7aa076d JS |
1858 | ``$(prefix)qapi-introspect.h`` |
1859 | Declares the above string | |
39a18158 | 1860 | |
f7aa076d | 1861 | Example:: |
39a18158 | 1862 | |
eb815e24 | 1863 | $ cat qapi-generated/example-qapi-introspect.h |
f7aa076d | 1864 | [Uninteresting stuff omitted...] |
39a18158 | 1865 | |
913b5e28 MA |
1866 | #ifndef EXAMPLE_QAPI_INTROSPECT_H |
1867 | #define EXAMPLE_QAPI_INTROSPECT_H | |
39a18158 | 1868 | |
913b5e28 | 1869 | #include "qapi/qmp/qlit.h" |
39a18158 | 1870 | |
913b5e28 MA |
1871 | extern const QLitObject example_qmp_schema_qlit; |
1872 | ||
1873 | #endif /* EXAMPLE_QAPI_INTROSPECT_H */ | |
eb815e24 | 1874 | $ cat qapi-generated/example-qapi-introspect.c |
f7aa076d | 1875 | [Uninteresting stuff omitted...] |
9ee86b85 | 1876 | |
7d0f982b MAL |
1877 | const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) { |
1878 | QLIT_QDICT(((QLitDictEntry[]) { | |
913b5e28 MA |
1879 | { "arg-type", QLIT_QSTR("0"), }, |
1880 | { "meta-type", QLIT_QSTR("command"), }, | |
1881 | { "name", QLIT_QSTR("my-command"), }, | |
1882 | { "ret-type", QLIT_QSTR("1"), }, | |
1883 | {} | |
1884 | })), | |
1885 | QLIT_QDICT(((QLitDictEntry[]) { | |
1886 | { "arg-type", QLIT_QSTR("2"), }, | |
1887 | { "meta-type", QLIT_QSTR("event"), }, | |
1888 | { "name", QLIT_QSTR("MY_EVENT"), }, | |
1889 | {} | |
7d0f982b | 1890 | })), |
8c643361 | 1891 | /* "0" = q_obj_my-command-arg */ |
7d0f982b MAL |
1892 | QLIT_QDICT(((QLitDictEntry[]) { |
1893 | { "members", QLIT_QLIST(((QLitObject[]) { | |
913b5e28 MA |
1894 | QLIT_QDICT(((QLitDictEntry[]) { |
1895 | { "name", QLIT_QSTR("arg1"), }, | |
1896 | { "type", QLIT_QSTR("[1]"), }, | |
1897 | {} | |
1898 | })), | |
1899 | {} | |
1900 | })), }, | |
1901 | { "meta-type", QLIT_QSTR("object"), }, | |
1902 | { "name", QLIT_QSTR("0"), }, | |
1903 | {} | |
7d0f982b | 1904 | })), |
8c643361 | 1905 | /* "1" = UserDefOne */ |
913b5e28 MA |
1906 | QLIT_QDICT(((QLitDictEntry[]) { |
1907 | { "members", QLIT_QLIST(((QLitObject[]) { | |
1908 | QLIT_QDICT(((QLitDictEntry[]) { | |
1909 | { "name", QLIT_QSTR("integer"), }, | |
1910 | { "type", QLIT_QSTR("int"), }, | |
1911 | {} | |
1912 | })), | |
1913 | QLIT_QDICT(((QLitDictEntry[]) { | |
1914 | { "default", QLIT_QNULL, }, | |
1915 | { "name", QLIT_QSTR("string"), }, | |
1916 | { "type", QLIT_QSTR("str"), }, | |
1917 | {} | |
1918 | })), | |
1919 | {} | |
1920 | })), }, | |
1921 | { "meta-type", QLIT_QSTR("object"), }, | |
1922 | { "name", QLIT_QSTR("1"), }, | |
1923 | {} | |
1924 | })), | |
8c643361 | 1925 | /* "2" = q_empty */ |
913b5e28 MA |
1926 | QLIT_QDICT(((QLitDictEntry[]) { |
1927 | { "members", QLIT_QLIST(((QLitObject[]) { | |
1928 | {} | |
1929 | })), }, | |
1930 | { "meta-type", QLIT_QSTR("object"), }, | |
1931 | { "name", QLIT_QSTR("2"), }, | |
1932 | {} | |
1933 | })), | |
1934 | QLIT_QDICT(((QLitDictEntry[]) { | |
1935 | { "element-type", QLIT_QSTR("1"), }, | |
1936 | { "meta-type", QLIT_QSTR("array"), }, | |
1937 | { "name", QLIT_QSTR("[1]"), }, | |
1938 | {} | |
1939 | })), | |
1940 | QLIT_QDICT(((QLitDictEntry[]) { | |
1941 | { "json-type", QLIT_QSTR("int"), }, | |
1942 | { "meta-type", QLIT_QSTR("builtin"), }, | |
1943 | { "name", QLIT_QSTR("int"), }, | |
1944 | {} | |
1945 | })), | |
1946 | QLIT_QDICT(((QLitDictEntry[]) { | |
1947 | { "json-type", QLIT_QSTR("string"), }, | |
1948 | { "meta-type", QLIT_QSTR("builtin"), }, | |
1949 | { "name", QLIT_QSTR("str"), }, | |
1950 | {} | |
1951 | })), | |
1952 | {} | |
7d0f982b | 1953 | })); |
913b5e28 | 1954 | |
f7aa076d | 1955 | [Uninteresting stuff omitted...] |