[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 05/18] docs: Document QAPI union types
From: |
Kevin Wolf |
Subject: |
[Qemu-devel] [PATCH 05/18] docs: Document QAPI union types |
Date: |
Tue, 23 Jul 2013 15:03:13 +0200 |
Signed-off-by: Kevin Wolf <address@hidden>
---
docs/qapi-code-gen.txt | 58 +++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 53 insertions(+), 5 deletions(-)
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index cccb11e..555ca66 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -34,7 +34,13 @@ OrderedDicts so that ordering is preserved.
There are two basic syntaxes used, type definitions and command definitions.
The first syntax defines a type and is represented by a dictionary. There are
-two kinds of types that are supported: complex user-defined types, and enums.
+three kinds of user-defined types that are supported: complex types,
+enumeration types and union types.
+
+Generally speaking, types definitions should always use CamelCase for the type
+names. Command names should be all lower case with words separated by a hyphen.
+
+=== Complex types ===
A complex type is a dictionary containing a single key who's value is a
dictionary. This corresponds to a struct in C or an Object in JSON. An
@@ -47,13 +53,57 @@ The use of '*' as a prefix to the name means the member is
optional. Optional
members should always be added to the end of the dictionary to preserve
backwards compatibility.
+=== Enumeration types ===
+
An enumeration type is a dictionary containing a single key who's value is a
list of strings. An example enumeration is:
{ 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
-Generally speaking, complex types and enums should always use CamelCase for
-the type names.
+=== Union types ===
+
+Union types are used to let the user choose between several different data
+types. A union type is defined using a dictionary as explained in the
+following paragraphs.
+
+
+A simple union type defines a mapping from discriminator values to data types
+like in this example:
+
+ { 'type': 'FileOptions', 'data': { 'filename': 'str' } }
+ { 'type': 'Qcow2Options',
+ 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
+
+ { 'union': 'BlockdevOptions',
+ 'data': { 'file': 'FileOptions',
+ 'qcow2': 'Qcow2Options' } }
+
+In the QMP wire format, a simple union is represented by a dictionary that
+contains the 'type' field as a discriminator, and a 'data' field that is of the
+specified data type corresponding to the discriminator value:
+
+ { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
+ "lazy-refcounts": true } }
+
+
+A union definition can specify a complex type as its base. In this case, the
+fields of the complex type are included as top-level fields of the union
+dictionary in the QMP wire format. An example definition is:
+
+ { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
+ { 'union': 'BlockdevOptions',
+ 'base': 'BlockdevCommonOptions',
+ 'data': { 'raw': 'RawOptions',
+ 'qcow2': 'Qcow2Options' } }
+
+And it looks like this on the wire:
+
+ { "type": "qcow2",
+ "readonly": false,
+ "data" : { "backing-file": "/some/place/my-image",
+ "lazy-refcounts": true } }
+
+=== Commands ===
Commands are defined by using a list containing three members. The first
member is the command name, the second member is a dictionary containing
@@ -65,8 +115,6 @@ An example command is:
'data': { 'arg1': 'str', '*arg2': 'str' },
'returns': 'str' }
-Command names should be all lower case with words separated by a hyphen.
-
== Code generation ==
--
1.8.1.4
- [Qemu-devel] [PATCH 01/18] qapi-types.py: Split off generate_struct_fields(), (continued)
- [Qemu-devel] [PATCH 01/18] qapi-types.py: Split off generate_struct_fields(), Kevin Wolf, 2013/07/23
- [Qemu-devel] [PATCH 03/18] qapi-visit.py: Split off generate_visit_struct_fields(), Kevin Wolf, 2013/07/23
- [Qemu-devel] [PATCH 04/18] qapi-visit.py: Implement 'base' for unions, Kevin Wolf, 2013/07/23
- [Qemu-devel] [PATCH 02/18] qapi-types.py: Implement 'base' for unions, Kevin Wolf, 2013/07/23
- [Qemu-devel] [PATCH 06/18] qapi: Add visitor for implicit structs, Kevin Wolf, 2013/07/23
- [Qemu-devel] [PATCH 05/18] docs: Document QAPI union types,
Kevin Wolf <=
- [Qemu-devel] [PATCH 07/18] qapi: Flat unions with arbitrary discriminator, Kevin Wolf, 2013/07/23
- [Qemu-devel] [PATCH v2 07/17] qapi: Flat unions with arbitrary discriminator, Kevin Wolf, 2013/07/26
- [Qemu-devel] [PATCH 09/18] qapi.py: Maintain a list of union types, Kevin Wolf, 2013/07/23
- [Qemu-devel] [PATCH 08/18] qapi: Add consume argument to qmp_input_get_object(), Kevin Wolf, 2013/07/23