Lines Matching +full:build +full:- +full:without +full:- +full:defaults
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
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
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 }`.
315 { "file": "/some/place/my-image",
316 "backing": "/some/place/my-backing-file" }
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 }`.
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 ---------------
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 --------
462 '*returns': TYPE-REF,
463 '*success-response': false,
465 '*allow-oob': true,
466 '*allow-preconfig': true,
473 Member 'data' defines the arguments. It defaults to an empty MEMBERS_
482 Member 'returns' defines the command's return type. It defaults to an
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
550 (OOB) execution. It defaults to false. For example::
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
584 before the machine is built. It defaults to false. For example::
590 'allow-preconfig': true }
593 started with --preconfig.
596 is safe to be run in a coroutine. It defaults to false. If it is true,
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
631 ------
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
683 --------
691 Sometimes, the behaviour of QEMU changes compatibly, but without a
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.
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_.
840 Example: a struct with conditional feature 'allow-negative-numbers' ::
844 'features': [ { 'name': 'allow-negative-numbers',
853 this particular build.
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' },
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",
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
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
1248 execution. It defaults to false.
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
1299 { "name": "MyType", "meta-type": "object",
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
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
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"), },
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"), },