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

[Luiz Capitulino]

On Tue, 23 Jun 2009 11:55:56 +0300
Avi Kivity <address@hidden> 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.

 Exactly.

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

 Sorry, I forgot to mention that I wouldn't include this file
in the patchset.

 But its format will be like POP3 or IMAP specs, something like:

"""
6.2 cont

Arguments: none.

Responses: + OK cont completed

<description>

<example>
"""

 We can have everything in the same file then.

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

 Ok, as Daniel also said we will need this.

 The only problem is that I was trying to avoid changing commands'
output too much, because this can turn into a maintenance nightmare.

 Note that we will have to maintain two protocols: the current existing
(user mode) and this new control mode.

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

 Right. What about changing 'help' output to only list command names?

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

 Well, numeric error codes seem redundant in text protocols. At least,
POP3 and IMAP don't use them.

 This may seem contradictory, but although this a low-level protocol,
I feel that text protocols tend to be very descriptive.

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

Yes, it will. I will fix this.