From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MJ9Y7-0007Jh-OR for qemu-devel@nongnu.org; Tue, 23 Jun 2009 13:12:47 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MJ9Y2-0007Es-OT for qemu-devel@nongnu.org; Tue, 23 Jun 2009 13:12:47 -0400 Received: from [199.232.76.173] (port=59349 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MJ9Y2-0007Eb-H1 for qemu-devel@nongnu.org; Tue, 23 Jun 2009 13:12:42 -0400 Received: from mx2.redhat.com ([66.187.237.31]:47683) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1MJ9Y1-0003iv-TD for qemu-devel@nongnu.org; Tue, 23 Jun 2009 13:12:42 -0400 Date: Tue, 23 Jun 2009 14:12:34 -0300 From: Luiz Capitulino Message-ID: <20090623141234.4c63b562@doriath> In-Reply-To: <20090623131034.GB16194@redhat.com> References: <20090623012811.53a62493@doriath> <4A40989C.1050805@redhat.com> <20090623100615.464404c8@doriath> <20090623131034.GB16194@redhat.com> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Subject: [Qemu-devel] Re: [PATCH 01/11] QMP: Introduce specification file List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: "Daniel P. Berrange" Cc: aliguori@us.ibm.com, ehabkost@redhat.com, jan.kiszka@siemens.com, dlaor@redhat.com, qemu-devel@nongnu.org, Avi Kivity On Tue, 23 Jun 2009 14:10:34 +0100 "Daniel P. Berrange" 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 wrote: > > > > > On 06/23/2009 07:28 AM, Luiz Capitulino wrote: > > > > This file contains detailed QMP description and definitions. > > > > > > > > Signed-off-by: Luiz Capitulino > > > > --- > > > > 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 > > > > + > > > > + > > > > +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 > > > > > > > > > > """ > > > > 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 QMP > > > > +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 > > > > + 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.