[{"id":1821438,"web_url":"http://patchwork.ozlabs.org/comment/1821438/","msgid":"<87lgi6gbak.fsf@dusky.pond.sub.org>","list_archive_url":null,"date":"2017-12-13T10:41:23","subject":"Re: [Qemu-devel] [PATCH v3 31/50] docs: document schema\n\tconfiguration","submitter":{"id":2645,"url":"http://patchwork.ozlabs.org/api/people/2645/","name":"Markus Armbruster","email":"armbru@redhat.com"},"content":"Cc: Eric for an additional pair of eyeballs.\n\nMarc-André Lureau writes:\n\n> Signed-off-by: Marc-André Lureau \n> ---\n> docs/devel/qapi-code-gen.txt | 37 +++++++++++++++++++++++++++++++++++++\n> 1 file changed, 37 insertions(+)\n>\n> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt\n> index 0a90f2278a..24fc6f74ee 100644\n> --- a/docs/devel/qapi-code-gen.txt\n> +++ b/docs/devel/qapi-code-gen.txt\n> @@ -682,6 +682,43 @@ Example: Red Hat, Inc. controls redhat.com, and may therefore add a\n> downstream command __com.redhat_drive-mirror.\n> \n> \n> +=== Configuring the schema ===\n> +\n> +'struct', 'enum', 'union', 'alternate', 'command' and 'event'\n> +top-level QAPI expressions can take a 'if' keyword like:\n\nan 'if' key\n\n> +\n> +{ 'struct': 'IfStruct', 'data': { 'foo': 'int' },\n> + 'if': 'defined(IF_STRUCT) && defined(FOO)' }\n\nPerhaps we should add something like\n\n Code generated for such conditional definitions will be guarded with\n #if IFCOND, where IFCOND is the value of the 'if' key.\n\n> +\n> +Members can be exploded as dictionnary with 'type' & 'if' keys:\n\ndictionary\n\nI get what you mean by \"can be exploded\", but can we phrase this more\nclearly?\n\nIn section \"Struct types\", we have\n\n A struct is a dictionary containing a single 'data' key whose value is\n a dictionary; the dictionary may be empty. This corresponds to a\n struct in C or an Object in JSON. Each value of the 'data' dictionary\n must be the name of a type, or a one-element array containing a type\n name.\n\nThe part \"must be the name of a type, or a one-element array containing\na type\" name is now wrong.\n\nLikewise, in section \"Enumeration types\"\n\n An enumeration type is a dictionary containing a single 'data' key\n whose value is a list of strings.\n\n> +\n> +{ 'struct': 'IfStruct', 'data':\n> + { 'foo': 'int',\n> + 'bar': { 'type': 'int', 'if': 'defined(IF_STRUCT_BAR)'} } }\n\nPerhaps add something like\n\n Code generated for such conditional members will be guarded with #if\n IFCOND, where IFCOND is the value of the 'if' key.\n\n> +\n> +Enum values can be exploded as dictionnary with 'name' & 'if' keys:\n\ndictionnary and exploded again.\n\n> +\n> +{ 'enum': 'IfEnum', 'data':\n> + [ 'foo',\n> + { 'name' : 'bar', 'if': 'defined(IF_ENUM_BAR)' } ] }\n> +\n> +The C code generators will wrap the corresponding lines with #if / #endif\n> +pre-processor conditions for a given 'if' value.\n> +\n> +Example for enum values:\n> +\n> +enum IfEnum {\n> + IF_ENUM_FOO,\n> +#if defined(IF_ENUM_BAR)\n> + IF_ENUM_BAR,\n> +#endif /* defined(IF_ENUM_BAR) */\n> + IF_ENUM__MAX\n> +}\n\nHmm. If enumeration documentation profits from an example, it stands to\nreason that the previous two would, too.\n\nShould we (additionally?) add examples of 'if' in section \"Code\ngeneration\"?\n\n> +\n> +Please note that you are responsbile to ensure that the C code will\n> +compile with an arbitrary combination of conditions, since the\n> +generators are unable to check it at this point.\n> +\n> == Client JSON Protocol introspection ==\n> \n> Clients of a Client JSON Protocol commonly need to figure out what\n\nDo we need to update section \"Client JSON Protocol introspection\"?","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=pass (mailfrom) smtp.mailfrom=nongnu.org\n\t(client-ip=2001:4830:134:3::11; helo=lists.gnu.org;\n\tenvelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n\treceiver=)","Received":["from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11])\n\t(using TLSv1 with cipher AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby ozlabs.org (Postfix) with ESMTPS id 3yxYDC1mzyz9s72\n\tfor ;\n\tWed, 13 Dec 2017 21:42:19 +1100 (AEDT)","from localhost ([::1]:34751 helo=lists.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.71) (envelope-from\n\t)\n\tid 1eP4UT-0007lc-8I\n\tfor incoming@patchwork.ozlabs.org; Wed, 13 Dec 2017 05:42:17 -0500","from eggs.gnu.org ([2001:4830:134:3::10]:38349)\n\tby lists.gnu.org with esmtp (Exim 4.71)\n\t(envelope-from ) id 1eP4Tk-0007hR-Re\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 05:41:37 -0500","from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)\n\t(envelope-from ) id 1eP4Tg-0004CS-TT\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 05:41:32 -0500","from mx1.redhat.com ([209.132.183.28]:34596)\n\tby eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)\n\t(Exim 4.71) (envelope-from ) id 1eP4Tg-0004BG-LP\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 05:41:28 -0500","from smtp.corp.redhat.com\n\t(int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12])\n\t(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby mx1.redhat.com (Postfix) with ESMTPS id BE936883AE\n\tfor ; Wed, 13 Dec 2017 10:41:27 +0000 (UTC)","from blackfin.pond.sub.org (ovpn-116-74.ams2.redhat.com\n\t[10.36.116.74])\n\tby smtp.corp.redhat.com (Postfix) with ESMTPS id 7F43670C5B;\n\tWed, 13 Dec 2017 10:41:25 +0000 (UTC)","by blackfin.pond.sub.org (Postfix, from userid 1000)\n\tid 0855E1138658; Wed, 13 Dec 2017 11:41:24 +0100 (CET)"],"From":"Markus Armbruster ","To":"=?utf-8?q?Marc-Andr=C3=A9?= Lureau ","References":"<20170911110623.24981-1-marcandre.lureau@redhat.com>\n\t<20170911110623.24981-32-marcandre.lureau@redhat.com>","Date":"Wed, 13 Dec 2017 11:41:23 +0100","In-Reply-To":"<20170911110623.24981-32-marcandre.lureau@redhat.com> (\n\t=?utf-8?b?Ik1hcmMtQW5kcsOp?= Lureau\"'s message of \"Mon,\n\t11 Sep 2017 \t13:06:04 +0200\")","Message-ID":"<87lgi6gbak.fsf@dusky.pond.sub.org>","User-Agent":"Gnus/5.13 (Gnus v5.13) Emacs/25.3 (gnu/linux)","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Transfer-Encoding":"quoted-printable","X-Scanned-By":"MIMEDefang 2.79 on 10.5.11.12","X-Greylist":"Sender IP whitelisted, not delayed by milter-greylist-4.5.16\n\t(mx1.redhat.com [10.5.110.26]);\n\tWed, 13 Dec 2017 10:41:27 +0000 (UTC)","X-detected-operating-system":"by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]\n\t[fuzzy]","X-Received-From":"209.132.183.28","Subject":"Re: [Qemu-devel] [PATCH v3 31/50] docs: document schema\n\tconfiguration","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.21","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Cc":"qemu-devel@nongnu.org","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"\"Qemu-devel\"\n\t"}},{"id":1821798,"web_url":"http://patchwork.ozlabs.org/comment/1821798/","msgid":"<315eff5b-0508-0dcb-8118-cf3eb5395ba4@redhat.com>","list_archive_url":null,"date":"2017-12-13T19:49:03","subject":"Re: [Qemu-devel] [PATCH v3 31/50] docs: document schema\n\tconfiguration","submitter":{"id":6591,"url":"http://patchwork.ozlabs.org/api/people/6591/","name":"Eric Blake","email":"eblake@redhat.com"},"content":"On 12/13/2017 04:41 AM, Markus Armbruster wrote:\n> Cc: Eric for an additional pair of eyeballs.\n> \n> Marc-André Lureau writes:\n> \n>> Signed-off-by: Marc-André Lureau \n>> ---\n>> +\n>> +Members can be exploded as dictionnary with 'type' & 'if' keys:\n> \n> dictionary\n> \n> I get what you mean by \"can be exploded\", but can we phrase this more\n> clearly?\n> \n> In section \"Struct types\", we have\n> \n> A struct is a dictionary containing a single 'data' key whose value is\n> a dictionary; the dictionary may be empty. This corresponds to a\n> struct in C or an Object in JSON. Each value of the 'data' dictionary\n> must be the name of a type, or a one-element array containing a type\n> name.\n> \n> The part \"must be the name of a type, or a one-element array containing\n> a type\" name is now wrong.\n\nMaybe:\n\nWhere a member can normally be defined with a single string value as its\ntype, it is also possible to supply a dictionary with both 'type' and\n'if' keys. The generated code will then guard the inclusion of that\nmember in the larger struct or command with #if IFCOND, where IFCOND is\nthe value of the 'if' key.\n\n>> +\n>> +{ 'struct': 'IfStruct', 'data':\n>> + { 'foo': 'int',\n>> + 'bar': { 'type': 'int', 'if': 'defined(IF_STRUCT_BAR)'} } }\n> \n> Perhaps add something like\n> \n> Code generated for such conditional members will be guarded with #if\n> IFCOND, where IFCOND is the value of the 'if' key.\n> \n\n> \n> Hmm. If enumeration documentation profits from an example, it stands to\n> reason that the previous two would, too.\n> \n> Should we (additionally?) add examples of 'if' in section \"Code\n> generation\"?\n\nIt makes the examples longer, but may be worthwhile.\n\n> \n>> +\n>> +Please note that you are responsbile to ensure that the C code will\n\ns/responsbile/responsible/\n\n>> +compile with an arbitrary combination of conditions, since the\n>> +generators are unable to check it at this point.\n>> +\n>> == Client JSON Protocol introspection ==\n>> \n>> Clients of a Client JSON Protocol commonly need to figure out what\n> \n> Do we need to update section \"Client JSON Protocol introspection\"?\n\nIt doesn't affect what the client can do with what it introspects, but\nmay indeed be worth mentioning that the presence of 'if' keys in the\nschema is reflected through to the introspection output.","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=pass (mailfrom) smtp.mailfrom=nongnu.org\n\t(client-ip=2001:4830:134:3::11; helo=lists.gnu.org;\n\tenvelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n\treceiver=)","Received":["from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11])\n\t(using TLSv1 with cipher AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby ozlabs.org (Postfix) with ESMTPS id 3yxnN801vXz9s81\n\tfor ;\n\tThu, 14 Dec 2017 06:50:00 +1100 (AEDT)","from localhost ([::1]:37293 helo=lists.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.71) (envelope-from\n\t)\n\tid 1ePD2T-0006ci-Sz\n\tfor incoming@patchwork.ozlabs.org; Wed, 13 Dec 2017 14:49:58 -0500","from eggs.gnu.org ([2001:4830:134:3::10]:55405)\n\tby lists.gnu.org with esmtp (Exim 4.71)\n\t(envelope-from ) id 1ePD1j-0006bR-HF\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 14:49:12 -0500","from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)\n\t(envelope-from ) id 1ePD1g-0007QZ-Cb\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 14:49:11 -0500","from mx1.redhat.com ([209.132.183.28]:43952)\n\tby eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)\n\t(Exim 4.71) (envelope-from ) id 1ePD1g-0007QC-2K\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 14:49:08 -0500","from smtp.corp.redhat.com\n\t(int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15])\n\t(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby mx1.redhat.com (Postfix) with ESMTPS id 3C5CF2D1EC7\n\tfor ; Wed, 13 Dec 2017 19:49:07 +0000 (UTC)","from [10.10.120.204] (ovpn-120-204.rdu2.redhat.com [10.10.120.204])\n\tby smtp.corp.redhat.com (Postfix) with ESMTP id BBA917BA39;\n\tWed, 13 Dec 2017 19:49:04 +0000 (UTC)"],"To":"Markus Armbruster , =?utf-8?q?Marc-Andr=C3=A9_Lurea?=\n\t=?utf-8?q?u?= ","References":"<20170911110623.24981-1-marcandre.lureau@redhat.com>\n\t<20170911110623.24981-32-marcandre.lureau@redhat.com>\n\t<87lgi6gbak.fsf@dusky.pond.sub.org>","From":"Eric Blake ","Openpgp":"url=http://people.redhat.com/eblake/eblake.gpg","Organization":"Red Hat, Inc.","Message-ID":"<315eff5b-0508-0dcb-8118-cf3eb5395ba4@redhat.com>","Date":"Wed, 13 Dec 2017 13:49:03 -0600","User-Agent":"Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101\n\tThunderbird/52.5.0","MIME-Version":"1.0","In-Reply-To":"<87lgi6gbak.fsf@dusky.pond.sub.org>","Content-Type":"multipart/signed; micalg=pgp-sha256;\n\tprotocol=\"application/pgp-signature\";\n\tboundary=\"Ssrsl67RSE4SC6ah4kxPKqhseeO9A3nww\"","X-Scanned-By":"MIMEDefang 2.79 on 10.5.11.15","X-Greylist":"Sender IP whitelisted, not delayed by milter-greylist-4.5.16\n\t(mx1.redhat.com [10.5.110.29]);\n\tWed, 13 Dec 2017 19:49:07 +0000 (UTC)","X-detected-operating-system":"by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]\n\t[fuzzy]","X-Received-From":"209.132.183.28","X-Content-Filtered-By":"Mailman/MimeDel 2.1.21","Subject":"Re: [Qemu-devel] [PATCH v3 31/50] docs: document schema\n\tconfiguration","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.21","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Cc":"qemu-devel@nongnu.org","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"\"Qemu-devel\"\n\t"}}]