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

[Luiz Capitulino <lcapitulino@redhat.com>]

 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

The QMP directory of that tree has some documents plus a Python script which
communicates with QEMU by using the protocol and emulates a shell, although
only few commands are working..

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.

What follows is the protocol draft spec. I will not post the patches because
the current implementation is buggy and limited, but it will improve in the
next weeks, as I'm going to work on it in parallel with the conversions.

Thanks.

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

All json-objects members are mandatory when not specified otherwise.

2.2 Server Greeting
-------------------

Right when connected the Server will issue a greeting message, which signals
that the connection has been successfully established and that the Server is
waiting for commands.

The format is:

{ "QEMU": json-string, "QMP": json-string, "capabilities": json-array }

 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

2.3 Issuing Commands
--------------------

The format for command execution is:

{ "execute": json-string, "id": json-value, "arguments": json-object }

 Where,

- The "execute" member identifies the command to be executed by the Server
- The "id" member is a transaction identification associated with the
  command execution, it is optional
- The "arguments" member is used to pass any arguments required for the
  execution of the command, it is optional when no arguments are required

For a listing of supported commands and theirs arguments, please, refer to
the qmp-command-set.txt file.

2.4 Commands Execution
----------------------

TODO: explain parallel execution and the "id" member.

2.5 Commands Responses
----------------------

There are two possible responses which the Server will issue as the result
of a command completion: success or error.

2.5.1 success
-------------

The success response is issued when the command execution has finished
without errors.

The format is:

{ "return": json-value, "id": json-value, "timestamp": json-string }

 Where,

- The "return" member contains the command returned data, which is defined
  in a per-command basis or json-null if the command does not return data
- The "id" member contains the transaction identification associated
  with the command execution (if issued by the Client)
- The "timestamp" member contains the exact time of when the response was
  generated by the Server (FIXME: format)

2.5.2 error
-----------

The error response is issued when the command execution could not be
completed because of an error condition.

The format is:

{ "error": { "code": json-number, "desc": json-string, "data": json-value } "id": json-value, "timestamp": json-string }

 Where,

- The "code" member contains the error code. Its first digit indicates the
  error type, as show below:

        1 Server
        2 Protocol
        3 Command Specific

- The "desc" member contains the error description
- The "data" member contains specific error data, it is optional
- The "id" member contains the transaction identification associated with
  the command execution (if issued by the Client)
- The "timestamp" member contains the exact time of when the response was
  generated by the Server (FIXME: format)

Section '2.7 Server and Protocol errors' contains additional information about
error handling.

2.6 Asynchronous events
-----------------------

As a result of state changes, the Server may send messages unilaterally
to the Client at any time. This is called 'asynchronous events'.

The format is:

{ "event": json-string, "timestamp": json-string, "data": json-value }

 Where,

- The "event" member contains the event's name
- The "timestamp" member contains the exact time of when the event happend
  in the Server (FIXME: format)
- The "data" member contains event specific data, which is defined in a
  per-event basis, it is optional

For a listing of supported asynchronous events, please, refer to the
qmp-command-set.txt file.

2.7 Server and Protocol errors
------------------------------

TODO: describe all possible server and protocol errors.

3. Examples
============

This section provides some examples of real QMP usage, in all of them
'C' stands for 'Client' and 'S' stands for 'Server'.

3.1 Simple 'stop' execution
---------------------------

S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
C: { "execute": "stop" }
S: { "return": null, "timestamp": "" }

3.2 KVM information
-------------------

S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
C: { "execute": "info", "id": 1, "arguments": { "item": "kvm" } }
S: { "return": "enabled", "id": 1, "timestamp": "" }

3.3 Error on 'info balloon' execution
-------------------------------------

S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
C: { "execute": "info", "id": "abc", "arguments": { "item": "balloon" } }
S: { "error": { "code": 354, "Ballooning not activated in VM" }, "id": "abc", "timestamp": "" }

3.4 Powerdown event
-------------------

S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
...
S: { "event": "POWERDOWN", "timestamp": "" }
...

4. Current Implementation
=========================

The current QMP implementation lacks some of the protocol capabilities
specified in this document.

The most important one is the execution of commands as discussed in the
section '2.3 Issuing Commands'. Currently the Server does not support it.

Protocol input is done by issuing regular ASCII strings, as it is done when
using the humam Monitor protocol.

For example, to query the current balloon information the Client should
issue:

"info balloon\r\n"

Additionally, the following limitations are present:

- The transaction "id" is not supported
- json-strings issued by the Server are not in Unicode format
- All "timestamp" members are always an empty json-string ""
- Error handling is basically not implemented
"""