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

[Avi Kivity <avi@redhat.com>]

On 06/23/2009 07:28 AM, Luiz Capitulino wrote:
> This file contains detailed QMP description and definitions.
>
> Signed-off-by: Luiz Capitulino<lcapitulino@redhat.com>
> ---
>   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
> +<lcapitulino@redhat.com>
> +
> +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.

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

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

> +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?

-- 
error compiling committee.c: too many arguments to function