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

[Luiz Capitulino]

On Tue, 29 Dec 2009 19:25:24 +0000
Nathan Baum <address@hidden> wrote:

> 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?

 No. Markus and I have just started talking about a documentation format
for QMP.

 Markus, it's time to dump your ideas on the list.

> 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.

 This looks very good! We were considering something along these lines
but we didn't consider having the description as part of the dict,
for example.

 This solves some issues we were trying to address.

 The only problem I can see is that the documentation and code will
be in different places, which makes it easier to get outdated.

> 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! :-)

 Well, you would have to change it later so it's better to wait.

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