From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:35731) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YavR0-00057t-Ra for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:07 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YavQx-0000VT-DV for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:06 -0400 Received: from resqmta-po-05v.sys.comcast.net ([96.114.154.164]:52111) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YavQx-0000V4-85 for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:03 -0400 From: Eric Blake Date: Wed, 25 Mar 2015 18:13:54 -0600 Message-Id: <1427328837-4406-3-git-send-email-eblake@redhat.com> In-Reply-To: <1427328837-4406-1-git-send-email-eblake@redhat.com> References: <1427328837-4406-1-git-send-email-eblake@redhat.com> Subject: [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: armbru@redhat.com QObject is an internal coding concept and requires the reader to reverse engineer the mapping; it is nicer to be explicit and call out specific JSON types. Signed-off-by: Eric Blake --- docs/qapi-code-gen.txt | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 1f7d0ca..7fb0db7 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -331,17 +331,21 @@ Resulting in this JSON object: Usage: { 'alternate: 'str', 'data': 'dict' } -An alternate type is one that allows a choice between two or more -QObject data types (string, integer, number, or dictionary, but not -array) on the wire. The definition is similar to a simple union type, -where each branch of the dictionary names a type, and where an -implicit C enum NameKind is created for the alternate Name. But +An alternate type is one that allows a choice between two or more JSON +data types on the wire. The definition is similar to a simple union +type, where each branch of the dictionary names a QAPI type, and where +an implicit C enum NameKind is created for the alternate Name. But unlike a union, the discriminator string is never passed on the wire -for QMP, instead appearing only in the generated C code. The type on -the wire serves an implicit discriminator, which in turn means that an -alternate can express a choice between a string and a single complex -type (passed as a dictionary), but cannot distinguish between two -different complex types. For example: +for QMP, instead appearing only in the generated C code. Rather, the +first byte of the value on the wire serves an implicit discriminator: +if the branch is typed as the 'bool' built-in, it accepts true and +false; if it is typed as any of the various numeric built-ins, it +accepts a JSON number; if it is typed as a 'str' built-in or named +enum types it accepts a JSON string, and if it is typed as a named +struct or union type it accepts a JSON object. Thus, an alternate can +express a choice between a string and a single complex type (passed as +a dictionary), but cannot distinguish between two different complex +types or two different numeric built-in types. For example: { 'alternate': 'BlockRef', 'data': { 'definition': 'BlockdevOptions', -- 2.1.0