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

[Luiz Capitulino <lcapitulino@redhat.com>]

On Tue, 23 Jun 2009 14:10:34 +0100
"Daniel P. Berrange" <berrange@redhat.com> wrote:

> On Tue, Jun 23, 2009 at 10:06:15AM -0300, Luiz Capitulino wrote:
> > On Tue, 23 Jun 2009 11:55:56 +0300
> > Avi Kivity <avi@redhat.com> wrote:
> > 
> > > 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.
> > 
> >  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.
> 
> I counter with FTP and HTTP, which do :-P
> 
> eg  http://www.faqs.org/rfcs/rfc959.html
> 
>          200 Command okay.
>          500 Syntax error, command unrecognized.
>              This may include errors such as command line too long.
>          501 Syntax error in parameters or arguments.
>          202 Command not implemented, superfluous at this site.
>          502 Command not implemented.
>          503 Bad sequence of commands.
>          504 Command not implemented for that parameter.

 There goes my argument. :)

 Anthony seems to prefer this way too, although I still think
this is a bit redundant, I don't have a strong opinion here.

 So, we can do this way then.