Name Date Size #Lines LOC

..02-Apr-2019-

READMEH A D27-Sep-20172.8 KiB8960

qmp-events.txtH A D27-Sep-20177.6 KiB267191

qmp-shellH A D27-Sep-20177.7 KiB260188

qmp-spec.txtH A D27-Sep-20179.2 KiB273191

qmp.pyH A D27-Sep-20173.7 KiB132102

README

1                          QEMU Monitor Protocol
2                          =====================
3
4Introduction
5-------------
6
7The QEMU Monitor Protocol (QMP) allows applications to communicate with
8QEMU's Monitor.
9
10QMP 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
16For detailed information on QMP's usage, please, refer to the following files:
17
18o qmp-spec.txt      QEMU Monitor Protocol current specification
19o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
20o qmp-events.txt    List of available asynchronous events
21
22There is also a simple Python script called 'qmp-shell' available.
23
24IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
25section in the qmp-commands.txt file before making any serious use of QMP.
26
27
28[1] http://www.json.org
29
30Usage
31-----
32
33To enable QMP, you need a QEMU monitor instance in "control mode". There are
34two ways of doing this.
35
36The simplest one is using the '-qmp' command-line option. The following
37example makes QMP available on localhost port 4444:
38
39  $ qemu [...] -qmp tcp:localhost:4444,server
40
41However, in order to have more complex combinations, like multiple monitors,
42the '-mon' command-line option should be used along with the '-chardev' one.
43For instance, the following example creates one user monitor on stdio and one
44QMP 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
50Please, refer to QEMU's manpage for more information.
51
52Simple Testing
53--------------
54
55To manually test QMP one can connect with telnet and issue commands by hand:
56
57$ telnet localhost 4444
58Trying 127.0.0.1...
59Connected to localhost.
60Escape 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
67Development Process
68-------------------
69
70When changing QMP's interface (by adding new commands, events or modifying
71existing ones) it's mandatory to update the relevant documentation, which is
72one (or more) of the files listed in the 'Introduction' section*.
73
74Also, it's strongly recommended to send the documentation patch first, before
75doing 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
85Homepage
86--------
87
88http://wiki.qemu.org/QMP
89