qemu/QMP
Anthony Liguori 404e7a4f4a virtio,pci,qom
Work by Alex to support VGA assignment,
 pci and virtio fixes by Stefan, Jason and myself, and a
 new qmp event for hotplug support by myself.
 
 Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.13 (GNU/Linux)
 
 iQEcBAABAgAGBQJRUfDAAAoJECgfDbjSjVRp5wwH/RiNzEuC0SNuMArXh2LS+qjn
 EavcSRTas5800Rl8bW2iYwJV38WhyW7jKs3JxbL5iK6XLeZvr7mureMRpsT6N5cR
 WPqoZBw2jIxcHmYZODHTGd9SrAmF2LpfKypN3a86P5P4sQvV/dEusPQx7ZNyi5I5
 kdhqNyP6Q6scAUbJVrNUbcOy8euLUtpEO2VQju/gikz2KLsQj6Hyxt9vKV2ZquYU
 B7pKvYt5UZhNPqhfBmRptW+U0CMYUPiZBZkZsTEPUibIFHQqGkMD/KtthFFDZc/U
 hjxttuETzjACR3KKgegwLVYCFEF8WadPJark4LWb4D9TA1MIdgo2NabNpqYxqrA=
 =PY9F
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'mst/tags/for_anthony' into staging

virtio,pci,qom

Work by Alex to support VGA assignment,
pci and virtio fixes by Stefan, Jason and myself, and a
new qmp event for hotplug support by myself.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>

# gpg: Signature made Tue 26 Mar 2013 02:02:24 PM CDT using RSA key ID D28D5469
# gpg: Can't check signature: public key not found

# By Alex Williamson (13) and others
# Via Michael S. Tsirkin
* mst/tags/for_anthony: (23 commits)
  pcie: Add endpoint capability initialization wrapper
  roms: switch oldnoconfig to olddefconfig
  pcie: Mangle types to match topology
  pci: Create and use API to determine root buses
  pci: Create pci_bus_is_express helper
  pci: Q35, Root Ports, and Switches create PCI Express buses
  pci: Allow PCI bus creation interfaces to specify the type of bus
  pci: Move PCI and PCIE type defines
  pci: Create and register a new PCI Express TypeInfo
  exec: assert that RAMBlock size is non-zero
  pci: refuse empty ROM files
  pci_bridge: Remove duplicate IRQ swizzle function
  pci_bridge: Use a default map_irq function
  pci: Fix INTx routing notifier recursion
  pci_bridge: drop formatting from source
  pci_bridge: factor out common code
  pci: Teach PCI Bridges about VGA routing
  pci: Add PCI VGA helpers
  virtio-pci: guest notifier mask without non-irqfd
  virtio-net: remove layout assumptions for mq ctrl
  ...
2013-03-26 16:16:43 -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 qmp: add path to device_deleted event 2013-03-26 21:02:16 +02:00
qmp-shell qmp: fix handling of boolean values in qmp-shell 2013-03-25 16:21:33 -04:00
qmp-spec.txt qmp: switch to the new error format on the wire 2012-08-13 14:17:53 -03:00
qmp.py qmp: add pull_event function 2012-10-24 10:26:22 +02: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