Lines Matching full:the
2 How to use the QAPI code generator
9 This work is licensed under the terms of the GNU GPL, version 2 or
10 later. See the COPYING file in the top-level directory.
20 format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
21 well as the QEMU Guest Agent (QGA) for communicating with the guest.
22 The remainder of this document uses "Client JSON Protocol" when
23 referring to the wire contents of a QMP or QGA connection.
25 To map between Client JSON Protocol interfaces and the native C API,
26 we generate C code from a QAPI schema. This document describes the
27 QAPI schema language, and how it gets mapped to the Client JSON
32 The QAPI schema language
35 The QAPI schema defines the Client JSON Protocol's commands and
39 It is permissible for the schema to contain additional types not used
40 by any commands or events, for the side effect of generated C code
56 string, and extend to the end of the line.
65 A second layer of syntax defines the sequences of JSON texts that are
81 * When JSON object member's name starts with ``*``, the member is
83 * The symbol ``STRING`` is a terminal, and matches any JSON string
84 * The symbol ``BOOL`` is a terminal, and matches JSON ``false`` or ``true``
87 The order of members within JSON objects does not matter unless
94 The top-level expressions are all JSON objects. Code and
113 The following types are predefined, and map to C as follows:
121 that fits into the C integer type
146 The QAPI schema definitions can be modularized using the 'include' directive::
150 The directive is evaluated recursively, and include paths are relative
151 to the file using the directive. Multiple includes of the same file
155 self-contained, but at the moment, nothing prevents an included file
157 an outer file. The parser may be made stricter in the future to
174 The pragma directive lets you control optional generator behavior.
176 Pragma's scope is currently the complete schema. Setting the same
177 pragma to different values in parts of the schema doesn't work.
186 violate the rules on permitted return types. Default is none.
213 Member 'enum' names the enum type.
215 Each member of the 'data' array defines a value of the enumeration
216 type. The form STRING is shorthand for :code:`{ 'name': STRING }`. The
226 On the wire, an enumeration type's value is represented by its
228 These are of the form PREFIX_NAME, where PREFIX is derived from the
229 enumeration type's name, and NAME from the value's name. For the
230 example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to
231 VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The
235 The generated C enumeration constants have values 0, 1, ..., N-1 (in
236 QAPI schema order), where N is the number of values. There is an
240 the job satisfactorily.
242 The optional 'if' member specifies a conditional. See `Configuring the
245 The optional 'features' member specifies features. See Features_
259 A string denotes the type named by the string.
261 A one-element array containing a string denotes an array of the type
262 named by the string. Example: ``['int']`` denotes an array of ``int``.
281 Member 'struct' names the struct type.
283 Each MEMBER of the 'data' object defines a member of the struct type.
287 The MEMBER's STRING name consists of an optional ``*`` prefix and the
288 struct member name. If ``*`` is present, the member is optional.
290 The MEMBER's value defines its properties, in particular its type.
291 The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`.
299 The C struct's members are generated in QAPI schema order.
301 The optional 'base' member names a struct type whose members are to be
302 included in this type. They go first in the C struct.
312 An example BlockdevOptionsGenericCOWFormat object on the wire could use
318 The optional 'if' member specifies a conditional. See `Configuring
319 the schema`_ below for more on this.
321 The optional 'features' member specifies features. See Features_
340 Member 'union' names the union type.
342 The 'base' member defines the common members. If it is a MEMBERS_
345 struct type whose members are the common members.
348 the base struct. That member's value selects a branch by its name.
351 Each BRANCH of the 'data' object defines a branch of the union. A
354 The BRANCH's STRING name is the branch name. It must be a value of
355 the discriminator enum type.
357 The BRANCH's value defines the branch's properties, in particular its
358 type. The type must a struct type. The form TYPE-REF_ is shorthand
361 In the Client JSON Protocol, a union is represented by an object with
362 the common members (from the base type) and the selected branch's
363 members. The two sets of member names must be disjoint.
381 The order of branches need not match the order of the enum values.
382 The branches need not cover all possible enum values. In the
384 with the base members in QAPI schema order, and then a union of
385 structures for each branch of the struct.
387 The optional 'if' member specifies a conditional. See `Configuring
388 the schema`_ below for more on this.
390 The optional 'features' member specifies features. See Features_
407 Member 'alternate' names the alternate type.
409 Each ALTERNATIVE of the 'data' object defines a branch of the
412 The ALTERNATIVE's STRING name is the branch name.
414 The ALTERNATIVE's value defines the branch's properties, in particular
415 its type. The form STRING is shorthand for :code:`{ 'type': STRING }`.
424 discriminator on the wire. Instead, the branch to use is inferred
425 from the value. An alternate can only express a choice between types
426 represented differently on the wire.
428 If a branch is typed as the 'bool' built-in, the alternate accepts
429 true and false; if it is typed as any of the various numeric
432 as the 'null' built-in, it accepts JSON null; and if it is typed as a
435 The example alternate declaration above allows using both of the
443 The optional 'if' member specifies a conditional. See `Configuring
444 the schema`_ below for more on this.
446 The optional 'features' member specifies features. See Features_
471 Member 'command' names the command.
473 Member 'data' defines the arguments. It defaults to an empty MEMBERS_
480 are the arguments. A union type requires ``'boxed': true``.
482 Member 'returns' defines the command's return type. It defaults to an
484 a complex type. To return anything else, the command must be listed
486 the command to return additional information will be harder. Use of
487 the pragma for new commands is strongly discouraged.
489 A command's error responses are not specified in the QAPI schema.
492 In the Client JSON Protocol, the value of the "execute" or "exec-oob"
493 member is the command name. The value of the "arguments" member then
494 has to conform to the arguments, and the value of the success
495 response's "return" member will conform to the return type.
513 The generator emits a prototype for the C function implementing the
514 command. The function itself needs to be written by hand. See
517 The function returns the return type. When member 'boxed' is absent,
518 it takes the command arguments as arguments one by one, in QAPI schema
519 order. Else it takes them wrapped in the C struct generated for the
523 The generator also emits a marshalling function that extracts
524 arguments for the user's function out of an input QDict, calls the
526 its return value. This is for use by the QMP monitor core.
541 Normally, the QAPI schema is used to describe synchronous exchanges,
542 where a response is expected. But in some cases, the action of a
544 response is not possible (although the command will still return an
546 the command definition includes the optional member 'success-response'
549 Member 'allow-oob' declares whether the command supports out-of-band
555 See the :doc:`/interop/qmp-spec` for out-of-band execution syntax
561 When a command is executed in-band, its handler runs in the main
562 thread with the BQL held.
565 dedicated monitor I/O thread with the BQL *not* held.
567 An OOB-capable command handler must satisfy the following conditions:
574 any lock it takes also satisfy the conditions for OOB command
577 The restrictions on locking limit access to shared state. Such access
578 requires synchronization, but OOB commands can't take the BQL or any
583 Member 'allow-preconfig' declares whether the command is available
584 before the machine is built. It defaults to false. For example::
592 QMP is available before the machine is built only when QEMU was
595 Member 'coroutine' tells the QMP dispatcher whether the command handler
597 the command handler is called from coroutine context and may yield while
599 blocking the guest and other background operations.
604 - The BQL isn't held across ``qemu_coroutine_yield()``, so
606 to be more careful to protect against changes in the global state.
610 replaced by yielding and reentering the coroutine when the condition
613 Since the command handler may assume coroutine context, any callers
614 other than the QMP dispatcher must also call it in coroutine context.
620 without a use case, it's not entirely clear what the semantics should
623 The optional 'if' member specifies a conditional. See `Configuring
624 the schema`_ below for more on this.
626 The optional 'features' member specifies features. See Features_
645 Member 'event' names the event. This is the event name used in the
648 Member 'data' defines the event-specific data. It defaults to an
655 are the event-specific data. A union type requires ``'boxed': true``.
668 The generator emits a function to send the event. When member 'boxed'
670 order. Else it takes them wrapped in the C struct generated for the
673 The optional 'if' member specifies a conditional. See `Configuring
674 the schema`_ below for more on this.
676 The optional 'features' member specifies features. See Features_
691 Sometimes, the behaviour of QEMU changes compatibly, but without a
692 change in the QMP syntax (usually by allowing values or operations
694 know whether the extension is available.
701 The optional 'if' member specifies a conditional. See `Configuring
702 the schema`_ below for more on this.
710 The feature strings are exposed to clients in introspection, as
738 Names beginning with ``q_`` are reserved for the generator, which uses
741 becomes ``q_default`` in the generated C code.
747 Type names ending with ``List`` are reserved for the generator, which
759 for the generator, which uses them for unions and for tracking
773 QAPI schema names that are externally visible, say in the Client JSON
775 downstream prefix of the form __RFQDN_ are reserved for the downstream
776 who controls the valid, reverse fully qualified domain name RFQDN.
783 Configuring the schema
796 The C code generated for the definition will then be guarded by an #if
816 This requires the longhand form of MEMBER.
828 requires the longhand form of ENUM-VALUE_.
837 Likewise, features can be conditional. This requires the longhand
847 Please note that you are responsible to ensure that the C code will
848 compile with an arbitrary combination of conditions, since the
851 The conditions apply to introspection as well, i.e. introspection
852 shows a conditional entity only when the condition is satisfied in
862 If the documentation comment starts like ::
867 it documents the definition of SYMBOL, else it's free-form
885 # This is a free-form comment which will go under the
893 A heading line must be the first line of the documentation
908 # Text of the example, may span
925 The actual number doesn't matter.
928 If a list item's text spans multiple lines, then the second and
929 subsequent lines must be correctly indented to line up with the
930 first character of the first line.
932 The usual ****strong****, *\*emphasized\** and ````literal```` markup
936 Use ``@foo`` to reference a name in the schema. This is an rST
937 extension. It is rendered the same way as ````foo````, but carries
966 Definition documentation, if present, must immediately precede the
972 Definition documentation starts with a line naming the definition,
978 Descriptions start with '\@name:'. The description text must be
984 .. FIXME The parser accepts these things in almost any order.
988 Extensions added after the definition was first released carry a
991 The feature descriptions must be preceded by a blank line and then a
999 A tagged section begins with a paragraph that starts with one of the
1001 the start of a new section.
1003 The second and subsequent lines of tagged sections must be indented
1013 document the success and the error response, respectively.
1022 A "Since: x.y.z" tagged section lists the release that introduced the
1026 QMP). In other sections, the text is formatted, and rST markup can be
1029 QMP Examples can be added by using the ``.. qmp-example::`` directive.
1036 Optionally, a plaintext title may be provided by using the ``:title:``
1037 directive option. If the title is omitted, the example title will
1048 or between QMP code blocks can be created by using the ``:annotated:``
1072 Highlighting in non-QMP languages can be accomplished by using the
1074 achieved by omitting the language argument.
1084 # @device: If the stats are for a virtual block device, the name
1085 # corresponding to the virtual block device.
1087 # @node-name: The node name of the device. (Since 2.3)
1100 # Query the @BlockStats for all virtual block devices.
1102 # @query-nodes: If true, the command will query all the block nodes
1126 it, the list may not be recognized, resulting in garbled output. Good
1131 # - its name matches the @name pattern, and
1132 # - if @vcpu is given, the event has the "vcpu" property.
1134 Without the blank line this would be a single paragraph.
1142 The last line's de-indent is wrong. The second and subsequent lines
1173 Undocumented members are not flagged, yet. Instead, the generated
1177 When you change documentation comments, please check the generated
1185 exactly the server (QEMU) supports.
1191 between qemu versions, we cannot make the same guarantees for
1194 the member to instead be non-optional and associated with a variant.
1198 an alternate that represents a choice between the original type and
1202 objects together describe the wire ABI, as defined in the QAPI schema.
1203 There is no specified order to the SchemaInfo objects returned; a
1204 client must search for a particular name throughout the entire array
1208 However, the SchemaInfo can't reflect all the rules and restrictions
1210 there), not interface specification. The specification is in the QAPI
1211 schema. To understand how QMP is to be used, you need to study the
1214 Like any other command, query-qmp-schema is itself defined in the QAPI
1215 schema, along with the SchemaInfo type. This text attempts to give an
1216 overview how things work. For details you need to consult the QAPI
1220 "features", and additional variant members depending on the value of
1226 SchemaInfo for commands and events have the same name as in the QAPI
1229 Command and event names are part of the wire ABI, but type names are
1230 not. Therefore, the SchemaInfo for types have auto-generated
1231 meaningless names. For readability, the examples in this section use
1234 Optional member "features" exposes the entity's feature strings as a
1242 The SchemaInfo for a command has meta-type "command", and variant
1243 members "arg-type", "ret-type" and "allow-oob". On the wire, the
1244 "arguments" member of a client's "execute" command must conform to the
1245 object type named by "arg-type". The "return" member that the server
1246 passes in a success response conforms to the type named by "ret-type".
1247 When "allow-oob" is true, it means the command supports out-of-band
1250 If the command takes no arguments, "arg-type" names an object type
1251 without members. Likewise, if the command returns nothing, "ret-type"
1254 Example: the SchemaInfo for command query-qmp-schema ::
1260 "SchemaInfoList" is the array of SchemaInfo type.
1262 The SchemaInfo for an event has meta-type "event", and variant member
1263 "arg-type". On the wire, a "data" member that the server passes in an
1264 event conforms to the object type named by "arg-type".
1266 If the event carries no additional information, "arg-type" names an
1267 object type without members. The event may not have a data member on
1268 the wire then.
1270 Each command or event defined with 'data' as MEMBERS object in the
1273 Example: the SchemaInfo for EVENT_C from section Events_ ::
1279 the two members from the event's definition.
1281 The SchemaInfo for struct and union types has meta-type "object" and
1284 The SchemaInfo for a union type additionally has variant members "tag"
1287 "members" is a JSON array describing the object's common members, if
1288 any. Each element is a JSON object with members "name" (the member's
1289 name), "type" (the name of its type), "features" (a JSON array of
1290 feature strings), and "default". The latter two are optional. The
1293 extensions. The "members" array is in no particular order; clients
1294 must search the entire object when learning whether a particular
1297 Example: the SchemaInfo for MyType from section `Struct types`_ ::
1305 "features" exposes the command's feature strings as a JSON array of
1308 Example: the SchemaInfo for TestType from section Features_::
1315 "tag" is the name of the common member serving as type tag.
1316 "variants" is a JSON array describing the object's variant members.
1317 Each element is a JSON object with members "case" (the value of type
1318 tag this element applies to) and "type" (the name of an object type
1319 that provides the variant members for this type tag value). The
1321 list cases in the same order as the corresponding "tag" enum type.
1323 Example: the SchemaInfo for union BlockdevOptions from section
1335 Note that base types are "flattened": its members are included in the
1338 The SchemaInfo for an alternate type has meta-type "alternate", and
1340 a JSON object with member "type", which names a type. Values of the
1342 no guarantee on the order in which "members" will be listed.
1344 Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ ::
1351 The SchemaInfo for an array type has meta-type "array", and variant
1352 member "element-type", which names the array's element type. Array
1353 types are implicitly defined. For convenience, the array's name may
1354 resemble the element type; however, clients should examine member
1358 Example: the SchemaInfo for ['str'] ::
1363 The SchemaInfo for an enumeration type has meta-type "enum" and
1366 "members" is a JSON array describing the enumeration values. Each
1367 element is a JSON object with member "name" (the member's name), and
1368 optionally "features" (a JSON array of feature strings). The
1369 "members" array is in no particular order; clients must search the
1372 Example: the SchemaInfo for MyEnum from section `Enumeration types`_ ::
1381 The SchemaInfo for a built-in type has the same name as the type in
1382 the QAPI schema (see section `Built-in Types`_), with one exception
1384 values of this type are encoded on the wire.
1386 Example: the SchemaInfo for str ::
1390 The QAPI schema supports a number of integer types that only differ in
1395 As explained above, type names are not part of the wire ABI. Not even
1396 the names of built-in types. Clients should examine member
1403 Maintaining backward compatibility at the Client JSON Protocol level
1404 while evolving the schema requires some care. This section is about
1411 Adding opt-in functionality to the send direction is backwards
1415 oblivious of the new functionality continue to work.
1421 The specified behavior of an absent optional argument should remain
1422 the same. With proper documentation, this policy still allows some
1424 specified to default to a sensible buffer size, the actual default
1425 value can still be changed. The specified default behavior is not the
1426 exact size of the buffer, only that the default size is sensible.
1428 Adding functionality to the receive direction is generally backwards
1430 Clients are expected to ignore the ones they don't know.
1436 introspection. The latter can conceivably confuse clients, so tread
1441 Any change to a command definition's 'data' or one of the types used
1445 'data', or one of the types used there (recursively) needs to consider
1452 affect the wire encoding. For complex types, this might make the
1454 the Client JSON Protocol permits.
1456 Since type names are not visible in the Client JSON Protocol, types
1464 The QAPI code generator qapi-gen.py generates code and documentation
1465 from the schema. Together with the core QAPI libraries, this code
1467 JSON Protocol server, unmarshal the arguments into the underlying C
1468 types, call into the corresponding C function, map the response back
1469 to a Client JSON Protocol response to be returned to the user, and
1470 introspect the commands.
1472 As an example, we'll use the following schema, which describes a
1475 type. The user is responsible for writing the implementation of
1476 qmp_my_command(); everything else is produced by the generator.
1495 For a more thorough look at generated code, the testsuite includes
1497 what the generator will accept, and compiles the resulting C code as
1504 The following files are created:
1507 C types corresponding to types defined in the schema
1510 Cleanup functions for the above C types
1512 The $(prefix) is an optional parameter used as a namespace to keep the
1600 Cleanup functions for the above C types
1606 These are the visitor functions used to walk through and convert
1608 QObject); the generated functions are named visit_type_FOO() and
1611 The following files are generated:
1615 convert QObjects into the corresponding C type and vice-versa, as
1751 These are the marshaling/dispatch functions for the commands defined
1752 in the schema. The generated code provides qmp_marshal_COMMAND(), and
1753 declares qmp_COMMAND() that the user must implement.
1755 The following files are generated:
1759 the schema
1762 Function prototypes for the QMP commands specified in the schema
1894 This is the code related to events defined in the schema, providing
1897 The following files are created:
1983 The following files are created:
1986 Defines a string holding a JSON description of the schema
1989 Declares the above string