d29f3196af
A number of changes I prefer to do in one shot: - Fix example - Small clarifications - Add multiple monitors example - Add 'Development Process' section Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
92 lines
2.9 KiB
Plaintext
92 lines
2.9 KiB
Plaintext
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 qemu-monitor.hx one, which
|
|
is the file that should be edited.
|
|
|
|
Homepage
|
|
--------
|
|
|
|
http://www.linux-kvm.org/page/MonitorProtocol
|