[PATCH v2 04/30] docs/devel/qapi-code-gen: Document 'features' introspection
Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
to update section "Client JSON Protocol introspection", and commit
23394b4c39 "qapi: Add feature flags to commands" didn't either. Make
up for that.
Signed-off-by: Markus Armbruster <armbru(a)redhat.com>
---
docs/devel/qapi-code-gen.txt | 43 +++++++++++++++++++++++-------------
1 file changed, 28 insertions(+), 15 deletions(-)
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 5906602504..297a725084 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -642,13 +642,8 @@ that previously resulted in an error). QMP clients may still need
to
know whether the extension is available.
For this purpose, a list of features can be specified for a command or
-struct type. This is exposed to the client as a list of strings,
-where each string signals that this build of QEMU shows a certain
-behaviour.
-
-Each member of the 'features' array defines a feature. It can either
-be { 'name': STRING, '*if': COND }, or STRING, which is shorthand for
-{ 'name': STRING }.
+struct type. Each list member can either be { 'name': STRING, '*if':
+COND }, or STRING, which is shorthand for { 'name': STRING }.
The optional 'if' member specifies a conditional. See "Configuring
the schema" below for more on this.
@@ -659,6 +654,12 @@ Example:
'data': { 'number': 'int' },
'features': [ 'allow-negative-numbers' ] }
+The feature strings are exposed to clients in introspection, as
+explained in section "Client JSON Protocol introspection".
+
+Intended use is to have each feature string signal that this build of
+QEMU shows a certain behaviour.
+
=== Naming rules and reserved names ===
@@ -965,7 +966,7 @@ schema, along with the SchemaInfo type. This text attempts to give
an
overview how things work. For details you need to consult the QAPI
schema.
-SchemaInfo objects have common members "name" and "meta-type", and
+SchemaInfo objects have common members "name", "meta-type", and
additional variant members depending on the value of meta-type.
Each SchemaInfo object describes a wire ABI entity of a certain
@@ -985,12 +986,13 @@ references by name.
QAPI schema definitions not reachable that way are omitted.
The SchemaInfo for a command has meta-type "command", and variant
-members "arg-type", "ret-type" and "allow-oob". On the
wire, the
-"arguments" member of a client's "execute" command must conform
to the
-object type named by "arg-type". The "return" member that the
server
-passes in a success response conforms to the type named by "ret-type".
-When "allow-oob" is true, it means the command supports out-of-band
-execution. It defaults to false.
+members "arg-type", "ret-type", "allow-oob", and
"features". On the
+wire, the "arguments" member of a client's "execute" command
must
+conform to the object type named by "arg-type". The "return" member
+that the server passes in a success response conforms to the type
+named by "ret-type". When "allow-oob" is true, it means the command
+supports out-of-band execution. It defaults to false. "features"
+exposes the command's feature strings as a JSON array of strings.
If the command takes no arguments, "arg-type" names an object type
without members. Likewise, if the command returns nothing, "ret-type"
@@ -1025,7 +1027,8 @@ Example: the SchemaInfo for EVENT_C from section Events
The SchemaInfo for struct and union types has meta-type "object".
-The SchemaInfo for a struct type has variant member "members".
+The SchemaInfo for a struct type has variant members "members" and
+"features".
The SchemaInfo for a union type additionally has variant members "tag"
and "variants".
@@ -1047,6 +1050,16 @@ Example: the SchemaInfo for MyType from section Struct types
{ "name": "member2", "type": "int" },
{ "name": "member3", "type": "str",
"default": null } ] }
+"features" exposes the command's feature strings as a JSON array of
+strings.
+
+Example: the SchemaInfo for TestType from section Features:
+
+ { "name": "TestType", "meta-type": "object",
+ "members": [
+ { "name": "number", "type": "int" } ],
+ "features": ["allow-negative-numbers"] }
+
"tag" is the name of the common member serving as type tag.
"variants" is a JSON array describing the object's variant members.
Each element is a JSON object with members "case" (the value of type
--
2.21.1