]>
Commit | Line | Data |
---|---|---|
b84da831 MR |
1 | = How to use the QAPI code generator = |
2 | ||
6fb55451 EB |
3 | Copyright IBM Corp. 2011 |
4 | Copyright (C) 2012-2015 Red Hat, Inc. | |
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 EB |
46 | |
47 | Comments are allowed; anything between an unquoted # and the following | |
48 | newline is ignored. Although there is not yet a documentation | |
49 | generator, a form of stylized comments has developed for consistently | |
50 | documenting details about an expression and when it was added to the | |
51 | schema. The documentation is delimited between two lines of ##, then | |
52 | the first line names the expression, an optional overview is provided, | |
53 | then individual documentation about each member of 'data' is provided, | |
54 | and finally, a 'Since: x.y.z' tag lists the release that introduced | |
55 | the expression. Optional fields are tagged with the phrase | |
56 | '#optional', often with their default value; and extensions added | |
57 | after the expression was first released are also given a '(since | |
58 | x.y.z)' comment. For example: | |
59 | ||
60 | ## | |
61 | # @BlockStats: | |
62 | # | |
63 | # Statistics of a virtual block device or a block backing device. | |
64 | # | |
65 | # @device: #optional If the stats are for a virtual block device, the name | |
66 | # corresponding to the virtual block device. | |
67 | # | |
68 | # @stats: A @BlockDeviceStats for the device. | |
69 | # | |
70 | # @parent: #optional This describes the file block device if it has one. | |
71 | # | |
72 | # @backing: #optional This describes the backing block device if it has one. | |
73 | # (Since 2.0) | |
74 | # | |
75 | # Since: 0.14.0 | |
76 | ## | |
3b2a8b85 | 77 | { 'struct': 'BlockStats', |
e790e666 EB |
78 | 'data': {'*device': 'str', 'stats': 'BlockDeviceStats', |
79 | '*parent': 'BlockStats', | |
80 | '*backing': 'BlockStats'} } | |
81 | ||
82 | The schema sets up a series of types, as well as commands and events | |
83 | that will use those types. Forward references are allowed: the parser | |
84 | scans in two passes, where the first pass learns all type names, and | |
85 | the second validates the schema and generates the code. This allows | |
86 | the definition of complex structs that can have mutually recursive | |
363b4262 EB |
87 | types, and allows for indefinite nesting of Client JSON Protocol that |
88 | satisfies the schema. A type name should not be defined more than | |
89 | once. It is permissible for the schema to contain additional types | |
90 | not used by any commands or events in the Client JSON Protocol, for | |
91 | the side effect of generated C code used internally. | |
e790e666 | 92 | |
7b1b98c4 | 93 | There are seven top-level expressions recognized by the parser: |
3b2a8b85 | 94 | 'include', 'command', 'struct', 'enum', 'union', 'alternate', and |
7b1b98c4 EB |
95 | 'event'. There are several groups of types: simple types (a number of |
96 | built-in types, such as 'int' and 'str'; as well as enumerations), | |
97 | complex types (structs and two flavors of unions), and alternate types | |
98 | (a choice between other types). The 'command' and 'event' expressions | |
e790e666 EB |
99 | can refer to existing types by name, or list an anonymous type as a |
100 | dictionary. Listing a type name inside an array refers to a | |
101 | single-dimension array of that type; multi-dimension arrays are not | |
102 | directly supported (although an array of a complex struct that | |
103 | contains an array member is possible). | |
104 | ||
105 | Types, commands, and events share a common namespace. Therefore, | |
106 | generally speaking, type definitions should always use CamelCase for | |
107 | user-defined type names, while built-in types are lowercase. Type | |
108 | definitions should not end in 'Kind', as this namespace is used for | |
255960dd EB |
109 | creating implicit C enums for visiting union types, or in 'List', as |
110 | this namespace is used for creating array types. Command names, | |
e790e666 EB |
111 | and field names within a type, should be all lower case with words |
112 | separated by a hyphen. However, some existing older commands and | |
113 | complex types use underscore; when extending such expressions, | |
114 | consistency is preferred over blindly avoiding underscore. Event | |
9fb081e0 EB |
115 | names should be ALL_CAPS with words separated by underscore. Field |
116 | names cannot start with 'has-' or 'has_', as this is reserved for | |
117 | tracking optional fields. | |
e790e666 EB |
118 | |
119 | Any name (command, event, type, field, or enum value) beginning with | |
120 | "x-" is marked experimental, and may be withdrawn or changed | |
121 | incompatibly in a future release. Downstream vendors may add | |
122 | extensions; such extensions should begin with a prefix matching | |
123 | "__RFQDN_" (for the reverse-fully-qualified-domain-name of the | |
124 | vendor), even if the rest of the name uses dash (example: | |
125 | __com.redhat_drive-mirror). Other than downstream extensions (with | |
126 | leading underscore and the use of dots), all names should begin with a | |
127 | letter, and contain only ASCII letters, digits, dash, and underscore. | |
9fb081e0 EB |
128 | Names beginning with 'q_' are reserved for the generator: QMP names |
129 | that resemble C keywords or other problematic strings will be munged | |
130 | in C to use this prefix. For example, a field named "default" in | |
131 | qapi becomes "q_default" in the generated C code. | |
e790e666 EB |
132 | |
133 | In the rest of this document, usage lines are given for each | |
134 | expression type, with literal strings written in lower case and | |
135 | placeholders written in capitals. If a literal string includes a | |
136 | prefix of '*', that key/value pair can be omitted from the expression. | |
3b2a8b85 | 137 | For example, a usage statement that includes '*base':STRUCT-NAME |
e790e666 | 138 | means that an expression has an optional key 'base', which if present |
3b2a8b85 | 139 | must have a value that forms a struct name. |
e790e666 EB |
140 | |
141 | ||
142 | === Built-in Types === | |
143 | ||
f133f2db MA |
144 | The following types are predefined, and map to C as follows: |
145 | ||
146 | Schema C JSON | |
147 | str char * any JSON string, UTF-8 | |
148 | number double any JSON number | |
149 | int int64_t a JSON number without fractional part | |
150 | that fits into the C integer type | |
151 | int8 int8_t likewise | |
152 | int16 int16_t likewise | |
153 | int32 int32_t likewise | |
154 | int64 int64_t likewise | |
155 | uint8 uint8_t likewise | |
156 | uint16 uint16_t likewise | |
157 | uint32 uint32_t likewise | |
158 | uint64 uint64_t likewise | |
159 | size uint64_t like uint64_t, except StringInputVisitor | |
160 | accepts size suffixes | |
161 | bool bool JSON true or false | |
28770e05 | 162 | any QObject * any JSON value |
51631493 | 163 | |
a719a27c LV |
164 | |
165 | === Includes === | |
166 | ||
e790e666 EB |
167 | Usage: { 'include': STRING } |
168 | ||
a719a27c LV |
169 | The QAPI schema definitions can be modularized using the 'include' directive: |
170 | ||
e790e666 | 171 | { 'include': 'path/to/file.json' } |
a719a27c LV |
172 | |
173 | The directive is evaluated recursively, and include paths are relative to the | |
e790e666 | 174 | file using the directive. Multiple includes of the same file are |
4247f839 | 175 | idempotent. No other keys should appear in the expression, and the include |
e790e666 EB |
176 | value should be a string. |
177 | ||
178 | As a matter of style, it is a good idea to have all files be | |
179 | self-contained, but at the moment, nothing prevents an included file | |
180 | from making a forward reference to a type that is only introduced by | |
181 | an outer file. The parser may be made stricter in the future to | |
182 | prevent incomplete include files. | |
a719a27c LV |
183 | |
184 | ||
3b2a8b85 | 185 | === Struct types === |
51631493 | 186 | |
3b2a8b85 | 187 | Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME } |
e790e666 | 188 | |
3b2a8b85 | 189 | A struct is a dictionary containing a single 'data' key whose |
e790e666 EB |
190 | value is a dictionary. This corresponds to a struct in C or an Object |
191 | in JSON. Each value of the 'data' dictionary must be the name of a | |
192 | type, or a one-element array containing a type name. An example of a | |
3b2a8b85 | 193 | struct is: |
b84da831 | 194 | |
3b2a8b85 | 195 | { 'struct': 'MyType', |
acf8394e | 196 | 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } |
b84da831 | 197 | |
e790e666 | 198 | The use of '*' as a prefix to the name means the member is optional in |
363b4262 | 199 | the corresponding JSON protocol usage. |
cc162655 EB |
200 | |
201 | The default initialization value of an optional argument should not be changed | |
202 | between versions of QEMU unless the new default maintains backward | |
203 | compatibility to the user-visible behavior of the old default. | |
204 | ||
205 | With proper documentation, this policy still allows some flexibility; for | |
206 | example, documenting that a default of 0 picks an optimal buffer size allows | |
207 | one release to declare the optimal size at 512 while another release declares | |
208 | the optimal size at 4096 - the user-visible behavior is not the bytes used by | |
209 | the buffer, but the fact that the buffer was optimal size. | |
210 | ||
211 | On input structures (only mentioned in the 'data' side of a command), changing | |
212 | from mandatory to optional is safe (older clients will supply the option, and | |
213 | newer clients can benefit from the default); changing from optional to | |
214 | mandatory is backwards incompatible (older clients may be omitting the option, | |
215 | and must continue to work). | |
216 | ||
217 | On output structures (only mentioned in the 'returns' side of a command), | |
218 | changing from mandatory to optional is in general unsafe (older clients may be | |
219 | expecting the field, and could crash if it is missing), although it can be done | |
220 | if the only way that the optional argument will be omitted is when it is | |
221 | triggered by the presence of a new input flag to the command that older clients | |
222 | don't know to send. Changing from optional to mandatory is safe. | |
223 | ||
224 | A structure that is used in both input and output of various commands | |
225 | must consider the backwards compatibility constraints of both directions | |
226 | of use. | |
622f557f | 227 | |
3b2a8b85 | 228 | A struct definition can specify another struct as its base. |
622f557f | 229 | In this case, the fields of the base type are included as top-level fields |
363b4262 EB |
230 | of the new struct's dictionary in the Client JSON Protocol wire |
231 | format. An example definition is: | |
622f557f | 232 | |
3b2a8b85 EB |
233 | { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } |
234 | { 'struct': 'BlockdevOptionsGenericCOWFormat', | |
622f557f KW |
235 | 'base': 'BlockdevOptionsGenericFormat', |
236 | 'data': { '*backing': 'str' } } | |
237 | ||
238 | An example BlockdevOptionsGenericCOWFormat object on the wire could use | |
239 | both fields like this: | |
240 | ||
241 | { "file": "/some/place/my-image", | |
242 | "backing": "/some/place/my-backing-file" } | |
243 | ||
e790e666 | 244 | |
51631493 KW |
245 | === Enumeration types === |
246 | ||
e790e666 | 247 | Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING } |
351d36e4 | 248 | { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING } |
e790e666 EB |
249 | |
250 | An enumeration type is a dictionary containing a single 'data' key | |
251 | whose value is a list of strings. An example enumeration is: | |
b84da831 MR |
252 | |
253 | { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } | |
254 | ||
e790e666 EB |
255 | Nothing prevents an empty enumeration, although it is probably not |
256 | useful. The list of strings should be lower case; if an enum name | |
257 | represents multiple words, use '-' between words. The string 'max' is | |
258 | not allowed as an enum value, and values should not be repeated. | |
259 | ||
351d36e4 DB |
260 | The enum constants will be named by using a heuristic to turn the |
261 | type name into a set of underscore separated words. For the example | |
262 | above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name | |
263 | of 'MY_ENUM_VALUE1' for the first value. If the default heuristic | |
264 | does not result in a desirable name, the optional 'prefix' field | |
265 | can be used when defining the enum. | |
266 | ||
363b4262 EB |
267 | The enumeration values are passed as strings over the Client JSON |
268 | Protocol, but are encoded as C enum integral values in generated code. | |
269 | While the C code starts numbering at 0, it is better to use explicit | |
e790e666 EB |
270 | comparisons to enum values than implicit comparisons to 0; the C code |
271 | will also include a generated enum member ending in _MAX for tracking | |
272 | the size of the enum, useful when using common functions for | |
273 | converting between strings and enum values. Since the wire format | |
274 | always passes by name, it is acceptable to reorder or add new | |
363b4262 EB |
275 | enumeration members in any location without breaking clients of Client |
276 | JSON Protocol; however, removing enum values would break | |
277 | compatibility. For any struct that has a field that will only contain | |
278 | a finite set of string values, using an enum type for that field is | |
279 | better than open-coding the field to be type 'str'. | |
e790e666 EB |
280 | |
281 | ||
51631493 KW |
282 | === Union types === |
283 | ||
e790e666 | 284 | Usage: { 'union': STRING, 'data': DICT } |
3b2a8b85 | 285 | or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME, |
e790e666 | 286 | 'discriminator': ENUM-MEMBER-OF-BASE } |
51631493 | 287 | |
e790e666 | 288 | Union types are used to let the user choose between several different |
7b1b98c4 EB |
289 | variants for an object. There are two flavors: simple (no |
290 | discriminator or base), flat (both discriminator and base). A union | |
291 | type is defined using a data dictionary as explained in the following | |
292 | paragraphs. | |
51631493 | 293 | |
e790e666 EB |
294 | A simple union type defines a mapping from automatic discriminator |
295 | values to data types like in this example: | |
51631493 | 296 | |
3b2a8b85 EB |
297 | { 'struct': 'FileOptions', 'data': { 'filename': 'str' } } |
298 | { 'struct': 'Qcow2Options', | |
51631493 KW |
299 | 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } } |
300 | ||
301 | { 'union': 'BlockdevOptions', | |
302 | 'data': { 'file': 'FileOptions', | |
303 | 'qcow2': 'Qcow2Options' } } | |
304 | ||
363b4262 EB |
305 | In the Client JSON Protocol, a simple union is represented by a |
306 | dictionary that contains the 'type' field as a discriminator, and a | |
307 | 'data' field that is of the specified data type corresponding to the | |
308 | discriminator value, as in these examples: | |
51631493 | 309 | |
e790e666 | 310 | { "type": "file", "data" : { "filename": "/some/place/my-image" } } |
51631493 KW |
311 | { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image", |
312 | "lazy-refcounts": true } } | |
313 | ||
e790e666 EB |
314 | The generated C code uses a struct containing a union. Additionally, |
315 | an implicit C enum 'NameKind' is created, corresponding to the union | |
316 | 'Name', for accessing the various branches of the union. No branch of | |
317 | the union can be named 'max', as this would collide with the implicit | |
318 | enum. The value for each branch can be of any type. | |
51631493 | 319 | |
3b2a8b85 | 320 | A flat union definition specifies a struct as its base, and |
e790e666 EB |
321 | avoids nesting on the wire. All branches of the union must be |
322 | complex types, and the top-level fields of the union dictionary on | |
323 | the wire will be combination of fields from both the base type and the | |
324 | appropriate branch type (when merging two dictionaries, there must be | |
325 | no keys in common). The 'discriminator' field must be the name of an | |
3b2a8b85 | 326 | enum-typed member of the base struct. |
51631493 | 327 | |
e790e666 EB |
328 | The following example enhances the above simple union example by |
329 | adding a common field 'readonly', renaming the discriminator to | |
330 | something more applicable, and reducing the number of {} required on | |
331 | the wire: | |
50f2bdc7 | 332 | |
94a3f0af | 333 | { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] } |
3b2a8b85 | 334 | { 'struct': 'BlockdevCommonOptions', |
bceae769 | 335 | 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } } |
50f2bdc7 KW |
336 | { 'union': 'BlockdevOptions', |
337 | 'base': 'BlockdevCommonOptions', | |
338 | 'discriminator': 'driver', | |
e790e666 | 339 | 'data': { 'file': 'FileOptions', |
50f2bdc7 KW |
340 | 'qcow2': 'Qcow2Options' } } |
341 | ||
e790e666 EB |
342 | Resulting in these JSON objects: |
343 | ||
344 | { "driver": "file", "readonly": true, | |
345 | "filename": "/some/place/my-image" } | |
346 | { "driver": "qcow2", "readonly": false, | |
347 | "backing-file": "/some/place/my-image", "lazy-refcounts": true } | |
348 | ||
349 | Notice that in a flat union, the discriminator name is controlled by | |
350 | the user, but because it must map to a base member with enum type, the | |
351 | code generator can ensure that branches exist for all values of the | |
352 | enum (although the order of the keys need not match the declaration of | |
353 | the enum). In the resulting generated C data types, a flat union is | |
354 | represented as a struct with the base member fields included directly, | |
355 | and then a union of structures for each branch of the struct. | |
356 | ||
357 | A simple union can always be re-written as a flat union where the base | |
358 | class has a single member named 'type', and where each branch of the | |
3b2a8b85 | 359 | union has a struct with a single member named 'data'. That is, |
50f2bdc7 | 360 | |
e790e666 | 361 | { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } } |
50f2bdc7 | 362 | |
e790e666 | 363 | is identical on the wire to: |
50f2bdc7 | 364 | |
e790e666 | 365 | { 'enum': 'Enum', 'data': ['one', 'two'] } |
3b2a8b85 EB |
366 | { 'struct': 'Base', 'data': { 'type': 'Enum' } } |
367 | { 'struct': 'Branch1', 'data': { 'data': 'str' } } | |
368 | { 'struct': 'Branch2', 'data': { 'data': 'int' } } | |
94a3f0af | 369 | { 'union': 'Flat', 'base': 'Base', 'discriminator': 'type', |
e790e666 | 370 | 'data': { 'one': 'Branch1', 'two': 'Branch2' } } |
69dd62df | 371 | |
e790e666 | 372 | |
7b1b98c4 | 373 | === Alternate types === |
69dd62df | 374 | |
7b1b98c4 EB |
375 | Usage: { 'alternate': STRING, 'data': DICT } |
376 | ||
377 | An alternate type is one that allows a choice between two or more JSON | |
378 | data types (string, integer, number, or object, but currently not | |
379 | array) on the wire. The definition is similar to a simple union type, | |
380 | where each branch of the union names a QAPI type. For example: | |
381 | ||
382 | { 'alternate': 'BlockRef', | |
69dd62df KW |
383 | 'data': { 'definition': 'BlockdevOptions', |
384 | 'reference': 'str' } } | |
385 | ||
7b1b98c4 EB |
386 | Just like for a simple union, an implicit C enum 'NameKind' is created |
387 | to enumerate the branches for the alternate 'Name'. | |
388 | ||
389 | Unlike a union, the discriminator string is never passed on the wire | |
363b4262 EB |
390 | for the Client JSON Protocol. Instead, the value's JSON type serves |
391 | as an implicit discriminator, which in turn means that an alternate | |
392 | can only express a choice between types represented differently in | |
393 | JSON. If a branch is typed as the 'bool' built-in, the alternate | |
394 | accepts true and false; if it is typed as any of the various numeric | |
395 | built-ins, it accepts a JSON number; if it is typed as a 'str' | |
396 | built-in or named enum type, it accepts a JSON string; and if it is | |
397 | typed as a complex type (struct or union), it accepts a JSON object. | |
398 | Two different complex types, for instance, aren't permitted, because | |
399 | both are represented as a JSON object. | |
7b1b98c4 EB |
400 | |
401 | The example alternate declaration above allows using both of the | |
402 | following example objects: | |
69dd62df KW |
403 | |
404 | { "file": "my_existing_block_device_id" } | |
405 | { "file": { "driver": "file", | |
406 | "readonly": false, | |
63922c64 | 407 | "filename": "/tmp/mydisk.qcow2" } } |
69dd62df KW |
408 | |
409 | ||
51631493 | 410 | === Commands === |
b84da831 | 411 | |
e790e666 | 412 | Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, |
9b090d42 | 413 | '*returns': TYPE-NAME, |
e790e666 EB |
414 | '*gen': false, '*success-response': false } |
415 | ||
416 | Commands are defined by using a dictionary containing several members, | |
417 | where three members are most common. The 'command' member is a | |
363b4262 EB |
418 | mandatory string, and determines the "execute" value passed in a |
419 | Client JSON Protocol command exchange. | |
e790e666 EB |
420 | |
421 | The 'data' argument maps to the "arguments" dictionary passed in as | |
363b4262 EB |
422 | part of a Client JSON Protocol command. The 'data' member is optional |
423 | and defaults to {} (an empty dictionary). If present, it must be the | |
315932b5 MA |
424 | string name of a complex type, or a dictionary that declares an |
425 | anonymous type with the same semantics as a 'struct' expression, with | |
426 | one exception noted below when 'gen' is used. | |
e790e666 EB |
427 | |
428 | The 'returns' member describes what will appear in the "return" field | |
363b4262 EB |
429 | of a Client JSON Protocol reply on successful completion of a command. |
430 | The member is optional from the command declaration; if absent, the | |
431 | "return" field will be an empty dictionary. If 'returns' is present, | |
432 | it must be the string name of a complex or built-in type, a | |
433 | one-element array containing the name of a complex or built-in type, | |
9b090d42 MA |
434 | with one exception noted below when 'gen' is used. Although it is |
435 | permitted to have the 'returns' member name a built-in type or an | |
436 | array of built-in types, any command that does this cannot be extended | |
437 | to return additional information in the future; thus, new commands | |
438 | should strongly consider returning a dictionary-based type or an array | |
439 | of dictionaries, even if the dictionary only contains one field at the | |
440 | present. | |
363b4262 EB |
441 | |
442 | All commands in Client JSON Protocol use a dictionary to report | |
443 | failure, with no way to specify that in QAPI. Where the error return | |
444 | is different than the usual GenericError class in order to help the | |
445 | client react differently to certain error conditions, it is worth | |
446 | documenting this in the comments before the command declaration. | |
e790e666 EB |
447 | |
448 | Some example commands: | |
449 | ||
450 | { 'command': 'my-first-command', | |
451 | 'data': { 'arg1': 'str', '*arg2': 'str' } } | |
3b2a8b85 | 452 | { 'struct': 'MyType', 'data': { '*value': 'str' } } |
e790e666 EB |
453 | { 'command': 'my-second-command', |
454 | 'returns': [ 'MyType' ] } | |
455 | ||
363b4262 | 456 | which would validate this Client JSON Protocol transaction: |
e790e666 EB |
457 | |
458 | => { "execute": "my-first-command", | |
459 | "arguments": { "arg1": "hello" } } | |
460 | <= { "return": { } } | |
461 | => { "execute": "my-second-command" } | |
462 | <= { "return": [ { "value": "one" }, { } ] } | |
463 | ||
464 | In rare cases, QAPI cannot express a type-safe representation of a | |
2d21291a MA |
465 | corresponding Client JSON Protocol command. You then have to suppress |
466 | generation of a marshalling function by including a key 'gen' with | |
467 | boolean value false, and instead write your own function. Please try | |
468 | to avoid adding new commands that rely on this, and instead use | |
469 | type-safe unions. For an example of this usage: | |
e790e666 EB |
470 | |
471 | { 'command': 'netdev_add', | |
b8a98326 | 472 | 'data': {'type': 'str', 'id': 'str'}, |
e790e666 EB |
473 | 'gen': false } |
474 | ||
475 | Normally, the QAPI schema is used to describe synchronous exchanges, | |
476 | where a response is expected. But in some cases, the action of a | |
477 | command is expected to change state in a way that a successful | |
478 | response is not possible (although the command will still return a | |
479 | normal dictionary error on failure). When a successful reply is not | |
480 | possible, the command expression should include the optional key | |
481 | 'success-response' with boolean value false. So far, only QGA makes | |
482 | use of this field. | |
b84da831 | 483 | |
b84da831 | 484 | |
21cd70df WX |
485 | === Events === |
486 | ||
e790e666 EB |
487 | Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT } |
488 | ||
489 | Events are defined with the keyword 'event'. It is not allowed to | |
490 | name an event 'MAX', since the generator also produces a C enumeration | |
491 | of all event names with a generated _MAX value at the end. When | |
492 | 'data' is also specified, additional info will be included in the | |
3b2a8b85 | 493 | event, with similar semantics to a 'struct' expression. Finally there |
e790e666 EB |
494 | will be C API generated in qapi-event.h; when called by QEMU code, a |
495 | message with timestamp will be emitted on the wire. | |
21cd70df WX |
496 | |
497 | An example event is: | |
498 | ||
499 | { 'event': 'EVENT_C', | |
500 | 'data': { '*a': 'int', 'b': 'str' } } | |
501 | ||
502 | Resulting in this JSON object: | |
503 | ||
504 | { "event": "EVENT_C", | |
505 | "data": { "b": "test string" }, | |
506 | "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } | |
b84da831 | 507 | |
59a2c4ce | 508 | |
39a18158 MA |
509 | == Client JSON Protocol introspection == |
510 | ||
511 | Clients of a Client JSON Protocol commonly need to figure out what | |
512 | exactly the server (QEMU) supports. | |
513 | ||
514 | For this purpose, QMP provides introspection via command | |
515 | query-qmp-schema. QGA currently doesn't support introspection. | |
516 | ||
517 | query-qmp-schema returns a JSON array of SchemaInfo objects. These | |
518 | objects together describe the wire ABI, as defined in the QAPI schema. | |
f5455044 EB |
519 | There is no specified order to the SchemaInfo objects returned; a |
520 | client must search for a particular name throughout the entire array | |
521 | to learn more about that name, but is at least guaranteed that there | |
522 | will be no collisions between type, command, and event names. | |
39a18158 MA |
523 | |
524 | However, the SchemaInfo can't reflect all the rules and restrictions | |
525 | that apply to QMP. It's interface introspection (figuring out what's | |
526 | there), not interface specification. The specification is in the QAPI | |
527 | schema. To understand how QMP is to be used, you need to study the | |
528 | QAPI schema. | |
529 | ||
530 | Like any other command, query-qmp-schema is itself defined in the QAPI | |
531 | schema, along with the SchemaInfo type. This text attempts to give an | |
532 | overview how things work. For details you need to consult the QAPI | |
533 | schema. | |
534 | ||
535 | SchemaInfo objects have common members "name" and "meta-type", and | |
536 | additional variant members depending on the value of meta-type. | |
537 | ||
538 | Each SchemaInfo object describes a wire ABI entity of a certain | |
539 | meta-type: a command, event or one of several kinds of type. | |
540 | ||
1a9a507b MA |
541 | SchemaInfo for commands and events have the same name as in the QAPI |
542 | schema. | |
39a18158 MA |
543 | |
544 | Command and event names are part of the wire ABI, but type names are | |
1a9a507b MA |
545 | not. Therefore, the SchemaInfo for types have auto-generated |
546 | meaningless names. For readability, the examples in this section use | |
547 | meaningful type names instead. | |
548 | ||
549 | To examine a type, start with a command or event using it, then follow | |
550 | references by name. | |
39a18158 MA |
551 | |
552 | QAPI schema definitions not reachable that way are omitted. | |
553 | ||
554 | The SchemaInfo for a command has meta-type "command", and variant | |
555 | members "arg-type" and "ret-type". On the wire, the "arguments" | |
556 | member of a client's "execute" command must conform to the object type | |
557 | named by "arg-type". The "return" member that the server passes in a | |
558 | success response conforms to the type named by "ret-type". | |
559 | ||
560 | If the command takes no arguments, "arg-type" names an object type | |
561 | without members. Likewise, if the command returns nothing, "ret-type" | |
562 | names an object type without members. | |
563 | ||
564 | Example: the SchemaInfo for command query-qmp-schema | |
565 | ||
566 | { "name": "query-qmp-schema", "meta-type": "command", | |
567 | "arg-type": ":empty", "ret-type": "SchemaInfoList" } | |
568 | ||
569 | Type ":empty" is an object type without members, and type | |
570 | "SchemaInfoList" is the array of SchemaInfo type. | |
571 | ||
572 | The SchemaInfo for an event has meta-type "event", and variant member | |
573 | "arg-type". On the wire, a "data" member that the server passes in an | |
574 | event conforms to the object type named by "arg-type". | |
575 | ||
576 | If the event carries no additional information, "arg-type" names an | |
577 | object type without members. The event may not have a data member on | |
578 | the wire then. | |
579 | ||
580 | Each command or event defined with dictionary-valued 'data' in the | |
1a9a507b | 581 | QAPI schema implicitly defines an object type. |
39a18158 MA |
582 | |
583 | Example: the SchemaInfo for EVENT_C from section Events | |
584 | ||
585 | { "name": "EVENT_C", "meta-type": "event", | |
586 | "arg-type": ":obj-EVENT_C-arg" } | |
587 | ||
588 | Type ":obj-EVENT_C-arg" is an implicitly defined object type with | |
589 | the two members from the event's definition. | |
590 | ||
591 | The SchemaInfo for struct and union types has meta-type "object". | |
592 | ||
593 | The SchemaInfo for a struct type has variant member "members". | |
594 | ||
595 | The SchemaInfo for a union type additionally has variant members "tag" | |
596 | and "variants". | |
597 | ||
598 | "members" is a JSON array describing the object's common members, if | |
599 | any. Each element is a JSON object with members "name" (the member's | |
600 | name), "type" (the name of its type), and optionally "default". The | |
601 | member is optional if "default" is present. Currently, "default" can | |
602 | only have value null. Other values are reserved for future | |
f5455044 EB |
603 | extensions. The "members" array is in no particular order; clients |
604 | must search the entire object when learning whether a particular | |
605 | member is supported. | |
39a18158 MA |
606 | |
607 | Example: the SchemaInfo for MyType from section Struct types | |
608 | ||
609 | { "name": "MyType", "meta-type": "object", | |
610 | "members": [ | |
611 | { "name": "member1", "type": "str" }, | |
612 | { "name": "member2", "type": "int" }, | |
613 | { "name": "member3", "type": "str", "default": null } ] } | |
614 | ||
615 | "tag" is the name of the common member serving as type tag. | |
616 | "variants" is a JSON array describing the object's variant members. | |
617 | Each element is a JSON object with members "case" (the value of type | |
618 | tag this element applies to) and "type" (the name of an object type | |
f5455044 EB |
619 | that provides the variant members for this type tag value). The |
620 | "variants" array is in no particular order, and is not guaranteed to | |
621 | list cases in the same order as the corresponding "tag" enum type. | |
39a18158 MA |
622 | |
623 | Example: the SchemaInfo for flat union BlockdevOptions from section | |
624 | Union types | |
625 | ||
626 | { "name": "BlockdevOptions", "meta-type": "object", | |
627 | "members": [ | |
628 | { "name": "driver", "type": "BlockdevDriver" }, | |
629 | { "name": "readonly", "type": "bool"} ], | |
630 | "tag": "driver", | |
631 | "variants": [ | |
632 | { "case": "file", "type": "FileOptions" }, | |
633 | { "case": "qcow2", "type": "Qcow2Options" } ] } | |
634 | ||
635 | Note that base types are "flattened": its members are included in the | |
636 | "members" array. | |
637 | ||
638 | A simple union implicitly defines an enumeration type for its implicit | |
639 | discriminator (called "type" on the wire, see section Union types). | |
39a18158 MA |
640 | |
641 | A simple union implicitly defines an object type for each of its | |
1a9a507b | 642 | variants. |
39a18158 MA |
643 | |
644 | Example: the SchemaInfo for simple union BlockdevOptions from section | |
645 | Union types | |
646 | ||
647 | { "name": "BlockdevOptions", "meta-type": "object", | |
648 | "members": [ | |
649 | { "name": "kind", "type": "BlockdevOptionsKind" } ], | |
650 | "tag": "type", | |
651 | "variants": [ | |
652 | { "case": "file", "type": ":obj-FileOptions-wrapper" }, | |
653 | { "case": "qcow2", "type": ":obj-Qcow2Options-wrapper" } ] } | |
654 | ||
655 | Enumeration type "BlockdevOptionsKind" and the object types | |
656 | ":obj-FileOptions-wrapper", ":obj-Qcow2Options-wrapper" are | |
657 | implicitly defined. | |
658 | ||
659 | The SchemaInfo for an alternate type has meta-type "alternate", and | |
660 | variant member "members". "members" is a JSON array. Each element is | |
661 | a JSON object with member "type", which names a type. Values of the | |
f5455044 EB |
662 | alternate type conform to exactly one of its member types. There is |
663 | no guarantee on the order in which "members" will be listed. | |
39a18158 MA |
664 | |
665 | Example: the SchemaInfo for BlockRef from section Alternate types | |
666 | ||
667 | { "name": "BlockRef", "meta-type": "alternate", | |
668 | "members": [ | |
669 | { "type": "BlockdevOptions" }, | |
670 | { "type": "str" } ] } | |
671 | ||
672 | The SchemaInfo for an array type has meta-type "array", and variant | |
673 | member "element-type", which names the array's element type. Array | |
ce5fcb47 EB |
674 | types are implicitly defined. For convenience, the array's name may |
675 | resemble the element type; however, clients should examine member | |
676 | "element-type" instead of making assumptions based on parsing member | |
677 | "name". | |
39a18158 MA |
678 | |
679 | Example: the SchemaInfo for ['str'] | |
680 | ||
ce5fcb47 | 681 | { "name": "[str]", "meta-type": "array", |
39a18158 MA |
682 | "element-type": "str" } |
683 | ||
684 | The SchemaInfo for an enumeration type has meta-type "enum" and | |
f5455044 EB |
685 | variant member "values". The values are listed in no particular |
686 | order; clients must search the entire enum when learning whether a | |
687 | particular value is supported. | |
39a18158 MA |
688 | |
689 | Example: the SchemaInfo for MyEnum from section Enumeration types | |
690 | ||
691 | { "name": "MyEnum", "meta-type": "enum", | |
692 | "values": [ "value1", "value2", "value3" ] } | |
693 | ||
694 | The SchemaInfo for a built-in type has the same name as the type in | |
695 | the QAPI schema (see section Built-in Types), with one exception | |
696 | detailed below. It has variant member "json-type" that shows how | |
697 | values of this type are encoded on the wire. | |
698 | ||
699 | Example: the SchemaInfo for str | |
700 | ||
701 | { "name": "str", "meta-type": "builtin", "json-type": "string" } | |
702 | ||
703 | The QAPI schema supports a number of integer types that only differ in | |
704 | how they map to C. They are identical as far as SchemaInfo is | |
705 | concerned. Therefore, they get all mapped to a single type "int" in | |
706 | SchemaInfo. | |
707 | ||
708 | As explained above, type names are not part of the wire ABI. Not even | |
709 | the names of built-in types. Clients should examine member | |
710 | "json-type" instead of hard-coding names of built-in types. | |
711 | ||
712 | ||
b84da831 MR |
713 | == Code generation == |
714 | ||
39a18158 MA |
715 | Schemas are fed into four scripts to generate all the code/files that, |
716 | paired with the core QAPI libraries, comprise everything required to | |
717 | take JSON commands read in by a Client JSON Protocol server, unmarshal | |
718 | the arguments into the underlying C types, call into the corresponding | |
719 | C function, and map the response back to a Client JSON Protocol | |
720 | response to be returned to the user. | |
b84da831 MR |
721 | |
722 | As an example, we'll use the following schema, which describes a single | |
723 | complex user-defined type (which will produce a C struct, along with a list | |
724 | node structure that can be used to chain together a list of such types in | |
725 | case we want to accept/return a list of this type with a command), and a | |
726 | command which takes that type as a parameter and returns the same type: | |
727 | ||
87a560c4 | 728 | $ cat example-schema.json |
3b2a8b85 | 729 | { 'struct': 'UserDefOne', |
b84da831 MR |
730 | 'data': { 'integer': 'int', 'string': 'str' } } |
731 | ||
732 | { 'command': 'my-command', | |
733 | 'data': {'arg1': 'UserDefOne'}, | |
734 | 'returns': 'UserDefOne' } | |
b84da831 | 735 | |
59a2c4ce EB |
736 | { 'event': 'MY_EVENT' } |
737 | ||
b84da831 MR |
738 | === scripts/qapi-types.py === |
739 | ||
740 | Used to generate the C types defined by a schema. The following files are | |
741 | created: | |
742 | ||
743 | $(prefix)qapi-types.h - C types corresponding to types defined in | |
744 | the schema you pass in | |
745 | $(prefix)qapi-types.c - Cleanup functions for the above C types | |
746 | ||
747 | The $(prefix) is an optional parameter used as a namespace to keep the | |
748 | generated code from one schema/code-generation separated from others so code | |
749 | can be generated/used from multiple schemas without clobbering previously | |
750 | created code. | |
751 | ||
752 | Example: | |
753 | ||
87a560c4 | 754 | $ python scripts/qapi-types.py --output-dir="qapi-generated" \ |
16d80f61 | 755 | --prefix="example-" example-schema.json |
87a560c4 | 756 | $ cat qapi-generated/example-qapi-types.c |
6e2bb3ec MA |
757 | [Uninteresting stuff omitted...] |
758 | ||
2b162ccb | 759 | void qapi_free_UserDefOne(UserDefOne *obj) |
6e2bb3ec | 760 | { |
f8b7f1a8 | 761 | QapiDeallocVisitor *qdv; |
6e2bb3ec MA |
762 | Visitor *v; |
763 | ||
764 | if (!obj) { | |
765 | return; | |
766 | } | |
767 | ||
f8b7f1a8 EB |
768 | qdv = qapi_dealloc_visitor_new(); |
769 | v = qapi_dealloc_get_visitor(qdv); | |
2b162ccb | 770 | visit_type_UserDefOne(v, &obj, NULL, NULL); |
f8b7f1a8 | 771 | qapi_dealloc_visitor_cleanup(qdv); |
6e2bb3ec | 772 | } |
b84da831 | 773 | |
2b162ccb | 774 | void qapi_free_UserDefOneList(UserDefOneList *obj) |
b84da831 | 775 | { |
f8b7f1a8 | 776 | QapiDeallocVisitor *qdv; |
b84da831 MR |
777 | Visitor *v; |
778 | ||
779 | if (!obj) { | |
780 | return; | |
781 | } | |
782 | ||
f8b7f1a8 EB |
783 | qdv = qapi_dealloc_visitor_new(); |
784 | v = qapi_dealloc_get_visitor(qdv); | |
2b162ccb | 785 | visit_type_UserDefOneList(v, &obj, NULL, NULL); |
f8b7f1a8 | 786 | qapi_dealloc_visitor_cleanup(qdv); |
b84da831 | 787 | } |
87a560c4 | 788 | $ cat qapi-generated/example-qapi-types.h |
6e2bb3ec MA |
789 | [Uninteresting stuff omitted...] |
790 | ||
791 | #ifndef EXAMPLE_QAPI_TYPES_H | |
792 | #define EXAMPLE_QAPI_TYPES_H | |
b84da831 | 793 | |
e790e666 | 794 | [Built-in types omitted...] |
b84da831 MR |
795 | |
796 | typedef struct UserDefOne UserDefOne; | |
797 | ||
2b162ccb MA |
798 | typedef struct UserDefOneList UserDefOneList; |
799 | ||
800 | struct UserDefOne { | |
801 | int64_t integer; | |
802 | char *string; | |
803 | }; | |
804 | ||
805 | void qapi_free_UserDefOne(UserDefOne *obj); | |
806 | ||
807 | struct UserDefOneList { | |
6e2bb3ec MA |
808 | union { |
809 | UserDefOne *value; | |
810 | uint64_t padding; | |
811 | }; | |
e98859a9 | 812 | UserDefOneList *next; |
b84da831 MR |
813 | }; |
814 | ||
59a2c4ce | 815 | void qapi_free_UserDefOneList(UserDefOneList *obj); |
b84da831 MR |
816 | |
817 | #endif | |
818 | ||
b84da831 MR |
819 | === scripts/qapi-visit.py === |
820 | ||
821 | Used to generate the visitor functions used to walk through and convert | |
822 | a QObject (as provided by QMP) to a native C data structure and | |
823 | vice-versa, as well as the visitor function used to dealloc a complex | |
824 | schema-defined C type. | |
825 | ||
826 | The following files are generated: | |
827 | ||
828 | $(prefix)qapi-visit.c: visitor function for a particular C type, used | |
829 | to automagically convert QObjects into the | |
830 | corresponding C type and vice-versa, as well | |
831 | as for deallocating memory for an existing C | |
832 | type | |
833 | ||
834 | $(prefix)qapi-visit.h: declarations for previously mentioned visitor | |
835 | functions | |
836 | ||
837 | Example: | |
838 | ||
87a560c4 | 839 | $ python scripts/qapi-visit.py --output-dir="qapi-generated" |
16d80f61 | 840 | --prefix="example-" example-schema.json |
87a560c4 | 841 | $ cat qapi-generated/example-qapi-visit.c |
6e2bb3ec | 842 | [Uninteresting stuff omitted...] |
b84da831 | 843 | |
f8b7f1a8 | 844 | static void visit_type_UserDefOne_fields(Visitor *v, UserDefOne **obj, Error **errp) |
6e2bb3ec MA |
845 | { |
846 | Error *err = NULL; | |
3a864e7c | 847 | |
f8b7f1a8 | 848 | visit_type_int(v, &(*obj)->integer, "integer", &err); |
297a3646 MA |
849 | if (err) { |
850 | goto out; | |
851 | } | |
f8b7f1a8 | 852 | visit_type_str(v, &(*obj)->string, "string", &err); |
297a3646 MA |
853 | if (err) { |
854 | goto out; | |
855 | } | |
6e2bb3ec | 856 | |
297a3646 | 857 | out: |
6e2bb3ec MA |
858 | error_propagate(errp, err); |
859 | } | |
b84da831 | 860 | |
f8b7f1a8 | 861 | void visit_type_UserDefOne(Visitor *v, UserDefOne **obj, const char *name, Error **errp) |
b84da831 | 862 | { |
297a3646 MA |
863 | Error *err = NULL; |
864 | ||
f8b7f1a8 | 865 | visit_start_struct(v, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), &err); |
297a3646 MA |
866 | if (!err) { |
867 | if (*obj) { | |
f8b7f1a8 | 868 | visit_type_UserDefOne_fields(v, obj, errp); |
6e2bb3ec | 869 | } |
f8b7f1a8 | 870 | visit_end_struct(v, &err); |
6e2bb3ec | 871 | } |
297a3646 | 872 | error_propagate(errp, err); |
b84da831 MR |
873 | } |
874 | ||
f8b7f1a8 | 875 | void visit_type_UserDefOneList(Visitor *v, UserDefOneList **obj, const char *name, Error **errp) |
b84da831 | 876 | { |
6e2bb3ec | 877 | Error *err = NULL; |
297a3646 | 878 | GenericList *i, **prev; |
6e2bb3ec | 879 | |
f8b7f1a8 | 880 | visit_start_list(v, name, &err); |
297a3646 MA |
881 | if (err) { |
882 | goto out; | |
883 | } | |
884 | ||
885 | for (prev = (GenericList **)obj; | |
f8b7f1a8 | 886 | !err && (i = visit_next_list(v, prev, &err)) != NULL; |
297a3646 MA |
887 | prev = &i) { |
888 | UserDefOneList *native_i = (UserDefOneList *)i; | |
f8b7f1a8 | 889 | visit_type_UserDefOne(v, &native_i->value, NULL, &err); |
b84da831 | 890 | } |
297a3646 MA |
891 | |
892 | error_propagate(errp, err); | |
893 | err = NULL; | |
f8b7f1a8 | 894 | visit_end_list(v, &err); |
297a3646 MA |
895 | out: |
896 | error_propagate(errp, err); | |
b84da831 | 897 | } |
87a560c4 | 898 | $ cat qapi-generated/example-qapi-visit.h |
6e2bb3ec | 899 | [Uninteresting stuff omitted...] |
b84da831 | 900 | |
6e2bb3ec MA |
901 | #ifndef EXAMPLE_QAPI_VISIT_H |
902 | #define EXAMPLE_QAPI_VISIT_H | |
b84da831 | 903 | |
e790e666 | 904 | [Visitors for built-in types omitted...] |
b84da831 | 905 | |
f8b7f1a8 EB |
906 | void visit_type_UserDefOne(Visitor *v, UserDefOne **obj, const char *name, Error **errp); |
907 | void visit_type_UserDefOneList(Visitor *v, UserDefOneList **obj, const char *name, Error **errp); | |
b84da831 MR |
908 | |
909 | #endif | |
b84da831 | 910 | |
b84da831 MR |
911 | === scripts/qapi-commands.py === |
912 | ||
913 | Used to generate the marshaling/dispatch functions for the commands defined | |
914 | in the schema. The following files are generated: | |
915 | ||
916 | $(prefix)qmp-marshal.c: command marshal/dispatch functions for each | |
917 | QMP command defined in the schema. Functions | |
918 | generated by qapi-visit.py are used to | |
2542bfd5 | 919 | convert QObjects received from the wire into |
b84da831 MR |
920 | function parameters, and uses the same |
921 | visitor functions to convert native C return | |
922 | values to QObjects from transmission back | |
923 | over the wire. | |
924 | ||
925 | $(prefix)qmp-commands.h: Function prototypes for the QMP commands | |
926 | specified in the schema. | |
927 | ||
928 | Example: | |
929 | ||
59a2c4ce | 930 | $ python scripts/qapi-commands.py --output-dir="qapi-generated" |
16d80f61 | 931 | --prefix="example-" example-schema.json |
87a560c4 | 932 | $ cat qapi-generated/example-qmp-marshal.c |
6e2bb3ec | 933 | [Uninteresting stuff omitted...] |
b84da831 | 934 | |
56d92b00 | 935 | static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp) |
b84da831 | 936 | { |
2a0f50e8 | 937 | Error *err = NULL; |
f8b7f1a8 EB |
938 | QmpOutputVisitor *qov = qmp_output_visitor_new(); |
939 | QapiDeallocVisitor *qdv; | |
b84da831 MR |
940 | Visitor *v; |
941 | ||
f8b7f1a8 | 942 | v = qmp_output_get_visitor(qov); |
2a0f50e8 EB |
943 | visit_type_UserDefOne(v, &ret_in, "unused", &err); |
944 | if (err) { | |
297a3646 | 945 | goto out; |
6e2bb3ec | 946 | } |
f8b7f1a8 | 947 | *ret_out = qmp_output_get_qobject(qov); |
297a3646 MA |
948 | |
949 | out: | |
2a0f50e8 | 950 | error_propagate(errp, err); |
f8b7f1a8 EB |
951 | qmp_output_visitor_cleanup(qov); |
952 | qdv = qapi_dealloc_visitor_new(); | |
953 | v = qapi_dealloc_get_visitor(qdv); | |
6e2bb3ec | 954 | visit_type_UserDefOne(v, &ret_in, "unused", NULL); |
f8b7f1a8 | 955 | qapi_dealloc_visitor_cleanup(qdv); |
b84da831 MR |
956 | } |
957 | ||
7fad30f0 | 958 | static void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp) |
b84da831 | 959 | { |
2a0f50e8 | 960 | Error *err = NULL; |
3f99144c | 961 | UserDefOne *retval; |
f8b7f1a8 EB |
962 | QmpInputVisitor *qiv = qmp_input_visitor_new_strict(QOBJECT(args)); |
963 | QapiDeallocVisitor *qdv; | |
b84da831 | 964 | Visitor *v; |
59a2c4ce | 965 | UserDefOne *arg1 = NULL; |
b84da831 | 966 | |
f8b7f1a8 | 967 | v = qmp_input_get_visitor(qiv); |
2a0f50e8 EB |
968 | visit_type_UserDefOne(v, &arg1, "arg1", &err); |
969 | if (err) { | |
b84da831 MR |
970 | goto out; |
971 | } | |
297a3646 | 972 | |
2a0f50e8 EB |
973 | retval = qmp_my_command(arg1, &err); |
974 | if (err) { | |
297a3646 | 975 | goto out; |
6e2bb3ec | 976 | } |
b84da831 | 977 | |
2a0f50e8 | 978 | qmp_marshal_output_UserDefOne(retval, ret, &err); |
297a3646 | 979 | |
b84da831 | 980 | out: |
2a0f50e8 | 981 | error_propagate(errp, err); |
f8b7f1a8 EB |
982 | qmp_input_visitor_cleanup(qiv); |
983 | qdv = qapi_dealloc_visitor_new(); | |
984 | v = qapi_dealloc_get_visitor(qdv); | |
6e2bb3ec | 985 | visit_type_UserDefOne(v, &arg1, "arg1", NULL); |
f8b7f1a8 | 986 | qapi_dealloc_visitor_cleanup(qdv); |
b84da831 MR |
987 | } |
988 | ||
989 | static void qmp_init_marshal(void) | |
990 | { | |
7fad30f0 | 991 | qmp_register_command("my-command", qmp_marshal_my_command, QCO_NO_OPTIONS); |
b84da831 MR |
992 | } |
993 | ||
994 | qapi_init(qmp_init_marshal); | |
87a560c4 | 995 | $ cat qapi-generated/example-qmp-commands.h |
6e2bb3ec | 996 | [Uninteresting stuff omitted...] |
b84da831 | 997 | |
6e2bb3ec MA |
998 | #ifndef EXAMPLE_QMP_COMMANDS_H |
999 | #define EXAMPLE_QMP_COMMANDS_H | |
b84da831 MR |
1000 | |
1001 | #include "example-qapi-types.h" | |
6e2bb3ec MA |
1002 | #include "qapi/qmp/qdict.h" |
1003 | #include "qapi/error.h" | |
b84da831 | 1004 | |
59a2c4ce EB |
1005 | UserDefOne *qmp_my_command(UserDefOne *arg1, Error **errp); |
1006 | ||
1007 | #endif | |
1008 | ||
1009 | === scripts/qapi-event.py === | |
1010 | ||
1011 | Used to generate the event-related C code defined by a schema. The | |
1012 | following files are created: | |
1013 | ||
1014 | $(prefix)qapi-event.h - Function prototypes for each event type, plus an | |
1015 | enumeration of all event names | |
1016 | $(prefix)qapi-event.c - Implementation of functions to send an event | |
1017 | ||
1018 | Example: | |
1019 | ||
1020 | $ python scripts/qapi-event.py --output-dir="qapi-generated" | |
16d80f61 | 1021 | --prefix="example-" example-schema.json |
59a2c4ce EB |
1022 | $ cat qapi-generated/example-qapi-event.c |
1023 | [Uninteresting stuff omitted...] | |
1024 | ||
1025 | void qapi_event_send_my_event(Error **errp) | |
1026 | { | |
1027 | QDict *qmp; | |
2a0f50e8 | 1028 | Error *err = NULL; |
59a2c4ce EB |
1029 | QMPEventFuncEmit emit; |
1030 | emit = qmp_event_get_func_emit(); | |
1031 | if (!emit) { | |
1032 | return; | |
1033 | } | |
1034 | ||
1035 | qmp = qmp_event_build_dict("MY_EVENT"); | |
1036 | ||
2a0f50e8 | 1037 | emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err); |
59a2c4ce | 1038 | |
2a0f50e8 | 1039 | error_propagate(errp, err); |
59a2c4ce EB |
1040 | QDECREF(qmp); |
1041 | } | |
1042 | ||
efd2eaa6 MA |
1043 | const char *const example_QAPIEvent_lookup[] = { |
1044 | [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", | |
1045 | [EXAMPLE_QAPI_EVENT_MAX] = NULL, | |
59a2c4ce EB |
1046 | }; |
1047 | $ cat qapi-generated/example-qapi-event.h | |
1048 | [Uninteresting stuff omitted...] | |
1049 | ||
1050 | #ifndef EXAMPLE_QAPI_EVENT_H | |
1051 | #define EXAMPLE_QAPI_EVENT_H | |
1052 | ||
1053 | #include "qapi/error.h" | |
1054 | #include "qapi/qmp/qdict.h" | |
1055 | #include "example-qapi-types.h" | |
1056 | ||
1057 | ||
1058 | void qapi_event_send_my_event(Error **errp); | |
1059 | ||
3a864e7c | 1060 | typedef enum example_QAPIEvent { |
59a2c4ce EB |
1061 | EXAMPLE_QAPI_EVENT_MY_EVENT = 0, |
1062 | EXAMPLE_QAPI_EVENT_MAX = 1, | |
016a335b | 1063 | } example_QAPIEvent; |
b84da831 | 1064 | |
efd2eaa6 MA |
1065 | extern const char *const example_QAPIEvent_lookup[]; |
1066 | ||
b84da831 | 1067 | #endif |
39a18158 MA |
1068 | |
1069 | === scripts/qapi-introspect.py === | |
1070 | ||
1071 | Used to generate the introspection C code for a schema. The following | |
1072 | files are created: | |
1073 | ||
1074 | $(prefix)qmp-introspect.c - Defines a string holding a JSON | |
1075 | description of the schema. | |
1076 | $(prefix)qmp-introspect.h - Declares the above string. | |
1077 | ||
1078 | Example: | |
1079 | ||
1080 | $ python scripts/qapi-introspect.py --output-dir="qapi-generated" | |
1081 | --prefix="example-" example-schema.json | |
1082 | $ cat qapi-generated/example-qmp-introspect.c | |
1083 | [Uninteresting stuff omitted...] | |
1084 | ||
1085 | const char example_qmp_schema_json[] = "[" | |
1a9a507b MA |
1086 | "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, " |
1087 | "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, " | |
1088 | "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, " | |
1089 | "{\"members\": [{\"name\": \"arg1\", \"type\": \"2\"}], \"meta-type\": \"object\", \"name\": \"1\"}, " | |
1090 | "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, " | |
39a18158 | 1091 | "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, " |
1a9a507b | 1092 | "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]"; |
39a18158 MA |
1093 | $ cat qapi-generated/example-qmp-introspect.h |
1094 | [Uninteresting stuff omitted...] | |
1095 | ||
1096 | #ifndef EXAMPLE_QMP_INTROSPECT_H | |
1097 | #define EXAMPLE_QMP_INTROSPECT_H | |
1098 | ||
1099 | extern const char example_qmp_schema_json[]; | |
1100 | ||
1101 | #endif |