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