]>
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 | ||
d5657258 PM |
548 | See the :doc:`/interop/qmp-spec` for out-of-band execution syntax |
549 | and semantics. | |
378112b0 | 550 | |
153d73f3 MA |
551 | Commands supporting out-of-band execution can still be executed |
552 | in-band. | |
378112b0 | 553 | |
153d73f3 MA |
554 | When a command is executed in-band, its handler runs in the main |
555 | thread with the BQL held. | |
378112b0 | 556 | |
153d73f3 MA |
557 | When a command is executed out-of-band, its handler runs in a |
558 | dedicated monitor I/O thread with the BQL *not* held. | |
378112b0 | 559 | |
153d73f3 | 560 | An OOB-capable command handler must satisfy the following conditions: |
378112b0 | 561 | |
153d73f3 MA |
562 | - It terminates quickly. |
563 | - It does not invoke system calls that may block. | |
378112b0 | 564 | - It does not access guest RAM that may block when userfaultfd is |
153d73f3 | 565 | enabled for postcopy live migration. |
4bfa7974 PX |
566 | - It takes only "fast" locks, i.e. all critical sections protected by |
567 | any lock it takes also satisfy the conditions for OOB command | |
568 | handler code. | |
569 | ||
570 | The restrictions on locking limit access to shared state. Such access | |
571 | requires synchronization, but OOB commands can't take the BQL or any | |
572 | other "slow" lock. | |
378112b0 | 573 | |
153d73f3 | 574 | When in doubt, do not implement OOB execution support. |
b84da831 | 575 | |
b6c37eba | 576 | Member 'allow-preconfig' declares whether the command is available |
f7aa076d | 577 | before the machine is built. It defaults to false. For example:: |
d6fe3d02 | 578 | |
c4cdf54c MA |
579 | { 'enum': 'QMPCapability', |
580 | 'data': [ 'oob' ] } | |
d6fe3d02 IM |
581 | { 'command': 'qmp_capabilities', |
582 | 'data': { '*enable': [ 'QMPCapability' ] }, | |
583 | 'allow-preconfig': true } | |
584 | ||
153d73f3 MA |
585 | QMP is available before the machine is built only when QEMU was |
586 | started with --preconfig. | |
587 | ||
04f22362 KW |
588 | Member 'coroutine' tells the QMP dispatcher whether the command handler |
589 | is safe to be run in a coroutine. It defaults to false. If it is true, | |
590 | the command handler is called from coroutine context and may yield while | |
591 | waiting for an external event (such as I/O completion) in order to avoid | |
592 | blocking the guest and other background operations. | |
593 | ||
594 | Coroutine safety can be hard to prove, similar to thread safety. Common | |
595 | pitfalls are: | |
596 | ||
55927c5f | 597 | - The global mutex isn't held across ``qemu_coroutine_yield()``, so |
04f22362 KW |
598 | operations that used to assume that they execute atomically may have |
599 | to be more careful to protect against changes in the global state. | |
600 | ||
55927c5f | 601 | - Nested event loops (``AIO_WAIT_WHILE()`` etc.) are problematic in |
04f22362 KW |
602 | coroutine context and can easily lead to deadlocks. They should be |
603 | replaced by yielding and reentering the coroutine when the condition | |
604 | becomes false. | |
605 | ||
606 | Since the command handler may assume coroutine context, any callers | |
607 | other than the QMP dispatcher must also call it in coroutine context. | |
bb4b9ead | 608 | In particular, HMP commands calling such a QMP command handler must be |
55927c5f | 609 | marked ``.coroutine = true`` in hmp-commands.hx. |
04f22362 | 610 | |
55927c5f | 611 | It is an error to specify both ``'coroutine': true`` and ``'allow-oob': true`` |
04f22362 KW |
612 | for a command. We don't currently have a use case for both together and |
613 | without a use case, it's not entirely clear what the semantics should | |
614 | be. | |
615 | ||
9c66762a JS |
616 | The optional 'if' member specifies a conditional. See `Configuring |
617 | the schema`_ below for more on this. | |
b6c37eba | 618 | |
9c66762a | 619 | The optional 'features' member specifies features. See Features_ |
013b4efc MA |
620 | below for more on this. |
621 | ||
b6c37eba | 622 | |
f7aa076d JS |
623 | Events |
624 | ------ | |
625 | ||
626 | Syntax:: | |
21cd70df | 627 | |
b6c37eba MA |
628 | EVENT = { 'event': STRING, |
629 | ( | |
630 | '*data': ( MEMBERS | STRING ), | |
631 | | | |
632 | 'data': STRING, | |
633 | 'boxed': true, | |
634 | ) | |
013b4efc MA |
635 | '*if': COND, |
636 | '*features': FEATURES } | |
b6c37eba MA |
637 | |
638 | Member 'event' names the event. This is the event name used in the | |
639 | Client JSON Protocol. | |
640 | ||
641 | Member 'data' defines the event-specific data. It defaults to an | |
642 | empty MEMBERS object. | |
643 | ||
644 | If 'data' is a MEMBERS object, then MEMBERS defines event-specific | |
645 | data just like a struct type's 'data' defines struct type members. | |
e790e666 | 646 | |
b6c37eba | 647 | If 'data' is a STRING, then STRING names a complex type whose members |
55927c5f | 648 | are the event-specific data. A union type requires ``'boxed': true``. |
21cd70df | 649 | |
f7aa076d | 650 | An example event is:: |
21cd70df | 651 | |
f7aa076d JS |
652 | { 'event': 'EVENT_C', |
653 | 'data': { '*a': 'int', 'b': 'str' } } | |
21cd70df | 654 | |
f7aa076d | 655 | Resulting in this JSON object:: |
21cd70df | 656 | |
f7aa076d JS |
657 | { "event": "EVENT_C", |
658 | "data": { "b": "test string" }, | |
659 | "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } | |
b84da831 | 660 | |
b6c37eba MA |
661 | The generator emits a function to send the event. When member 'boxed' |
662 | is absent, it takes event-specific data one by one, in QAPI schema | |
663 | order. Else it takes them wrapped in the C struct generated for the | |
9c66762a | 664 | complex type. See section `Code generated for events`_ for examples. |
b6c37eba | 665 | |
9c66762a JS |
666 | The optional 'if' member specifies a conditional. See `Configuring |
667 | the schema`_ below for more on this. | |
c818408e | 668 | |
9c66762a | 669 | The optional 'features' member specifies features. See Features_ |
013b4efc MA |
670 | below for more on this. |
671 | ||
59a2c4ce | 672 | |
9c66762a JS |
673 | .. _FEATURE: |
674 | ||
f7aa076d JS |
675 | Features |
676 | -------- | |
677 | ||
678 | Syntax:: | |
6a8c0b51 | 679 | |
b6c37eba MA |
680 | FEATURES = [ FEATURE, ... ] |
681 | FEATURE = STRING | |
682 | | { 'name': STRING, '*if': COND } | |
683 | ||
6a8c0b51 | 684 | Sometimes, the behaviour of QEMU changes compatibly, but without a |
b6c37eba MA |
685 | change in the QMP syntax (usually by allowing values or operations |
686 | that previously resulted in an error). QMP clients may still need to | |
687 | know whether the extension is available. | |
6a8c0b51 | 688 | |
ebf1b324 MA |
689 | For this purpose, a list of features can be specified for definitions, |
690 | enumeration values, and struct members. Each feature list member can | |
691 | either be ``{ 'name': STRING, '*if': COND }``, or STRING, which is | |
692 | shorthand for ``{ 'name': STRING }``. | |
6a8c0b51 | 693 | |
9c66762a JS |
694 | The optional 'if' member specifies a conditional. See `Configuring |
695 | the schema`_ below for more on this. | |
6a8c0b51 | 696 | |
f7aa076d | 697 | Example:: |
6a8c0b51 | 698 | |
f7aa076d JS |
699 | { 'struct': 'TestType', |
700 | 'data': { 'number': 'int' }, | |
701 | 'features': [ 'allow-negative-numbers' ] } | |
6a8c0b51 | 702 | |
86014c64 | 703 | The feature strings are exposed to clients in introspection, as |
9c66762a | 704 | explained in section `Client JSON Protocol introspection`_. |
86014c64 MA |
705 | |
706 | Intended use is to have each feature string signal that this build of | |
707 | QEMU shows a certain behaviour. | |
708 | ||
6a8c0b51 | 709 | |
f7aa076d JS |
710 | Special features |
711 | ~~~~~~~~~~~~~~~~ | |
f965e8fe | 712 | |
b6c18755 MA |
713 | Feature "deprecated" marks a command, event, enum value, or struct |
714 | member as deprecated. It is not supported elsewhere so far. | |
715 | Interfaces so marked may be withdrawn in future releases in accordance | |
716 | with QEMU's deprecation policy. | |
f965e8fe | 717 | |
a3c45b3e MA |
718 | Feature "unstable" marks a command, event, enum value, or struct |
719 | member as unstable. It is not supported elsewhere so far. Interfaces | |
720 | so marked may be withdrawn or changed incompatibly in future releases. | |
721 | ||
f965e8fe | 722 | |
f7aa076d JS |
723 | Naming rules and reserved names |
724 | ------------------------------- | |
f5821f52 MA |
725 | |
726 | All names must begin with a letter, and contain only ASCII letters, | |
727 | digits, hyphen, and underscore. There are two exceptions: enum values | |
728 | may start with a digit, and names that are downstream extensions (see | |
9c66762a | 729 | section `Downstream extensions`_) start with underscore. |
f5821f52 | 730 | |
55927c5f | 731 | Names beginning with ``q_`` are reserved for the generator, which uses |
f5821f52 | 732 | them for munging QMP names that resemble C keywords or other |
55927c5f JS |
733 | problematic strings. For example, a member named ``default`` in qapi |
734 | becomes ``q_default`` in the generated C code. | |
f5821f52 MA |
735 | |
736 | Types, commands, and events share a common namespace. Therefore, | |
737 | generally speaking, type definitions should always use CamelCase for | |
738 | user-defined type names, while built-in types are lowercase. | |
739 | ||
55927c5f | 740 | Type names ending with ``Kind`` or ``List`` are reserved for the |
f5821f52 MA |
741 | generator, which uses them for implicit union enums and array types, |
742 | respectively. | |
743 | ||
1524559f MA |
744 | Command names, member names within a type, and feature names should be |
745 | all lower case with words separated by a hyphen. However, some | |
746 | existing older commands and complex types use underscore; when | |
747 | extending them, consistency is preferred over blindly avoiding | |
748 | underscore. | |
f5821f52 MA |
749 | |
750 | Event names should be ALL_CAPS with words separated by underscore. | |
751 | ||
55927c5f | 752 | Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved |
f5821f52 MA |
753 | for the generator, which uses them for unions and for tracking |
754 | optional members. | |
755 | ||
a3c45b3e MA |
756 | Names beginning with ``x-`` used to signify "experimental". This |
757 | convention has been replaced by special feature "unstable". | |
f5821f52 | 758 | |
9c66762a JS |
759 | Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let |
760 | you violate naming rules. Use for new code is strongly discouraged. See | |
761 | `Pragma directives`_ for details. | |
f5821f52 MA |
762 | |
763 | ||
f7aa076d JS |
764 | Downstream extensions |
765 | --------------------- | |
79f75981 MA |
766 | |
767 | QAPI schema names that are externally visible, say in the Client JSON | |
768 | Protocol, need to be managed with care. Names starting with a | |
769 | downstream prefix of the form __RFQDN_ are reserved for the downstream | |
770 | who controls the valid, reverse fully qualified domain name RFQDN. | |
771 | RFQDN may only contain ASCII letters, digits, hyphen and period. | |
772 | ||
773 | Example: Red Hat, Inc. controls redhat.com, and may therefore add a | |
55927c5f | 774 | downstream command ``__com.redhat_drive-mirror``. |
79f75981 MA |
775 | |
776 | ||
f7aa076d JS |
777 | Configuring the schema |
778 | ---------------------- | |
779 | ||
780 | Syntax:: | |
967c8851 | 781 | |
b6c37eba | 782 | COND = STRING |
3248c1aa MAL |
783 | | { 'all: [ COND, ... ] } |
784 | | { 'any: [ COND, ... ] } | |
785 | | { 'not': COND } | |
b6c37eba MA |
786 | |
787 | All definitions take an optional 'if' member. Its value must be a | |
3248c1aa MAL |
788 | string, or an object with a single member 'all', 'any' or 'not'. |
789 | ||
790 | The C code generated for the definition will then be guarded by an #if | |
791 | preprocessing directive with an operand generated from that condition: | |
792 | ||
793 | * STRING will generate defined(STRING) | |
794 | * { 'all': [COND, ...] } will generate (COND && ...) | |
795 | * { 'any': [COND, ...] } will generate (COND || ...) | |
796 | * { 'not': COND } will generate !COND | |
967c8851 | 797 | |
f7aa076d | 798 | Example: a conditional struct :: |
967c8851 MAL |
799 | |
800 | { 'struct': 'IfStruct', 'data': { 'foo': 'int' }, | |
3248c1aa | 801 | 'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } } |
967c8851 | 802 | |
f7aa076d | 803 | gets its generated code guarded like this:: |
967c8851 | 804 | |
3248c1aa | 805 | #if defined(CONFIG_FOO) && defined(HAVE_BAR) |
967c8851 | 806 | ... generated code ... |
3248c1aa | 807 | #endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */ |
967c8851 | 808 | |
de3b3f52 MA |
809 | Individual members of complex types can also be made conditional. |
810 | This requires the longhand form of MEMBER. | |
ccadd6bc | 811 | |
b6c37eba | 812 | Example: a struct type with unconditional member 'foo' and conditional |
f7aa076d | 813 | member 'bar' :: |
ccadd6bc | 814 | |
4cfd6537 MA |
815 | { 'struct': 'IfStruct', |
816 | 'data': { 'foo': 'int', | |
817 | 'bar': { 'type': 'int', 'if': 'IFCOND'} } } | |
ccadd6bc | 818 | |
b6c37eba | 819 | A union's discriminator may not be conditional. |
6cc32b0e | 820 | |
c2985e38 MA |
821 | Likewise, individual enumeration values may be conditional. This |
822 | requires the longhand form of ENUM-VALUE_. | |
b6c37eba MA |
823 | |
824 | Example: an enum type with unconditional value 'foo' and conditional | |
f7aa076d | 825 | value 'bar' :: |
6cc32b0e | 826 | |
4cfd6537 MA |
827 | { 'enum': 'IfEnum', |
828 | 'data': [ 'foo', | |
829 | { 'name' : 'bar', 'if': 'IFCOND' } ] } | |
6cc32b0e | 830 | |
b6c37eba | 831 | Likewise, features can be conditional. This requires the longhand |
9c66762a | 832 | form of FEATURE_. |
6a8c0b51 | 833 | |
f7aa076d | 834 | Example: a struct with conditional feature 'allow-negative-numbers' :: |
6a8c0b51 | 835 | |
f7aa076d JS |
836 | { 'struct': 'TestType', |
837 | 'data': { 'number': 'int' }, | |
838 | 'features': [ { 'name': 'allow-negative-numbers', | |
3248c1aa | 839 | 'if': 'IFCOND' } ] } |
6a8c0b51 | 840 | |
967c8851 MAL |
841 | Please note that you are responsible to ensure that the C code will |
842 | compile with an arbitrary combination of conditions, since the | |
b6c37eba | 843 | generator is unable to check it at this point. |
967c8851 | 844 | |
b6c37eba MA |
845 | The conditions apply to introspection as well, i.e. introspection |
846 | shows a conditional entity only when the condition is satisfied in | |
847 | this particular build. | |
967c8851 MAL |
848 | |
849 | ||
f7aa076d JS |
850 | Documentation comments |
851 | ---------------------- | |
f5821f52 | 852 | |
55927c5f | 853 | A multi-line comment that starts and ends with a ``##`` line is a |
b6c37eba MA |
854 | documentation comment. |
855 | ||
f7aa076d | 856 | If the documentation comment starts like :: |
b6c37eba MA |
857 | |
858 | ## | |
859 | # @SYMBOL: | |
860 | ||
55927c5f | 861 | it documents the definition of SYMBOL, else it's free-form |
b6c37eba MA |
862 | documentation. |
863 | ||
9c66762a | 864 | See below for more on `Definition documentation`_. |
b6c37eba MA |
865 | |
866 | Free-form documentation may be used to provide additional text and | |
867 | structuring content. | |
f5821f52 | 868 | |
f7aa076d JS |
869 | |
870 | Headings and subheadings | |
871 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
f5821f52 | 872 | |
55ec69f8 | 873 | A free-form documentation comment containing a line which starts with |
55927c5f | 874 | some ``=`` symbols and then a space defines a section heading:: |
f5821f52 | 875 | |
55ec69f8 PM |
876 | ## |
877 | # = This is a top level heading | |
878 | # | |
879 | # This is a free-form comment which will go under the | |
880 | # top level heading. | |
881 | ## | |
f5821f52 | 882 | |
55ec69f8 PM |
883 | ## |
884 | # == This is a second level heading | |
885 | ## | |
f5821f52 | 886 | |
55ec69f8 PM |
887 | A heading line must be the first line of the documentation |
888 | comment block. | |
f5821f52 | 889 | |
55ec69f8 PM |
890 | Section headings must always be correctly nested, so you can only |
891 | define a third-level heading inside a second-level heading, and so on. | |
f5821f52 | 892 | |
f7aa076d JS |
893 | |
894 | Documentation markup | |
895 | ~~~~~~~~~~~~~~~~~~~~ | |
d98884b7 | 896 | |
55ec69f8 | 897 | Documentation comments can use most rST markup. In particular, |
55927c5f | 898 | a ``::`` literal block can be used for examples:: |
f5821f52 | 899 | |
55ec69f8 PM |
900 | # :: |
901 | # | |
902 | # Text of the example, may span | |
903 | # multiple lines | |
f5821f52 | 904 | |
55927c5f | 905 | ``*`` starts an itemized list:: |
f5821f52 MA |
906 | |
907 | # * First item, may span | |
908 | # multiple lines | |
909 | # * Second item | |
910 | ||
55927c5f | 911 | You can also use ``-`` instead of ``*``. |
f5821f52 | 912 | |
55927c5f | 913 | A decimal number followed by ``.`` starts a numbered list:: |
f5821f52 MA |
914 | |
915 | # 1. First item, may span | |
916 | # multiple lines | |
917 | # 2. Second item | |
918 | ||
55ec69f8 | 919 | The actual number doesn't matter. |
f5821f52 | 920 | |
55ec69f8 PM |
921 | Lists of either kind must be preceded and followed by a blank line. |
922 | If a list item's text spans multiple lines, then the second and | |
923 | subsequent lines must be correctly indented to line up with the | |
924 | first character of the first line. | |
f5821f52 | 925 | |
55927c5f JS |
926 | The usual ****strong****, *\*emphasized\** and ````literal```` markup |
927 | should be used. If you need a single literal ``*``, you will need to | |
f1a787b5 MA |
928 | backslash-escape it. |
929 | ||
930 | Use ``@foo`` to reference a name in the schema. This is an rST | |
931 | extension. It is rendered the same way as ````foo````, but carries | |
932 | additional meaning. | |
f5821f52 | 933 | |
f7aa076d | 934 | Example:: |
f5821f52 | 935 | |
f7aa076d JS |
936 | ## |
937 | # Some text foo with **bold** and *emphasis* | |
c1101028 | 938 | # |
f7aa076d JS |
939 | # 1. with a list |
940 | # 2. like that | |
941 | # | |
942 | # And some code: | |
943 | # | |
944 | # :: | |
945 | # | |
946 | # $ echo foo | |
947 | # -> do this | |
948 | # <- get that | |
949 | ## | |
f5821f52 | 950 | |
9d167491 MA |
951 | For legibility, wrap text paragraphs so every line is at most 70 |
952 | characters long. | |
953 | ||
954 | Separate sentences with two spaces. | |
955 | ||
f5821f52 | 956 | |
f7aa076d JS |
957 | Definition documentation |
958 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
f5821f52 | 959 | |
b6c37eba MA |
960 | Definition documentation, if present, must immediately precede the |
961 | definition it documents. | |
f5821f52 | 962 | |
9c66762a | 963 | When documentation is required (see pragma_ 'doc-required'), every |
b6c37eba | 964 | definition must have documentation. |
f5821f52 | 965 | |
b6c37eba MA |
966 | Definition documentation starts with a line naming the definition, |
967 | followed by an optional overview, a description of each argument (for | |
968 | commands and events), member (for structs and unions), branch (for | |
53e9e547 MA |
969 | alternates), or value (for enums), a description of each feature (if |
970 | any), and finally optional tagged sections. | |
f5821f52 | 971 | |
9d167491 MA |
972 | Descriptions start with '\@name:'. The description text should be |
973 | indented like this:: | |
974 | ||
975 | # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed | |
976 | # do eiusmod tempor incididunt ut labore et dolore magna aliqua. | |
a69a6d4b | 977 | |
a2836b32 | 978 | .. FIXME The parser accepts these things in almost any order. |
a69a6d4b | 979 | |
a2836b32 | 980 | .. FIXME union branches should be described, too. |
f5821f52 | 981 | |
b6c37eba | 982 | Extensions added after the definition was first released carry a |
0c7811ae | 983 | "(since x.y.z)" comment. |
f5821f52 | 984 | |
53e9e547 MA |
985 | The feature descriptions must be preceded by a line "Features:", like |
986 | this:: | |
987 | ||
988 | # Features: | |
9d167491 | 989 | # |
53e9e547 MA |
990 | # @feature: Description text |
991 | ||
f5821f52 MA |
992 | A tagged section starts with one of the following words: |
993 | "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". | |
994 | The section ends with the start of a new section. | |
995 | ||
9d167491 MA |
996 | The second and subsequent lines of sections other than |
997 | "Example"/"Examples" should be indented like this:: | |
998 | ||
999 | # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco | |
1000 | # laboris nisi ut aliquip ex ea commodo consequat. | |
1001 | # | |
1002 | # Duis aute irure dolor in reprehenderit in voluptate velit esse | |
1003 | # cillum dolore eu fugiat nulla pariatur. | |
a69a6d4b | 1004 | |
0c7811ae | 1005 | A "Since: x.y.z" tagged section lists the release that introduced the |
b6c37eba | 1006 | definition. |
f5821f52 | 1007 | |
9d167491 | 1008 | An "Example" or "Examples" section is rendered entirely |
f57e1d05 MA |
1009 | as literal fixed-width text. "TODO" sections are not rendered at all |
1010 | (they are for developers, not users of QMP). In other sections, the | |
1011 | text is formatted, and rST markup can be used. | |
55ec69f8 | 1012 | |
f7aa076d JS |
1013 | For example:: |
1014 | ||
1015 | ## | |
1016 | # @BlockStats: | |
1017 | # | |
1018 | # Statistics of a virtual block device or a block backing device. | |
1019 | # | |
1020 | # @device: If the stats are for a virtual block device, the name | |
9d167491 | 1021 | # corresponding to the virtual block device. |
f7aa076d JS |
1022 | # |
1023 | # @node-name: The node name of the device. (since 2.3) | |
1024 | # | |
1025 | # ... more members ... | |
1026 | # | |
1027 | # Since: 0.14.0 | |
1028 | ## | |
1029 | { 'struct': 'BlockStats', | |
1030 | 'data': {'*device': 'str', '*node-name': 'str', | |
1031 | ... more members ... } } | |
1032 | ||
1033 | ## | |
1034 | # @query-blockstats: | |
1035 | # | |
1036 | # Query the @BlockStats for all virtual block devices. | |
1037 | # | |
9d167491 MA |
1038 | # @query-nodes: If true, the command will query all the block nodes |
1039 | # ... explain, explain ... (since 2.3) | |
f7aa076d JS |
1040 | # |
1041 | # Returns: A list of @BlockStats for each virtual block devices. | |
1042 | # | |
1043 | # Since: 0.14.0 | |
1044 | # | |
1045 | # Example: | |
1046 | # | |
1047 | # -> { "execute": "query-blockstats" } | |
1048 | # <- { | |
1049 | # ... lots of output ... | |
1050 | # } | |
1051 | # | |
1052 | ## | |
1053 | { 'command': 'query-blockstats', | |
1054 | 'data': { '*query-nodes': 'bool' }, | |
1055 | 'returns': ['BlockStats'] } | |
1056 | ||
1057 | ||
e2e9e567 MA |
1058 | Markup pitfalls |
1059 | ~~~~~~~~~~~~~~~ | |
1060 | ||
1061 | A blank line is required between list items and paragraphs. Without | |
1062 | it, the list may not be recognized, resulting in garbled output. Good | |
1063 | example:: | |
1064 | ||
1065 | # An event's state is modified if: | |
1066 | # | |
1067 | # - its name matches the @name pattern, and | |
1068 | # - if @vcpu is given, the event has the "vcpu" property. | |
1069 | ||
1070 | Without the blank line this would be a single paragraph. | |
1071 | ||
1072 | Indentation matters. Bad example:: | |
1073 | ||
1074 | # @none: None (no memory side cache in this proximity domain, | |
1075 | # or cache associativity unknown) | |
08349786 | 1076 | # (since 5.0) |
e2e9e567 | 1077 | |
08349786 MA |
1078 | The last line's de-indent is wrong. The second and subsequent lines |
1079 | need to line up with each other, like this:: | |
1080 | ||
1081 | # @none: None (no memory side cache in this proximity domain, | |
1082 | # or cache associativity unknown) | |
1083 | # (since 5.0) | |
e2e9e567 MA |
1084 | |
1085 | Section tags are case-sensitive and end with a colon. Good example:: | |
1086 | ||
1087 | # Since: 7.1 | |
1088 | ||
1089 | Bad examples (all ordinary paragraphs):: | |
1090 | ||
1091 | # since: 7.1 | |
1092 | ||
1093 | # Since 7.1 | |
1094 | ||
1095 | # Since : 7.1 | |
1096 | ||
1097 | Likewise, member descriptions require a colon. Good example:: | |
1098 | ||
1099 | # @interface-id: Interface ID | |
1100 | ||
1101 | Bad examples (all ordinary paragraphs):: | |
1102 | ||
1103 | # @interface-id Interface ID | |
1104 | ||
1105 | # @interface-id : Interface ID | |
1106 | ||
1107 | Undocumented members are not flagged, yet. Instead, the generated | |
1108 | documentation describes them as "Not documented". Think twice before | |
1109 | adding more undocumented members. | |
1110 | ||
1111 | When you change documentation comments, please check the generated | |
1112 | documentation comes out as intended! | |
1113 | ||
1114 | ||
f7aa076d JS |
1115 | Client JSON Protocol introspection |
1116 | ================================== | |
39a18158 MA |
1117 | |
1118 | Clients of a Client JSON Protocol commonly need to figure out what | |
1119 | exactly the server (QEMU) supports. | |
1120 | ||
1121 | For this purpose, QMP provides introspection via command | |
1122 | query-qmp-schema. QGA currently doesn't support introspection. | |
1123 | ||
39a65e2c EB |
1124 | While Client JSON Protocol wire compatibility should be maintained |
1125 | between qemu versions, we cannot make the same guarantees for | |
1126 | introspection stability. For example, one version of qemu may provide | |
1127 | a non-variant optional member of a struct, and a later version rework | |
1128 | the member to instead be non-optional and associated with a variant. | |
1129 | Likewise, one version of qemu may list a member with open-ended type | |
1130 | 'str', and a later version could convert it to a finite set of strings | |
1131 | via an enum type; or a member may be converted from a specific type to | |
1132 | an alternate that represents a choice between the original type and | |
1133 | something else. | |
1134 | ||
39a18158 MA |
1135 | query-qmp-schema returns a JSON array of SchemaInfo objects. These |
1136 | objects together describe the wire ABI, as defined in the QAPI schema. | |
f5455044 EB |
1137 | There is no specified order to the SchemaInfo objects returned; a |
1138 | client must search for a particular name throughout the entire array | |
1139 | to learn more about that name, but is at least guaranteed that there | |
1140 | will be no collisions between type, command, and event names. | |
39a18158 MA |
1141 | |
1142 | However, the SchemaInfo can't reflect all the rules and restrictions | |
1143 | that apply to QMP. It's interface introspection (figuring out what's | |
1144 | there), not interface specification. The specification is in the QAPI | |
1145 | schema. To understand how QMP is to be used, you need to study the | |
1146 | QAPI schema. | |
1147 | ||
1148 | Like any other command, query-qmp-schema is itself defined in the QAPI | |
1149 | schema, along with the SchemaInfo type. This text attempts to give an | |
1150 | overview how things work. For details you need to consult the QAPI | |
1151 | schema. | |
1152 | ||
013b4efc MA |
1153 | SchemaInfo objects have common members "name", "meta-type", |
1154 | "features", and additional variant members depending on the value of | |
1155 | meta-type. | |
39a18158 MA |
1156 | |
1157 | Each SchemaInfo object describes a wire ABI entity of a certain | |
1158 | meta-type: a command, event or one of several kinds of type. | |
1159 | ||
1a9a507b MA |
1160 | SchemaInfo for commands and events have the same name as in the QAPI |
1161 | schema. | |
39a18158 MA |
1162 | |
1163 | Command and event names are part of the wire ABI, but type names are | |
1a9a507b MA |
1164 | not. Therefore, the SchemaInfo for types have auto-generated |
1165 | meaningless names. For readability, the examples in this section use | |
1166 | meaningful type names instead. | |
1167 | ||
013b4efc MA |
1168 | Optional member "features" exposes the entity's feature strings as a |
1169 | JSON array of strings. | |
1170 | ||
1a9a507b MA |
1171 | To examine a type, start with a command or event using it, then follow |
1172 | references by name. | |
39a18158 MA |
1173 | |
1174 | QAPI schema definitions not reachable that way are omitted. | |
1175 | ||
1176 | The SchemaInfo for a command has meta-type "command", and variant | |
013b4efc MA |
1177 | members "arg-type", "ret-type" and "allow-oob". On the wire, the |
1178 | "arguments" member of a client's "execute" command must conform to the | |
1179 | object type named by "arg-type". The "return" member that the server | |
1180 | passes in a success response conforms to the type named by "ret-type". | |
1181 | When "allow-oob" is true, it means the command supports out-of-band | |
1182 | execution. It defaults to false. | |
39a18158 MA |
1183 | |
1184 | If the command takes no arguments, "arg-type" names an object type | |
1185 | without members. Likewise, if the command returns nothing, "ret-type" | |
1186 | names an object type without members. | |
1187 | ||
f7aa076d | 1188 | Example: the SchemaInfo for command query-qmp-schema :: |
39a18158 | 1189 | |
f7aa076d JS |
1190 | { "name": "query-qmp-schema", "meta-type": "command", |
1191 | "arg-type": "q_empty", "ret-type": "SchemaInfoList" } | |
39a18158 | 1192 | |
f7aa076d JS |
1193 | Type "q_empty" is an automatic object type without members, and type |
1194 | "SchemaInfoList" is the array of SchemaInfo type. | |
39a18158 MA |
1195 | |
1196 | The SchemaInfo for an event has meta-type "event", and variant member | |
1197 | "arg-type". On the wire, a "data" member that the server passes in an | |
1198 | event conforms to the object type named by "arg-type". | |
1199 | ||
1200 | If the event carries no additional information, "arg-type" names an | |
1201 | object type without members. The event may not have a data member on | |
1202 | the wire then. | |
1203 | ||
b6c37eba | 1204 | Each command or event defined with 'data' as MEMBERS object in the |
1a9a507b | 1205 | QAPI schema implicitly defines an object type. |
39a18158 | 1206 | |
9c66762a | 1207 | Example: the SchemaInfo for EVENT_C from section Events_ :: |
39a18158 MA |
1208 | |
1209 | { "name": "EVENT_C", "meta-type": "event", | |
7599697c | 1210 | "arg-type": "q_obj-EVENT_C-arg" } |
39a18158 | 1211 | |
7599697c | 1212 | Type "q_obj-EVENT_C-arg" is an implicitly defined object type with |
39a18158 MA |
1213 | the two members from the event's definition. |
1214 | ||
c2985e38 MA |
1215 | The SchemaInfo for struct and union types has meta-type "object" and |
1216 | variant member "members". | |
39a18158 MA |
1217 | |
1218 | The SchemaInfo for a union type additionally has variant members "tag" | |
1219 | and "variants". | |
1220 | ||
1221 | "members" is a JSON array describing the object's common members, if | |
1222 | any. Each element is a JSON object with members "name" (the member's | |
b6c18755 MA |
1223 | name), "type" (the name of its type), "features" (a JSON array of |
1224 | feature strings), and "default". The latter two are optional. The | |
39a18158 MA |
1225 | member is optional if "default" is present. Currently, "default" can |
1226 | only have value null. Other values are reserved for future | |
f5455044 EB |
1227 | extensions. The "members" array is in no particular order; clients |
1228 | must search the entire object when learning whether a particular | |
1229 | member is supported. | |
39a18158 | 1230 | |
9c66762a | 1231 | Example: the SchemaInfo for MyType from section `Struct types`_ :: |
39a18158 MA |
1232 | |
1233 | { "name": "MyType", "meta-type": "object", | |
1234 | "members": [ | |
1235 | { "name": "member1", "type": "str" }, | |
1236 | { "name": "member2", "type": "int" }, | |
1237 | { "name": "member3", "type": "str", "default": null } ] } | |
1238 | ||
86014c64 MA |
1239 | "features" exposes the command's feature strings as a JSON array of |
1240 | strings. | |
1241 | ||
9c66762a | 1242 | Example: the SchemaInfo for TestType from section Features_:: |
86014c64 MA |
1243 | |
1244 | { "name": "TestType", "meta-type": "object", | |
1245 | "members": [ | |
1246 | { "name": "number", "type": "int" } ], | |
1247 | "features": ["allow-negative-numbers"] } | |
1248 | ||
39a18158 MA |
1249 | "tag" is the name of the common member serving as type tag. |
1250 | "variants" is a JSON array describing the object's variant members. | |
1251 | Each element is a JSON object with members "case" (the value of type | |
1252 | tag this element applies to) and "type" (the name of an object type | |
f5455044 EB |
1253 | that provides the variant members for this type tag value). The |
1254 | "variants" array is in no particular order, and is not guaranteed to | |
1255 | list cases in the same order as the corresponding "tag" enum type. | |
39a18158 | 1256 | |
4e99f4b1 | 1257 | Example: the SchemaInfo for union BlockdevOptions from section |
9c66762a | 1258 | `Union types`_ :: |
39a18158 MA |
1259 | |
1260 | { "name": "BlockdevOptions", "meta-type": "object", | |
1261 | "members": [ | |
1262 | { "name": "driver", "type": "BlockdevDriver" }, | |
bd59adce | 1263 | { "name": "read-only", "type": "bool", "default": null } ], |
39a18158 MA |
1264 | "tag": "driver", |
1265 | "variants": [ | |
bd59adce EB |
1266 | { "case": "file", "type": "BlockdevOptionsFile" }, |
1267 | { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] } | |
39a18158 MA |
1268 | |
1269 | Note that base types are "flattened": its members are included in the | |
1270 | "members" array. | |
1271 | ||
39a18158 MA |
1272 | The SchemaInfo for an alternate type has meta-type "alternate", and |
1273 | variant member "members". "members" is a JSON array. Each element is | |
1274 | a JSON object with member "type", which names a type. Values of the | |
f5455044 EB |
1275 | alternate type conform to exactly one of its member types. There is |
1276 | no guarantee on the order in which "members" will be listed. | |
39a18158 | 1277 | |
9c66762a | 1278 | Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ :: |
39a18158 | 1279 | |
bd59adce | 1280 | { "name": "BlockdevRef", "meta-type": "alternate", |
39a18158 MA |
1281 | "members": [ |
1282 | { "type": "BlockdevOptions" }, | |
1283 | { "type": "str" } ] } | |
1284 | ||
1285 | The SchemaInfo for an array type has meta-type "array", and variant | |
1286 | member "element-type", which names the array's element type. Array | |
ce5fcb47 EB |
1287 | types are implicitly defined. For convenience, the array's name may |
1288 | resemble the element type; however, clients should examine member | |
1289 | "element-type" instead of making assumptions based on parsing member | |
1290 | "name". | |
39a18158 | 1291 | |
f7aa076d | 1292 | Example: the SchemaInfo for ['str'] :: |
39a18158 | 1293 | |
ce5fcb47 | 1294 | { "name": "[str]", "meta-type": "array", |
39a18158 MA |
1295 | "element-type": "str" } |
1296 | ||
1297 | The SchemaInfo for an enumeration type has meta-type "enum" and | |
75ecee72 MA |
1298 | variant member "members". |
1299 | ||
1300 | "members" is a JSON array describing the enumeration values. Each | |
b6c18755 MA |
1301 | element is a JSON object with member "name" (the member's name), and |
1302 | optionally "features" (a JSON array of feature strings). The | |
75ecee72 MA |
1303 | "members" array is in no particular order; clients must search the |
1304 | entire array when learning whether a particular value is supported. | |
39a18158 | 1305 | |
9c66762a | 1306 | Example: the SchemaInfo for MyEnum from section `Enumeration types`_ :: |
39a18158 MA |
1307 | |
1308 | { "name": "MyEnum", "meta-type": "enum", | |
75ecee72 MA |
1309 | "members": [ |
1310 | { "name": "value1" }, | |
1311 | { "name": "value2" }, | |
1312 | { "name": "value3" } | |
1313 | ] } | |
39a18158 MA |
1314 | |
1315 | The SchemaInfo for a built-in type has the same name as the type in | |
9c66762a | 1316 | the QAPI schema (see section `Built-in Types`_), with one exception |
39a18158 MA |
1317 | detailed below. It has variant member "json-type" that shows how |
1318 | values of this type are encoded on the wire. | |
1319 | ||
f7aa076d | 1320 | Example: the SchemaInfo for str :: |
39a18158 MA |
1321 | |
1322 | { "name": "str", "meta-type": "builtin", "json-type": "string" } | |
1323 | ||
1324 | The QAPI schema supports a number of integer types that only differ in | |
1325 | how they map to C. They are identical as far as SchemaInfo is | |
1326 | concerned. Therefore, they get all mapped to a single type "int" in | |
1327 | SchemaInfo. | |
1328 | ||
1329 | As explained above, type names are not part of the wire ABI. Not even | |
1330 | the names of built-in types. Clients should examine member | |
1331 | "json-type" instead of hard-coding names of built-in types. | |
1332 | ||
1333 | ||
f7aa076d JS |
1334 | Compatibility considerations |
1335 | ============================ | |
ab76bc27 MA |
1336 | |
1337 | Maintaining backward compatibility at the Client JSON Protocol level | |
1338 | while evolving the schema requires some care. This section is about | |
1339 | syntactic compatibility, which is necessary, but not sufficient, for | |
1340 | actual compatibility. | |
1341 | ||
1342 | Clients send commands with argument data, and receive command | |
1343 | responses with return data and events with event data. | |
1344 | ||
1345 | Adding opt-in functionality to the send direction is backwards | |
1346 | compatible: adding commands, optional arguments, enumeration values, | |
1347 | union and alternate branches; turning an argument type into an | |
1348 | alternate of that type; making mandatory arguments optional. Clients | |
1349 | oblivious of the new functionality continue to work. | |
1350 | ||
1351 | Incompatible changes include removing commands, command arguments, | |
1352 | enumeration values, union and alternate branches, adding mandatory | |
1353 | command arguments, and making optional arguments mandatory. | |
1354 | ||
1355 | The specified behavior of an absent optional argument should remain | |
1356 | the same. With proper documentation, this policy still allows some | |
1357 | flexibility; for example, when an optional 'buffer-size' argument is | |
1358 | specified to default to a sensible buffer size, the actual default | |
1359 | value can still be changed. The specified default behavior is not the | |
1360 | exact size of the buffer, only that the default size is sensible. | |
1361 | ||
1362 | Adding functionality to the receive direction is generally backwards | |
1363 | compatible: adding events, adding return and event data members. | |
1364 | Clients are expected to ignore the ones they don't know. | |
1365 | ||
1366 | Removing "unreachable" stuff like events that can't be triggered | |
1367 | anymore, optional return or event data members that can't be sent | |
1368 | anymore, and return or event data member (enumeration) values that | |
1369 | can't be sent anymore makes no difference to clients, except for | |
1370 | introspection. The latter can conceivably confuse clients, so tread | |
1371 | carefully. | |
1372 | ||
1373 | Incompatible changes include removing return and event data members. | |
1374 | ||
1375 | Any change to a command definition's 'data' or one of the types used | |
1376 | there (recursively) needs to consider send direction compatibility. | |
1377 | ||
1378 | Any change to a command definition's 'return', an event definition's | |
1379 | 'data', or one of the types used there (recursively) needs to consider | |
1380 | receive direction compatibility. | |
1381 | ||
1382 | Any change to types used in both contexts need to consider both. | |
1383 | ||
b6c37eba | 1384 | Enumeration type values and complex and alternate type members may be |
ab76bc27 MA |
1385 | reordered freely. For enumerations and alternate types, this doesn't |
1386 | affect the wire encoding. For complex types, this might make the | |
1387 | implementation emit JSON object members in a different order, which | |
1388 | the Client JSON Protocol permits. | |
1389 | ||
1390 | Since type names are not visible in the Client JSON Protocol, types | |
1391 | may be freely renamed. Even certain refactorings are invisible, such | |
1392 | as splitting members from one type into a common base type. | |
1393 | ||
1394 | ||
f7aa076d JS |
1395 | Code generation |
1396 | =============== | |
b84da831 | 1397 | |
fb0bc835 MA |
1398 | The QAPI code generator qapi-gen.py generates code and documentation |
1399 | from the schema. Together with the core QAPI libraries, this code | |
1400 | provides everything required to take JSON commands read in by a Client | |
1401 | JSON Protocol server, unmarshal the arguments into the underlying C | |
1402 | types, call into the corresponding C function, map the response back | |
1403 | to a Client JSON Protocol response to be returned to the user, and | |
1404 | introspect the commands. | |
b84da831 | 1405 | |
9ee86b85 EB |
1406 | As an example, we'll use the following schema, which describes a |
1407 | single complex user-defined type, along with command which takes a | |
1408 | list of that type as a parameter, and returns a single element of that | |
1409 | type. The user is responsible for writing the implementation of | |
f7aa076d | 1410 | qmp_my_command(); everything else is produced by the generator. :: |
b84da831 | 1411 | |
87a560c4 | 1412 | $ cat example-schema.json |
3b2a8b85 | 1413 | { 'struct': 'UserDefOne', |
94f9bd33 | 1414 | 'data': { 'integer': 'int', '*string': 'str', '*flag': 'bool' } } |
b84da831 MR |
1415 | |
1416 | { 'command': 'my-command', | |
9ee86b85 | 1417 | 'data': { 'arg1': ['UserDefOne'] }, |
b84da831 | 1418 | 'returns': 'UserDefOne' } |
b84da831 | 1419 | |
59a2c4ce EB |
1420 | { 'event': 'MY_EVENT' } |
1421 | ||
f7aa076d | 1422 | We run qapi-gen.py like this:: |
fb0bc835 MA |
1423 | |
1424 | $ python scripts/qapi-gen.py --output-dir="qapi-generated" \ | |
1425 | --prefix="example-" example-schema.json | |
1426 | ||
9ee86b85 EB |
1427 | For a more thorough look at generated code, the testsuite includes |
1428 | tests/qapi-schema/qapi-schema-tests.json that covers more examples of | |
1429 | what the generator will accept, and compiles the resulting C code as | |
1430 | part of 'make check-unit'. | |
1431 | ||
f7aa076d JS |
1432 | |
1433 | Code generated for QAPI types | |
1434 | ----------------------------- | |
b84da831 | 1435 | |
fb0bc835 | 1436 | The following files are created: |
b84da831 | 1437 | |
f7aa076d JS |
1438 | ``$(prefix)qapi-types.h`` |
1439 | C types corresponding to types defined in the schema | |
fb0bc835 | 1440 | |
f7aa076d JS |
1441 | ``$(prefix)qapi-types.c`` |
1442 | Cleanup functions for the above C types | |
b84da831 MR |
1443 | |
1444 | The $(prefix) is an optional parameter used as a namespace to keep the | |
1445 | generated code from one schema/code-generation separated from others so code | |
1446 | can be generated/used from multiple schemas without clobbering previously | |
1447 | created code. | |
1448 | ||
f7aa076d | 1449 | Example:: |
b84da831 | 1450 | |
9ee86b85 | 1451 | $ cat qapi-generated/example-qapi-types.h |
f7aa076d | 1452 | [Uninteresting stuff omitted...] |
9ee86b85 EB |
1453 | |
1454 | #ifndef EXAMPLE_QAPI_TYPES_H | |
1455 | #define EXAMPLE_QAPI_TYPES_H | |
1456 | ||
913b5e28 | 1457 | #include "qapi/qapi-builtin-types.h" |
9ee86b85 EB |
1458 | |
1459 | typedef struct UserDefOne UserDefOne; | |
1460 | ||
1461 | typedef struct UserDefOneList UserDefOneList; | |
1462 | ||
64355088 MA |
1463 | typedef struct q_obj_my_command_arg q_obj_my_command_arg; |
1464 | ||
9ee86b85 EB |
1465 | struct UserDefOne { |
1466 | int64_t integer; | |
9ee86b85 | 1467 | char *string; |
94f9bd33 MA |
1468 | bool has_flag; |
1469 | bool flag; | |
9ee86b85 EB |
1470 | }; |
1471 | ||
1472 | void qapi_free_UserDefOne(UserDefOne *obj); | |
221db5da | 1473 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne) |
9ee86b85 EB |
1474 | |
1475 | struct UserDefOneList { | |
1476 | UserDefOneList *next; | |
1477 | UserDefOne *value; | |
1478 | }; | |
1479 | ||
1480 | void qapi_free_UserDefOneList(UserDefOneList *obj); | |
221db5da | 1481 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList) |
9ee86b85 | 1482 | |
64355088 MA |
1483 | struct q_obj_my_command_arg { |
1484 | UserDefOneList *arg1; | |
1485 | }; | |
1486 | ||
913b5e28 | 1487 | #endif /* EXAMPLE_QAPI_TYPES_H */ |
87a560c4 | 1488 | $ cat qapi-generated/example-qapi-types.c |
f7aa076d | 1489 | [Uninteresting stuff omitted...] |
6e2bb3ec | 1490 | |
2b162ccb | 1491 | void qapi_free_UserDefOne(UserDefOne *obj) |
6e2bb3ec | 1492 | { |
6e2bb3ec MA |
1493 | Visitor *v; |
1494 | ||
1495 | if (!obj) { | |
1496 | return; | |
1497 | } | |
1498 | ||
2c0ef9f4 | 1499 | v = qapi_dealloc_visitor_new(); |
9ee86b85 | 1500 | visit_type_UserDefOne(v, NULL, &obj, NULL); |
2c0ef9f4 | 1501 | visit_free(v); |
6e2bb3ec | 1502 | } |
b84da831 | 1503 | |
2b162ccb | 1504 | void qapi_free_UserDefOneList(UserDefOneList *obj) |
b84da831 | 1505 | { |
b84da831 MR |
1506 | Visitor *v; |
1507 | ||
1508 | if (!obj) { | |
1509 | return; | |
1510 | } | |
1511 | ||
2c0ef9f4 | 1512 | v = qapi_dealloc_visitor_new(); |
9ee86b85 | 1513 | visit_type_UserDefOneList(v, NULL, &obj, NULL); |
2c0ef9f4 | 1514 | visit_free(v); |
b84da831 | 1515 | } |
b84da831 | 1516 | |
f7aa076d | 1517 | [Uninteresting stuff omitted...] |
913b5e28 | 1518 | |
9c66762a | 1519 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d | 1520 | each sub-module SUBDIR/SUBMODULE.json is actually generated into :: |
ce32bf85 | 1521 | |
f7aa076d JS |
1522 | SUBDIR/$(prefix)qapi-types-SUBMODULE.h |
1523 | SUBDIR/$(prefix)qapi-types-SUBMODULE.c | |
ce32bf85 MA |
1524 | |
1525 | If qapi-gen.py is run with option --builtins, additional files are | |
1526 | created: | |
1527 | ||
f7aa076d JS |
1528 | ``qapi-builtin-types.h`` |
1529 | C types corresponding to built-in types | |
1530 | ||
1531 | ``qapi-builtin-types.c`` | |
1532 | Cleanup functions for the above C types | |
ce32bf85 | 1533 | |
ce32bf85 | 1534 | |
f7aa076d JS |
1535 | Code generated for visiting QAPI types |
1536 | -------------------------------------- | |
b84da831 | 1537 | |
fb0bc835 MA |
1538 | These are the visitor functions used to walk through and convert |
1539 | between a native QAPI C data structure and some other format (such as | |
1540 | QObject); the generated functions are named visit_type_FOO() and | |
1541 | visit_type_FOO_members(). | |
b84da831 MR |
1542 | |
1543 | The following files are generated: | |
1544 | ||
f7aa076d JS |
1545 | ``$(prefix)qapi-visit.c`` |
1546 | Visitor function for a particular C type, used to automagically | |
1547 | convert QObjects into the corresponding C type and vice-versa, as | |
1548 | well as for deallocating memory for an existing C type | |
b84da831 | 1549 | |
f7aa076d JS |
1550 | ``$(prefix)qapi-visit.h`` |
1551 | Declarations for previously mentioned visitor functions | |
b84da831 | 1552 | |
f7aa076d | 1553 | Example:: |
b84da831 | 1554 | |
9ee86b85 | 1555 | $ cat qapi-generated/example-qapi-visit.h |
f7aa076d | 1556 | [Uninteresting stuff omitted...] |
9ee86b85 EB |
1557 | |
1558 | #ifndef EXAMPLE_QAPI_VISIT_H | |
1559 | #define EXAMPLE_QAPI_VISIT_H | |
1560 | ||
913b5e28 MA |
1561 | #include "qapi/qapi-builtin-visit.h" |
1562 | #include "example-qapi-types.h" | |
1563 | ||
9ee86b85 | 1564 | |
012d4c96 | 1565 | bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp); |
e0366f9f MA |
1566 | |
1567 | bool visit_type_UserDefOne(Visitor *v, const char *name, | |
1568 | UserDefOne **obj, Error **errp); | |
1569 | ||
1570 | bool visit_type_UserDefOneList(Visitor *v, const char *name, | |
1571 | UserDefOneList **obj, Error **errp); | |
9ee86b85 | 1572 | |
012d4c96 | 1573 | bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp); |
64355088 | 1574 | |
913b5e28 | 1575 | #endif /* EXAMPLE_QAPI_VISIT_H */ |
87a560c4 | 1576 | $ cat qapi-generated/example-qapi-visit.c |
f7aa076d | 1577 | [Uninteresting stuff omitted...] |
b84da831 | 1578 | |
012d4c96 | 1579 | bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp) |
6e2bb3ec | 1580 | { |
44ea9d9b MA |
1581 | bool has_string = !!obj->string; |
1582 | ||
012d4c96 MA |
1583 | if (!visit_type_int(v, "integer", &obj->integer, errp)) { |
1584 | return false; | |
297a3646 | 1585 | } |
44ea9d9b | 1586 | if (visit_optional(v, "string", &has_string)) { |
012d4c96 MA |
1587 | if (!visit_type_str(v, "string", &obj->string, errp)) { |
1588 | return false; | |
9ee86b85 | 1589 | } |
297a3646 | 1590 | } |
94f9bd33 MA |
1591 | if (visit_optional(v, "flag", &obj->has_flag)) { |
1592 | if (!visit_type_bool(v, "flag", &obj->flag, errp)) { | |
1593 | return false; | |
1594 | } | |
1595 | } | |
cdd2b228 | 1596 | return true; |
6e2bb3ec | 1597 | } |
b84da831 | 1598 | |
e0366f9f MA |
1599 | bool visit_type_UserDefOne(Visitor *v, const char *name, |
1600 | UserDefOne **obj, Error **errp) | |
b84da831 | 1601 | { |
cdd2b228 | 1602 | bool ok = false; |
297a3646 | 1603 | |
012d4c96 MA |
1604 | if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) { |
1605 | return false; | |
9ee86b85 EB |
1606 | } |
1607 | if (!*obj) { | |
8e08bf4e MA |
1608 | /* incomplete */ |
1609 | assert(visit_is_dealloc(v)); | |
e0366f9f | 1610 | ok = true; |
9ee86b85 | 1611 | goto out_obj; |
6e2bb3ec | 1612 | } |
cdd2b228 | 1613 | if (!visit_type_UserDefOne_members(v, *obj, errp)) { |
15c2f669 EB |
1614 | goto out_obj; |
1615 | } | |
cdd2b228 | 1616 | ok = visit_check_struct(v, errp); |
9ee86b85 | 1617 | out_obj: |
1158bb2a | 1618 | visit_end_struct(v, (void **)obj); |
cdd2b228 | 1619 | if (!ok && visit_is_input(v)) { |
68ab47e4 EB |
1620 | qapi_free_UserDefOne(*obj); |
1621 | *obj = NULL; | |
1622 | } | |
cdd2b228 | 1623 | return ok; |
b84da831 MR |
1624 | } |
1625 | ||
e0366f9f MA |
1626 | bool visit_type_UserDefOneList(Visitor *v, const char *name, |
1627 | UserDefOneList **obj, Error **errp) | |
b84da831 | 1628 | { |
cdd2b228 | 1629 | bool ok = false; |
d9f62dde EB |
1630 | UserDefOneList *tail; |
1631 | size_t size = sizeof(**obj); | |
6e2bb3ec | 1632 | |
012d4c96 MA |
1633 | if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) { |
1634 | return false; | |
297a3646 MA |
1635 | } |
1636 | ||
d9f62dde EB |
1637 | for (tail = *obj; tail; |
1638 | tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) { | |
cdd2b228 MA |
1639 | if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) { |
1640 | goto out_obj; | |
d9f62dde | 1641 | } |
b84da831 | 1642 | } |
297a3646 | 1643 | |
cdd2b228 MA |
1644 | ok = visit_check_list(v, errp); |
1645 | out_obj: | |
1158bb2a | 1646 | visit_end_list(v, (void **)obj); |
cdd2b228 | 1647 | if (!ok && visit_is_input(v)) { |
68ab47e4 EB |
1648 | qapi_free_UserDefOneList(*obj); |
1649 | *obj = NULL; | |
1650 | } | |
cdd2b228 | 1651 | return ok; |
b84da831 | 1652 | } |
b84da831 | 1653 | |
012d4c96 | 1654 | bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp) |
64355088 | 1655 | { |
012d4c96 MA |
1656 | if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) { |
1657 | return false; | |
64355088 | 1658 | } |
cdd2b228 | 1659 | return true; |
64355088 MA |
1660 | } |
1661 | ||
f7aa076d | 1662 | [Uninteresting stuff omitted...] |
913b5e28 | 1663 | |
9c66762a | 1664 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d | 1665 | each sub-module SUBDIR/SUBMODULE.json is actually generated into :: |
ce32bf85 | 1666 | |
f7aa076d JS |
1667 | SUBDIR/$(prefix)qapi-visit-SUBMODULE.h |
1668 | SUBDIR/$(prefix)qapi-visit-SUBMODULE.c | |
ce32bf85 MA |
1669 | |
1670 | If qapi-gen.py is run with option --builtins, additional files are | |
1671 | created: | |
1672 | ||
f7aa076d JS |
1673 | ``qapi-builtin-visit.h`` |
1674 | Visitor functions for built-in types | |
1675 | ||
1676 | ``qapi-builtin-visit.c`` | |
1677 | Declarations for these visitor functions | |
ce32bf85 | 1678 | |
ce32bf85 | 1679 | |
f7aa076d JS |
1680 | Code generated for commands |
1681 | --------------------------- | |
fb0bc835 MA |
1682 | |
1683 | These are the marshaling/dispatch functions for the commands defined | |
1684 | in the schema. The generated code provides qmp_marshal_COMMAND(), and | |
1685 | declares qmp_COMMAND() that the user must implement. | |
b84da831 | 1686 | |
fb0bc835 | 1687 | The following files are generated: |
b84da831 | 1688 | |
f7aa076d JS |
1689 | ``$(prefix)qapi-commands.c`` |
1690 | Command marshal/dispatch functions for each QMP command defined in | |
1691 | the schema | |
b84da831 | 1692 | |
f7aa076d JS |
1693 | ``$(prefix)qapi-commands.h`` |
1694 | Function prototypes for the QMP commands specified in the schema | |
b84da831 | 1695 | |
ff8e4827 VSO |
1696 | ``$(prefix)qapi-commands.trace-events`` |
1697 | Trace event declarations, see :ref:`tracing`. | |
1698 | ||
f7aa076d JS |
1699 | ``$(prefix)qapi-init-commands.h`` |
1700 | Command initialization prototype | |
00ca24ff | 1701 | |
f7aa076d JS |
1702 | ``$(prefix)qapi-init-commands.c`` |
1703 | Command initialization code | |
00ca24ff | 1704 | |
f7aa076d | 1705 | Example:: |
b84da831 | 1706 | |
eb815e24 | 1707 | $ cat qapi-generated/example-qapi-commands.h |
f7aa076d | 1708 | [Uninteresting stuff omitted...] |
9ee86b85 | 1709 | |
913b5e28 MA |
1710 | #ifndef EXAMPLE_QAPI_COMMANDS_H |
1711 | #define EXAMPLE_QAPI_COMMANDS_H | |
9ee86b85 EB |
1712 | |
1713 | #include "example-qapi-types.h" | |
9ee86b85 EB |
1714 | |
1715 | UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp); | |
64355088 | 1716 | void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp); |
9ee86b85 | 1717 | |
913b5e28 | 1718 | #endif /* EXAMPLE_QAPI_COMMANDS_H */ |
ff8e4827 VSO |
1719 | |
1720 | $ cat qapi-generated/example-qapi-commands.trace-events | |
1721 | # AUTOMATICALLY GENERATED, DO NOT MODIFY | |
1722 | ||
1723 | qmp_enter_my_command(const char *json) "%s" | |
1724 | qmp_exit_my_command(const char *result, bool succeeded) "%s %d" | |
1725 | ||
eb815e24 | 1726 | $ cat qapi-generated/example-qapi-commands.c |
f7aa076d | 1727 | [Uninteresting stuff omitted...] |
b84da831 | 1728 | |
e0366f9f MA |
1729 | static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, |
1730 | QObject **ret_out, Error **errp) | |
b84da831 | 1731 | { |
b84da831 MR |
1732 | Visitor *v; |
1733 | ||
e0366f9f | 1734 | v = qobject_output_visitor_new_qmp(ret_out); |
cdd2b228 | 1735 | if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) { |
3b098d56 | 1736 | visit_complete(v, ret_out); |
6e2bb3ec | 1737 | } |
2c0ef9f4 EB |
1738 | visit_free(v); |
1739 | v = qapi_dealloc_visitor_new(); | |
9ee86b85 | 1740 | visit_type_UserDefOne(v, "unused", &ret_in, NULL); |
2c0ef9f4 | 1741 | visit_free(v); |
b84da831 MR |
1742 | } |
1743 | ||
64355088 | 1744 | void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp) |
b84da831 | 1745 | { |
2a0f50e8 | 1746 | Error *err = NULL; |
cdd2b228 | 1747 | bool ok = false; |
b84da831 | 1748 | Visitor *v; |
2061487b | 1749 | UserDefOne *retval; |
64355088 | 1750 | q_obj_my_command_arg arg = {0}; |
b84da831 | 1751 | |
e0366f9f | 1752 | v = qobject_input_visitor_new_qmp(QOBJECT(args)); |
cdd2b228 | 1753 | if (!visit_start_struct(v, NULL, NULL, 0, errp)) { |
ed841535 EB |
1754 | goto out; |
1755 | } | |
cdd2b228 MA |
1756 | if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) { |
1757 | ok = visit_check_struct(v, errp); | |
15c2f669 | 1758 | } |
1158bb2a | 1759 | visit_end_struct(v, NULL); |
cdd2b228 | 1760 | if (!ok) { |
b84da831 MR |
1761 | goto out; |
1762 | } | |
297a3646 | 1763 | |
ff8e4827 VSO |
1764 | if (trace_event_get_state_backends(TRACE_QMP_ENTER_MY_COMMAND)) { |
1765 | g_autoptr(GString) req_json = qobject_to_json(QOBJECT(args)); | |
1766 | ||
1767 | trace_qmp_enter_my_command(req_json->str); | |
1768 | } | |
1769 | ||
64355088 | 1770 | retval = qmp_my_command(arg.arg1, &err); |
2a0f50e8 | 1771 | if (err) { |
ff8e4827 | 1772 | trace_qmp_exit_my_command(error_get_pretty(err), false); |
167d913f | 1773 | error_propagate(errp, err); |
297a3646 | 1774 | goto out; |
6e2bb3ec | 1775 | } |
b84da831 | 1776 | |
cdd2b228 | 1777 | qmp_marshal_output_UserDefOne(retval, ret, errp); |
297a3646 | 1778 | |
ff8e4827 VSO |
1779 | if (trace_event_get_state_backends(TRACE_QMP_EXIT_MY_COMMAND)) { |
1780 | g_autoptr(GString) ret_json = qobject_to_json(*ret); | |
1781 | ||
1782 | trace_qmp_exit_my_command(ret_json->str, true); | |
1783 | } | |
1784 | ||
b84da831 | 1785 | out: |
2c0ef9f4 EB |
1786 | visit_free(v); |
1787 | v = qapi_dealloc_visitor_new(); | |
ed841535 | 1788 | visit_start_struct(v, NULL, NULL, 0, NULL); |
64355088 | 1789 | visit_type_q_obj_my_command_arg_members(v, &arg, NULL); |
1158bb2a | 1790 | visit_end_struct(v, NULL); |
2c0ef9f4 | 1791 | visit_free(v); |
b84da831 | 1792 | } |
cdd2b228 | 1793 | |
f7aa076d | 1794 | [Uninteresting stuff omitted...] |
00ca24ff | 1795 | $ cat qapi-generated/example-qapi-init-commands.h |
f7aa076d | 1796 | [Uninteresting stuff omitted...] |
00ca24ff MA |
1797 | #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H |
1798 | #define EXAMPLE_QAPI_INIT_COMMANDS_H | |
b84da831 | 1799 | |
00ca24ff MA |
1800 | #include "qapi/qmp/dispatch.h" |
1801 | ||
1802 | void example_qmp_init_marshal(QmpCommandList *cmds); | |
1803 | ||
1804 | #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */ | |
1805 | $ cat qapi-generated/example-qapi-init-commands.c | |
f7aa076d | 1806 | [Uninteresting stuff omitted...] |
64355088 | 1807 | void example_qmp_init_marshal(QmpCommandList *cmds) |
b84da831 | 1808 | { |
64355088 | 1809 | QTAILQ_INIT(cmds); |
b84da831 | 1810 | |
64355088 | 1811 | qmp_register_command(cmds, "my-command", |
a680ea07 | 1812 | qmp_marshal_my_command, 0, 0); |
64355088 | 1813 | } |
f7aa076d | 1814 | [Uninteresting stuff omitted...] |
913b5e28 | 1815 | |
9c66762a | 1816 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d | 1817 | each sub-module SUBDIR/SUBMODULE.json is actually generated into:: |
ce32bf85 | 1818 | |
f7aa076d JS |
1819 | SUBDIR/$(prefix)qapi-commands-SUBMODULE.h |
1820 | SUBDIR/$(prefix)qapi-commands-SUBMODULE.c | |
ce32bf85 | 1821 | |
f7aa076d JS |
1822 | |
1823 | Code generated for events | |
1824 | ------------------------- | |
59a2c4ce | 1825 | |
fb0bc835 MA |
1826 | This is the code related to events defined in the schema, providing |
1827 | qapi_event_send_EVENT(). | |
1828 | ||
1829 | The following files are created: | |
59a2c4ce | 1830 | |
f7aa076d JS |
1831 | ``$(prefix)qapi-events.h`` |
1832 | Function prototypes for each event type | |
fb0bc835 | 1833 | |
f7aa076d JS |
1834 | ``$(prefix)qapi-events.c`` |
1835 | Implementation of functions to send an event | |
59a2c4ce | 1836 | |
f7aa076d JS |
1837 | ``$(prefix)qapi-emit-events.h`` |
1838 | Enumeration of all event names, and common event code declarations | |
5d75648b | 1839 | |
f7aa076d JS |
1840 | ``$(prefix)qapi-emit-events.c`` |
1841 | Common event code definitions | |
5d75648b | 1842 | |
f7aa076d | 1843 | Example:: |
59a2c4ce | 1844 | |
eb815e24 | 1845 | $ cat qapi-generated/example-qapi-events.h |
f7aa076d | 1846 | [Uninteresting stuff omitted...] |
9ee86b85 | 1847 | |
913b5e28 MA |
1848 | #ifndef EXAMPLE_QAPI_EVENTS_H |
1849 | #define EXAMPLE_QAPI_EVENTS_H | |
9ee86b85 | 1850 | |
913b5e28 | 1851 | #include "qapi/util.h" |
9ee86b85 EB |
1852 | #include "example-qapi-types.h" |
1853 | ||
3ab72385 | 1854 | void qapi_event_send_my_event(void); |
9ee86b85 | 1855 | |
913b5e28 | 1856 | #endif /* EXAMPLE_QAPI_EVENTS_H */ |
eb815e24 | 1857 | $ cat qapi-generated/example-qapi-events.c |
f7aa076d | 1858 | [Uninteresting stuff omitted...] |
59a2c4ce | 1859 | |
3ab72385 | 1860 | void qapi_event_send_my_event(void) |
59a2c4ce EB |
1861 | { |
1862 | QDict *qmp; | |
59a2c4ce EB |
1863 | |
1864 | qmp = qmp_event_build_dict("MY_EVENT"); | |
1865 | ||
a9529100 | 1866 | example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp); |
59a2c4ce | 1867 | |
cb3e7f08 | 1868 | qobject_unref(qmp); |
59a2c4ce EB |
1869 | } |
1870 | ||
f7aa076d | 1871 | [Uninteresting stuff omitted...] |
5d75648b | 1872 | $ cat qapi-generated/example-qapi-emit-events.h |
f7aa076d | 1873 | [Uninteresting stuff omitted...] |
5d75648b MA |
1874 | |
1875 | #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H | |
1876 | #define EXAMPLE_QAPI_EMIT_EVENTS_H | |
1877 | ||
1878 | #include "qapi/util.h" | |
1879 | ||
1880 | typedef enum example_QAPIEvent { | |
1881 | EXAMPLE_QAPI_EVENT_MY_EVENT, | |
1882 | EXAMPLE_QAPI_EVENT__MAX, | |
1883 | } example_QAPIEvent; | |
1884 | ||
1885 | #define example_QAPIEvent_str(val) \ | |
1886 | qapi_enum_lookup(&example_QAPIEvent_lookup, (val)) | |
1887 | ||
1888 | extern const QEnumLookup example_QAPIEvent_lookup; | |
1889 | ||
1890 | void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict); | |
1891 | ||
1892 | #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */ | |
1893 | $ cat qapi-generated/example-qapi-emit-events.c | |
f7aa076d | 1894 | [Uninteresting stuff omitted...] |
5d75648b | 1895 | |
fb0bc835 MA |
1896 | const QEnumLookup example_QAPIEvent_lookup = { |
1897 | .array = (const char *const[]) { | |
1898 | [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", | |
1899 | }, | |
1900 | .size = EXAMPLE_QAPI_EVENT__MAX | |
59a2c4ce | 1901 | }; |
39a18158 | 1902 | |
f7aa076d | 1903 | [Uninteresting stuff omitted...] |
913b5e28 | 1904 | |
9c66762a | 1905 | For a modular QAPI schema (see section `Include directives`_), code for |
f7aa076d JS |
1906 | each sub-module SUBDIR/SUBMODULE.json is actually generated into :: |
1907 | ||
1908 | SUBDIR/$(prefix)qapi-events-SUBMODULE.h | |
1909 | SUBDIR/$(prefix)qapi-events-SUBMODULE.c | |
ce32bf85 | 1910 | |
ce32bf85 | 1911 | |
f7aa076d JS |
1912 | Code generated for introspection |
1913 | -------------------------------- | |
39a18158 | 1914 | |
fb0bc835 | 1915 | The following files are created: |
39a18158 | 1916 | |
f7aa076d JS |
1917 | ``$(prefix)qapi-introspect.c`` |
1918 | Defines a string holding a JSON description of the schema | |
fb0bc835 | 1919 | |
f7aa076d JS |
1920 | ``$(prefix)qapi-introspect.h`` |
1921 | Declares the above string | |
39a18158 | 1922 | |
f7aa076d | 1923 | Example:: |
39a18158 | 1924 | |
eb815e24 | 1925 | $ cat qapi-generated/example-qapi-introspect.h |
f7aa076d | 1926 | [Uninteresting stuff omitted...] |
39a18158 | 1927 | |
913b5e28 MA |
1928 | #ifndef EXAMPLE_QAPI_INTROSPECT_H |
1929 | #define EXAMPLE_QAPI_INTROSPECT_H | |
39a18158 | 1930 | |
913b5e28 | 1931 | #include "qapi/qmp/qlit.h" |
39a18158 | 1932 | |
913b5e28 MA |
1933 | extern const QLitObject example_qmp_schema_qlit; |
1934 | ||
1935 | #endif /* EXAMPLE_QAPI_INTROSPECT_H */ | |
eb815e24 | 1936 | $ cat qapi-generated/example-qapi-introspect.c |
f7aa076d | 1937 | [Uninteresting stuff omitted...] |
9ee86b85 | 1938 | |
7d0f982b MAL |
1939 | const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) { |
1940 | QLIT_QDICT(((QLitDictEntry[]) { | |
913b5e28 MA |
1941 | { "arg-type", QLIT_QSTR("0"), }, |
1942 | { "meta-type", QLIT_QSTR("command"), }, | |
1943 | { "name", QLIT_QSTR("my-command"), }, | |
1944 | { "ret-type", QLIT_QSTR("1"), }, | |
1945 | {} | |
1946 | })), | |
1947 | QLIT_QDICT(((QLitDictEntry[]) { | |
1948 | { "arg-type", QLIT_QSTR("2"), }, | |
1949 | { "meta-type", QLIT_QSTR("event"), }, | |
1950 | { "name", QLIT_QSTR("MY_EVENT"), }, | |
1951 | {} | |
7d0f982b | 1952 | })), |
8c643361 | 1953 | /* "0" = q_obj_my-command-arg */ |
7d0f982b MAL |
1954 | QLIT_QDICT(((QLitDictEntry[]) { |
1955 | { "members", QLIT_QLIST(((QLitObject[]) { | |
913b5e28 MA |
1956 | QLIT_QDICT(((QLitDictEntry[]) { |
1957 | { "name", QLIT_QSTR("arg1"), }, | |
1958 | { "type", QLIT_QSTR("[1]"), }, | |
1959 | {} | |
1960 | })), | |
1961 | {} | |
1962 | })), }, | |
1963 | { "meta-type", QLIT_QSTR("object"), }, | |
1964 | { "name", QLIT_QSTR("0"), }, | |
1965 | {} | |
7d0f982b | 1966 | })), |
8c643361 | 1967 | /* "1" = UserDefOne */ |
913b5e28 MA |
1968 | QLIT_QDICT(((QLitDictEntry[]) { |
1969 | { "members", QLIT_QLIST(((QLitObject[]) { | |
1970 | QLIT_QDICT(((QLitDictEntry[]) { | |
1971 | { "name", QLIT_QSTR("integer"), }, | |
1972 | { "type", QLIT_QSTR("int"), }, | |
1973 | {} | |
1974 | })), | |
1975 | QLIT_QDICT(((QLitDictEntry[]) { | |
1976 | { "default", QLIT_QNULL, }, | |
1977 | { "name", QLIT_QSTR("string"), }, | |
1978 | { "type", QLIT_QSTR("str"), }, | |
1979 | {} | |
1980 | })), | |
94f9bd33 MA |
1981 | QLIT_QDICT(((QLitDictEntry[]) { |
1982 | { "default", QLIT_QNULL, }, | |
1983 | { "name", QLIT_QSTR("flag"), }, | |
1984 | { "type", QLIT_QSTR("bool"), }, | |
1985 | {} | |
1986 | })), | |
913b5e28 MA |
1987 | {} |
1988 | })), }, | |
1989 | { "meta-type", QLIT_QSTR("object"), }, | |
1990 | { "name", QLIT_QSTR("1"), }, | |
1991 | {} | |
1992 | })), | |
8c643361 | 1993 | /* "2" = q_empty */ |
913b5e28 MA |
1994 | QLIT_QDICT(((QLitDictEntry[]) { |
1995 | { "members", QLIT_QLIST(((QLitObject[]) { | |
1996 | {} | |
1997 | })), }, | |
1998 | { "meta-type", QLIT_QSTR("object"), }, | |
1999 | { "name", QLIT_QSTR("2"), }, | |
2000 | {} | |
2001 | })), | |
2002 | QLIT_QDICT(((QLitDictEntry[]) { | |
2003 | { "element-type", QLIT_QSTR("1"), }, | |
2004 | { "meta-type", QLIT_QSTR("array"), }, | |
2005 | { "name", QLIT_QSTR("[1]"), }, | |
2006 | {} | |
2007 | })), | |
2008 | QLIT_QDICT(((QLitDictEntry[]) { | |
2009 | { "json-type", QLIT_QSTR("int"), }, | |
2010 | { "meta-type", QLIT_QSTR("builtin"), }, | |
2011 | { "name", QLIT_QSTR("int"), }, | |
2012 | {} | |
2013 | })), | |
2014 | QLIT_QDICT(((QLitDictEntry[]) { | |
2015 | { "json-type", QLIT_QSTR("string"), }, | |
2016 | { "meta-type", QLIT_QSTR("builtin"), }, | |
2017 | { "name", QLIT_QSTR("str"), }, | |
2018 | {} | |
2019 | })), | |
94f9bd33 MA |
2020 | QLIT_QDICT(((QLitDictEntry[]) { |
2021 | { "json-type", QLIT_QSTR("boolean"), }, | |
2022 | { "meta-type", QLIT_QSTR("builtin"), }, | |
2023 | { "name", QLIT_QSTR("bool"), }, | |
2024 | {} | |
2025 | })), | |
913b5e28 | 2026 | {} |
7d0f982b | 2027 | })); |
913b5e28 | 2028 | |
f7aa076d | 2029 | [Uninteresting stuff omitted...] |