Lines Matching +full:json +full:- +full:schema
7 Copyright (C) 2012-2016 Red Hat, Inc.
10 later. See the COPYING file in the top-level directory.
17 QAPI is a native C API within QEMU which provides management-level
19 users/processes, this interface is made available by a JSON-based wire
22 The remainder of this document uses "Client JSON Protocol" when
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
29 Client JSON Protocol compatibility.
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
43 There are several kinds of types: simple types (a number of built-in
49 Schema syntax
50 -------------
52 Syntax is loosely based on `JSON <http://www.ietf.org/rfc/rfc8259.txt>`_.
65 A second layer of syntax defines the sequences of JSON texts that are
66 a correctly structured QAPI schema. We provide a grammar for this
67 syntax in an EBNF-like notation:
69 * Production rules look like ``non-terminal = expression``
77 * JSON's structural characters are terminals: ``{ } [ ] : ,``
78 * JSON's literal names are terminals: ``false true``
80 this JSON string, with a leading ``*`` stripped off
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``
85 * ALL-CAPS words other than ``STRING`` are non-terminals
87 The order of members within JSON objects does not matter unless
90 A QAPI schema consists of a series of top-level expressions::
92 SCHEMA = TOP-LEVEL-EXPR...
94 The top-level expressions are all JSON objects. Code and
95 documentation is generated in schema definition order. Code order
98 A top-level expressions is either a directive or a definition::
100 TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION
110 Built-in Types
111 --------------
116 Schema C JSON
118 ``str`` ``char *`` any JSON string, UTF-8
119 ``number`` ``double`` any JSON number
120 ``int`` ``int64_t`` a JSON number without fractional part
132 ``bool`` ``bool`` JSON ``true`` or ``false``
133 ``null`` ``QNull *`` JSON ``null``
134 ``any`` ``QObject *`` any JSON value
135 ``QType`` ``QType`` JSON string matching enum ``QType`` values
140 ------------------
146 The QAPI schema definitions can be modularized using the 'include' directive::
148 { 'include': 'path/to/file.json' }
155 self-contained, but at the moment, nothing prevents an included file
163 -----------------
168 '*doc-required': BOOL,
169 '*command-name-exceptions': [ STRING, ... ],
170 '*command-returns-exceptions': [ STRING, ... ],
171 '*documentation-exceptions': [ STRING, ... ],
172 '*member-name-exceptions': [ STRING, ... ] } }
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.
179 Pragma 'doc-required' takes a boolean value. If true, documentation
182 Pragma 'command-name-exceptions' takes a list of commands whose names
183 may contain ``"_"`` instead of ``"-"``. Default is none.
185 Pragma 'command-returns-exceptions' takes a list of commands that may
188 Pragma 'documentation-exceptions' takes a list of types, commands, and
192 Pragma 'member-name-exceptions' takes a list of types whose member
193 names may contain uppercase letters, and ``"_"`` instead of ``"-"``.
196 .. _ENUM-VALUE:
199 -----------------
204 'data': [ ENUM-VALUE, ... ],
208 ENUM-VALUE = STRING
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
243 schema`_ below for more on this.
249 .. _TYPE-REF:
252 -------------------------------
256 TYPE-REF = STRING | ARRAY-TYPE
257 ARRAY-TYPE = [ STRING ]
261 A one-element array containing a string denotes an array of the type
266 ------------
276 MEMBER = STRING : TYPE-REF
277 | STRING : { 'type': TYPE-REF,
291 The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`.
298 A struct type corresponds to a struct in C, and an object in JSON.
299 The C struct's members are generated in QAPI schema order.
315 { "file": "/some/place/my-image",
316 "backing": "/some/place/my-backing-file" }
319 the schema`_ below for more on this.
326 -----------
337 BRANCH = STRING : TYPE-REF
338 | STRING : { 'type': TYPE-REF, '*if': COND }
347 Member 'discriminator' must name a non-optional enum-typed member of
358 type. The type must a struct type. The form TYPE-REF_ is shorthand
359 for :code:`{ 'type': TYPE-REF }`.
361 In the Client JSON Protocol, a union is represented by an object with
369 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
374 Resulting in these JSON objects::
376 { "driver": "file", "read-only": true,
377 "filename": "/some/place/my-image" }
378 { "driver": "qcow2", "read-only": false,
379 "backing": "/some/place/my-image", "lazy-refcounts": true }
384 with the base members in QAPI schema order, and then a union of
388 the schema`_ below for more on this.
395 ---------------
428 If a branch is typed as the 'bool' built-in, the alternate accepts
430 built-ins, it accepts a JSON number; if it is typed as a 'str'
431 built-in or named enum type, it accepts a JSON string; if it is typed
432 as the 'null' built-in, it accepts JSON null; and if it is typed as a
433 complex type (struct or union), it accepts a JSON object.
440 "read-only": false,
444 the schema`_ below for more on this.
451 --------
462 '*returns': TYPE-REF,
463 '*success-response': false,
465 '*allow-oob': true,
466 '*allow-preconfig': true,
485 in pragma 'commands-returns-exceptions'. If you do this, extending
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"
499 { 'command': 'my-first-command',
502 { 'command': 'my-second-command',
505 which would validate this Client JSON Protocol transaction::
507 => { "execute": "my-first-command",
510 => { "execute": "my-second-command" }
518 it takes the command arguments as arguments one by one, in QAPI schema
528 In rare cases, QAPI cannot express a type-safe representation of a
529 corresponding Client JSON Protocol command. You then have to suppress
539 use type-safe unions.
541 Normally, the QAPI schema is used to describe synchronous exchanges,
546 the command definition includes the optional member 'success-response'
549 Member 'allow-oob' declares whether the command supports out-of-band
553 'data': { 'uri': 'str' }, 'allow-oob': true }
555 See the :doc:`/interop/qmp-spec` for out-of-band execution syntax
558 Commands supporting out-of-band execution can still be executed
559 in-band.
561 When a command is executed in-band, its handler runs in the main
564 When a command is executed out-of-band, its handler runs in a
567 An OOB-capable command handler must satisfy the following conditions:
569 - It terminates quickly.
570 - It does not invoke system calls that may block.
571 - It does not access guest RAM that may block when userfaultfd is
573 - It takes only "fast" locks, i.e. all critical sections protected by
583 Member 'allow-preconfig' declares whether the command is available
590 'allow-preconfig': true }
593 started with --preconfig.
604 - The BQL isn't held across ``qemu_coroutine_yield()``, so
608 - Nested event loops (``AIO_WAIT_WHILE()`` etc.) are problematic in
616 marked ``.coroutine = true`` in hmp-commands.hx.
618 It is an error to specify both ``'coroutine': true`` and ``'allow-oob': true``
624 the schema`_ below for more on this.
631 ------
646 Client JSON Protocol.
648 Member 'data' defines the event-specific data. It defaults to an
651 If 'data' is a MEMBERS_ object, then MEMBERS defines event-specific
655 are the event-specific data. A union type requires ``'boxed': true``.
662 Resulting in this JSON object::
669 is absent, it takes event-specific data one by one, in QAPI schema
674 the schema`_ below for more on this.
683 --------
702 the schema`_ below for more on this.
708 'features': [ 'allow-negative-numbers' ] }
711 explained in section `Client JSON Protocol introspection`_.
731 -------------------------------
745 user-defined type names, while built-in types are lowercase.
758 Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved
762 Names beginning with ``x-`` used to signify "experimental". This
765 Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
771 ---------------------
773 QAPI schema names that are externally visible, say in the Client JSON
780 downstream command ``__com.redhat_drive-mirror``.
783 Configuring the schema
784 ----------------------
828 requires the longhand form of ENUM-VALUE_.
840 Example: a struct with conditional feature 'allow-negative-numbers' ::
844 'features': [ { 'name': 'allow-negative-numbers',
857 ----------------------
859 A multi-line comment that starts and ends with a ``##`` line is a
867 it documents the definition of SYMBOL, else it's free-form
872 Free-form documentation may be used to provide additional text and
879 Free-form documentation does not start with ``@SYMBOL`` and can contain
888 # This is a free-form comment which will go under the
914 a ``::`` literal block can be used for pre-formatted text::
927 You can also use ``-`` instead of ``*``.
944 backslash-escape it.
946 Use ```foo``` to reference a definition in the schema. This generates
947 a link to the definition. In the event that such a cross-reference is
948 ambiguous, you can use `QAPI cross-reference roles
949 <QAPI-domain-cross-references>` to disambiguate.
968 # -> do this
969 # <- get that
984 When documentation is required (see pragma_ 'doc-required'), every
1034 # - If @device does not exist, DeviceNotFound
1035 # - Any other error returns a GenericError.
1044 QMP Examples can be added by using the ``.. qmp-example::`` directive.
1046 block which accepts standard JSON syntax with additional server
1047 directionality indicators (``->`` and ``<-``), and elisions. An
1057 # .. qmp-example::
1059 # -> { "execute": "query-name" }
1060 # <- { "return": { "name": "Fred" } }
1062 More complex or multi-step examples where exposition is needed before
1069 # .. qmp-example::
1076 # -> { "execute": "query-block" }
1077 # <- { "return": [
1079 # "device": "ide0-hd0",
1087 Highlighting in non-QMP languages can be accomplished by using the
1088 ``.. code-block:: lang`` directive, and non-highlighted text can be
1102 # @node-name: The node name of the device. (Since 2.3)
1109 'data': {'*device': 'str', '*node-name': 'str',
1113 # @query-blockstats:
1117 # @query-nodes: If true, the command will query all the block nodes
1125 # .. qmp-example::
1127 # -> { "execute": "query-blockstats" }
1128 # <- {
1132 { 'command': 'query-blockstats',
1133 'data': { '*query-nodes': 'bool' },
1146 # - its name matches the @name pattern, and
1147 # - if @vcpu is given, the event has the "vcpu" property.
1157 The last line's de-indent is wrong. The second and subsequent lines
1164 Section tags are case-sensitive and end with a colon. They are only
1180 # @interface-id: Interface ID
1184 # @interface-id Interface ID
1186 # @interface-id : Interface ID
1196 Client JSON Protocol introspection
1199 Clients of a Client JSON Protocol commonly need to figure out what
1203 query-qmp-schema. QGA currently doesn't support introspection.
1205 While Client JSON Protocol wire compatibility should be maintained
1208 a non-variant optional member of a struct, and a later version rework
1209 the member to instead be non-optional and associated with a variant.
1210 Likewise, one version of qemu may list a member with open-ended type
1216 query-qmp-schema returns a JSON array of SchemaInfo objects. These
1217 objects together describe the wire ABI, as defined in the QAPI schema.
1226 schema. To understand how QMP is to be used, you need to study the
1227 QAPI schema.
1229 Like any other command, query-qmp-schema is itself defined in the QAPI
1230 schema, along with the SchemaInfo type. This text attempts to give an
1232 schema.
1234 SchemaInfo objects have common members "name", "meta-type",
1236 meta-type.
1239 meta-type: a command, event or one of several kinds of type.
1242 schema.
1245 not. Therefore, the SchemaInfo for types have auto-generated
1250 JSON array of strings.
1255 QAPI schema definitions not reachable that way are omitted.
1257 The SchemaInfo for a command has meta-type "command", and variant
1258 members "arg-type", "ret-type" and "allow-oob". On the wire, the
1260 object type named by "arg-type". The "return" member that the server
1261 passes in a success response conforms to the type named by "ret-type".
1262 When "allow-oob" is true, it means the command supports out-of-band
1265 If the command takes no arguments, "arg-type" names an object type
1266 without members. Likewise, if the command returns nothing, "ret-type"
1269 Example: the SchemaInfo for command query-qmp-schema ::
1271 { "name": "query-qmp-schema", "meta-type": "command",
1272 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1277 The SchemaInfo for an event has meta-type "event", and variant member
1278 "arg-type". On the wire, a "data" member that the server passes in an
1279 event conforms to the object type named by "arg-type".
1281 If the event carries no additional information, "arg-type" names an
1286 QAPI schema implicitly defines an object type.
1290 { "name": "EVENT_C", "meta-type": "event",
1291 "arg-type": "q_obj-EVENT_C-arg" }
1293 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1296 The SchemaInfo for struct and union types has meta-type "object" and
1302 "members" is a JSON array describing the object's common members, if
1303 any. Each element is a JSON object with members "name" (the member's
1304 name), "type" (the name of its type), "features" (a JSON array of
1314 { "name": "MyType", "meta-type": "object",
1320 "features" exposes the command's feature strings as a JSON array of
1325 { "name": "TestType", "meta-type": "object",
1328 "features": ["allow-negative-numbers"] }
1331 "variants" is a JSON array describing the object's variant members.
1332 Each element is a JSON object with members "case" (the value of type
1341 { "name": "BlockdevOptions", "meta-type": "object",
1344 { "name": "read-only", "type": "bool", "default": null } ],
1353 The SchemaInfo for an alternate type has meta-type "alternate", and
1354 variant member "members". "members" is a JSON array. Each element is
1355 a JSON object with member "type", which names a type. Values of the
1361 { "name": "BlockdevRef", "meta-type": "alternate",
1366 The SchemaInfo for an array type has meta-type "array", and variant
1367 member "element-type", which names the array's element type. Array
1370 "element-type" instead of making assumptions based on parsing member
1375 { "name": "[str]", "meta-type": "array",
1376 "element-type": "str" }
1378 The SchemaInfo for an enumeration type has meta-type "enum" and
1381 "members" is a JSON array describing the enumeration values. Each
1382 element is a JSON object with member "name" (the member's name), and
1383 optionally "features" (a JSON array of feature strings). The
1389 { "name": "MyEnum", "meta-type": "enum",
1396 The SchemaInfo for a built-in type has the same name as the type in
1397 the QAPI schema (see section `Built-in Types`_), with one exception
1398 detailed below. It has variant member "json-type" that shows how
1403 { "name": "str", "meta-type": "builtin", "json-type": "string" }
1405 The QAPI schema supports a number of integer types that only differ in
1411 the names of built-in types. Clients should examine member
1412 "json-type" instead of hard-coding names of built-in types.
1418 Maintaining backward compatibility at the Client JSON Protocol level
1419 while evolving the schema requires some care. This section is about
1426 Adding opt-in functionality to the send direction is backwards
1438 flexibility; for example, when an optional 'buffer-size' argument is
1468 implementation emit JSON object members in a different order, which
1469 the Client JSON Protocol permits.
1471 Since type names are not visible in the Client JSON Protocol, types
1479 The QAPI code generator qapi-gen.py generates code and documentation
1480 from the schema. Together with the core QAPI libraries, this code
1481 provides everything required to take JSON commands read in by a Client
1482 JSON Protocol server, unmarshal the arguments into the underlying C
1484 to a Client JSON Protocol response to be returned to the user, and
1487 As an example, we'll use the following schema, which describes a
1488 single complex user-defined type, along with command which takes a
1495 $ cat example-schema.json
1499 { 'command': 'my-command',
1505 We run qapi-gen.py like this::
1507 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1508 --prefix="example-" example-schema.json
1511 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1513 part of 'make check-unit'.
1517 -----------------------------
1521 ``$(prefix)qapi-types.h``
1522 C types corresponding to types defined in the schema
1524 ``$(prefix)qapi-types.c``
1528 generated code from one schema/code-generation separated from others so code
1534 $ cat qapi-generated/example-qapi-types.h
1540 #include "qapi/qapi-builtin-types.h"
1571 $ cat qapi-generated/example-qapi-types.c
1602 For a modular QAPI schema (see section `Include directives`_), code for
1603 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1605 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1606 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1608 If qapi-gen.py is run with option --builtins, additional files are
1611 ``qapi-builtin-types.h``
1612 C types corresponding to built-in types
1614 ``qapi-builtin-types.c``
1619 --------------------------------------
1628 ``$(prefix)qapi-visit.c``
1630 convert QObjects into the corresponding C type and vice-versa, as
1633 ``$(prefix)qapi-visit.h``
1638 $ cat qapi-generated/example-qapi-visit.h
1644 #include "qapi/qapi-builtin-visit.h"
1645 #include "example-qapi-types.h"
1659 $ cat qapi-generated/example-qapi-visit.c
1664 bool has_string = !!obj->string;
1666 if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1670 if (!visit_type_str(v, "string", &obj->string, errp)) {
1674 if (visit_optional(v, "flag", &obj->has_flag)) {
1675 if (!visit_type_bool(v, "flag", &obj->flag, errp)) {
1722 if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
1739 if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1747 For a modular QAPI schema (see section `Include directives`_), code for
1748 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1750 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1751 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1753 If qapi-gen.py is run with option --builtins, additional files are
1756 ``qapi-builtin-visit.h``
1757 Visitor functions for built-in types
1759 ``qapi-builtin-visit.c``
1764 ---------------------------
1767 in the schema. The generated code provides qmp_marshal_COMMAND(), and
1772 ``$(prefix)qapi-commands.c``
1774 the schema
1776 ``$(prefix)qapi-commands.h``
1777 Function prototypes for the QMP commands specified in the schema
1779 ``$(prefix)qapi-commands.trace-events``
1782 ``$(prefix)qapi-init-commands.h``
1785 ``$(prefix)qapi-init-commands.c``
1790 $ cat qapi-generated/example-qapi-commands.h
1796 #include "example-qapi-types.h"
1803 $ cat qapi-generated/example-qapi-commands.trace-events
1806 qmp_enter_my_command(const char *json) "%s"
1809 $ cat qapi-generated/example-qapi-commands.c
1850 trace_qmp_enter_my_command(req_json->str);
1865 trace_qmp_exit_my_command(ret_json->str, true);
1878 $ cat qapi-generated/example-qapi-init-commands.h
1883 #include "qapi/qmp-registry.h"
1888 $ cat qapi-generated/example-qapi-init-commands.c
1894 qmp_register_command(cmds, "my-command",
1899 For a modular QAPI schema (see section `Include directives`_), code for
1900 each sub-module SUBDIR/SUBMODULE.json is actually generated into::
1902 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1903 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1907 -------------------------
1909 This is the code related to events defined in the schema, providing
1914 ``$(prefix)qapi-events.h``
1917 ``$(prefix)qapi-events.c``
1920 ``$(prefix)qapi-emit-events.h``
1923 ``$(prefix)qapi-emit-events.c``
1928 $ cat qapi-generated/example-qapi-events.h
1935 #include "example-qapi-types.h"
1940 $ cat qapi-generated/example-qapi-events.c
1955 $ cat qapi-generated/example-qapi-emit-events.h
1976 $ cat qapi-generated/example-qapi-emit-events.c
1988 For a modular QAPI schema (see section `Include directives`_), code for
1989 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1991 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1992 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1996 --------------------------------
2000 ``$(prefix)qapi-introspect.c``
2001 Defines a string holding a JSON description of the schema
2003 ``$(prefix)qapi-introspect.h``
2008 $ cat qapi-generated/example-qapi-introspect.h
2019 $ cat qapi-generated/example-qapi-introspect.c
2024 { "arg-type", QLIT_QSTR("0"), },
2025 { "meta-type", QLIT_QSTR("command"), },
2026 { "name", QLIT_QSTR("my-command"), },
2027 { "ret-type", QLIT_QSTR("1"), },
2031 { "arg-type", QLIT_QSTR("2"), },
2032 { "meta-type", QLIT_QSTR("event"), },
2036 /* "0" = q_obj_my-command-arg */
2046 { "meta-type", QLIT_QSTR("object"), },
2072 { "meta-type", QLIT_QSTR("object"), },
2081 { "meta-type", QLIT_QSTR("object"), },
2086 { "element-type", QLIT_QSTR("1"), },
2087 { "meta-type", QLIT_QSTR("array"), },
2092 { "json-type", QLIT_QSTR("int"), },
2093 { "meta-type", QLIT_QSTR("builtin"), },
2098 { "json-type", QLIT_QSTR("string"), },
2099 { "meta-type", QLIT_QSTR("builtin"), },
2104 { "json-type", QLIT_QSTR("boolean"), },
2105 { "meta-type", QLIT_QSTR("builtin"), },