Lines Matching +full:string +full:- +full:array +full:- +full:property
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
43 There are several kinds of types: simple types (a number of built-in
50 -------------
56 string, and extend to the end of the line.
67 syntax in an EBNF-like notation:
69 * Production rules look like ``non-terminal = expression``
79 * String literals enclosed in ``'single quotes'`` are terminal, and match
80 this JSON string, with a leading ``*`` stripped off
83 * The symbol ``STRING`` is a terminal, and matches any JSON string
85 * ALL-CAPS words other than ``STRING`` are non-terminals
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
98 A top-level expressions is either a directive or a definition::
100 TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION
110 Built-in Types
111 --------------
118 ``str`` ``char *`` any JSON string, UTF-8
135 ``QType`` ``QType`` JSON string matching enum ``QType`` values
140 ------------------
144 INCLUDE = { 'include': STRING }
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, ... ] } }
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 -----------------
203 ENUM = { 'enum': STRING,
204 'data': [ ENUM-VALUE, ... ],
205 '*prefix': STRING,
208 ENUM-VALUE = STRING
209 | { 'name': STRING,
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
227 (string) name. In C, it's represented by an enumeration constant.
235 The generated C enumeration constants have values 0, 1, ..., N-1 (in
239 Do not use string or an integer type when an enumeration type can do
249 .. _TYPE-REF:
251 Type references and array types
252 -------------------------------
256 TYPE-REF = STRING | ARRAY-TYPE
257 ARRAY-TYPE = [ STRING ]
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``.
266 ------------
270 STRUCT = { 'struct': STRING,
272 '*base': STRING,
276 MEMBER = STRING : TYPE-REF
277 | STRING : { 'type': TYPE-REF,
287 The MEMBER's STRING name consists of an optional ``*`` prefix and the
291 The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`.
315 { "file": "/some/place/my-image",
316 "backing": "/some/place/my-backing-file" }
326 -----------
330 UNION = { 'union': STRING,
331 'base': ( MEMBERS | STRING ),
332 'discriminator': STRING,
337 BRANCH = STRING : TYPE-REF
338 | STRING : { 'type': TYPE-REF, '*if': COND }
344 member defines struct type members. If it is a STRING, it names a
347 Member 'discriminator' must name a non-optional enum-typed member of
354 The BRANCH's STRING name is the branch name. It must be a value of
358 type. The type must a struct type. The form TYPE-REF_ is shorthand
359 for :code:`{ 'type': TYPE-REF }`.
369 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
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 }
395 ---------------
399 ALTERNATE = { 'alternate': STRING,
404 ALTERNATIVE = STRING : STRING
405 | STRING : { 'type': STRING, '*if': COND }
412 The ALTERNATIVE's STRING name is the branch name.
415 its type. The form STRING is shorthand for :code:`{ 'type': STRING }`.
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
440 "read-only": false,
451 --------
455 COMMAND = { 'command': STRING,
457 '*data': ( MEMBERS | STRING ),
459 'data': STRING,
462 '*returns': TYPE-REF,
463 '*success-response': false,
465 '*allow-oob': true,
466 '*allow-preconfig': true,
479 If 'data' is a STRING, then STRING names a complex type whose members
483 empty struct type. It must normally be a complex type or an array of
485 in pragma 'commands-returns-exceptions'. If you do this, extending
492 In the Client JSON Protocol, the value of the "execute" or "exec-oob"
499 { 'command': 'my-first-command',
502 { 'command': 'my-second-command',
507 => { "execute": "my-first-command",
510 => { "execute": "my-second-command" }
528 In rare cases, QAPI cannot express a type-safe representation of a
539 use type-safe unions.
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``
631 ------
635 EVENT = { 'event': STRING,
637 '*data': ( MEMBERS | STRING ),
639 'data': STRING,
648 Member 'data' defines the event-specific data. It defaults to an
651 If 'data' is a MEMBERS object, then MEMBERS defines event-specific
654 If 'data' is a STRING, then STRING names a complex type whose members
655 are the event-specific data. A union type requires ``'boxed': true``.
665 "data": { "b": "test string" },
669 is absent, it takes event-specific data one by one, in QAPI schema
683 --------
688 FEATURE = STRING
689 | { 'name': STRING, '*if': COND }
698 either be ``{ 'name': STRING, '*if': COND }``, or STRING, which is
699 shorthand for ``{ 'name': STRING }``.
708 'features': [ 'allow-negative-numbers' ] }
713 Intended use is to have each feature string signal that this build of
731 -------------------------------
745 user-defined type names, while built-in types are lowercase.
748 uses them for array types.
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 ---------------------
780 downstream command ``__com.redhat_drive-mirror``.
784 ----------------------
788 COND = STRING
794 string, or an object with a single member 'all', 'any' or 'not'.
799 * STRING will generate defined(STRING)
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 A free-form documentation comment containing a line which starts with
885 # This is a free-form comment which will go under the
897 define a third-level heading inside a second-level heading, and so on.
904 a ``::`` literal block can be used for pre-formatted text::
917 You can also use ``-`` instead of ``*``.
934 backslash-escape it.
953 # -> do this
954 # <- get that
969 When documentation is required (see pragma_ 'doc-required'), every
1019 # - If @device does not exist, DeviceNotFound
1020 # - Any other error returns a GenericError.
1029 QMP Examples can be added by using the ``.. qmp-example::`` directive.
1032 directionality indicators (``->`` and ``<-``), and elisions. An
1042 # .. qmp-example::
1044 # -> { "execute": "query-name" }
1045 # <- { "return": { "name": "Fred" } }
1047 More complex or multi-step examples where exposition is needed before
1054 # .. qmp-example::
1061 # -> { "execute": "query-block" }
1062 # <- { "return": [
1064 # "device": "ide0-hd0",
1072 Highlighting in non-QMP languages can be accomplished by using the
1073 ``.. code-block:: lang`` directive, and non-highlighted text can be
1087 # @node-name: The node name of the device. (Since 2.3)
1094 'data': {'*device': 'str', '*node-name': 'str',
1098 # @query-blockstats:
1102 # @query-nodes: If true, the command will query all the block nodes
1110 # .. qmp-example::
1112 # -> { "execute": "query-blockstats" }
1113 # <- {
1117 { 'command': 'query-blockstats',
1118 'data': { '*query-nodes': 'bool' },
1131 # - its name matches the @name pattern, and
1132 # - if @vcpu is given, the event has the "vcpu" property.
1142 The last line's de-indent is wrong. The second and subsequent lines
1149 Section tags are case-sensitive and end with a colon. They are only
1165 # @interface-id: Interface ID
1169 # @interface-id Interface ID
1171 # @interface-id : Interface ID
1188 query-qmp-schema. QGA currently doesn't support introspection.
1193 a non-variant optional member of a struct, and a later version rework
1194 the member to instead be non-optional and associated with a variant.
1195 Likewise, one version of qemu may list a member with open-ended type
1201 query-qmp-schema returns a JSON array of SchemaInfo objects. These
1204 client must search for a particular name throughout the entire array
1214 Like any other command, query-qmp-schema is itself defined in the QAPI
1219 SchemaInfo objects have common members "name", "meta-type",
1221 meta-type.
1224 meta-type: a command, event or one of several kinds of type.
1230 not. Therefore, the SchemaInfo for types have auto-generated
1235 JSON array of strings.
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
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 ::
1256 { "name": "query-qmp-schema", "meta-type": "command",
1257 "arg-type": "q_empty", "ret-type": "SchemaInfoList" }
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
1275 { "name": "EVENT_C", "meta-type": "event",
1276 "arg-type": "q_obj-EVENT_C-arg" }
1278 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1281 The SchemaInfo for struct and union types has meta-type "object" and
1287 "members" is a JSON array describing the object's common members, if
1289 name), "type" (the name of its type), "features" (a JSON array of
1293 extensions. The "members" array is in no particular order; clients
1299 { "name": "MyType", "meta-type": "object",
1305 "features" exposes the command's feature strings as a JSON array of
1310 { "name": "TestType", "meta-type": "object",
1313 "features": ["allow-negative-numbers"] }
1316 "variants" is a JSON array describing the object's variant members.
1320 "variants" array is in no particular order, and is not guaranteed to
1326 { "name": "BlockdevOptions", "meta-type": "object",
1329 { "name": "read-only", "type": "bool", "default": null } ],
1336 "members" array.
1338 The SchemaInfo for an alternate type has meta-type "alternate", and
1339 variant member "members". "members" is a JSON array. Each element is
1346 { "name": "BlockdevRef", "meta-type": "alternate",
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
1355 "element-type" instead of making assumptions based on parsing member
1360 { "name": "[str]", "meta-type": "array",
1361 "element-type": "str" }
1363 The SchemaInfo for an enumeration type has meta-type "enum" and
1366 "members" is a JSON array describing the enumeration values. Each
1368 optionally "features" (a JSON array of feature strings). The
1369 "members" array is in no particular order; clients must search the
1370 entire array when learning whether a particular value is supported.
1374 { "name": "MyEnum", "meta-type": "enum",
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
1383 detailed below. It has variant member "json-type" that shows how
1388 { "name": "str", "meta-type": "builtin", "json-type": "string" }
1396 the names of built-in types. Clients should examine member
1397 "json-type" instead of hard-coding names of built-in types.
1411 Adding opt-in functionality to the send direction is backwards
1423 flexibility; for example, when an optional 'buffer-size' argument is
1464 The QAPI code generator qapi-gen.py generates code and documentation
1473 single complex user-defined type, along with command which takes a
1480 $ cat example-schema.json
1482 'data': { 'integer': 'int', '*string': 'str', '*flag': 'bool' } }
1484 { 'command': 'my-command',
1490 We run qapi-gen.py like this::
1492 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1493 --prefix="example-" example-schema.json
1496 tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1498 part of 'make check-unit'.
1502 -----------------------------
1506 ``$(prefix)qapi-types.h``
1509 ``$(prefix)qapi-types.c``
1513 generated code from one schema/code-generation separated from others so code
1519 $ cat qapi-generated/example-qapi-types.h
1525 #include "qapi/qapi-builtin-types.h"
1535 char *string;
1556 $ cat qapi-generated/example-qapi-types.c
1588 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1590 SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1591 SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1593 If qapi-gen.py is run with option --builtins, additional files are
1596 ``qapi-builtin-types.h``
1597 C types corresponding to built-in types
1599 ``qapi-builtin-types.c``
1604 --------------------------------------
1613 ``$(prefix)qapi-visit.c``
1615 convert QObjects into the corresponding C type and vice-versa, as
1618 ``$(prefix)qapi-visit.h``
1623 $ cat qapi-generated/example-qapi-visit.h
1629 #include "qapi/qapi-builtin-visit.h"
1630 #include "example-qapi-types.h"
1644 $ cat qapi-generated/example-qapi-visit.c
1649 bool has_string = !!obj->string;
1651 if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1654 if (visit_optional(v, "string", &has_string)) {
1655 if (!visit_type_str(v, "string", &obj->string, errp)) {
1659 if (visit_optional(v, "flag", &obj->has_flag)) {
1660 if (!visit_type_bool(v, "flag", &obj->flag, errp)) {
1707 if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
1724 if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1733 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1735 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1736 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1738 If qapi-gen.py is run with option --builtins, additional files are
1741 ``qapi-builtin-visit.h``
1742 Visitor functions for built-in types
1744 ``qapi-builtin-visit.c``
1749 ---------------------------
1757 ``$(prefix)qapi-commands.c``
1761 ``$(prefix)qapi-commands.h``
1764 ``$(prefix)qapi-commands.trace-events``
1767 ``$(prefix)qapi-init-commands.h``
1770 ``$(prefix)qapi-init-commands.c``
1775 $ cat qapi-generated/example-qapi-commands.h
1781 #include "example-qapi-types.h"
1788 $ cat qapi-generated/example-qapi-commands.trace-events
1794 $ cat qapi-generated/example-qapi-commands.c
1835 trace_qmp_enter_my_command(req_json->str);
1850 trace_qmp_exit_my_command(ret_json->str, true);
1863 $ cat qapi-generated/example-qapi-init-commands.h
1868 #include "qapi/qmp-registry.h"
1873 $ cat qapi-generated/example-qapi-init-commands.c
1879 qmp_register_command(cmds, "my-command",
1885 each sub-module SUBDIR/SUBMODULE.json is actually generated into::
1887 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1888 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1892 -------------------------
1899 ``$(prefix)qapi-events.h``
1902 ``$(prefix)qapi-events.c``
1905 ``$(prefix)qapi-emit-events.h``
1908 ``$(prefix)qapi-emit-events.c``
1913 $ cat qapi-generated/example-qapi-events.h
1920 #include "example-qapi-types.h"
1925 $ cat qapi-generated/example-qapi-events.c
1940 $ cat qapi-generated/example-qapi-emit-events.h
1961 $ cat qapi-generated/example-qapi-emit-events.c
1965 .array = (const char *const[]) {
1974 each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1976 SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1977 SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1981 --------------------------------
1985 ``$(prefix)qapi-introspect.c``
1986 Defines a string holding a JSON description of the schema
1988 ``$(prefix)qapi-introspect.h``
1989 Declares the above string
1993 $ cat qapi-generated/example-qapi-introspect.h
2004 $ cat qapi-generated/example-qapi-introspect.c
2009 { "arg-type", QLIT_QSTR("0"), },
2010 { "meta-type", QLIT_QSTR("command"), },
2011 { "name", QLIT_QSTR("my-command"), },
2012 { "ret-type", QLIT_QSTR("1"), },
2016 { "arg-type", QLIT_QSTR("2"), },
2017 { "meta-type", QLIT_QSTR("event"), },
2021 /* "0" = q_obj_my-command-arg */
2031 { "meta-type", QLIT_QSTR("object"), },
2045 { "name", QLIT_QSTR("string"), },
2057 { "meta-type", QLIT_QSTR("object"), },
2066 { "meta-type", QLIT_QSTR("object"), },
2071 { "element-type", QLIT_QSTR("1"), },
2072 { "meta-type", QLIT_QSTR("array"), },
2077 { "json-type", QLIT_QSTR("int"), },
2078 { "meta-type", QLIT_QSTR("builtin"), },
2083 { "json-type", QLIT_QSTR("string"), },
2084 { "meta-type", QLIT_QSTR("builtin"), },
2089 { "json-type", QLIT_QSTR("boolean"), },
2090 { "meta-type", QLIT_QSTR("builtin"), },