From patchwork Sun Apr 5 04:08:00 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Blake X-Patchwork-Id: 458217 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org 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 5B2341401AF for ; Sun, 5 Apr 2015 14:25:06 +1000 (AEST) Received: from localhost ([::1]:35125 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Yec7M-00031Z-A3 for incoming@patchwork.ozlabs.org; Sun, 05 Apr 2015 00:25:04 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42984) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YebrM-0000RV-T1 for qemu-devel@nongnu.org; Sun, 05 Apr 2015 00:08:36 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YebrL-0002uC-8Q for qemu-devel@nongnu.org; Sun, 05 Apr 2015 00:08:32 -0400 Received: from mx1.redhat.com ([209.132.183.28]:36454) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YebrL-0002tu-0y for qemu-devel@nongnu.org; Sun, 05 Apr 2015 00:08:31 -0400 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id t3548UjL025304 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Sun, 5 Apr 2015 00:08:30 -0400 Received: from red.redhat.com (ovpn-113-46.phx2.redhat.com [10.3.113.46]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id t35489wP008523; Sun, 5 Apr 2015 00:08:29 -0400 From: Eric Blake To: qemu-devel@nongnu.org Date: Sat, 4 Apr 2015 22:08:00 -0600 Message-Id: <1428206887-7921-30-git-send-email-eblake@redhat.com> In-Reply-To: <1428206887-7921-1-git-send-email-eblake@redhat.com> References: <1428206887-7921-1-git-send-email-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.24 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Cc: kwolf@redhat.com, berto@igalia.co, armbru@redhat.com Subject: [Qemu-devel] [PATCH v6 29/36] qapi: Document 'struct' metatype 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Referring to "type" as both a meta-type (built-in, enum, union, alternte, or struct) and a specific type (the name that the schema uses for declaring structs) is confusing. Now that the generator accepts 'struct' as a synonym for 'type', update all documentation to use saner wording. Signed-off-by: Eric Blake Reviewed-by: Markus Armbruster --- v6: new patch --- docs/qapi-code-gen.txt | 56 +++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 8a76cc1..6206032 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -71,7 +71,7 @@ x.y.z)' comment. For example: # # Since: 0.14.0 ## - { 'type': 'BlockStats', + { 'struct': 'BlockStats', 'data': {'*device': 'str', 'stats': 'BlockDeviceStats', '*parent': 'BlockStats', '*backing': 'BlockStats'} } @@ -85,7 +85,7 @@ types, and allows for indefinite nesting of QMP that satisfies the schema. A type name should not be defined more than once. There are seven top-level expressions recognized by the parser: -'include', 'command', 'type', 'enum', 'union', 'alternate', and +'include', 'command', 'struct', 'enum', 'union', 'alternate', and 'event'. There are several groups of types: simple types (a number of built-in types, such as 'int' and 'str'; as well as enumerations), complex types (structs and two flavors of unions), and alternate types @@ -127,9 +127,9 @@ In the rest of this document, usage lines are given for each expression type, with literal strings written in lower case and placeholders written in capitals. If a literal string includes a prefix of '*', that key/value pair can be omitted from the expression. -For example, a usage statement that includes '*base':COMPLEX-TYPE-NAME +For example, a usage statement that includes '*base':STRUCT-NAME means that an expression has an optional key 'base', which if present -must have a value that forms a complex type name. +must have a value that forms a struct name. === Built-in Types === @@ -167,17 +167,17 @@ an outer file. The parser may be made stricter in the future to prevent incomplete include files. -=== Complex types === +=== Struct types === -Usage: { 'type': STRING, 'data': DICT, '*base': COMPLEX-TYPE-NAME } +Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME } -A complex type is a dictionary containing a single 'data' key whose +A struct is a dictionary containing a single 'data' key whose value is a dictionary. This corresponds to a struct in C or an Object in JSON. Each value of the 'data' dictionary must be the name of a type, or a one-element array containing a type name. An example of a -complex type is: +struct is: - { 'type': 'MyType', + { 'struct': 'MyType', 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } The use of '*' as a prefix to the name means the member is optional in @@ -210,13 +210,13 @@ A structure that is used in both input and output of various commands must consider the backwards compatibility constraints of both directions of use. -A complex type definition can specify another complex type as its base. +A struct definition can specify another struct as its base. In this case, the fields of the base type are included as top-level fields -of the new complex type's dictionary in the QMP wire format. An example +of the new struct's dictionary in the QMP wire format. An example definition is: - { 'type': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } - { 'type': 'BlockdevOptionsGenericCOWFormat', + { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } + { 'struct': 'BlockdevOptionsGenericCOWFormat', 'base': 'BlockdevOptionsGenericFormat', 'data': { '*backing': 'str' } } @@ -251,7 +251,7 @@ converting between strings and enum values. Since the wire format always passes by name, it is acceptable to reorder or add new enumeration members in any location without breaking QMP clients; however, removing enum values would break compatibility. For any -complex type that has a field that will only contain a finite set of +struct that has a field that will only contain a finite set of string values, using an enum type for that field is better than open-coding the field to be type 'str'. @@ -259,7 +259,7 @@ open-coding the field to be type 'str'. === Union types === Usage: { 'union': STRING, 'data': DICT } -or: { 'union': STRING, 'data': DICT, 'base': COMPLEX-TYPE-NAME, +or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME, 'discriminator': ENUM-MEMBER-OF-BASE } Union types are used to let the user choose between several different @@ -271,8 +271,8 @@ paragraphs. A simple union type defines a mapping from automatic discriminator values to data types like in this example: - { 'type': 'FileOptions', 'data': { 'filename': 'str' } } - { 'type': 'Qcow2Options', + { 'struct': 'FileOptions', 'data': { 'filename': 'str' } } + { 'struct': 'Qcow2Options', 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } } { 'union': 'BlockdevOptions', @@ -295,13 +295,13 @@ the union can be named 'max', as this would collide with the implicit enum. The value for each branch can be of any type. -A flat union definition specifies a complex type as its base, and +A flat union definition specifies a struct as its base, and avoids nesting on the wire. All branches of the union must be complex types, and the top-level fields of the union dictionary on the wire will be combination of fields from both the base type and the appropriate branch type (when merging two dictionaries, there must be no keys in common). The 'discriminator' field must be the name of an -enum-typed member of the base type. +enum-typed member of the base struct. The following example enhances the above simple union example by adding a common field 'readonly', renaming the discriminator to @@ -309,7 +309,7 @@ something more applicable, and reducing the number of {} required on the wire: { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] } - { 'type': 'BlockdevCommonOptions', + { 'struct': 'BlockdevCommonOptions', 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } } { 'union': 'BlockdevOptions', 'base': 'BlockdevCommonOptions', @@ -341,9 +341,9 @@ union has a complex type with a single member named 'data'. That is, is identical on the wire to: { 'enum': 'Enum', 'data': ['one', 'two'] } - { 'type': 'Base', 'data': { 'type': 'Enum' } } - { 'type': 'Branch1', 'data': { 'data': 'str' } } - { 'type': 'Branch2', 'data': { 'data': 'int' } } + { 'struct': 'Base', 'data': { 'type': 'Enum' } } + { 'struct': 'Branch1', 'data': { 'data': 'str' } } + { 'struct': 'Branch2', 'data': { 'data': 'int' } } { 'union': 'Flat': 'base': 'Base', 'discriminator': 'type', 'data': { 'one': 'Branch1', 'two': 'Branch2' } } @@ -401,7 +401,7 @@ part of a QMP command. The 'data' member is optional and defaults to {} (an empty dictionary). If present, it must be the string name of a complex type, a one-element array containing the name of a complex type, or a dictionary that declares an anonymous type with the same -semantics as a 'type' expression, with one exception noted below when +semantics as a 'struct' expression, with one exception noted below when 'gen' is used. The 'returns' member describes what will appear in the "return" field @@ -410,7 +410,7 @@ optional from the command declaration; if absent, the "return" field will be an empty dictionary. If 'returns' is present, it must be the string name of a complex or built-in type, a one-element array containing the name of a complex or built-in type, or a dictionary -that declares an anonymous type with the same semantics as a 'type' +that declares an anonymous type with the same semantics as a 'struct' expression, with one exception noted below when 'gen' is used. Although it is permitted to have the 'returns' member name a built-in type or an array of built-in types, any command that does this cannot @@ -429,7 +429,7 @@ Some example commands: { 'command': 'my-first-command', 'data': { 'arg1': 'str', '*arg2': 'str' } } - { 'type': 'MyType', 'data': { '*value': 'str' } } + { 'struct': 'MyType', 'data': { '*value': 'str' } } { 'command': 'my-second-command', 'returns': [ 'MyType' ] } @@ -473,7 +473,7 @@ Events are defined with the keyword 'event'. It is not allowed to name an event 'MAX', since the generator also produces a C enumeration of all event names with a generated _MAX value at the end. When 'data' is also specified, additional info will be included in the -event, with similar semantics to a 'type' expression. Finally there +event, with similar semantics to a 'struct' expression. Finally there will be C API generated in qapi-event.h; when called by QEMU code, a message with timestamp will be emitted on the wire. @@ -504,7 +504,7 @@ case we want to accept/return a list of this type with a command), and a command which takes that type as a parameter and returns the same type: $ cat example-schema.json - { 'type': 'UserDefOne', + { 'struct': 'UserDefOne', 'data': { 'integer': 'int', 'string': 'str' } } { 'command': 'my-command',