Re: [Qemu-devel] ANN: QEMU Monitor Protocol git tree

[Luiz Capitulino <lcapitulino@redhat.com>]

On Tue, 22 Sep 2009 20:56:04 -0500
Anthony Liguori <anthony@codemonkey.ws> wrote:

> Luiz Capitulino wrote:
> >  Hi there,
> >
> > While I was converting command handlers to the QObject style I realized that
> > it would be very interesting to have the protocol working up front, so that
> > converted handlers could be tested to assure that their data types have been
> > chosen correctly.
> >
> > More importantly, some protocol design decisions can affect handlers signatures,
> > so having at least an idea of how the protocol will look like will help us to
> > stay on the right track during mass conversion.
> >
> > So, I have implemented a rudimentary version of the QEMU Monitor Protocol (QMP)
> > it has a command-line switch to enable the protocol.
> >
> > You will find it at:
> >
> > http://repo.or.cz/w/qemu/qmp-unstable.git
> >   
> 
> I think this is a pretty reasonable approach to take since qmp is 
> relatively isolated from the changes going on in the rest of the tree.

 Yeah, nice.

> > Now the controversial part: it's json based. ;)
> >
> > I have chosen json because of the reasons already explained by others in
> > the original QMP thread. Basically, json is so simple that if we design
> > a small protocol from scratch, chances are it will look like json.
> >   
> 
> json is not a deal break.  My main concern was our ability to extend 
> json and whether supporting stock json libraries was a hard 
> requirement.  I also would like to see a C client library since our 
> biggest consumer (libvirt) is based in C.

 Ok, I agree. I've seen some json implementations out there
(not exactly in the form of a library), but didn't try any of them.

> But the wire protocol is the thing I care the least about.  I care more 
> about the internal refactoring.

 Yes, me too.

 For now we can focus on protocol decisions that may affect the
internal refactoring (and that's my goal with this tree).

 For example, looks like we are going to need a more sophisticated
error handling implementation in order to support the protocol
requirements.

 I'm working on this and should post patches soon.

> > """
> >            QEMU Monitor Protocol Draft Specification - Version 0.1
> >
> > 1. Introduction
> > ===============
> >
> > This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
> > which is available for applications to control QEMU at the machine-level.
> >
> > To enable QMP support, QEMU has to be run in "control mode". This is done by
> > starting QEMU with the appropriate command-line options. Please, refer to the
> > QEMU manual page for more information.
> >
> > This specification is a work in progress and part of it may NOT be available
> > in QEMU, the 'Current Implementation' section has details regarding what has
> > already been implemented and known problems.
> >
> > 2. Protocol Specification
> > =========================
> >
> > This section details the protocol format. For the purpose of this document
> > "Client" is any application which is communicating with QEMU in control mode,
> > and "Server" is QEMU itself.
> >
> > JSON data structures, when mentioned in this document, are always in the
> > following format:
> >
> >     json-DATA-STRUCTURE-NAME
> >
> > Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
> > the JSON standard:
> >
> > http://www.ietf.org/rfc/rfc4627.txt
> >
> > For convenience, json-objects mentioned in this document will have its members
> > in a certain order. However, in real protocol usage json-objects members can
> > be in ANY order, thus no particular order should be assumed.
> >
> > 2.1 General Definitions
> > -----------------------
> >
> > All interactions transmitted by Client and Server are json-objects that end
> > with CRLF.
> >   
> 
> CRLF?  Really?
> 
> Ignoring the dos-ism, since you can parse JSON with a regexp, why do we 
> need explicit message boundaries?

 Hm, I've assumed some kind of end of line would be needed.

> >  Where,
> >
> > - The "QEMU" member contains the QEMU version
> > - The "QMP" member contains the QMP version
> > - The "capabilities" member specify the availability of features beyond the
> >   baseline specification
> >
> >   
> Version and capability are a bit redundant, no?  Any reason to have 
> QEMU's version in the initial hello too?

 I thought that clients would always want to know to what
QEMU they are talking to.

 What do you suggest?