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

[Stefan Hajnoczi <stefanha@gmail.com>]

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?

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

Will look more later.

Stefan