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

[Kevin Wolf]

Am 11.03.2015 um 20:22 hat Markus Armbruster geschrieben:
> Alberto Garcia <address@hidden> writes:
> 
> > On Wed, Mar 11, 2015 at 11:21:43AM +0100, Markus Armbruster wrote:
> >
> >> > I can actually try to implement full introspection support, but I
> >> > would like to know what API you would like. Something like this?
> >> >
> >> >    'query-commands'
> >> >    'query-enums'
> >> >    'query-events'
> >> >    'query-types'
> >> >    'query-unions'
> >> 
> >> You propose a separate query-FOO for each kind of thing in the
> >> schema: command, event, the various types.  Not fundamentally
> >> different to a single query-schema.  We can discuss which of the two
> >> approaches is easier to use.
> >
> > I don't think it makes much difference in terms of complexity
> > from the QEMU side. I proposed those because query-commands and
> > query-events already exist, so adding the missing ones seemed the most
> > straightforward solution to me.
> 
> They only tell you what commands and events exist, but nothing about
> their 'data' or 'returns'.

True, but luckily they were defined to return not just a list of
strings, but of CommandInfo dicts. So extending that seems to be the
natural option in order to get a coherent interface in the end.

> > But if query-schema is more convenient I don't have any problem with
> > that.
> 
> The real work is processing the full schema into the externally visible
> sub-schema.  Whether to split it into several parts for presentation is
> the least of my worries.
> 
> I'm fine with with building up introspection step by step.  But I want
> us to have a reasonable idea of the end result.  Without that,
> incremental development together with our ABI promise is prone to
> produce a tangled mess.  We already have enough of those :)

Okay. Let's try to define just enough to get a reasonable idea of the
end result.

Let's start with the commands that we will have, without looking at
the structure of their arguments and return values yet:

* query-commands, which returns a list of CommandInfos. This contains at
  least the name of each command. (Mandated by backwards compatibility
  requirements)

* query-events, which returns a list of EventInfos.  This contains at
  least the name of each event. (Mandated by backwards compatibility
  requirements)

* Something to query the full description of commands, including the
  type of their return value and name, type and optionality of their
  arguments.

  I propose combining this with query-commands by extending CommandInfo.

* Something to query QAPI types, including:

  - The fields of a complex type, including their name, type and
    optionality.

    I propose that this information be returned in a structure analogous
    to how arguments are described in query-commands, whatever that may
    be.

  - The possible values of an enum type

  - Union types are complex (sorry, my bad), we probably don't want to
    expose them the way they are in the schema. This needs more thought.

  The details of how each type is described, as well as the exact
  command to query it, aren't of importance for adding command argument
  querying and shouldn't affect it, so I'd leave that for later.

  What I do propose is that in order to maintain consistency with the
  already existing query-{commands,events}, we introduct a separate
  command for these. This may be a single 'query-types', but it could
  also be 'query-complex-types'/'query-enums'/'query-unions'.

  Unless you think it makes a difference for defining what we need now,
  I think we can leave this question open.

* Possibly something to query the fields of events, if we ever need
  that (I doubt it). If we do, in consistency with the above I propose
  extending EventInfo and exposing the information the same way as for
  command arguments and complex type fields.

Do you agree so far?

Anything else you want to get answered before you think you have a
reasonable idea of the end result on the high level?

If not, the next step would be to define the exact structure of each
command. I for one don't think that there is a need to define it for all
of the commands now, but you may think otherwise?

If so, putting together the schema for the query commands (without
implementing them yet) shouldn't be that hard and I'd be happy to do
that. Perhaps with the exception of union types, but if you think it's
important, I can propose something for them, too.

> I feel a necessary early step is to actually define our schema language,
> and separate syntactic sugar from its core.  Introspection wants the
> core, but for schema development, a modest amount of sugar is
> convenient.  Some of the current schema syntax needs to be redefined as
> sugar for a suitable desugared form.  We've discussed this for "asterisk
> means optional" already.  Eric's series brings us closer, it just needs
> to be finished.

Our schema language is an implementation detail, we shouldn't worry
about it too much in this discussion. As long as we agree that arguments
do have a name, a type and a boolean that describes whether they are
optional (and I don't think anyone would deny that), we can use that in
a future-proof external API.

> If we can't crack the whole problem in the next development cycle,
> perhaps we can identify a minimally useful sub-schema that is unlikely
> to be affected by the above work.  We could then expose that early, with
> the idea of extending it later.

We've done that for several years and we haven't cracked it. We need to
start doing something. Now.

Look at blockdev. We only started moving because we stopped discussing
and actually started hacking on it. And blockdev is much more complex
and we still haven't figured out all the details. In comparison with
blockdev, schema introspection doesn't look that hard any more.

Kevin