[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v6 29/36] qapi: Document 'struct' metatype
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH v6 29/36] qapi: Document 'struct' metatype |
Date: |
Tue, 28 Apr 2015 14:12:06 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) |
Eric Blake <address@hidden> writes:
> 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 <address@hidden>
>
> ---
>
> 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,
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 complex type with a single member named 'data'. That is,
Should we use 'struct' instead of 'complex type' here?
{ 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
> 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',
Reviewed-by: Markus Armbruster <address@hidden>
- [Qemu-devel] [PATCH v6 27/36] qapi: More rigorous checking for type safety bypass, (continued)
- [Qemu-devel] [PATCH v6 27/36] qapi: More rigorous checking for type safety bypass, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 25/36] qapi: Require valid names, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 24/36] qapi: More rigourous checking of types, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 23/36] qapi: Add some type check tests, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 28/36] qapi: Prefer 'struct' over 'type' in generator, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 29/36] qapi: Document 'struct' metatype, Eric Blake, 2015/04/05
- Re: [Qemu-devel] [PATCH v6 29/36] qapi: Document 'struct' metatype,
Markus Armbruster <=
- [Qemu-devel] [PATCH v6 31/36] qapi: Merge UserDefTwo and UserDefNested in tests, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 34/36] qapi: Drop inline nested structs in query-pci, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 33/36] qapi: Drop inline nested struct in query-version, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 35/36] qapi: Drop support for inline nested types, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 36/36] qapi: Tweak doc references to QMP when QGA is also meant, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 32/36] qapi: Drop tests for inline nested structs, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 30/36] qapi: Use 'struct' instead of 'type' in schema, Eric Blake, 2015/04/05