From nobody Fri Dec 19 06:57:15 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1549483079425774.2476794383356; Wed, 6 Feb 2019 11:57:59 -0800 (PST) Received: from localhost ([127.0.0.1]:57797 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1grTKU-0001Cd-Gp for importer@patchew.org; Wed, 06 Feb 2019 14:57:54 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38210) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1grTIg-0008SX-Fb for qemu-devel@nongnu.org; Wed, 06 Feb 2019 14:56:03 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1grTIf-0007up-Im for qemu-devel@nongnu.org; Wed, 06 Feb 2019 14:56:02 -0500 Received: from mx1.redhat.com ([209.132.183.28]:44040) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1grTId-0007sX-AR; Wed, 06 Feb 2019 14:55:59 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 8200558577; Wed, 6 Feb 2019 19:55:58 +0000 (UTC) Received: from localhost (unknown [10.40.205.248]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 11D7D87DB; Wed, 6 Feb 2019 19:55:57 +0000 (UTC) From: Max Reitz To: qemu-block@nongnu.org Date: Wed, 6 Feb 2019 20:55:45 +0100 Message-Id: <20190206195551.28893-3-mreitz@redhat.com> In-Reply-To: <20190206195551.28893-1-mreitz@redhat.com> References: <20190206195551.28893-1-mreitz@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.39]); Wed, 06 Feb 2019 19:55:58 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v3 2/8] 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, Michael Roth , Markus Armbruster , Max Reitz Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" Reviewed-by: Eric Blake Signed-off-by: Max Reitz --- 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 87183d3a09..32c576f30b 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 th= e 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. =20 The following example enhances the above simple union example by adding an optional common member 'read-only', renaming the @@ -504,6 +504,23 @@ 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. =20 +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, --=20 2.20.1