ShuriZma
/
xemu
mirror of https://github.com/xemu-project/xemu.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

QMP: Update README file 

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>
This commit is contained in:
Luiz Capitulino 2010-08-20 16:42:32 -03:00 committed by Anthony Liguori
parent 05705ce2f8
commit d29f3196af
1 changed files with 48 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
QMP/README
View File

@ -7,60 +7,85 @@ Introduction
The QEMU Monitor Protocol (QMP) allows applications to communicate with The QEMU Monitor Protocol (QMP) allows applications to communicate with
QEMU's Monitor. QEMU's Monitor.
QMP is JSON[1] based and has the following features: QMP is JSON[1] based and currently has the following features:
- Lightweight, text-based, easy to parse data format - Lightweight, text-based, easy to parse data format
- Asynchronous events support - Asynchronous messages support (ie. events)
- Stability - Capabilities Negotiation
For more information, please, refer to the following files: For detailed information on QMP's usage, please, refer to the following files:
o qmp-spec.txt QEMU Monitor Protocol current specification o qmp-spec.txt QEMU Monitor Protocol current specification
o qmp-commands.txt QMP supported commands o qmp-commands.txt QMP supported commands (auto-generated at build-time)
o qmp-events.txt List of available asynchronous events o qmp-events.txt List of available asynchronous events
There are also two simple Python scripts available: There are also two simple Python scripts available:
o qmp-shell A shell o qmp-shell A shell
o vm-info Show some information about the Virtual Machine 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 [1] http://www.json.org
Usage Usage
----- -----
To enable QMP, QEMU has to be started in "control mode". There are 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 the '-qmp' two ways of doing this.
command-line option.
For example: 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 $ qemu [...] -qmp tcp:localhost:4444,server
Will start QEMU in control mode, waiting for a client TCP connection However, in order to have more complex combinations, like multiple monitors,
on localhost port 4444. 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.
It is also possible to use the '-mon' command-line option to have $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
more complex combinations. Please, refer to the QEMU's manpage for -chardev socket,id=mon1,host=localhost,port=4444,server \
more information. -mon chardev=mon1,mode=control
Please, refer to QEMU's manpage for more information.
Simple Testing Simple Testing
-------------- --------------
To manually test QMP one can connect with telnet and issue commands: To manually test QMP one can connect with telnet and issue commands by hand:
$ telnet localhost 4444 $ telnet localhost 4444
Trying 127.0.0.1... Trying 127.0.0.1...
Connected to localhost. Connected to localhost.
Escape character is '^]'. Escape character is '^]'.
{"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}} {"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
{ "execute": "qmp_capabilities" } { "execute": "qmp_capabilities" }
{"return": {}} {"return": {}}
{ "execute": "query-version" } { "execute": "query-version" }
{"return": {"qemu": "0.12.50", "package": ""}} {"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
Contact 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 http://www.linux-kvm.org/page/MonitorProtocol
Luiz Fernando N. Capitulino <lcapitulino@redhat.com>