From patchwork Fri Mar 18 10:04:27 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 8617881 Return-Path: X-Original-To: patchwork-qemu-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 37E58C0553 for ; Fri, 18 Mar 2016 10:12:38 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 581FC202E9 for ; Fri, 18 Mar 2016 10:12:37 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 3F8FA200D6 for ; Fri, 18 Mar 2016 10:12:36 +0000 (UTC) Received: from localhost ([::1]:42673 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1agrOU-0005VI-Ho for patchwork-qemu-devel@patchwork.kernel.org; Fri, 18 Mar 2016 06:12:34 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:53056) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1agrGs-0008Es-8B for qemu-devel@nongnu.org; Fri, 18 Mar 2016 06:04:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1agrGl-0001US-LX for qemu-devel@nongnu.org; Fri, 18 Mar 2016 06:04:42 -0400 Received: from mx1.redhat.com ([209.132.183.28]:40215) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1agrGl-0001U1-CF for qemu-devel@nongnu.org; Fri, 18 Mar 2016 06:04:35 -0400 Received: from int-mx14.intmail.prod.int.phx2.redhat.com (int-mx14.intmail.prod.int.phx2.redhat.com [10.5.11.27]) by mx1.redhat.com (Postfix) with ESMTPS id 0D946461D2 for ; Fri, 18 Mar 2016 10:04:35 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-116-34.ams2.redhat.com [10.36.116.34]) by int-mx14.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id u2IA4WSq007156 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Fri, 18 Mar 2016 06:04:33 -0400 Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 167A23004FAF; Fri, 18 Mar 2016 11:04:30 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Date: Fri, 18 Mar 2016 11:04:27 +0100 Message-Id: <1458295469-22215-14-git-send-email-armbru@redhat.com> In-Reply-To: <1458295469-22215-1-git-send-email-armbru@redhat.com> References: <1458295469-22215-1-git-send-email-armbru@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.27 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PULL 13/15] qapi: Make BlockdevOptions doc example closer to reality 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+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Eric Blake 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 Message-Id: <1458254921-17042-14-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster --- 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" } ] }