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

[Markus Armbruster]

Luiz Capitulino <address@hidden> writes:

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

That was just before Christmas, and that's why I haven't gotten around
to posting it here properly.

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

Indeed.  I'm working on it, and hope get it posted today.

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

It does.  Thanks for the pointer!

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

We did, actually :)

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

Not necessarily.  Documentation will be in whatever place we put it.
Some places require tools to extract it.

[...]