motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-09-08 16:07:39 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/devel/qapi-code-gen: Document 'features' introspection

Browse source 
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@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200317115459.31821-5-armbru@redhat.com>
This commit is contained in:
Markus Armbruster 2020-03-17 12:54:29 +01:00
parent ad52292ea1
commit 86014c64f9
1 changed files with 28 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

43
docs/devel/qapi-code-gen.txt
View file

@ -642,13 +642,8 @@ that previously resulted in an error). QMP clients may still need to
know whether the extension is available. know whether the extension is available.
For this purpose, a list of features can be specified for a command or 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, struct type. Each list member can either be { 'name': STRING, '*if':
where each string signals that this build of QEMU shows a certain COND }, or STRING, which is shorthand for { 'name': STRING }.
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 }.
The optional 'if' member specifies a conditional. See "Configuring The optional 'if' member specifies a conditional. See "Configuring
the schema" below for more on this. the schema" below for more on this.
@ -659,6 +654,12 @@ Example:
'data': { 'number': 'int' }, 'data': { 'number': 'int' },
'features': [ 'allow-negative-numbers' ] } '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 === === 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 overview how things work. For details you need to consult the QAPI
schema. 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. additional variant members depending on the value of meta-type.
Each SchemaInfo object describes a wire ABI entity of a certain 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. QAPI schema definitions not reachable that way are omitted.
The SchemaInfo for a command has meta-type "command", and variant The SchemaInfo for a command has meta-type "command", and variant
members "arg-type", "ret-type" and "allow-oob". On the wire, the members "arg-type", "ret-type", "allow-oob", and "features". On the
"arguments" member of a client's "execute" command must conform to the wire, the "arguments" member of a client's "execute" command must
object type named by "arg-type". The "return" member that the server conform to the object type named by "arg-type". The "return" member
passes in a success response conforms to the type named by "ret-type". that the server passes in a success response conforms to the type
When "allow-oob" is true, it means the command supports out-of-band named by "ret-type". When "allow-oob" is true, it means the command
execution. It defaults to false. 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 If the command takes no arguments, "arg-type" names an object type
without members. Likewise, if the command returns nothing, "ret-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 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" The SchemaInfo for a union type additionally has variant members "tag"
and "variants". and "variants".
@ -1047,6 +1050,16 @@ Example: the SchemaInfo for MyType from section Struct types
{ "name": "member2", "type": "int" }, { "name": "member2", "type": "int" },
{ "name": "member3", "type": "str", "default": null } ] } { "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. "tag" is the name of the common member serving as type tag.
"variants" is a JSON array describing the object's variant members. "variants" is a JSON array describing the object's variant members.
Each element is a JSON object with members "case" (the value of type Each element is a JSON object with members "case" (the value of type