← Back to branch summary

~ahs3/+junk/cq-qemu

« back to all changes in this revision

Viewing changes to QMP/README

  • Committer: Al Stone
  • Date: 2012-02-09 01:17:20 UTC
  • Revision ID: albert.stone@canonical.com-20120209011720-tztl7ik3qayz80p4
first commit to bzr for qemu

Show diffs side-by-side

added added

removed removed

Lines of Context:
QMP/README
 
1
                          QEMU Monitor Protocol
 
2
                          =====================
 
3
 
 
4
Introduction
 
5
-------------
 
6
 
 
7
The QEMU Monitor Protocol (QMP) allows applications to communicate with
 
8
QEMU's Monitor.
 
9
 
 
10
QMP is JSON[1] based and currently has the following features:
 
11
 
 
12
- Lightweight, text-based, easy to parse data format
 
13
- Asynchronous messages support (ie. events)
 
14
- Capabilities Negotiation
 
15
 
 
16
For detailed information on QMP's usage, please, refer to the following files:
 
17
 
 
18
o qmp-spec.txt      QEMU Monitor Protocol current specification
 
19
o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
 
20
o qmp-events.txt    List of available asynchronous events
 
21
 
 
22
There is also a simple Python script called 'qmp-shell' available.
 
23
 
 
24
IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
 
25
section in the qmp-commands.txt file before making any serious use of QMP.
 
26
 
 
27
 
 
28
[1] http://www.json.org
 
29
 
 
30
Usage
 
31
-----
 
32
 
 
33
To enable QMP, you need a QEMU monitor instance in "control mode". There are
 
34
two ways of doing this.
 
35
 
 
36
The simplest one is using the '-qmp' command-line option. The following
 
37
example makes QMP available on localhost port 4444:
 
38
 
 
39
  $ qemu [...] -qmp tcp:localhost:4444,server
 
40
 
 
41
However, in order to have more complex combinations, like multiple monitors,
 
42
the '-mon' command-line option should be used along with the '-chardev' one.
 
43
For instance, the following example creates one user monitor on stdio and one
 
44
QMP monitor on localhost port 4444.
 
45
 
 
46
   $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
 
47
                -chardev socket,id=mon1,host=localhost,port=4444,server \
 
48
                -mon chardev=mon1,mode=control
 
49
 
 
50
Please, refer to QEMU's manpage for more information.
 
51
 
 
52
Simple Testing
 
53
--------------
 
54
 
 
55
To manually test QMP one can connect with telnet and issue commands by hand:
 
56
 
 
57
$ telnet localhost 4444
 
58
Trying 127.0.0.1...
 
59
Connected to localhost.
 
60
Escape character is '^]'.
 
61
{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
 
62
{ "execute": "qmp_capabilities" }
 
63
{"return": {}}
 
64
{ "execute": "query-version" }
 
65
{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
 
66
 
 
67
Development Process
 
68
-------------------
 
69
 
 
70
When changing QMP's interface (by adding new commands, events or modifying
 
71
existing ones) it's mandatory to update the relevant documentation, which is
 
72
one (or more) of the files listed in the 'Introduction' section*.
 
73
 
 
74
Also, it's strongly recommended to send the documentation patch first, before
 
75
doing any code change. This is so because:
 
76
 
 
77
  1. Avoids the code dictating the interface
 
78
 
 
79
  2. Review can improve your interface.  Letting that happen before
 
80
     you implement it can save you work.
 
81
 
 
82
* The qmp-commands.txt file is generated from the qmp-commands.hx one, which
 
83
  is the file that should be edited.
 
84
 
 
85
Homepage
 
86
--------
 
87
 
 
88
http://wiki.qemu.org/QMP