From 9ff6403c20232b826766d34cbb66caea8c650bf1 Mon Sep 17 00:00:00 2001 From: Kevin Wolf Date: Mon, 9 Sep 2013 14:28:10 +0200 Subject: [PATCH 19/38] docs: Document QAPI union types RH-Author: Kevin Wolf 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 RH-Acked-by: Max Reitz RH-Acked-by: Miroslav Rezanina Bugzilla: 1005818 Signed-off-by: Kevin Wolf Reviewed-by: Eric Blake (cherry picked from commit 51631493e4876081ae27078b50bd95bd4418bf37) Signed-off-by: Kevin Wolf --- docs/qapi-code-gen.txt | 62 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 55 insertions(+), 7 deletions(-) Signed-off-by: Miroslav Rezanina --- 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