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