Re: [Qemu-devel] [PATCH 2/3] QMP: Introduce commands documentation

[Jan Kiszka <jan.kiszka@siemens.com>]

Stefan Hajnoczi wrote:
> On Mon, May 31, 2010 at 6:43 PM, Luiz Capitulino <lcapitulino@redhat.com> wrote:
> Hi Luiz,
> 
> I'm interested in QMP, have left some feedback.  As I get up to speed
> with QMP my questions and suggestions will hopefully be useful.
> Apologies in advance if any of my thoughts here are old news and have
> been discussed elsewhere :).
> 
> I didn't see documentation on the errors that a command can encounter.
>  Error documentation would be useful for commands where the client
> needs to react by trying an alternative command.  If errors are opaque
> or undocumented, then the client can't perform error recovery, they
> can only log the error or prompt the user for help.
> 
>> @@ -113,6 +184,35 @@ Password: ********
>>
>>  @end table
>>  ETEXI
>> +SQMP
>> +change
>> +------
>> +
>> +Change a removable medium or VNC configuration.
>> +
>> +Arguments:
>> +
>> +- "device": device name (json-string)
>> +- "target": filename or item (json-string)
>> +- "arg": additional argument (json-string, optional)
>> +
>> +Examples:
>> +
>> +1. Change a removable medium
>> +
>> +-> { "execute": "change",
>> +             "arguments": { "device": "ide1-cd0",
>> +                            "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
>> +<- { "return": {} }
>> +
>> +2. Change VNC password
>> +
>> +-> { "execute": "change",
>> +             "arguments": { "device": "vnc", "target": "password",
>> +                            "arg": "foobar1" } }
>> +<- { "return": {} }
>> +
>> +EQMP
>>
>>     {
>>         .name       = "screendump",
> 
> For removable media is there a way to use, for instance, sheepdog, or
> is the target strictly a file name?
> 
> Can the VNC password be removed when arg is the empty string or arg is
> not present?
> 
>> @@ -532,6 +747,24 @@ STEXI
>>  @findex cpu
>>  Set the default CPU.
>>  ETEXI
>> +SQMP
>> +cpu
>> +---
>> +
>> +Set the default CPU.
>> +
>> +Arguments:
>> +
>> +- "index": the CPU's index (json-int)
>> +
>> +Example:
>> +
>> +-> { "execute": "cpu", "arguments": { "index": 0 } }
>> +<- { "return": {} }
>> +
>> +Note: CPUs' indexes are obtained with the 'query-cpus' command.
>> +
>> +EQMP
>>
>>     {
>>         .name       = "mouse_move",
> 
> I believe this is the per-monitor default cpu for memory dumping and
> other per-cpu commands.  The concept of the default cpu makes sense
> for an interactive monitor, humans don't want to type the cpu index
> for each cpu-specific command.  For QMP it feels cleaner to have a cpu
> argument for commands that are per-cpu.  As a newcomer I'm not sure of
> the philosophy for QMP commands, 1:1 with monitor commands or as
> appropriate for a JSON interface?

Makes some sense.

I've a simple patch in my queue that can be used to assign different
arguments for QMP and HMP use. So we could add a 'cpu' argument to all
those QMP commands that so far rely on the above mechanism.

> 
> If the QMP cpu command is supported in a QEMU release, can it be
> phased out later?

Better avoid it being rolled out.

That said, first let us merge this documentation as baseline, then fix
such things (including error documentation) on top of it.

Jan

-- 
Siemens AG, Corporate Technology, CT T DE IT 1
Corporate Competence Center Embedded Linux