Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc

[Markus Armbruster]

Luiz Capitulino <address@hidden> writes:

> On Thu, 13 May 2010 16:48:13 +0300
> Avi Kivity <address@hidden> wrote:
>
>> On 05/05/2010 10:11 PM, Luiz Capitulino wrote:
>> > One of the most important missing feature in QMP today is its
>> > supported commands documentation.
>> >
>> > The plan is to make it part of self-description support, however
>> > self-description is a big task we have been postponing for a
>> > long time now and still don't know when it's going to be done.
>> >
>> > In order not to compromise QMP adoption and make users' life easier,
>> > this commit adds a simple text documentation which fully describes
>> > all QMP supported commands.
>> >
>> > This is not ideal for a number of reasons (harder to maintain,
>> > text-only, etc) but does improve the current situation.
[...]
>> > +pmemsave
>> > +--------
>> > +
>> > +Save to disk physical memory dump starting at 'val' of size 'size'.
>> > +
>> > +Arguments:
>> > +
>> > +- "val": the starting address (json-int)
>> >    
>> 
>> Why "val" instead of "address" or "physical-address"?
>
>  Mea culpa, for this and most inconsistencies you find in the protocol.
>
>  The reason is that I did a lot of conversions in a hurry, so that
> we could get libvirt working under QMP as soon as possible.
>
>  Unfortunately, some bad names and some bad behaviors from the user
> Monitor leaked into QMP. Lesson learned, although sometimes it's very
> difficult to define what a name/behavior should be in QMP.

Once we declare QMP stable, we're stuck with bad names forever.  So
better fix them before we stabilize.  Best to fix them all in one go,
and prepare the (hopefully straightforward) libvirt patch to go with it.

[...]