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

[Luiz Capitulino <lcapitulino@redhat.com>]

On Tue, 01 Jun 2010 09:40:44 +0200
Jan Kiszka <jan.kiszka@siemens.com> wrote:

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

 Nice.

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

 After 0.13 no incompatible protocol change will be allowed.

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

 Exactly, the goal now is to describe the current protocol state.