From 9ff6403c20232b826766d34cbb66caea8c650bf1 Mon Sep 17 00:00:00 2001

From: Kevin Wolf <kwolf@redhat.com>

Date: Mon, 9 Sep 2013 14:28:10 +0200

Subject: [PATCH 19/38] docs: Document QAPI union types

RH-Author: Kevin Wolf <kwolf@redhat.com>

Message-id: <1378736903-18489-20-git-send-email-kwolf@redhat.com>

Patchwork-id: 54206

O-Subject: [RHEL-7.0 qemu-kvm PATCH 19/32] docs: Document QAPI union types

Bugzilla: 1005818

RH-Acked-by: Fam Zheng <famz@redhat.com>

RH-Acked-by: Max Reitz <mreitz@redhat.com>

RH-Acked-by: Miroslav Rezanina <mrezanin@redhat.com>

Bugzilla: 1005818

Signed-off-by: Kevin Wolf <kwolf@redhat.com>

Reviewed-by: Eric Blake <eblake@redhat.com>

(cherry picked from commit 51631493e4876081ae27078b50bd95bd4418bf37)

Signed-off-by: Kevin Wolf <kwolf@redhat.com>

---

 docs/qapi-code-gen.txt | 62 ++++++++++++++++++++++++++++++++++++++++++++------

 1 file changed, 55 insertions(+), 7 deletions(-)

Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>

---

 docs/qapi-code-gen.txt |   62 ++++++++++++++++++++++++++++++++++++++++++-----

 1 files changed, 55 insertions(+), 7 deletions(-)

diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt

index cccb11e..f6f8d33 100644

--- a/docs/qapi-code-gen.txt

+++ b/docs/qapi-code-gen.txt

@@ -34,9 +34,15 @@ 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.

-A complex type is a dictionary containing a single key who's value is a

+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 whose value is a

 dictionary.  This corresponds to a struct in C or an Object in JSON.  An

 example of a complex type is:

@@ -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.

-An enumeration type is a dictionary containing a single key who's value is a

+=== Enumeration types ===

+

+An enumeration type is a dictionary containing a single key whose 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.7.1