[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL 13/15] qapi: Make BlockdevOptions doc example closer
From: |
Markus Armbruster |
Subject: |
[Qemu-devel] [PULL 13/15] qapi: Make BlockdevOptions doc example closer to reality |
Date: |
Fri, 18 Mar 2016 11:04:27 +0100 |
From: Eric Blake <address@hidden>
Although we don't want to repeat the entire BlockdevOptions
QMP command in the example, it helps if we aren't needlessly
diverging (the initial example was written before we had
committed the actual QMP interface). Use names that match what
is found in qapi/block-core.json, such as '*read-only' rather
than 'readonly', or 'BlockdevRef' rather than 'BlockRef'.
For the simple union example, invent BlockdevOptionsSimple so
that later text is unambiguous which of the two union forms is
meant (telling the user to refer back to two 'BlockdevOptions'
wasn't nice, and QMP has only the flat union form).
Also, mention that the discriminator of a flat union is
non-optional.
Signed-off-by: Eric Blake <address@hidden>
Message-Id: <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>
---
docs/qapi-code-gen.txt | 74 +++++++++++++++++++++++++-------------------------
1 file changed, 37 insertions(+), 37 deletions(-)
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index c648f76..12af1b8 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -297,22 +297,22 @@ be empty.
A simple union type defines a mapping from automatic discriminator
values to data types like in this example:
- { 'struct': 'FileOptions', 'data': { 'filename': 'str' } }
- { 'struct': 'Qcow2Options',
- 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
+ { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } }
+ { 'struct': 'BlockdevOptionsQcow2',
+ 'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } }
- { 'union': 'BlockdevOptions',
- 'data': { 'file': 'FileOptions',
- 'qcow2': 'Qcow2Options' } }
+ { 'union': 'BlockdevOptionsSimple',
+ 'data': { 'file': 'BlockdevOptionsFile',
+ 'qcow2': 'BlockdevOptionsQcow2' } }
In the Client JSON Protocol, a simple union is represented by a
dictionary that contains the 'type' member as a discriminator, and a
'data' member that is of the specified data type corresponding to the
discriminator value, as in these examples:
- { "type": "file", "data" : { "filename": "/some/place/my-image" } }
- { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
- "lazy-refcounts": true } }
+ { "type": "file", "data": { "filename": "/some/place/my-image" } }
+ { "type": "qcow2", "data": { "backing": "/some/place/my-image",
+ "lazy-refcounts": true } }
The generated C code uses a struct containing a union. Additionally,
an implicit C enum 'NameKind' is created, corresponding to the union
@@ -325,29 +325,29 @@ avoids nesting on the wire. All branches of the union
must be
complex types, and the top-level members of the union dictionary on
the wire will be combination of members from both the base type and the
appropriate branch type (when merging two dictionaries, there must be
-no keys in common). The 'discriminator' member must be the name of an
-enum-typed member of the base struct.
+no keys in common). The 'discriminator' member must be the name of a
+non-optional enum-typed member of the base struct.
The following example enhances the above simple union example by
-adding a common member 'readonly', renaming the discriminator to
-something more applicable, and reducing the number of {} required on
-the wire:
+adding an optional common member 'read-only', renaming the
+discriminator to something more applicable than the simple union's
+default of 'type', and reducing the number of {} required on the wire:
{ 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
- { 'struct': 'BlockdevCommonOptions',
- 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } }
+ { 'struct': 'BlockdevOptionsBase',
+ 'data': { 'driver': 'BlockdevDriver', '*read-only': 'bool' } }
{ 'union': 'BlockdevOptions',
- 'base': 'BlockdevCommonOptions',
+ 'base': 'BlockdevOptionsBase',
'discriminator': 'driver',
- 'data': { 'file': 'FileOptions',
- 'qcow2': 'Qcow2Options' } }
+ 'data': { 'file': 'BlockdevOptionsFile',
+ 'qcow2': 'BlockdevOptionsQcow2' } }
Resulting in these JSON objects:
- { "driver": "file", "readonly": true,
+ { "driver": "file", "read-only": true,
"filename": "/some/place/my-image" }
- { "driver": "qcow2", "readonly": false,
- "backing-file": "/some/place/my-image", "lazy-refcounts": true }
+ { "driver": "qcow2", "read-only": false,
+ "backing": "/some/place/my-image", "lazy-refcounts": true }
Notice that in a flat union, the discriminator name is controlled by
the user, but because it must map to a base member with enum type, the
@@ -382,7 +382,7 @@ data types (string, integer, number, or object, but
currently not
array) on the wire. The definition is similar to a simple union type,
where each branch of the union names a QAPI type. For example:
- { 'alternate': 'BlockRef',
+ { 'alternate': 'BlockdevRef',
'data': { 'definition': 'BlockdevOptions',
'reference': 'str' } }
@@ -403,7 +403,7 @@ following example objects:
{ "file": "my_existing_block_device_id" }
{ "file": { "driver": "file",
- "readonly": false,
+ "read-only": false,
"filename": "/tmp/mydisk.qcow2" } }
@@ -637,11 +637,11 @@ Union types
{ "name": "BlockdevOptions", "meta-type": "object",
"members": [
{ "name": "driver", "type": "BlockdevDriver" },
- { "name": "readonly", "type": "bool"} ],
+ { "name": "read-only", "type": "bool", "default": null } ],
"tag": "driver",
"variants": [
- { "case": "file", "type": "FileOptions" },
- { "case": "qcow2", "type": "Qcow2Options" } ] }
+ { "case": "file", "type": "BlockdevOptionsFile" },
+ { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
Note that base types are "flattened": its members are included in the
"members" array.
@@ -652,20 +652,20 @@ discriminator (called "type" on the wire, see section
Union types).
A simple union implicitly defines an object type for each of its
variants.
-Example: the SchemaInfo for simple union BlockdevOptions from section
+Example: the SchemaInfo for simple union BlockdevOptionsSimple from section
Union types
- { "name": "BlockdevOptions", "meta-type": "object",
+ { "name": "BlockdevOptionsSimple", "meta-type": "object",
"members": [
- { "name": "type", "type": "BlockdevOptionsKind" } ],
+ { "name": "type", "type": "BlockdevOptionsSimpleKind" } ],
"tag": "type",
"variants": [
- { "case": "file", "type": "q_obj-FileOptions-wrapper" },
- { "case": "qcow2", "type": "q_obj-Qcow2Options-wrapper" } ] }
+ { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" },
+ { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] }
- Enumeration type "BlockdevOptionsKind" and the object types
- "q_obj-FileOptions-wrapper", "q_obj-Qcow2Options-wrapper" are
- implicitly defined.
+ Enumeration type "BlockdevOptionsSimpleKind" and the object types
+ "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper"
+ are implicitly defined.
The SchemaInfo for an alternate type has meta-type "alternate", and
variant member "members". "members" is a JSON array. Each element is
@@ -673,9 +673,9 @@ a JSON object with member "type", which names a type.
Values of the
alternate type conform to exactly one of its member types. There is
no guarantee on the order in which "members" will be listed.
-Example: the SchemaInfo for BlockRef from section Alternate types
+Example: the SchemaInfo for BlockdevRef from section Alternate types
- { "name": "BlockRef", "meta-type": "alternate",
+ { "name": "BlockdevRef", "meta-type": "alternate",
"members": [
{ "type": "BlockdevOptions" },
{ "type": "str" } ] }
--
2.4.3
- [Qemu-devel] [PULL 00/15] QAPI patches for 2016-03-18, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 01/15] qapi: Assert in places where variants are not handled, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 14/15] qapi: Allow anonymous base for flat union, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 08/15] qapi-commands: Utilize implicit struct visits, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 06/15] qapi-event: Drop qmp_output_get_qobject() null check, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 04/15] qapi: Adjust names of implicit types, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 10/15] qapi: Inline gen_visit_members() into lone caller, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 15/15] qapi: Use anonymous bases in QMP flat unions, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 02/15] qapi: Fix command with named empty argument type, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 11/15] qapi: Drop unused c_null(), Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 13/15] qapi: Make BlockdevOptions doc example closer to reality,
Markus Armbruster <=
- [Qemu-devel] [PULL 09/15] qapi-commands: Inline single-use helpers of gen_marshal(), Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 03/15] qapi: Make c_type() more OO-like, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 05/15] qapi: Emit implicit structs in generated C, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 07/15] qapi-event: Utilize implicit struct visits, Markus Armbruster, 2016/03/18
- [Qemu-devel] [PULL 12/15] qapi: Don't special-case simple union wrappers, Markus Armbruster, 2016/03/18
- Re: [Qemu-devel] [PULL 00/15] QAPI patches for 2016-03-18, Peter Maydell, 2016/03/18