Re: [Qemu-devel] [PATCH 0/1] Get the list of arguments from a QMP command

[Alberto Garcia <berto@igalia.com>]

On Sat, Mar 14, 2015 at 05:12:33PM +0100, Markus Armbruster wrote:

  [QMP introspection]
> Detail.  I want us to figure out what information we want to provide
> first, how to encode it second, and how to fit it into the existing
> introspection interfaces third.

Ok, I managed to find some time to take look at this.

Here's a rough proposal of the kind of information we can provide
and how to encode it. The type names I'm using are probably not very
well thought-out, but my intention at this point is to discuss the
structure rather than the names.

So let's start with the basics:

  { 'type': 'SimpleTypeInfo',
    'data': {
        'name': 'str',
        'array': 'bool'
    }
  }

This would be what describes a single, named data type (as opposed
to a dictionary). The name would refer to any of the build-in types,
complex types, enums or unions. Alternatively instead of an 'str' it
could also be an enum, which could be auto-generated and would contain
all possible type names. I don't know if this last option is feasible,
I had the impression that it's not for commands with 'gen' == 'no',
but correct me if I'm wrong.

Then I think that all instances where a simple type can appear also
allow arrays, so an additional boolean field can be used for that,
e.g.:

    'returns': 'str'           // name: str, array: no
    'returns': ['EventInfo']   // name: EventInfo, array: yes

Next:

  { 'type': 'DataFieldInfo',
    'data': {
        'name': 'str',
        'optional': 'bool',
        'type': 'SimpleTypeInfo'
    }
  }

That's for command arguments and fields in complex data types and
events. I think this one does not need much explanation. I admit that
the name that I chose is not very good :)

  { 'type': 'ComplexTypeInfo',
    'data': {
        'name': 'str',
        'fields': [ 'DataFieldInfo' ]
    }
  }

  { 'type': 'EnumInfo',
    'data': {
        'name': 'str',
        'values': [ 'str' ]
    }
  }

  { 'type': 'EventInfo',
    'data': {
        'name': 'str',
        'fields': [ 'DataFieldInfo' ]
    }
  }

This is for complex types, unions and events. I also think they don't
need much explanation. ComplexTypeInfo and EventInfo could be merged
into the same type, although I guess it's a good idea to keep them
separated in case one of them needs to be extended in the future.

  { 'type': 'UnionFieldInfo',
    'data': {
        'name': 'str',
        'type': 'str',
    }
  }

  { 'type': 'UnionInfo',
    'data': {
        'name': 'str',
        '*base': 'str'
        '*discriminator': 'str',
        'fields': [ 'UnionFieldInfo' ]
    }
  }

Unions. The type for 'base' could be (instead of 'str') an
autogenerated enum with all complex data types. 'discriminator' would
be 'type' for the default case. If the union is anonymous then this
field would be absent.

  { 'type': 'CommandInfo',
    'data': {
        'name': 'str',
        'args': [ 'DataFieldInfo' ],
        '*returns': 'SimpleTypeInfo',
        'gen': 'bool',
        'success-response': 'bool'
    }
  }

Commands. As far as I can see all of them return a single type (or an
array thereof), but this could be replaced if we want something else.

I think that's all.

Then as you said we could hide complex types and flatten them all when
we expose them. It would probably makes things easier in terms of
allowing changes in the API, but sounds like it would make the life of
API users more difficult? I don't know.

Last, about the query commands, I don't think they're so important
at the moment. Whether we want to have 'query-schema' or a set of
'query-*' for different things, or a combination of both, is something
that does not really have much impact on this discussion. Once we know
what we want to expose, the commands will come naturally I think.

Berto