]>
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 | |
7 | later. See the COPYING file in the top-level directory. | |
8 | ||
9 | == Introduction == | |
10 | ||
b84da831 | 11 | QAPI is a native C API within QEMU which provides management-level |
e790e666 EB |
12 | functionality to internal and external users. For external |
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 | |
363b4262 EB |
19 | To map Client JSON Protocol interfaces to the native C QAPI |
20 | implementations, a JSON-based schema is used to define types and | |
21 | function signatures, and a set of scripts is used to generate types, | |
22 | signatures, and marshaling/dispatch code. This document will describe | |
23 | how the schemas, scripts, and resulting code are used. | |
b84da831 MR |
24 | |
25 | ||
26 | == QMP/Guest agent schema == | |
27 | ||
e790e666 EB |
28 | A QAPI schema file is designed to be loosely based on JSON |
29 | (http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style | |
30 | and the use of comments; a QAPI schema file is then parsed by a python | |
31 | code generation program. A valid QAPI schema consists of a series of | |
32 | top-level expressions, with no commas between them. Where | |
33 | dictionaries (JSON objects) are used, they are parsed as python | |
34 | OrderedDicts so that ordering is preserved (for predictable layout of | |
35 | generated C structs and parameter lists). Ordering doesn't matter | |
36 | between top-level expressions or the keys within an expression, but | |
37 | does matter within dictionary values for 'data' and 'returns' members | |
38 | of a single expression. QAPI schema input is written using 'single | |
363b4262 EB |
39 | quotes' instead of JSON's "double quotes" (in contrast, Client JSON |
40 | Protocol uses no comments, and while input accepts 'single quotes' as | |
41 | an extension, output is strict JSON using only "double quotes"). As | |
42 | in JSON, trailing commas are not permitted in arrays or dictionaries. | |
43 | Input must be ASCII (although QMP supports full Unicode strings, the | |
44 | QAPI parser does not). At present, there is no place where a QAPI | |
45 | schema requires the use of JSON numbers or null. | |
e790e666 | 46 | |
3313b612 MAL |
47 | |
48 | === Comments === | |
49 | ||
e790e666 | 50 | Comments are allowed; anything between an unquoted # and the following |
3313b612 MAL |
51 | newline is ignored. |
52 | ||
53 | A multi-line comment that starts and ends with a '##' line is a | |
54 | documentation comment. These are parsed by the documentation | |
55 | generator, which recognizes certain markup detailed below. | |
56 | ||
57 | ||
58 | ==== Documentation markup ==== | |
59 | ||
60 | Comment text starting with '=' is a section title: | |
61 | ||
62 | # = Section title | |
63 | ||
64 | Double the '=' for a subsection title: | |
65 | ||
66 | # == Subection title | |
67 | ||
68 | '|' denotes examples: | |
69 | ||
70 | # | Text of the example, may span | |
71 | # | multiple lines | |
72 | ||
73 | '*' starts an itemized list: | |
74 | ||
75 | # * First item, may span | |
76 | # multiple lines | |
77 | # * Second item | |
78 | ||
79 | You can also use '-' instead of '*'. | |
80 | ||
81 | A decimal number followed by '.' starts a numbered list: | |
82 | ||
83 | # 1. First item, may span | |
84 | # multiple lines | |
85 | # 2. Second item | |
86 | ||
87 | The actual number doesn't matter. You could even use '*' instead of | |
88 | '2.' for the second item. | |
89 | ||
90 | Lists can't be nested. Blank lines are currently not supported within | |
91 | lists. | |
92 | ||
93 | Additional whitespace between the initial '#' and the comment text is | |
94 | permitted. | |
95 | ||
96 | *foo* and _foo_ are for strong and emphasis styles respectively (they | |
97 | do not work over multiple lines). @foo is used to reference a name in | |
98 | the schema. | |
99 | ||
100 | Example: | |
101 | ||
102 | ## | |
103 | # = Section | |
104 | # == Subsection | |
105 | # | |
106 | # Some text foo with *strong* and _emphasis_ | |
107 | # 1. with a list | |
108 | # 2. like that | |
109 | # | |
110 | # And some code: | |
111 | # | $ echo foo | |
112 | # | -> do this | |
113 | # | <- get that | |
114 | # | |
115 | ## | |
116 | ||
117 | ||
118 | ==== Expression documentation ==== | |
119 | ||
bc52d03f | 120 | Each expression that isn't an include directive may be preceded by a |
3313b612 MAL |
121 | documentation block. Such blocks are called expression documentation |
122 | blocks. | |
123 | ||
bc52d03f MA |
124 | When documentation is required (see pragma 'doc-required'), expression |
125 | documentation blocks are mandatory. | |
126 | ||
3313b612 MAL |
127 | The documentation block consists of a first line naming the |
128 | expression, an optional overview, a description of each argument (for | |
129 | commands and events) or member (for structs, unions and alternates), | |
130 | and optional tagged sections. | |
131 | ||
132 | FIXME: the parser accepts these things in almost any order. | |
133 | ||
1d8bda12 MA |
134 | Extensions added after the expression was first released carry a |
135 | '(since x.y.z)' comment. | |
3313b612 MAL |
136 | |
137 | A tagged section starts with one of the following words: | |
138 | "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". | |
139 | The section ends with the start of a new section. | |
140 | ||
141 | A 'Since: x.y.z' tagged section lists the release that introduced the | |
142 | expression. | |
143 | ||
144 | For example: | |
145 | ||
146 | ## | |
147 | # @BlockStats: | |
148 | # | |
149 | # Statistics of a virtual block device or a block backing device. | |
150 | # | |
1d8bda12 | 151 | # @device: If the stats are for a virtual block device, the name |
3313b612 MAL |
152 | # corresponding to the virtual block device. |
153 | # | |
1d8bda12 | 154 | # @node-name: The node name of the device. (since 2.3) |
3313b612 MAL |
155 | # |
156 | # ... more members ... | |
157 | # | |
158 | # Since: 0.14.0 | |
159 | ## | |
160 | { 'struct': 'BlockStats', | |
161 | 'data': {'*device': 'str', '*node-name': 'str', | |
162 | ... more members ... } } | |
163 | ||
164 | ## | |
165 | # @query-blockstats: | |
166 | # | |
167 | # Query the @BlockStats for all virtual block devices. | |
168 | # | |
1d8bda12 | 169 | # @query-nodes: If true, the command will query all the |
3313b612 MAL |
170 | # block nodes ... explain, explain ... (since 2.3) |
171 | # | |
172 | # Returns: A list of @BlockStats for each virtual block devices. | |
173 | # | |
174 | # Since: 0.14.0 | |
175 | # | |
176 | # Example: | |
177 | # | |
178 | # -> { "execute": "query-blockstats" } | |
179 | # <- { | |
180 | # ... lots of output ... | |
181 | # } | |
182 | # | |
183 | ## | |
184 | { 'command': 'query-blockstats', | |
185 | 'data': { '*query-nodes': 'bool' }, | |
186 | 'returns': ['BlockStats'] } | |
187 | ||
188 | ==== Free-form documentation ==== | |
189 | ||
190 | A documentation block that isn't an expression documentation block is | |
191 | a free-form documentation block. These may be used to provide | |
192 | additional text and structuring content. | |
193 | ||
194 | ||
195 | === Schema overview === | |
e790e666 EB |
196 | |
197 | The schema sets up a series of types, as well as commands and events | |
198 | that will use those types. Forward references are allowed: the parser | |
199 | scans in two passes, where the first pass learns all type names, and | |
200 | the second validates the schema and generates the code. This allows | |
201 | the definition of complex structs that can have mutually recursive | |
363b4262 EB |
202 | types, and allows for indefinite nesting of Client JSON Protocol that |
203 | satisfies the schema. A type name should not be defined more than | |
204 | once. It is permissible for the schema to contain additional types | |
205 | not used by any commands or events in the Client JSON Protocol, for | |
206 | the side effect of generated C code used internally. | |
e790e666 | 207 | |
bc52d03f MA |
208 | There are eight top-level expressions recognized by the parser: |
209 | 'include', 'pragma', 'command', 'struct', 'enum', 'union', | |
210 | 'alternate', and 'event'. There are several groups of types: simple | |
211 | types (a number of built-in types, such as 'int' and 'str'; as well as | |
212 | enumerations), complex types (structs and two flavors of unions), and | |
213 | alternate types (a choice between other types). The 'command' and | |
214 | 'event' expressions can refer to existing types by name, or list an | |
215 | anonymous type as a dictionary. Listing a type name inside an array | |
216 | refers to a single-dimension array of that type; multi-dimension | |
217 | arrays are not directly supported (although an array of a complex | |
218 | struct that contains an array member is possible). | |
e790e666 | 219 | |
79f75981 MA |
220 | All names must begin with a letter, and contain only ASCII letters, |
221 | digits, hyphen, and underscore. There are two exceptions: enum values | |
222 | may start with a digit, and names that are downstream extensions (see | |
223 | section Downstream extensions) start with underscore. | |
224 | ||
225 | Names beginning with 'q_' are reserved for the generator, which uses | |
226 | them for munging QMP names that resemble C keywords or other | |
227 | problematic strings. For example, a member named "default" in qapi | |
228 | becomes "q_default" in the generated C code. | |
229 | ||
e790e666 EB |
230 | Types, commands, and events share a common namespace. Therefore, |
231 | generally speaking, type definitions should always use CamelCase for | |
79f75981 MA |
232 | user-defined type names, while built-in types are lowercase. |
233 | ||
234 | Type names ending with 'Kind' or 'List' are reserved for the | |
235 | generator, which uses them for implicit union enums and array types, | |
236 | respectively. | |
237 | ||
238 | Command names, and member names within a type, should be all lower | |
239 | case with words separated by a hyphen. However, some existing older | |
240 | commands and complex types use underscore; when extending such | |
241 | expressions, consistency is preferred over blindly avoiding | |
242 | underscore. | |
243 | ||
244 | Event names should be ALL_CAPS with words separated by underscore. | |
245 | ||
246 | Member names starting with 'has-' or 'has_' are reserved for the | |
247 | generator, which uses them for tracking optional members. | |
e790e666 | 248 | |
9ee86b85 | 249 | Any name (command, event, type, member, or enum value) beginning with |
e790e666 | 250 | "x-" is marked experimental, and may be withdrawn or changed |
79f75981 | 251 | incompatibly in a future release. |
e790e666 | 252 | |
2cfbae3c MA |
253 | Pragma 'name-case-whitelist' lets you violate the rules on use of |
254 | upper and lower case. Use for new code is strongly discouraged. | |
255 | ||
e790e666 EB |
256 | In the rest of this document, usage lines are given for each |
257 | expression type, with literal strings written in lower case and | |
258 | placeholders written in capitals. If a literal string includes a | |
259 | prefix of '*', that key/value pair can be omitted from the expression. | |
3b2a8b85 | 260 | For example, a usage statement that includes '*base':STRUCT-NAME |
e790e666 | 261 | means that an expression has an optional key 'base', which if present |
3b2a8b85 | 262 | must have a value that forms a struct name. |
e790e666 EB |
263 | |
264 | ||
265 | === Built-in Types === | |
266 | ||
f133f2db MA |
267 | The following types are predefined, and map to C as follows: |
268 | ||
269 | Schema C JSON | |
270 | str char * any JSON string, UTF-8 | |
271 | number double any JSON number | |
272 | int int64_t a JSON number without fractional part | |
273 | that fits into the C integer type | |
274 | int8 int8_t likewise | |
275 | int16 int16_t likewise | |
276 | int32 int32_t likewise | |
277 | int64 int64_t likewise | |
278 | uint8 uint8_t likewise | |
279 | uint16 uint16_t likewise | |
280 | uint32 uint32_t likewise | |
281 | uint64 uint64_t likewise | |
282 | size uint64_t like uint64_t, except StringInputVisitor | |
283 | accepts size suffixes | |
284 | bool bool JSON true or false | |
28770e05 | 285 | any QObject * any JSON value |
7264f5c5 | 286 | QType QType JSON string matching enum QType values |
51631493 | 287 | |
a719a27c | 288 | |
bc52d03f | 289 | === Include directives === |
a719a27c | 290 | |
e790e666 EB |
291 | Usage: { 'include': STRING } |
292 | ||
a719a27c LV |
293 | The QAPI schema definitions can be modularized using the 'include' directive: |
294 | ||
e790e666 | 295 | { 'include': 'path/to/file.json' } |
a719a27c LV |
296 | |
297 | The directive is evaluated recursively, and include paths are relative to the | |
e790e666 | 298 | file using the directive. Multiple includes of the same file are |
4247f839 | 299 | idempotent. No other keys should appear in the expression, and the include |
e790e666 EB |
300 | value should be a string. |
301 | ||
302 | As a matter of style, it is a good idea to have all files be | |
303 | self-contained, but at the moment, nothing prevents an included file | |
304 | from making a forward reference to a type that is only introduced by | |
305 | an outer file. The parser may be made stricter in the future to | |
306 | prevent incomplete include files. | |
a719a27c LV |
307 | |
308 | ||
bc52d03f MA |
309 | === Pragma directives === |
310 | ||
311 | Usage: { 'pragma': DICT } | |
312 | ||
313 | The pragma directive lets you control optional generator behavior. | |
314 | The dictionary's entries are pragma names and values. | |
315 | ||
316 | Pragma's scope is currently the complete schema. Setting the same | |
317 | pragma to different values in parts of the schema doesn't work. | |
318 | ||
319 | Pragma 'doc-required' takes a boolean value. If true, documentation | |
320 | is required. Default is false. | |
321 | ||
1554a8fa MA |
322 | Pragma 'returns-whitelist' takes a list of command names that may |
323 | violate the rules on permitted return types. Default is none. | |
324 | ||
2cfbae3c MA |
325 | Pragma 'name-case-whitelist' takes a list of names that may violate |
326 | rules on use of upper- vs. lower-case letters. Default is none. | |
327 | ||
bc52d03f | 328 | |
3b2a8b85 | 329 | === Struct types === |
51631493 | 330 | |
3b2a8b85 | 331 | Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME } |
e790e666 | 332 | |
02a57ae3 EB |
333 | A struct is a dictionary containing a single 'data' key whose value is |
334 | a dictionary; the dictionary may be empty. This corresponds to a | |
335 | struct in C or an Object in JSON. Each value of the 'data' dictionary | |
336 | must be the name of a type, or a one-element array containing a type | |
337 | name. An example of a struct is: | |
b84da831 | 338 | |
3b2a8b85 | 339 | { 'struct': 'MyType', |
acf8394e | 340 | 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } |
b84da831 | 341 | |
e790e666 | 342 | The use of '*' as a prefix to the name means the member is optional in |
363b4262 | 343 | the corresponding JSON protocol usage. |
cc162655 EB |
344 | |
345 | The default initialization value of an optional argument should not be changed | |
346 | between versions of QEMU unless the new default maintains backward | |
347 | compatibility to the user-visible behavior of the old default. | |
348 | ||
349 | With proper documentation, this policy still allows some flexibility; for | |
350 | example, documenting that a default of 0 picks an optimal buffer size allows | |
351 | one release to declare the optimal size at 512 while another release declares | |
352 | the optimal size at 4096 - the user-visible behavior is not the bytes used by | |
353 | the buffer, but the fact that the buffer was optimal size. | |
354 | ||
355 | On input structures (only mentioned in the 'data' side of a command), changing | |
356 | from mandatory to optional is safe (older clients will supply the option, and | |
357 | newer clients can benefit from the default); changing from optional to | |
358 | mandatory is backwards incompatible (older clients may be omitting the option, | |
359 | and must continue to work). | |
360 | ||
361 | On output structures (only mentioned in the 'returns' side of a command), | |
362 | changing from mandatory to optional is in general unsafe (older clients may be | |
9ee86b85 EB |
363 | expecting the member, and could crash if it is missing), although it |
364 | can be done if the only way that the optional argument will be omitted | |
365 | is when it is triggered by the presence of a new input flag to the | |
366 | command that older clients don't know to send. Changing from optional | |
367 | to mandatory is safe. | |
cc162655 EB |
368 | |
369 | A structure that is used in both input and output of various commands | |
370 | must consider the backwards compatibility constraints of both directions | |
371 | of use. | |
622f557f | 372 | |
3b2a8b85 | 373 | A struct definition can specify another struct as its base. |
9ee86b85 | 374 | In this case, the members of the base type are included as top-level members |
363b4262 EB |
375 | of the new struct's dictionary in the Client JSON Protocol wire |
376 | format. An example definition is: | |
622f557f | 377 | |
3b2a8b85 EB |
378 | { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } |
379 | { 'struct': 'BlockdevOptionsGenericCOWFormat', | |
622f557f KW |
380 | 'base': 'BlockdevOptionsGenericFormat', |
381 | 'data': { '*backing': 'str' } } | |
382 | ||
383 | An example BlockdevOptionsGenericCOWFormat object on the wire could use | |
9ee86b85 | 384 | both members like this: |
622f557f KW |
385 | |
386 | { "file": "/some/place/my-image", | |
387 | "backing": "/some/place/my-backing-file" } | |
388 | ||
e790e666 | 389 | |
51631493 KW |
390 | === Enumeration types === |
391 | ||
e790e666 | 392 | Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING } |
351d36e4 | 393 | { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING } |
e790e666 EB |
394 | |
395 | An enumeration type is a dictionary containing a single 'data' key | |
396 | whose value is a list of strings. An example enumeration is: | |
b84da831 MR |
397 | |
398 | { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } | |
399 | ||
e790e666 EB |
400 | Nothing prevents an empty enumeration, although it is probably not |
401 | useful. The list of strings should be lower case; if an enum name | |
402 | represents multiple words, use '-' between words. The string 'max' is | |
403 | not allowed as an enum value, and values should not be repeated. | |
404 | ||
351d36e4 DB |
405 | The enum constants will be named by using a heuristic to turn the |
406 | type name into a set of underscore separated words. For the example | |
407 | above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name | |
408 | of 'MY_ENUM_VALUE1' for the first value. If the default heuristic | |
9ee86b85 | 409 | does not result in a desirable name, the optional 'prefix' member |
351d36e4 DB |
410 | can be used when defining the enum. |
411 | ||
363b4262 EB |
412 | The enumeration values are passed as strings over the Client JSON |
413 | Protocol, but are encoded as C enum integral values in generated code. | |
414 | While the C code starts numbering at 0, it is better to use explicit | |
e790e666 EB |
415 | comparisons to enum values than implicit comparisons to 0; the C code |
416 | will also include a generated enum member ending in _MAX for tracking | |
417 | the size of the enum, useful when using common functions for | |
418 | converting between strings and enum values. Since the wire format | |
419 | always passes by name, it is acceptable to reorder or add new | |
363b4262 EB |
420 | enumeration members in any location without breaking clients of Client |
421 | JSON Protocol; however, removing enum values would break | |
9ee86b85 EB |
422 | compatibility. For any struct that has a member that will only contain |
423 | a finite set of string values, using an enum type for that member is | |
424 | better than open-coding the member to be type 'str'. | |
e790e666 EB |
425 | |
426 | ||
51631493 KW |
427 | === Union types === |
428 | ||
e790e666 | 429 | Usage: { 'union': STRING, 'data': DICT } |
ac4338f8 | 430 | or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME-OR-DICT, |
e790e666 | 431 | 'discriminator': ENUM-MEMBER-OF-BASE } |
51631493 | 432 | |
e790e666 | 433 | Union types are used to let the user choose between several different |
7b1b98c4 | 434 | variants for an object. There are two flavors: simple (no |
02a57ae3 | 435 | discriminator or base), and flat (both discriminator and base). A union |
7b1b98c4 | 436 | type is defined using a data dictionary as explained in the following |
02a57ae3 EB |
437 | paragraphs. The data dictionary for either type of union must not |
438 | be empty. | |
51631493 | 439 | |
e790e666 EB |
440 | A simple union type defines a mapping from automatic discriminator |
441 | values to data types like in this example: | |
51631493 | 442 | |
bd59adce EB |
443 | { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } } |
444 | { 'struct': 'BlockdevOptionsQcow2', | |
445 | 'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } } | |
51631493 | 446 | |
bd59adce EB |
447 | { 'union': 'BlockdevOptionsSimple', |
448 | 'data': { 'file': 'BlockdevOptionsFile', | |
449 | 'qcow2': 'BlockdevOptionsQcow2' } } | |
51631493 | 450 | |
363b4262 | 451 | In the Client JSON Protocol, a simple union is represented by a |
9ee86b85 EB |
452 | dictionary that contains the 'type' member as a discriminator, and a |
453 | 'data' member that is of the specified data type corresponding to the | |
363b4262 | 454 | discriminator value, as in these examples: |
51631493 | 455 | |
bd59adce EB |
456 | { "type": "file", "data": { "filename": "/some/place/my-image" } } |
457 | { "type": "qcow2", "data": { "backing": "/some/place/my-image", | |
458 | "lazy-refcounts": true } } | |
51631493 | 459 | |
e790e666 EB |
460 | The generated C code uses a struct containing a union. Additionally, |
461 | an implicit C enum 'NameKind' is created, corresponding to the union | |
462 | 'Name', for accessing the various branches of the union. No branch of | |
463 | the union can be named 'max', as this would collide with the implicit | |
464 | enum. The value for each branch can be of any type. | |
51631493 | 465 | |
ac4338f8 EB |
466 | A flat union definition avoids nesting on the wire, and specifies a |
467 | set of common members that occur in all variants of the union. The | |
d33c8a7d | 468 | 'base' key must specify either a type name (the type must be a |
ac4338f8 EB |
469 | struct, not a union), or a dictionary representing an anonymous type. |
470 | All branches of the union must be complex types, and the top-level | |
471 | members of the union dictionary on the wire will be combination of | |
472 | members from both the base type and the appropriate branch type (when | |
473 | merging two dictionaries, there must be no keys in common). The | |
474 | 'discriminator' member must be the name of a non-optional enum-typed | |
475 | member of the base struct. | |
51631493 | 476 | |
e790e666 | 477 | The following example enhances the above simple union example by |
bd59adce EB |
478 | adding an optional common member 'read-only', renaming the |
479 | discriminator to something more applicable than the simple union's | |
480 | default of 'type', and reducing the number of {} required on the wire: | |
50f2bdc7 | 481 | |
94a3f0af | 482 | { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] } |
50f2bdc7 | 483 | { 'union': 'BlockdevOptions', |
ac4338f8 | 484 | 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' }, |
50f2bdc7 | 485 | 'discriminator': 'driver', |
bd59adce EB |
486 | 'data': { 'file': 'BlockdevOptionsFile', |
487 | 'qcow2': 'BlockdevOptionsQcow2' } } | |
50f2bdc7 | 488 | |
e790e666 EB |
489 | Resulting in these JSON objects: |
490 | ||
bd59adce | 491 | { "driver": "file", "read-only": true, |
e790e666 | 492 | "filename": "/some/place/my-image" } |
bd59adce EB |
493 | { "driver": "qcow2", "read-only": false, |
494 | "backing": "/some/place/my-image", "lazy-refcounts": true } | |
e790e666 EB |
495 | |
496 | Notice that in a flat union, the discriminator name is controlled by | |
497 | the user, but because it must map to a base member with enum type, the | |
498 | code generator can ensure that branches exist for all values of the | |
499 | enum (although the order of the keys need not match the declaration of | |
500 | the enum). In the resulting generated C data types, a flat union is | |
9ee86b85 EB |
501 | represented as a struct with the base members included directly, and |
502 | then a union of structures for each branch of the struct. | |
e790e666 EB |
503 | |
504 | A simple union can always be re-written as a flat union where the base | |
505 | class has a single member named 'type', and where each branch of the | |
3b2a8b85 | 506 | union has a struct with a single member named 'data'. That is, |
50f2bdc7 | 507 | |
e790e666 | 508 | { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } } |
50f2bdc7 | 509 | |
e790e666 | 510 | is identical on the wire to: |
50f2bdc7 | 511 | |
e790e666 | 512 | { 'enum': 'Enum', 'data': ['one', 'two'] } |
3b2a8b85 EB |
513 | { 'struct': 'Branch1', 'data': { 'data': 'str' } } |
514 | { 'struct': 'Branch2', 'data': { 'data': 'int' } } | |
ac4338f8 | 515 | { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type', |
e790e666 | 516 | 'data': { 'one': 'Branch1', 'two': 'Branch2' } } |
69dd62df | 517 | |
e790e666 | 518 | |
7b1b98c4 | 519 | === Alternate types === |
69dd62df | 520 | |
7b1b98c4 EB |
521 | Usage: { 'alternate': STRING, 'data': DICT } |
522 | ||
523 | An alternate type is one that allows a choice between two or more JSON | |
524 | data types (string, integer, number, or object, but currently not | |
525 | array) on the wire. The definition is similar to a simple union type, | |
526 | where each branch of the union names a QAPI type. For example: | |
527 | ||
bd59adce | 528 | { 'alternate': 'BlockdevRef', |
69dd62df KW |
529 | 'data': { 'definition': 'BlockdevOptions', |
530 | 'reference': 'str' } } | |
531 | ||
7b1b98c4 | 532 | Unlike a union, the discriminator string is never passed on the wire |
363b4262 EB |
533 | for the Client JSON Protocol. Instead, the value's JSON type serves |
534 | as an implicit discriminator, which in turn means that an alternate | |
535 | can only express a choice between types represented differently in | |
536 | JSON. If a branch is typed as the 'bool' built-in, the alternate | |
537 | accepts true and false; if it is typed as any of the various numeric | |
538 | built-ins, it accepts a JSON number; if it is typed as a 'str' | |
539 | built-in or named enum type, it accepts a JSON string; and if it is | |
540 | typed as a complex type (struct or union), it accepts a JSON object. | |
541 | Two different complex types, for instance, aren't permitted, because | |
542 | both are represented as a JSON object. | |
7b1b98c4 EB |
543 | |
544 | The example alternate declaration above allows using both of the | |
545 | following example objects: | |
69dd62df KW |
546 | |
547 | { "file": "my_existing_block_device_id" } | |
548 | { "file": { "driver": "file", | |
bd59adce | 549 | "read-only": false, |
63922c64 | 550 | "filename": "/tmp/mydisk.qcow2" } } |
69dd62df KW |
551 | |
552 | ||
51631493 | 553 | === Commands === |
b84da831 | 554 | |
e790e666 | 555 | Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, |
c818408e | 556 | '*returns': TYPE-NAME, '*boxed': true, |
e790e666 EB |
557 | '*gen': false, '*success-response': false } |
558 | ||
559 | Commands are defined by using a dictionary containing several members, | |
560 | where three members are most common. The 'command' member is a | |
363b4262 EB |
561 | mandatory string, and determines the "execute" value passed in a |
562 | Client JSON Protocol command exchange. | |
e790e666 EB |
563 | |
564 | The 'data' argument maps to the "arguments" dictionary passed in as | |
363b4262 EB |
565 | part of a Client JSON Protocol command. The 'data' member is optional |
566 | and defaults to {} (an empty dictionary). If present, it must be the | |
315932b5 | 567 | string name of a complex type, or a dictionary that declares an |
700dc9f5 | 568 | anonymous type with the same semantics as a 'struct' expression. |
e790e666 | 569 | |
9ee86b85 | 570 | The 'returns' member describes what will appear in the "return" member |
363b4262 EB |
571 | of a Client JSON Protocol reply on successful completion of a command. |
572 | The member is optional from the command declaration; if absent, the | |
9ee86b85 | 573 | "return" member will be an empty dictionary. If 'returns' is present, |
363b4262 | 574 | it must be the string name of a complex or built-in type, a |
700dc9f5 | 575 | one-element array containing the name of a complex or built-in type. |
1554a8fa MA |
576 | To return anything else, you have to list the command in pragma |
577 | 'returns-whitelist'. If you do this, the command cannot be extended | |
578 | to return additional information in the future. Use of | |
579 | 'returns-whitelist' for new commands is strongly discouraged. | |
363b4262 EB |
580 | |
581 | All commands in Client JSON Protocol use a dictionary to report | |
582 | failure, with no way to specify that in QAPI. Where the error return | |
583 | is different than the usual GenericError class in order to help the | |
584 | client react differently to certain error conditions, it is worth | |
585 | documenting this in the comments before the command declaration. | |
e790e666 EB |
586 | |
587 | Some example commands: | |
588 | ||
589 | { 'command': 'my-first-command', | |
590 | 'data': { 'arg1': 'str', '*arg2': 'str' } } | |
3b2a8b85 | 591 | { 'struct': 'MyType', 'data': { '*value': 'str' } } |
e790e666 EB |
592 | { 'command': 'my-second-command', |
593 | 'returns': [ 'MyType' ] } | |
594 | ||
363b4262 | 595 | which would validate this Client JSON Protocol transaction: |
e790e666 EB |
596 | |
597 | => { "execute": "my-first-command", | |
598 | "arguments": { "arg1": "hello" } } | |
599 | <= { "return": { } } | |
600 | => { "execute": "my-second-command" } | |
601 | <= { "return": [ { "value": "one" }, { } ] } | |
602 | ||
c818408e EB |
603 | The generator emits a prototype for the user's function implementing |
604 | the command. Normally, 'data' is a dictionary for an anonymous type, | |
605 | or names a struct type (possibly empty, but not a union), and its | |
606 | members are passed as separate arguments to this function. If the | |
607 | command definition includes a key 'boxed' with the boolean value true, | |
608 | then 'data' is instead the name of any non-empty complex type | |
609 | (struct, union, or alternate), and a pointer to that QAPI type is | |
610 | passed as a single argument. | |
611 | ||
612 | The generator also emits a marshalling function that extracts | |
613 | arguments for the user's function out of an input QDict, calls the | |
614 | user's function, and if it succeeded, builds an output QObject from | |
615 | its return value. | |
616 | ||
e790e666 | 617 | In rare cases, QAPI cannot express a type-safe representation of a |
2d21291a MA |
618 | corresponding Client JSON Protocol command. You then have to suppress |
619 | generation of a marshalling function by including a key 'gen' with | |
620 | boolean value false, and instead write your own function. Please try | |
621 | to avoid adding new commands that rely on this, and instead use | |
622 | type-safe unions. For an example of this usage: | |
e790e666 EB |
623 | |
624 | { 'command': 'netdev_add', | |
b8a98326 | 625 | 'data': {'type': 'str', 'id': 'str'}, |
e790e666 EB |
626 | 'gen': false } |
627 | ||
628 | Normally, the QAPI schema is used to describe synchronous exchanges, | |
629 | where a response is expected. But in some cases, the action of a | |
630 | command is expected to change state in a way that a successful | |
631 | response is not possible (although the command will still return a | |
632 | normal dictionary error on failure). When a successful reply is not | |
633 | possible, the command expression should include the optional key | |
634 | 'success-response' with boolean value false. So far, only QGA makes | |
9ee86b85 | 635 | use of this member. |
b84da831 | 636 | |
b84da831 | 637 | |
21cd70df WX |
638 | === Events === |
639 | ||
c818408e EB |
640 | Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, |
641 | '*boxed': true } | |
e790e666 EB |
642 | |
643 | Events are defined with the keyword 'event'. It is not allowed to | |
644 | name an event 'MAX', since the generator also produces a C enumeration | |
645 | of all event names with a generated _MAX value at the end. When | |
646 | 'data' is also specified, additional info will be included in the | |
3b2a8b85 | 647 | event, with similar semantics to a 'struct' expression. Finally there |
e790e666 EB |
648 | will be C API generated in qapi-event.h; when called by QEMU code, a |
649 | message with timestamp will be emitted on the wire. | |
21cd70df WX |
650 | |
651 | An example event is: | |
652 | ||
653 | { 'event': 'EVENT_C', | |
654 | 'data': { '*a': 'int', 'b': 'str' } } | |
655 | ||
656 | Resulting in this JSON object: | |
657 | ||
658 | { "event": "EVENT_C", | |
659 | "data": { "b": "test string" }, | |
660 | "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } | |
b84da831 | 661 | |
c818408e EB |
662 | The generator emits a function to send the event. Normally, 'data' is |
663 | a dictionary for an anonymous type, or names a struct type (possibly | |
664 | empty, but not a union), and its members are passed as separate | |
665 | arguments to this function. If the event definition includes a key | |
666 | 'boxed' with the boolean value true, then 'data' is instead the name of | |
667 | any non-empty complex type (struct, union, or alternate), and a | |
668 | pointer to that QAPI type is passed as a single argument. | |
669 | ||
59a2c4ce | 670 | |
79f75981 MA |
671 | === Downstream extensions === |
672 | ||
673 | QAPI schema names that are externally visible, say in the Client JSON | |
674 | Protocol, need to be managed with care. Names starting with a | |
675 | downstream prefix of the form __RFQDN_ are reserved for the downstream | |
676 | who controls the valid, reverse fully qualified domain name RFQDN. | |
677 | RFQDN may only contain ASCII letters, digits, hyphen and period. | |
678 | ||
679 | Example: Red Hat, Inc. controls redhat.com, and may therefore add a | |
680 | downstream command __com.redhat_drive-mirror. | |
681 | ||
682 | ||
39a18158 MA |
683 | == Client JSON Protocol introspection == |
684 | ||
685 | Clients of a Client JSON Protocol commonly need to figure out what | |
686 | exactly the server (QEMU) supports. | |
687 | ||
688 | For this purpose, QMP provides introspection via command | |
689 | query-qmp-schema. QGA currently doesn't support introspection. | |
690 | ||
39a65e2c EB |
691 | While Client JSON Protocol wire compatibility should be maintained |
692 | between qemu versions, we cannot make the same guarantees for | |
693 | introspection stability. For example, one version of qemu may provide | |
694 | a non-variant optional member of a struct, and a later version rework | |
695 | the member to instead be non-optional and associated with a variant. | |
696 | Likewise, one version of qemu may list a member with open-ended type | |
697 | 'str', and a later version could convert it to a finite set of strings | |
698 | via an enum type; or a member may be converted from a specific type to | |
699 | an alternate that represents a choice between the original type and | |
700 | something else. | |
701 | ||
39a18158 MA |
702 | query-qmp-schema returns a JSON array of SchemaInfo objects. These |
703 | objects together describe the wire ABI, as defined in the QAPI schema. | |
f5455044 EB |
704 | There is no specified order to the SchemaInfo objects returned; a |
705 | client must search for a particular name throughout the entire array | |
706 | to learn more about that name, but is at least guaranteed that there | |
707 | will be no collisions between type, command, and event names. | |
39a18158 MA |
708 | |
709 | However, the SchemaInfo can't reflect all the rules and restrictions | |
710 | that apply to QMP. It's interface introspection (figuring out what's | |
711 | there), not interface specification. The specification is in the QAPI | |
712 | schema. To understand how QMP is to be used, you need to study the | |
713 | QAPI schema. | |
714 | ||
715 | Like any other command, query-qmp-schema is itself defined in the QAPI | |
716 | schema, along with the SchemaInfo type. This text attempts to give an | |
717 | overview how things work. For details you need to consult the QAPI | |
718 | schema. | |
719 | ||
720 | SchemaInfo objects have common members "name" and "meta-type", and | |
721 | additional variant members depending on the value of meta-type. | |
722 | ||
723 | Each SchemaInfo object describes a wire ABI entity of a certain | |
724 | meta-type: a command, event or one of several kinds of type. | |
725 | ||
1a9a507b MA |
726 | SchemaInfo for commands and events have the same name as in the QAPI |
727 | schema. | |
39a18158 MA |
728 | |
729 | Command and event names are part of the wire ABI, but type names are | |
1a9a507b MA |
730 | not. Therefore, the SchemaInfo for types have auto-generated |
731 | meaningless names. For readability, the examples in this section use | |
732 | meaningful type names instead. | |
733 | ||
734 | To examine a type, start with a command or event using it, then follow | |
735 | references by name. | |
39a18158 MA |
736 | |
737 | QAPI schema definitions not reachable that way are omitted. | |
738 | ||
739 | The SchemaInfo for a command has meta-type "command", and variant | |
740 | members "arg-type" and "ret-type". On the wire, the "arguments" | |
741 | member of a client's "execute" command must conform to the object type | |
742 | named by "arg-type". The "return" member that the server passes in a | |
743 | success response conforms to the type named by "ret-type". | |
744 | ||
745 | If the command takes no arguments, "arg-type" names an object type | |
746 | without members. Likewise, if the command returns nothing, "ret-type" | |
747 | names an object type without members. | |
748 | ||
749 | Example: the SchemaInfo for command query-qmp-schema | |
750 | ||
751 | { "name": "query-qmp-schema", "meta-type": "command", | |
7599697c | 752 | "arg-type": "q_empty", "ret-type": "SchemaInfoList" } |
39a18158 | 753 | |
7599697c | 754 | Type "q_empty" is an automatic object type without members, and type |
39a18158 MA |
755 | "SchemaInfoList" is the array of SchemaInfo type. |
756 | ||
757 | The SchemaInfo for an event has meta-type "event", and variant member | |
758 | "arg-type". On the wire, a "data" member that the server passes in an | |
759 | event conforms to the object type named by "arg-type". | |
760 | ||
761 | If the event carries no additional information, "arg-type" names an | |
762 | object type without members. The event may not have a data member on | |
763 | the wire then. | |
764 | ||
765 | Each command or event defined with dictionary-valued 'data' in the | |
1a9a507b | 766 | QAPI schema implicitly defines an object type. |
39a18158 MA |
767 | |
768 | Example: the SchemaInfo for EVENT_C from section Events | |
769 | ||
770 | { "name": "EVENT_C", "meta-type": "event", | |
7599697c | 771 | "arg-type": "q_obj-EVENT_C-arg" } |
39a18158 | 772 | |
7599697c | 773 | Type "q_obj-EVENT_C-arg" is an implicitly defined object type with |
39a18158 MA |
774 | the two members from the event's definition. |
775 | ||
776 | The SchemaInfo for struct and union types has meta-type "object". | |
777 | ||
778 | The SchemaInfo for a struct type has variant member "members". | |
779 | ||
780 | The SchemaInfo for a union type additionally has variant members "tag" | |
781 | and "variants". | |
782 | ||
783 | "members" is a JSON array describing the object's common members, if | |
784 | any. Each element is a JSON object with members "name" (the member's | |
785 | name), "type" (the name of its type), and optionally "default". The | |
786 | member is optional if "default" is present. Currently, "default" can | |
787 | only have value null. Other values are reserved for future | |
f5455044 EB |
788 | extensions. The "members" array is in no particular order; clients |
789 | must search the entire object when learning whether a particular | |
790 | member is supported. | |
39a18158 MA |
791 | |
792 | Example: the SchemaInfo for MyType from section Struct types | |
793 | ||
794 | { "name": "MyType", "meta-type": "object", | |
795 | "members": [ | |
796 | { "name": "member1", "type": "str" }, | |
797 | { "name": "member2", "type": "int" }, | |
798 | { "name": "member3", "type": "str", "default": null } ] } | |
799 | ||
800 | "tag" is the name of the common member serving as type tag. | |
801 | "variants" is a JSON array describing the object's variant members. | |
802 | Each element is a JSON object with members "case" (the value of type | |
803 | tag this element applies to) and "type" (the name of an object type | |
f5455044 EB |
804 | that provides the variant members for this type tag value). The |
805 | "variants" array is in no particular order, and is not guaranteed to | |
806 | list cases in the same order as the corresponding "tag" enum type. | |
39a18158 MA |
807 | |
808 | Example: the SchemaInfo for flat union BlockdevOptions from section | |
809 | Union types | |
810 | ||
811 | { "name": "BlockdevOptions", "meta-type": "object", | |
812 | "members": [ | |
813 | { "name": "driver", "type": "BlockdevDriver" }, | |
bd59adce | 814 | { "name": "read-only", "type": "bool", "default": null } ], |
39a18158 MA |
815 | "tag": "driver", |
816 | "variants": [ | |
bd59adce EB |
817 | { "case": "file", "type": "BlockdevOptionsFile" }, |
818 | { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] } | |
39a18158 MA |
819 | |
820 | Note that base types are "flattened": its members are included in the | |
821 | "members" array. | |
822 | ||
823 | A simple union implicitly defines an enumeration type for its implicit | |
824 | discriminator (called "type" on the wire, see section Union types). | |
39a18158 MA |
825 | |
826 | A simple union implicitly defines an object type for each of its | |
1a9a507b | 827 | variants. |
39a18158 | 828 | |
bd59adce | 829 | Example: the SchemaInfo for simple union BlockdevOptionsSimple from section |
39a18158 MA |
830 | Union types |
831 | ||
bd59adce | 832 | { "name": "BlockdevOptionsSimple", "meta-type": "object", |
39a18158 | 833 | "members": [ |
bd59adce | 834 | { "name": "type", "type": "BlockdevOptionsSimpleKind" } ], |
39a18158 MA |
835 | "tag": "type", |
836 | "variants": [ | |
bd59adce EB |
837 | { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" }, |
838 | { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] } | |
39a18158 | 839 | |
bd59adce EB |
840 | Enumeration type "BlockdevOptionsSimpleKind" and the object types |
841 | "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper" | |
842 | are implicitly defined. | |
39a18158 MA |
843 | |
844 | The SchemaInfo for an alternate type has meta-type "alternate", and | |
845 | variant member "members". "members" is a JSON array. Each element is | |
846 | a JSON object with member "type", which names a type. Values of the | |
f5455044 EB |
847 | alternate type conform to exactly one of its member types. There is |
848 | no guarantee on the order in which "members" will be listed. | |
39a18158 | 849 | |
bd59adce | 850 | Example: the SchemaInfo for BlockdevRef from section Alternate types |
39a18158 | 851 | |
bd59adce | 852 | { "name": "BlockdevRef", "meta-type": "alternate", |
39a18158 MA |
853 | "members": [ |
854 | { "type": "BlockdevOptions" }, | |
855 | { "type": "str" } ] } | |
856 | ||
857 | The SchemaInfo for an array type has meta-type "array", and variant | |
858 | member "element-type", which names the array's element type. Array | |
ce5fcb47 EB |
859 | types are implicitly defined. For convenience, the array's name may |
860 | resemble the element type; however, clients should examine member | |
861 | "element-type" instead of making assumptions based on parsing member | |
862 | "name". | |
39a18158 MA |
863 | |
864 | Example: the SchemaInfo for ['str'] | |
865 | ||
ce5fcb47 | 866 | { "name": "[str]", "meta-type": "array", |
39a18158 MA |
867 | "element-type": "str" } |
868 | ||
869 | The SchemaInfo for an enumeration type has meta-type "enum" and | |
f5455044 EB |
870 | variant member "values". The values are listed in no particular |
871 | order; clients must search the entire enum when learning whether a | |
872 | particular value is supported. | |
39a18158 MA |
873 | |
874 | Example: the SchemaInfo for MyEnum from section Enumeration types | |
875 | ||
876 | { "name": "MyEnum", "meta-type": "enum", | |
877 | "values": [ "value1", "value2", "value3" ] } | |
878 | ||
879 | The SchemaInfo for a built-in type has the same name as the type in | |
880 | the QAPI schema (see section Built-in Types), with one exception | |
881 | detailed below. It has variant member "json-type" that shows how | |
882 | values of this type are encoded on the wire. | |
883 | ||
884 | Example: the SchemaInfo for str | |
885 | ||
886 | { "name": "str", "meta-type": "builtin", "json-type": "string" } | |
887 | ||
888 | The QAPI schema supports a number of integer types that only differ in | |
889 | how they map to C. They are identical as far as SchemaInfo is | |
890 | concerned. Therefore, they get all mapped to a single type "int" in | |
891 | SchemaInfo. | |
892 | ||
893 | As explained above, type names are not part of the wire ABI. Not even | |
894 | the names of built-in types. Clients should examine member | |
895 | "json-type" instead of hard-coding names of built-in types. | |
896 | ||
897 | ||
b84da831 MR |
898 | == Code generation == |
899 | ||
9ee86b85 | 900 | Schemas are fed into five scripts to generate all the code/files that, |
39a18158 MA |
901 | paired with the core QAPI libraries, comprise everything required to |
902 | take JSON commands read in by a Client JSON Protocol server, unmarshal | |
903 | the arguments into the underlying C types, call into the corresponding | |
9ee86b85 EB |
904 | C function, map the response back to a Client JSON Protocol response |
905 | to be returned to the user, and introspect the commands. | |
b84da831 | 906 | |
9ee86b85 EB |
907 | As an example, we'll use the following schema, which describes a |
908 | single complex user-defined type, along with command which takes a | |
909 | list of that type as a parameter, and returns a single element of that | |
910 | type. The user is responsible for writing the implementation of | |
911 | qmp_my_command(); everything else is produced by the generator. | |
b84da831 | 912 | |
87a560c4 | 913 | $ cat example-schema.json |
3b2a8b85 | 914 | { 'struct': 'UserDefOne', |
9ee86b85 | 915 | 'data': { 'integer': 'int', '*string': 'str' } } |
b84da831 MR |
916 | |
917 | { 'command': 'my-command', | |
9ee86b85 | 918 | 'data': { 'arg1': ['UserDefOne'] }, |
b84da831 | 919 | 'returns': 'UserDefOne' } |
b84da831 | 920 | |
59a2c4ce EB |
921 | { 'event': 'MY_EVENT' } |
922 | ||
9ee86b85 EB |
923 | For a more thorough look at generated code, the testsuite includes |
924 | tests/qapi-schema/qapi-schema-tests.json that covers more examples of | |
925 | what the generator will accept, and compiles the resulting C code as | |
926 | part of 'make check-unit'. | |
927 | ||
b84da831 MR |
928 | === scripts/qapi-types.py === |
929 | ||
9ee86b85 EB |
930 | Used to generate the C types defined by a schema, along with |
931 | supporting code. The following files are created: | |
b84da831 MR |
932 | |
933 | $(prefix)qapi-types.h - C types corresponding to types defined in | |
934 | the schema you pass in | |
935 | $(prefix)qapi-types.c - Cleanup functions for the above C types | |
936 | ||
937 | The $(prefix) is an optional parameter used as a namespace to keep the | |
938 | generated code from one schema/code-generation separated from others so code | |
939 | can be generated/used from multiple schemas without clobbering previously | |
940 | created code. | |
941 | ||
942 | Example: | |
943 | ||
87a560c4 | 944 | $ python scripts/qapi-types.py --output-dir="qapi-generated" \ |
16d80f61 | 945 | --prefix="example-" example-schema.json |
9ee86b85 EB |
946 | $ cat qapi-generated/example-qapi-types.h |
947 | [Uninteresting stuff omitted...] | |
948 | ||
949 | #ifndef EXAMPLE_QAPI_TYPES_H | |
950 | #define EXAMPLE_QAPI_TYPES_H | |
951 | ||
952 | [Built-in types omitted...] | |
953 | ||
954 | typedef struct UserDefOne UserDefOne; | |
955 | ||
956 | typedef struct UserDefOneList UserDefOneList; | |
957 | ||
958 | struct UserDefOne { | |
959 | int64_t integer; | |
960 | bool has_string; | |
961 | char *string; | |
962 | }; | |
963 | ||
964 | void qapi_free_UserDefOne(UserDefOne *obj); | |
965 | ||
966 | struct UserDefOneList { | |
967 | UserDefOneList *next; | |
968 | UserDefOne *value; | |
969 | }; | |
970 | ||
971 | void qapi_free_UserDefOneList(UserDefOneList *obj); | |
972 | ||
973 | #endif | |
87a560c4 | 974 | $ cat qapi-generated/example-qapi-types.c |
6e2bb3ec MA |
975 | [Uninteresting stuff omitted...] |
976 | ||
2b162ccb | 977 | void qapi_free_UserDefOne(UserDefOne *obj) |
6e2bb3ec | 978 | { |
6e2bb3ec MA |
979 | Visitor *v; |
980 | ||
981 | if (!obj) { | |
982 | return; | |
983 | } | |
984 | ||
2c0ef9f4 | 985 | v = qapi_dealloc_visitor_new(); |
9ee86b85 | 986 | visit_type_UserDefOne(v, NULL, &obj, NULL); |
2c0ef9f4 | 987 | visit_free(v); |
6e2bb3ec | 988 | } |
b84da831 | 989 | |
2b162ccb | 990 | void qapi_free_UserDefOneList(UserDefOneList *obj) |
b84da831 | 991 | { |
b84da831 MR |
992 | Visitor *v; |
993 | ||
994 | if (!obj) { | |
995 | return; | |
996 | } | |
997 | ||
2c0ef9f4 | 998 | v = qapi_dealloc_visitor_new(); |
9ee86b85 | 999 | visit_type_UserDefOneList(v, NULL, &obj, NULL); |
2c0ef9f4 | 1000 | visit_free(v); |
b84da831 | 1001 | } |
b84da831 | 1002 | |
b84da831 MR |
1003 | === scripts/qapi-visit.py === |
1004 | ||
9ee86b85 EB |
1005 | Used to generate the visitor functions used to walk through and |
1006 | convert between a native QAPI C data structure and some other format | |
1007 | (such as QObject); the generated functions are named visit_type_FOO() | |
1008 | and visit_type_FOO_members(). | |
b84da831 MR |
1009 | |
1010 | The following files are generated: | |
1011 | ||
1012 | $(prefix)qapi-visit.c: visitor function for a particular C type, used | |
1013 | to automagically convert QObjects into the | |
1014 | corresponding C type and vice-versa, as well | |
1015 | as for deallocating memory for an existing C | |
1016 | type | |
1017 | ||
1018 | $(prefix)qapi-visit.h: declarations for previously mentioned visitor | |
1019 | functions | |
1020 | ||
1021 | Example: | |
1022 | ||
87a560c4 | 1023 | $ python scripts/qapi-visit.py --output-dir="qapi-generated" |
16d80f61 | 1024 | --prefix="example-" example-schema.json |
9ee86b85 EB |
1025 | $ cat qapi-generated/example-qapi-visit.h |
1026 | [Uninteresting stuff omitted...] | |
1027 | ||
1028 | #ifndef EXAMPLE_QAPI_VISIT_H | |
1029 | #define EXAMPLE_QAPI_VISIT_H | |
1030 | ||
1031 | [Visitors for built-in types omitted...] | |
1032 | ||
1033 | void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp); | |
1034 | void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp); | |
1035 | void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp); | |
1036 | ||
1037 | #endif | |
87a560c4 | 1038 | $ cat qapi-generated/example-qapi-visit.c |
6e2bb3ec | 1039 | [Uninteresting stuff omitted...] |
b84da831 | 1040 | |
9ee86b85 | 1041 | void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp) |
6e2bb3ec MA |
1042 | { |
1043 | Error *err = NULL; | |
3a864e7c | 1044 | |
9ee86b85 | 1045 | visit_type_int(v, "integer", &obj->integer, &err); |
297a3646 MA |
1046 | if (err) { |
1047 | goto out; | |
1048 | } | |
9ee86b85 EB |
1049 | if (visit_optional(v, "string", &obj->has_string)) { |
1050 | visit_type_str(v, "string", &obj->string, &err); | |
1051 | if (err) { | |
1052 | goto out; | |
1053 | } | |
297a3646 | 1054 | } |
6e2bb3ec | 1055 | |
297a3646 | 1056 | out: |
6e2bb3ec MA |
1057 | error_propagate(errp, err); |
1058 | } | |
b84da831 | 1059 | |
9ee86b85 | 1060 | void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp) |
b84da831 | 1061 | { |
297a3646 MA |
1062 | Error *err = NULL; |
1063 | ||
9ee86b85 EB |
1064 | visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err); |
1065 | if (err) { | |
1066 | goto out; | |
1067 | } | |
1068 | if (!*obj) { | |
1069 | goto out_obj; | |
6e2bb3ec | 1070 | } |
9ee86b85 | 1071 | visit_type_UserDefOne_members(v, *obj, &err); |
15c2f669 EB |
1072 | if (err) { |
1073 | goto out_obj; | |
1074 | } | |
1075 | visit_check_struct(v, &err); | |
9ee86b85 | 1076 | out_obj: |
1158bb2a | 1077 | visit_end_struct(v, (void **)obj); |
68ab47e4 EB |
1078 | if (err && visit_is_input(v)) { |
1079 | qapi_free_UserDefOne(*obj); | |
1080 | *obj = NULL; | |
1081 | } | |
9ee86b85 | 1082 | out: |
297a3646 | 1083 | error_propagate(errp, err); |
b84da831 MR |
1084 | } |
1085 | ||
9ee86b85 | 1086 | void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp) |
b84da831 | 1087 | { |
6e2bb3ec | 1088 | Error *err = NULL; |
d9f62dde EB |
1089 | UserDefOneList *tail; |
1090 | size_t size = sizeof(**obj); | |
6e2bb3ec | 1091 | |
d9f62dde | 1092 | visit_start_list(v, name, (GenericList **)obj, size, &err); |
297a3646 MA |
1093 | if (err) { |
1094 | goto out; | |
1095 | } | |
1096 | ||
d9f62dde EB |
1097 | for (tail = *obj; tail; |
1098 | tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) { | |
1099 | visit_type_UserDefOne(v, NULL, &tail->value, &err); | |
1100 | if (err) { | |
1101 | break; | |
1102 | } | |
b84da831 | 1103 | } |
297a3646 | 1104 | |
1158bb2a | 1105 | visit_end_list(v, (void **)obj); |
68ab47e4 EB |
1106 | if (err && visit_is_input(v)) { |
1107 | qapi_free_UserDefOneList(*obj); | |
1108 | *obj = NULL; | |
1109 | } | |
297a3646 MA |
1110 | out: |
1111 | error_propagate(errp, err); | |
b84da831 | 1112 | } |
b84da831 | 1113 | |
b84da831 MR |
1114 | === scripts/qapi-commands.py === |
1115 | ||
9ee86b85 EB |
1116 | Used to generate the marshaling/dispatch functions for the commands |
1117 | defined in the schema. The generated code implements | |
bd6092e4 MAL |
1118 | qmp_marshal_COMMAND() (registered automatically), and declares |
1119 | qmp_COMMAND() that the user must implement. The following files are | |
1120 | generated: | |
b84da831 MR |
1121 | |
1122 | $(prefix)qmp-marshal.c: command marshal/dispatch functions for each | |
1123 | QMP command defined in the schema. Functions | |
1124 | generated by qapi-visit.py are used to | |
2542bfd5 | 1125 | convert QObjects received from the wire into |
b84da831 MR |
1126 | function parameters, and uses the same |
1127 | visitor functions to convert native C return | |
1128 | values to QObjects from transmission back | |
1129 | over the wire. | |
1130 | ||
1131 | $(prefix)qmp-commands.h: Function prototypes for the QMP commands | |
1132 | specified in the schema. | |
1133 | ||
1134 | Example: | |
1135 | ||
59a2c4ce | 1136 | $ python scripts/qapi-commands.py --output-dir="qapi-generated" |
16d80f61 | 1137 | --prefix="example-" example-schema.json |
9ee86b85 EB |
1138 | $ cat qapi-generated/example-qmp-commands.h |
1139 | [Uninteresting stuff omitted...] | |
1140 | ||
1141 | #ifndef EXAMPLE_QMP_COMMANDS_H | |
1142 | #define EXAMPLE_QMP_COMMANDS_H | |
1143 | ||
1144 | #include "example-qapi-types.h" | |
1145 | #include "qapi/qmp/qdict.h" | |
1146 | #include "qapi/error.h" | |
1147 | ||
1148 | UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp); | |
1149 | ||
1150 | #endif | |
87a560c4 | 1151 | $ cat qapi-generated/example-qmp-marshal.c |
6e2bb3ec | 1152 | [Uninteresting stuff omitted...] |
b84da831 | 1153 | |
56d92b00 | 1154 | static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp) |
b84da831 | 1155 | { |
2a0f50e8 | 1156 | Error *err = NULL; |
b84da831 MR |
1157 | Visitor *v; |
1158 | ||
7d5e199a | 1159 | v = qobject_output_visitor_new(ret_out); |
9ee86b85 | 1160 | visit_type_UserDefOne(v, "unused", &ret_in, &err); |
3b098d56 EB |
1161 | if (!err) { |
1162 | visit_complete(v, ret_out); | |
6e2bb3ec | 1163 | } |
2a0f50e8 | 1164 | error_propagate(errp, err); |
2c0ef9f4 EB |
1165 | visit_free(v); |
1166 | v = qapi_dealloc_visitor_new(); | |
9ee86b85 | 1167 | visit_type_UserDefOne(v, "unused", &ret_in, NULL); |
2c0ef9f4 | 1168 | visit_free(v); |
b84da831 MR |
1169 | } |
1170 | ||
7fad30f0 | 1171 | static void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp) |
b84da831 | 1172 | { |
2a0f50e8 | 1173 | Error *err = NULL; |
3f99144c | 1174 | UserDefOne *retval; |
b84da831 | 1175 | Visitor *v; |
9ee86b85 | 1176 | UserDefOneList *arg1 = NULL; |
b84da831 | 1177 | |
048abb7b | 1178 | v = qobject_input_visitor_new(QOBJECT(args)); |
ed841535 EB |
1179 | visit_start_struct(v, NULL, NULL, 0, &err); |
1180 | if (err) { | |
1181 | goto out; | |
1182 | } | |
9ee86b85 | 1183 | visit_type_UserDefOneList(v, "arg1", &arg1, &err); |
15c2f669 EB |
1184 | if (!err) { |
1185 | visit_check_struct(v, &err); | |
1186 | } | |
1158bb2a | 1187 | visit_end_struct(v, NULL); |
2a0f50e8 | 1188 | if (err) { |
b84da831 MR |
1189 | goto out; |
1190 | } | |
297a3646 | 1191 | |
2a0f50e8 EB |
1192 | retval = qmp_my_command(arg1, &err); |
1193 | if (err) { | |
297a3646 | 1194 | goto out; |
6e2bb3ec | 1195 | } |
b84da831 | 1196 | |
2a0f50e8 | 1197 | qmp_marshal_output_UserDefOne(retval, ret, &err); |
297a3646 | 1198 | |
b84da831 | 1199 | out: |
2a0f50e8 | 1200 | error_propagate(errp, err); |
2c0ef9f4 EB |
1201 | visit_free(v); |
1202 | v = qapi_dealloc_visitor_new(); | |
ed841535 | 1203 | visit_start_struct(v, NULL, NULL, 0, NULL); |
9ee86b85 | 1204 | visit_type_UserDefOneList(v, "arg1", &arg1, NULL); |
1158bb2a | 1205 | visit_end_struct(v, NULL); |
2c0ef9f4 | 1206 | visit_free(v); |
b84da831 MR |
1207 | } |
1208 | ||
1209 | static void qmp_init_marshal(void) | |
1210 | { | |
7fad30f0 | 1211 | qmp_register_command("my-command", qmp_marshal_my_command, QCO_NO_OPTIONS); |
b84da831 MR |
1212 | } |
1213 | ||
1214 | qapi_init(qmp_init_marshal); | |
59a2c4ce EB |
1215 | |
1216 | === scripts/qapi-event.py === | |
1217 | ||
9ee86b85 EB |
1218 | Used to generate the event-related C code defined by a schema, with |
1219 | implementations for qapi_event_send_FOO(). The following files are | |
1220 | created: | |
59a2c4ce EB |
1221 | |
1222 | $(prefix)qapi-event.h - Function prototypes for each event type, plus an | |
1223 | enumeration of all event names | |
1224 | $(prefix)qapi-event.c - Implementation of functions to send an event | |
1225 | ||
1226 | Example: | |
1227 | ||
1228 | $ python scripts/qapi-event.py --output-dir="qapi-generated" | |
16d80f61 | 1229 | --prefix="example-" example-schema.json |
9ee86b85 EB |
1230 | $ cat qapi-generated/example-qapi-event.h |
1231 | [Uninteresting stuff omitted...] | |
1232 | ||
1233 | #ifndef EXAMPLE_QAPI_EVENT_H | |
1234 | #define EXAMPLE_QAPI_EVENT_H | |
1235 | ||
1236 | #include "qapi/error.h" | |
1237 | #include "qapi/qmp/qdict.h" | |
1238 | #include "example-qapi-types.h" | |
1239 | ||
1240 | ||
1241 | void qapi_event_send_my_event(Error **errp); | |
1242 | ||
1243 | typedef enum example_QAPIEvent { | |
1244 | EXAMPLE_QAPI_EVENT_MY_EVENT = 0, | |
1245 | EXAMPLE_QAPI_EVENT__MAX = 1, | |
1246 | } example_QAPIEvent; | |
1247 | ||
1248 | extern const char *const example_QAPIEvent_lookup[]; | |
1249 | ||
1250 | #endif | |
59a2c4ce EB |
1251 | $ cat qapi-generated/example-qapi-event.c |
1252 | [Uninteresting stuff omitted...] | |
1253 | ||
1254 | void qapi_event_send_my_event(Error **errp) | |
1255 | { | |
1256 | QDict *qmp; | |
2a0f50e8 | 1257 | Error *err = NULL; |
59a2c4ce EB |
1258 | QMPEventFuncEmit emit; |
1259 | emit = qmp_event_get_func_emit(); | |
1260 | if (!emit) { | |
1261 | return; | |
1262 | } | |
1263 | ||
1264 | qmp = qmp_event_build_dict("MY_EVENT"); | |
1265 | ||
2a0f50e8 | 1266 | emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err); |
59a2c4ce | 1267 | |
2a0f50e8 | 1268 | error_propagate(errp, err); |
59a2c4ce EB |
1269 | QDECREF(qmp); |
1270 | } | |
1271 | ||
efd2eaa6 MA |
1272 | const char *const example_QAPIEvent_lookup[] = { |
1273 | [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", | |
7fb1cf16 | 1274 | [EXAMPLE_QAPI_EVENT__MAX] = NULL, |
59a2c4ce | 1275 | }; |
39a18158 MA |
1276 | |
1277 | === scripts/qapi-introspect.py === | |
1278 | ||
1279 | Used to generate the introspection C code for a schema. The following | |
1280 | files are created: | |
1281 | ||
1282 | $(prefix)qmp-introspect.c - Defines a string holding a JSON | |
1283 | description of the schema. | |
1284 | $(prefix)qmp-introspect.h - Declares the above string. | |
1285 | ||
1286 | Example: | |
1287 | ||
1288 | $ python scripts/qapi-introspect.py --output-dir="qapi-generated" | |
1289 | --prefix="example-" example-schema.json | |
39a18158 MA |
1290 | $ cat qapi-generated/example-qmp-introspect.h |
1291 | [Uninteresting stuff omitted...] | |
1292 | ||
1293 | #ifndef EXAMPLE_QMP_INTROSPECT_H | |
1294 | #define EXAMPLE_QMP_INTROSPECT_H | |
1295 | ||
1296 | extern const char example_qmp_schema_json[]; | |
1297 | ||
1298 | #endif | |
9ee86b85 EB |
1299 | $ cat qapi-generated/example-qmp-introspect.c |
1300 | [Uninteresting stuff omitted...] | |
1301 | ||
1302 | const char example_qmp_schema_json[] = "[" | |
1303 | "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, " | |
1304 | "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, " | |
1305 | "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, " | |
1306 | "{\"members\": [{\"name\": \"arg1\", \"type\": \"[2]\"}], \"meta-type\": \"object\", \"name\": \"1\"}, " | |
1307 | "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"default\": null, \"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, " | |
1308 | "{\"element-type\": \"2\", \"meta-type\": \"array\", \"name\": \"[2]\"}, " | |
1309 | "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, " | |
1310 | "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]"; |