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 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
992 line "Features:", like this::
995 # Features:
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
1038 default to "Example:".
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' },
1125 A blank line is required between list items and paragraphs. Without
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
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
1214 Like any other command, query-qmp-schema is itself defined in the QAPI
1219 SchemaInfo objects have common members "name", "meta-type",
1220 "features", and additional variant members depending on the value of
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
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
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"
1252 names an object type without members.
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" }
1259 Type "q_empty" is an automatic object type without members, and 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
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
1289 name), "type" (the name of its type), "features" (a JSON array of
1290 feature strings), and "default". The latter two are optional. The
1291 member is optional if "default" is present. Currently, "default" can
1299 { "name": "MyType", "meta-type": "object",
1303 { "name": "member3", "type": "str", "default": null } ] }
1305 "features" exposes the command's feature strings as a JSON array of
1310 { "name": "TestType", "meta-type": "object",
1313 "features": ["allow-negative-numbers"] }
1326 { "name": "BlockdevOptions", "meta-type": "object",
1329 { "name": "read-only", "type": "bool", "default": null } ],
1338 The SchemaInfo for an alternate type has meta-type "alternate", and
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
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
1368 optionally "features" (a JSON array of feature strings). The
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
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.
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
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
1514 can be generated/used from multiple schemas without clobbering previously
1519 $ cat qapi-generated/example-qapi-types.h
1525 #include "qapi/qapi-builtin-types.h"
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)) {
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
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``
1988 ``$(prefix)qapi-introspect.h``
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"), },
2044 { "default", QLIT_QNULL, },
2050 { "default", QLIT_QNULL, },
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"), },