qemu/QMP
Luiz Capitulino 1d00a07de9 QMP: Revamp the Python class example
This commit simplifies and fixes a number of problems in the Python
QEMUMonitorProtocol example class.

It's almost a rewrite and it DOES BREAK the qmp-shell script (which
is going to be fixed in the next commit).

However, I'm not going to split this in different commits because it
could get up to 10 commits, it's really not worth it for a simple
demo class.

Highlights:

 o TCP sockets support
 o QMP events support
 o Add documentation
 o Fix a number of unhandled errors
 o Simplify methods that send commands to the Monitor

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
2010-11-17 09:51:07 -02:00
..
qmp-events.txt Trivial fix for QMP/qmp-events.txt 2010-10-22 10:08:37 -02:00
qmp-shell QMP: Teach basic capability negotiation to python example 2010-07-01 14:27:13 -03:00
qmp-spec.txt QMP: Add "Downstream extension of QMP" to spec 2010-05-19 12:04:08 -03:00
qmp.py QMP: Revamp the Python class example 2010-11-17 09:51:07 -02:00
README QMP/README: Update QMP homepage address 2010-10-01 10:20:07 -03:00
vm-info QMP: Teach basic capability negotiation to python example 2010-07-01 14:27:13 -03:00

                          QEMU Monitor Protocol
                          =====================

Introduction
-------------

The QEMU Monitor Protocol (QMP) allows applications to communicate with
QEMU's Monitor.

QMP is JSON[1] based and currently has the following features:

- Lightweight, text-based, easy to parse data format
- Asynchronous messages support (ie. events)
- Capabilities Negotiation

For detailed information on QMP's usage, please, refer to the following files:

o qmp-spec.txt      QEMU Monitor Protocol current specification
o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
o qmp-events.txt    List of available asynchronous events

There are also two simple Python scripts available:

o qmp-shell  A shell
o vm-info    Show some information about the Virtual Machine

IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
section in the qmp-commands.txt file before making any serious use of QMP.


[1] http://www.json.org

Usage
-----

To enable QMP, you need a QEMU monitor instance in "control mode". There are
two ways of doing this.

The simplest one is using the '-qmp' command-line option. The following
example makes QMP available on localhost port 4444:

  $ qemu [...] -qmp tcp:localhost:4444,server

However, in order to have more complex combinations, like multiple monitors,
the '-mon' command-line option should be used along with the '-chardev' one.
For instance, the following example creates one user monitor on stdio and one
QMP monitor on localhost port 4444.

   $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
                -chardev socket,id=mon1,host=localhost,port=4444,server \
                -mon chardev=mon1,mode=control

Please, refer to QEMU's manpage for more information.

Simple Testing
--------------

To manually test QMP one can connect with telnet and issue commands by hand:

$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
{ "execute": "qmp_capabilities" }
{"return": {}}
{ "execute": "query-version" }
{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}

Development Process
-------------------

When changing QMP's interface (by adding new commands, events or modifying
existing ones) it's mandatory to update the relevant documentation, which is
one (or more) of the files listed in the 'Introduction' section*.

Also, it's strongly recommended to send the documentation patch first, before
doing any code change. This is so because:

  1. Avoids the code dictating the interface

  2. Review can improve your interface.  Letting that happen before
     you implement it can save you work.

* The qmp-commands.txt file is generated from the qmp-commands.hx one, which
  is the file that should be edited.

Homepage
--------

http://wiki.qemu.org/QMP