qemu/QMP
Anthony Liguori 05d4f2f2ca Merge remote-tracking branch 'kwolf/for-anthony' into staging
* kwolf/for-anthony: (30 commits)
  qemu-iotests: add tests for streaming error handling
  qemu-iotests: map underscore to dash in QMP argument names
  blkdebug: process all set_state rules in the old state
  stream: add on-error argument
  block: introduce block job error
  iostatus: reorganize io error code
  iostatus: change is_read to a bool
  iostatus: move BlockdevOnError declaration to QAPI
  iostatus: rename BlockErrorAction, BlockQMPEventAction
  qemu-iotests: add test for pausing a streaming operation
  qmp: add block-job-pause and block-job-resume
  block: add support for job pause/resume
  qmp: add 'busy' member to BlockJobInfo
  block: add block_job_query
  block: move job APIs to separate files
  block: fix documentation of block_job_cancel_sync
  qerror/block: introduce QERR_BLOCK_JOB_NOT_ACTIVE
  qemu-iotests: add initial tests for live block commit
  QAPI: add command for live block commit, 'block-commit'
  block: helper function, to find the base image of a chain
  ...
2012-10-04 19:53:50 -05:00
..
README QMP: Drop vm-info example script 2010-11-17 09:51:07 -02:00
qemu-ga-client Add qemu-ga-client script 2012-09-26 10:45:02 -03:00
qmp qmp: add test tool for QMP 2011-12-06 11:40:00 -02:00
qmp-events.txt block: introduce block job error 2012-09-28 19:40:56 +02:00
qmp-shell Add support for pretty-printing response in qmp-shell 2012-09-05 15:48:56 -03:00
qmp-spec.txt qmp: switch to the new error format on the wire 2012-08-13 14:17:53 -03:00
qmp.py Support settimeout in QEMUMonitorProtocol 2012-09-26 10:45:02 -03:00
qom-fuse qom: quick and dirty QOM filesystem based on FUSE 2012-04-26 13:14:57 -05:00
qom-get qom: add test tools 2012-02-22 12:18:26 -06:00
qom-list qom: add test tools 2012-02-22 12:18:26 -06:00
qom-set qom: add test tools 2012-02-22 12:18:26 -06:00

README

                          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 is also a simple Python script called 'qmp-shell' available.

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