Re: [Qemu-devel] [PATCH 11/11] Change the monitor to use the new do_info_qtree.

[Nathan Baum]

On Tue, 2009-12-29 at 15:15 -0200, Luiz Capitulino wrote:
> On Sat, 26 Dec 2009 21:19:22 +0000
> Nathan Baum <address@hidden> wrote:
> 
> > Signed-off-by: Nathan Baum <address@hidden>
> > ---
> >  hw/qdev.c |    9 ++++++++-
> >  hw/qdev.h |    3 ++-
> >  monitor.c |    3 ++-
> >  3 files changed, 12 insertions(+), 3 deletions(-)
> > 
> > diff --git a/hw/qdev.c b/hw/qdev.c
> > index f5d68c6..d9d3778 100644
> > --- a/hw/qdev.c
> > +++ b/hw/qdev.c
> > @@ -727,6 +727,12 @@ static void do_info_qbus(Monitor *mon, BusState *bus, 
> > QObject **ret_data)
> >      *ret_data = (QObject *) qdict;
> >  }
> >  
> > +void do_info_qtree(Monitor *mon, QObject **ret_data)
> > +{
> > +    if (main_system_bus)
> > +        do_info_qbus(mon, main_system_bus, ret_data);
> > +}
> > +
> 
>  What I'm missing here is a high-level documentation of the
> data type you're building.

Oh yes. I didn't think about that!

I'm not sure if there's a policy on how complicated QMP responses will
be documented?

One possibility that seems quite nice is to use something like JSON
Schema[1], which describes JSON objects using JSON, since that means QMP
clients can ask Qemu itself to describe its own protocol, and the result
could be automatically processed (with some hypothetical "qmpdoc" tool)
to produce human-readable documentation.

In the mean time, I'm quite happy to write up something in the spirit of
the the current informal specification language from qmp-spec. (Like:

qtree-info = [ qbus-info* ]

qbus-info = { "bus": json-string,
              "type": json-string,
              "allow_hotplug": json-bool,
              "children": [ qdev-info* ] }

etc...

?)

This should give people who don't want to have to wade through the code
an idea of what they can expect out of it! :-)

[1] http://json-schema.org/