Lines Matching +full:- +full:- +full:without +full:- +full:default +full:- +full:features
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 -------------
67 syntax in an EBNF-like notation:
69 * Production rules look like ``non-terminal = expression``
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
120 ``int`` ``int64_t`` a JSON number without fractional part
140 ------------------
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
180 is required. Default is false.
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
186 violate the rules on permitted return types. Default is none.
188 Pragma 'documentation-exceptions' takes a list of types, commands, and
189 events whose members / arguments need not be documented. Default is
192 Pragma 'member-name-exceptions' takes a list of types whose member
193 names may contain uppercase letters, and ``"_"`` instead of ``"-"``.
194 Default is none.
196 .. _ENUM-VALUE:
199 -----------------
204 'data': [ ENUM-VALUE, ... ],
207 '*features': FEATURES }
208 ENUM-VALUE = STRING
211 '*features': FEATURES }
235 The generated C enumeration constants have values 0, 1, ..., N-1 (in
245 The optional 'features' member specifies features. See Features_
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 ------------
274 '*features': FEATURES }
276 MEMBER = STRING : TYPE-REF
277 | STRING : { 'type': TYPE-REF,
279 '*features': FEATURES }
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" }
321 The optional 'features' member specifies features. See Features_
326 -----------
335 '*features': FEATURES }
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 }`.
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 }
390 The optional 'features' member specifies features. See Features_
395 ---------------
402 '*features': FEATURES }
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,
446 The optional 'features' member specifies features. See Features_
451 --------
462 '*returns': TYPE-REF,
463 '*success-response': false,
465 '*allow-oob': true,
466 '*allow-preconfig': true,
469 '*features': FEATURES }
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``
620 without a use case, it's not entirely clear what the semantics should
626 The optional 'features' member specifies features. See Features_
631 ------
643 '*features': FEATURES }
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``.
669 is absent, it takes event-specific data one by one, in QAPI schema
676 The optional 'features' member specifies features. See Features_
682 Features section in The QAPI schema language
683 --------
687 FEATURES = [ FEATURE, ... ]
691 Sometimes, the behaviour of QEMU changes compatibly, but without a
696 For this purpose, a list of features can be specified for definitions,
708 'features': [ 'allow-negative-numbers' ] }
717 Special features
731 -------------------------------
740 problematic strings. For example, a member named ``default`` in qapi
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 ---------------------
780 downstream command ``__com.redhat_drive-mirror``.
784 ----------------------
828 requires the longhand form of ENUM-VALUE_.
837 Likewise, features can be conditional. This requires the longhand
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.
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
1007 line "Features:", like this::
1010 # Features:
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.
1047 directionality indicators (``->`` and ``<-``), and elisions. An
1053 default to "Example:".
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' },
1140 A blank line is required between list items and paragraphs. Without
1146 # - its name matches the @name pattern, and
1147 # - if @vcpu is given, the event has the "vcpu" property.
1149 Without the blank line this would be a single paragraph.
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
1203 query-qmp-schema. QGA currently doesn't support introspection.
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
1229 Like any other command, query-qmp-schema is itself defined in the QAPI
1234 SchemaInfo objects have common members "name", "meta-type",
1235 "features", and additional variant members depending on the value of
1236 meta-type.
1239 meta-type: a command, event or one of several kinds of type.
1245 not. Therefore, the SchemaInfo for types have auto-generated
1249 Optional member "features" exposes the entity's feature strings as a
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"
1267 names an object type without members.
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" }
1274 Type "q_empty" is an automatic object type without members, and type
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
1282 object type without members. The event may not have a data member on
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
1304 name), "type" (the name of its type), "features" (a JSON array of
1305 feature strings), and "default". The latter two are optional. The
1306 member is optional if "default" is present. Currently, "default" can
1314 { "name": "MyType", "meta-type": "object",
1318 { "name": "member3", "type": "str", "default": null } ] }
1320 "features" exposes the command's feature strings as a JSON array of
1325 { "name": "TestType", "meta-type": "object",
1328 "features": ["allow-negative-numbers"] }
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
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
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" }
1411 the names of built-in types. Clients should examine member
1412 "json-type" instead of hard-coding names of built-in types.
1426 Adding opt-in functionality to the send direction is backwards
1438 flexibility; for example, when an optional 'buffer-size' argument is
1439 specified to default to a sensible buffer size, the actual default
1440 value can still be changed. The specified default behavior is not the
1441 exact size of the buffer, only that the default size is sensible.
1479 The QAPI code generator qapi-gen.py generates code and documentation
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``
1524 ``$(prefix)qapi-types.c``
1528 generated code from one schema/code-generation separated from others so code
1529 can be generated/used from multiple schemas without clobbering previously
1534 $ cat qapi-generated/example-qapi-types.h
1540 #include "qapi/qapi-builtin-types.h"
1571 $ cat qapi-generated/example-qapi-types.c
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)) {
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 ---------------------------
1772 ``$(prefix)qapi-commands.c``
1776 ``$(prefix)qapi-commands.h``
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
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",
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 -------------------------
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
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``
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"), },
2059 { "default", QLIT_QNULL, },
2065 { "default", QLIT_QNULL, },
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"), },