[Qemu-devel] Re: [PATCH 01/11] QMP: Introduce specification file

[Daniel P. Berrange]

On Tue, Jun 23, 2009 at 11:55:56AM +0300, Avi Kivity wrote:
> On 06/23/2009 07:28 AM, Luiz Capitulino wrote:
> >This file contains detailed QMP description and definitions.
> >
> >Signed-off-by: Luiz Capitulino<address@hidden>
> >---
> >  monitor-protocol-spec.txt |  180 
> >  +++++++++++++++++++++++++++++++++++++++++++++
> >  1 files changed, 180 insertions(+), 0 deletions(-)
> >  create mode 100644 monitor-protocol-spec.txt
> >
> >diff --git a/monitor-protocol-spec.txt b/monitor-protocol-spec.txt
> >new file mode 100644
> >index 0000000..d20e3f9
> >--- /dev/null
> >+++ b/monitor-protocol-spec.txt
> >@@ -0,0 +1,180 @@
> >+               QEMU Monitor Protocol Specification - Version 0.1
> >+
> >+                                Luiz Capitulino
> >+<address@hidden>
> >+
> >+1. Introduction
> >+===============
> >+
> >+This document specifies the QEMU Monitor Protocol (QMP), a text-based 
> >protocol
> >+which is available for applications to control QEMU at the machine-level.
> >   
> 
> Without a doubt, this is a the most important file of this patchset.  
> There's a huge difference between working with an implementation and 
> working with a specification.
> 
> >+
> >+For a detailed list of supported commands, please, refer to file
> >+monitor-protocol-commands.txt.
> >   
> 
> I don't see you update that file anywhere.  In any case, my preference 
> would be to have everything in one file.
> 
> >+3.1 General definition
> >+----------------------
> >+
> >+ o Only ASCII is permitted
> >   
> 
> Since the some commands contain user-specified strings, UTF-8 is needed.

This would imply that QEMU does charset conversion of all data going in
or out of the monitor, to cope with the case of being run in a non-UTF8
locale. This is probably worth it though, because the only viable
alternative would be to have the monitor always work in the locale the
QEMU is launched under which pushes the problem off to every client.

> I think it's worthwhile to define a quoted string format, to be used 
> both in commands and responses.

Definitely need a quoted string format, space delimited is not sufficient
to cope with filenames with spaces in them

> 
> >+
> >+3.3.1 Server Greeting
> >+---------------------
> >+
> >+Sent when a new connection is opened.
> >+
> >+Format: + OK QEMU<version>  QMP<version>
> >+Example: + OK QEMU 0.10.50 QMP 0.1
> >   
> 
> Clients should never make decisions based on the qemu or qmp version.  
> Rather, we should provide a facility to query the availability of features.

True, but having QEMU print full version info when connecting is still 
a useful thing for clients to log for developer debugging.


> >+ o Command completion failed
> >+
> >+    Format: - ERR<reason>
> >+    Example: - ERR could not find network device 'foo'
> >+
> >   
> 
> Maybe add a numeric error code (to be defined by individual commands).

I think that would be particularly useful to allow clients to distinguish
the error from a command which does not exist, vs a command that exists
but failed. There's probably a handful of common errors that you want
to detect from all commands with the same error handling logic. 

> 
> >+4.3 Events
> >+----------
> >+
> >+Client queries the Server about memory, but QEMU reboots.
> >+
> >+S: + OK QEMU 0.10.50 QMP 0.1
> >+C: info balloon
> >+S: * EVENT reboot
> >   
> 
> The guest reboots (actually, resets), not qemu.  And 'info balloon' will 
> eventually print its response, no?

Might we need to have timestamp assoicated with each response, or will we
define that responses are explicitly ordered wrt events,to reflect the order
in which they're handled. eg When the 'info balloon' response arrives, we
want to know whether the data it contains is reflecting state before or
after the reboot. 

Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|