From patchwork Wed May 9 16:55:19 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Max Reitz X-Patchwork-Id: 911046 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=nongnu.org (client-ip=2001:4830:134:3::11; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=redhat.com Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 40h35B5hbrz9s4t for ; Thu, 10 May 2018 03:19:58 +1000 (AEST) Received: from localhost ([::1]:57872 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fGSku-00068M-EZ for incoming@patchwork.ozlabs.org; Wed, 09 May 2018 13:19:56 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:59632) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fGSNR-0003RP-1x for qemu-devel@nongnu.org; Wed, 09 May 2018 12:55:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fGSNQ-0006Y2-76 for qemu-devel@nongnu.org; Wed, 09 May 2018 12:55:41 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:39966 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fGSNO-0006UT-0P; Wed, 09 May 2018 12:55:38 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id D1B018E7B9; Wed, 9 May 2018 16:55:36 +0000 (UTC) Received: from localhost (unknown [10.40.205.23]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7D843D74CB; Wed, 9 May 2018 16:55:36 +0000 (UTC) From: Max Reitz To: qemu-block@nongnu.org Date: Wed, 9 May 2018 18:55:19 +0200 Message-Id: <20180509165530.29561-3-mreitz@redhat.com> In-Reply-To: <20180509165530.29561-1-mreitz@redhat.com> References: <20180509165530.29561-1-mreitz@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.11.54.5 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.2]); Wed, 09 May 2018 16:55:36 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.2]); Wed, 09 May 2018 16:55:36 +0000 (UTC) for IP:'10.11.54.5' DOMAIN:'int-mx05.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'mreitz@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PATCH 02/13] docs/qapi: Document optional discriminators X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , qemu-devel@nongnu.org, Markus Armbruster , Michael Roth , Max Reitz Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Signed-off-by: Max Reitz Reviewed-by: Eric Blake --- docs/devel/qapi-code-gen.txt | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index b9b6eabd08..35b9f0d99d 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -472,8 +472,8 @@ 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 a non-optional enum-typed -member of the base struct. +'discriminator' member must be the name of an enum-typed member of the +base struct. The following example enhances the above simple union example by adding an optional common member 'read-only', renaming the @@ -502,6 +502,23 @@ the enum). In the resulting generated C data types, a flat union is represented as a struct with the base members included directly, and then a union of structures for each branch of the struct. +If the discriminator points to an optional member of the base struct, +its default value must be specified as a 'default-variant'. In the +following example, the above BlockDriver struct is changed so it +defaults to the 'file' driver if that field is omitted on the wire: + + { 'union': 'BlockdevOptions', + 'base': { '*driver': 'BlockdevDriver', '*read-only': 'bool' }, + 'discriminator': 'driver', + 'default-variant': 'file', + 'data': { 'file': 'BlockdevOptionsFile', + 'qcow2': 'BlockdevOptionsQcow2' } } + +Now the 'file' JSON object can be abbreviated to: + + { "read-only": "true", + "filename": "/some/place/my-image" } + A simple union can always be re-written as a flat union where the base class has a single member named 'type', and where each branch of the union has a struct with a single member named 'data'. That is,