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