Re: [Qemu-devel] [PATCH v6 29/36] qapi: Document 'struct' metatype

[Markus Armbruster]

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>