From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:35758) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YavR4-0005Cy-LB for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YavQx-0000Vh-Ed for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:10 -0400 Received: from resqmta-po-06v.sys.comcast.net ([96.114.154.165]:59959) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YavQx-0000Uw-8A for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:03 -0400 From: Eric Blake Date: Wed, 25 Mar 2015 18:13:53 -0600 Message-Id: <1427328837-4406-2-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 1/5] qapi: Minor tweaks to qapi-code-gen.txt List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: armbru@redhat.com Several minor things pointed out by Markus during review of my sweeping changes. Signed-off-by: Eric Blake --- docs/qapi-code-gen.txt | 44 ++++++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 8792b94..1f7d0ca 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -82,13 +82,14 @@ 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 'event'. There are several built-in types, such as 'int' and 'str'; -additionally, the top-level expressions can define complex types, -enumeration types, two flavors of union types, and an alternate type. -The 'command' expression can refer to existing types by name, or list -an anonymous type as a dictionary. Listing a type name inside an -array refers to a single-dimension array of that type; multi-dimension -arrays are not directly supported (although an array of a complex -struct that contains an array member is possible). +additionally, the top-level expressions can define complex types +(structs and two flavors of unions), as well as enumeration and +alternate types. The 'command' and 'event' expressions can refer to +existing types by name, or list an anonymous type as a dictionary. +Listing a type name inside an array refers to a single-dimension array +of that type; multi-dimension arrays are not directly supported +(although an array of a complex struct that contains an array member +is possible). Types, commands, and events share a common namespace. Therefore, generally speaking, type definitions should always use CamelCase for @@ -117,6 +118,12 @@ underscore. It is okay to reuse names that match C keywords; the generator will rename a field named "default" in the QAPI to "q_default" in the generated C code. +In the rest of this document, usage lines are given for each +expression type, written in the style of the QAPI syntax. For +example, a usage statement that includes '*base':'complex-type-name' +means that an expression has an optional key 'base', which if present +must have a value that forms a 'complex-type-name'. + === Built-in Types === @@ -138,7 +145,7 @@ Usage: { 'include': 'str' } The QAPI schema definitions can be modularized using the 'include' directive: - { 'include': 'path/to/file.json'} + { 'include': 'path/to/file.json' } The directive is evaluated recursively, and include paths are relative to the file using the directive. Multiple includes of the same file are @@ -159,8 +166,8 @@ Usage: { 'type': 'str', 'data': 'dict', '*base': 'complex-type-name' } A complex type 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 -complex, enum, union, alternate, or built-in type, or a one-element -array containing a type name. An example of a complex type is: +type, or a one-element array containing a type name. An example of a +complex type is: { 'type': 'MyType', 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } @@ -280,8 +287,9 @@ implicit enum. A flat union definition specifies a complex type as its base, and avoids nesting on the wire. In this case, the fields of the complex type are included as top-level fields of the union dictionary in the -QMP wire format, and the 'discriminator' field must be the name of an -enum-typed member of the base type. An example definition is: +QMP wire format common to all branches of the union, and the +'discriminator' field must be the name of an enum-typed member of the +base type. An example definition is: { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } } { 'union': 'BlockdevOptions', @@ -350,7 +358,7 @@ This example allows using both of the following example objects: === Commands === Usage: { 'command': 'str', '*data': 'dict-or-complex-type-name', - '*returns': 'type', + '*returns': 'dict-or-type-name', '*gen': false, '*success-response': false } Commands are defined by using a dictionary containing several members, @@ -358,13 +366,13 @@ where three members are most common. The 'command' member is a mandatory string, and determines the "execute" value passed in a QMP command exchange. -The 'data' member is optional; if absent, the command accepts an -optional empty dictionary. If present, it must be the string name of -a complex type, a one-element array containing the name of a complex +The 'data' argument maps to the "arguments" dictionary passed in as +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 -'gen' is used. The 'data' argument maps to the "arguments" dictionary -passed in as part of a QMP command. +'gen' is used. The 'returns' member describes what will appear in the "return" field of a QMP reply on successful completion of a command. The member is -- 2.1.0