From patchwork Tue Jul 23 13:03:13 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kevin Wolf X-Patchwork-Id: 261096 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 592F62C00BA for ; Tue, 23 Jul 2013 23:52:18 +1000 (EST) Received: from localhost ([::1]:49154 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V1cJM-0005IX-Br for incoming@patchwork.ozlabs.org; Tue, 23 Jul 2013 09:07:28 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54329) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V1cFp-00006z-Fc for qemu-devel@nongnu.org; Tue, 23 Jul 2013 09:03:51 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V1cFj-0007Qb-Td for qemu-devel@nongnu.org; Tue, 23 Jul 2013 09:03:49 -0400 Received: from mx1.redhat.com ([209.132.183.28]:37969) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V1cFj-0007QP-K1 for qemu-devel@nongnu.org; Tue, 23 Jul 2013 09:03:43 -0400 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id r6ND3hZc011389 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 23 Jul 2013 09:03:43 -0400 Received: from dhcp-200-207.str.redhat.com (ovpn-116-56.ams2.redhat.com [10.36.116.56]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id r6ND3U6D008625; Tue, 23 Jul 2013 09:03:41 -0400 From: Kevin Wolf To: qemu-devel@nongnu.org Date: Tue, 23 Jul 2013 15:03:13 +0200 Message-Id: <1374584606-5615-6-git-send-email-kwolf@redhat.com> In-Reply-To: <1374584606-5615-1-git-send-email-kwolf@redhat.com> References: <1374584606-5615-1-git-send-email-kwolf@redhat.com> X-Scanned-By: MIMEDefang 2.67 on 10.5.11.12 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Cc: kwolf@redhat.com, armbru@redhat.com, stefanha@redhat.com, lcapitulino@redhat.com Subject: [Qemu-devel] [PATCH 05/18] docs: Document QAPI union types X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Signed-off-by: Kevin Wolf Reviewed-by: Eric Blake --- 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 ==