From 942ab6865ab217f370dc2e81415774aabe8b1ea8 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 9 Mar 2020 15:26:38 +0100 Subject: docs/devel/qapi-code-gen: Fix typo in grammar An ALTERNATIVE's value can only be a type name. Arrays are not supported, yet. The text gets it right: "The form STRING is shorthand for { 'type': STRING }." The grammar doesn't. Fix it. Fixes: b6c37ebaaf074cac8fe8a4781dc3e79db23e914e Reported-by: John Snow Signed-off-by: Markus Armbruster Message-Id: <20200309142638.19988-1-armbru@redhat.com> Reviewed-by: John Snow --- docs/devel/qapi-code-gen.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 59d6973e1e..e73979e182 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -399,7 +399,7 @@ Syntax: 'data': ALTERNATIVES, '*if': COND } ALTERNATIVES = { ALTERNATIVE, ... } - ALTERNATIVE = STRING : TYPE-REF + ALTERNATIVE = STRING : STRING | STRING : { 'type': STRING, '*if': COND } Member 'alternate' names the alternate type. -- cgit v1.2.3 From ad52292ea14f20b5ad296e0dee8a2a801c77717e Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 17 Mar 2020 12:54:28 +0100 Subject: docs/devel/qapi-code-gen: Clarify allow-oob introspection Mention SchemaInfo variant member "allow-oob" defaults to false. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200317115459.31821-4-armbru@redhat.com> --- docs/devel/qapi-code-gen.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index e73979e182..3ce03e6efa 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -988,9 +988,9 @@ 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 set, it means the command supports -out-of-band execution. +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. If the command takes no arguments, "arg-type" names an object type without members. Likewise, if the command returns nothing, "ret-type" -- cgit v1.2.3 From 86014c64f9a1509ab2a99d864b606882584e1f58 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 17 Mar 2020 12:54:29 +0100 Subject: 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 Reviewed-by: Eric Blake Message-Id: <20200317115459.31821-5-armbru@redhat.com> --- docs/devel/qapi-code-gen.txt | 43 ++++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 15 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 3ce03e6efa..300f277f79 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 -- cgit v1.2.3 From 013b4efc9be9af8276bd891cd52267d409f1d712 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 17 Mar 2020 12:54:37 +0100 Subject: qapi: Add feature flags to remaining definitions In v4.1.0, we added feature flags just to struct types (commit 6a8c0b5102^..f3ed93d545), to satisfy an immediate need (commit c9d4070991 "file-posix: Add dynamic-auto-read-only QAPI feature"). In v4.2.0, we added them to commands (commit 23394b4c39 "qapi: Add feature flags to commands") to satisfy another immediate need (commit d76744e65e "qapi: Allow introspecting fix for savevm's cooperation with blockdev"). Add them to the remaining definitions: enumeration types, union types, alternate types, and events. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200317115459.31821-13-armbru@redhat.com> --- docs/devel/qapi-code-gen.txt | 54 +++++++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 16 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 300f277f79..43f31b4b63 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -172,7 +172,8 @@ Syntax: ENUM = { 'enum': STRING, 'data': [ ENUM-VALUE, ... ], '*prefix': STRING, - '*if': COND } + '*if': COND, + '*features': FEATURES } ENUM-VALUE = STRING | { 'name': STRING, '*if': COND } @@ -207,6 +208,9 @@ the job satisfactorily. The optional 'if' member specifies a conditional. See "Configuring the schema" below for more on this. +The optional 'features' member specifies features. See "Features" +below for more on this. + === Type references and array types === @@ -279,12 +283,14 @@ below for more on this. Syntax: UNION = { 'union': STRING, 'data': BRANCHES, - '*if': COND } + '*if': COND, + '*features': FEATURES } | { 'union': STRING, 'data': BRANCHES, 'base': ( MEMBERS | STRING ), 'discriminator': STRING, - '*if': COND } + '*if': COND, + '*features': FEATURES } BRANCHES = { BRANCH, ... } BRANCH = STRING : TYPE-REF | STRING : { 'type': TYPE-REF, '*if': COND } @@ -391,13 +397,17 @@ is identical on the wire to: The optional 'if' member specifies a conditional. See "Configuring the schema" below for more on this. +The optional 'features' member specifies features. See "Features" +below for more on this. + === Alternate types === Syntax: ALTERNATE = { 'alternate': STRING, 'data': ALTERNATIVES, - '*if': COND } + '*if': COND, + '*features': FEATURES } ALTERNATIVES = { ALTERNATIVE, ... } ALTERNATIVE = STRING : STRING | STRING : { 'type': STRING, '*if': COND } @@ -441,6 +451,9 @@ following example objects: The optional 'if' member specifies a conditional. See "Configuring the schema" below for more on this. +The optional 'features' member specifies features. See "Features" +below for more on this. + === Commands === @@ -584,6 +597,9 @@ started with --preconfig. The optional 'if' member specifies a conditional. See "Configuring the schema" below for more on this. +The optional 'features' member specifies features. See "Features" +below for more on this. + === Events === @@ -595,7 +611,8 @@ Syntax: 'data': STRING, 'boxed': true, ) - '*if': COND } + '*if': COND, + '*features': FEATURES } Member 'event' names the event. This is the event name used in the Client JSON Protocol. @@ -628,6 +645,9 @@ complex type. See section "Code generated for events" for examples. The optional 'if' member specifies a conditional. See "Configuring the schema" below for more on this. +The optional 'features' member specifies features. See "Features" +below for more on this. + === Features === @@ -966,8 +986,9 @@ 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", "meta-type", and -additional variant members depending on the value of meta-type. +SchemaInfo objects have common members "name", "meta-type", +"features", and additional variant members depending on the value of +meta-type. Each SchemaInfo object describes a wire ABI entity of a certain meta-type: a command, event or one of several kinds of type. @@ -980,19 +1001,21 @@ not. Therefore, the SchemaInfo for types have auto-generated meaningless names. For readability, the examples in this section use meaningful type names instead. +Optional member "features" exposes the entity's feature strings as a +JSON array of strings. + To examine a type, start with a command or event using it, then follow 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", "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. +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. If the command takes no arguments, "arg-type" names an object type without members. Likewise, if the command returns nothing, "ret-type" @@ -1027,8 +1050,7 @@ 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 members "members" and -"features". +The SchemaInfo for a struct type has variant member "members". The SchemaInfo for a union type additionally has variant members "tag" and "variants". -- cgit v1.2.3 From 84ab00868798a65e19d76d3cb5f1552c6b25ceb4 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 17 Mar 2020 12:54:45 +0100 Subject: qapi: Add feature flags to struct members MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Markus Armbruster Reviewed-by: Marc-André Lureau Message-Id: <20200317115459.31821-21-armbru@redhat.com> --- docs/devel/qapi-code-gen.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 43f31b4b63..39ae2cad98 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -234,7 +234,9 @@ Syntax: '*features': FEATURES } MEMBERS = { MEMBER, ... } MEMBER = STRING : TYPE-REF - | STRING : { 'type': TYPE-REF, '*if': COND } + | STRING : { 'type': TYPE-REF, + '*if': COND, + '*features': FEATURES } Member 'struct' names the struct type. -- cgit v1.2.3 From f965e8fea6a915343d160ba6043deb75710d8df1 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 17 Mar 2020 12:54:50 +0100 Subject: qapi: New special feature flag "deprecated" Unlike regular feature flags, the new special feature flag "deprecated" is recognized by the QAPI generator. For now, it's only permitted with commands, events, and struct members. It will be put to use shortly. Signed-off-by: Markus Armbruster Message-Id: <20200317115459.31821-26-armbru@redhat.com> Reviewed-by: Eric Blake [Doc typo fixed] --- docs/devel/qapi-code-gen.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 39ae2cad98..1967adfa92 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -683,6 +683,12 @@ Intended use is to have each feature string signal that this build of QEMU shows a certain behaviour. +==== Special features ==== + +Feature "deprecated" marks a command, event, or struct member as +deprecated. It is not supported elsewhere so far. + + === Naming rules and reserved names === All names must begin with a letter, and contain only ASCII letters, -- cgit v1.2.3