blob: f6a3a031e9f90add1afeb55552df05eec78a81f7 [file] [log] [blame]
Luiz Capitulino52bbff72013-09-10 17:15:49 -04001 QEMU Machine Protocol
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -02002 =====================
3
4Introduction
Luiz Capitulino52bbff72013-09-10 17:15:49 -04005------------
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -02006
Luiz Capitulino52bbff72013-09-10 17:15:49 -04007The QEMU Machine Protocol (QMP) allows applications to operate a
8QEMU instance.
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -02009
Luiz Capitulino52bbff72013-09-10 17:15:49 -040010QMP is JSON[1] based and features the following:
Luiz Capitulino052f1b92009-12-18 13:25:02 -020011
12- Lightweight, text-based, easy to parse data format
Luiz Capitulinod29f3192010-08-20 16:42:32 -030013- Asynchronous messages support (ie. events)
14- Capabilities Negotiation
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020015
Luiz Capitulinod29f3192010-08-20 16:42:32 -030016For detailed information on QMP's usage, please, refer to the following files:
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020017
Luiz Capitulino52bbff72013-09-10 17:15:49 -040018o qmp-spec.txt QEMU Machine Protocol current specification
Luiz Capitulinod29f3192010-08-20 16:42:32 -030019o qmp-commands.txt QMP supported commands (auto-generated at build-time)
Jan Kiszkab40292e2010-05-31 14:43:31 -030020o qmp-events.txt List of available asynchronous events
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020021
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020022[1] http://www.json.org
23
24Usage
25-----
26
Luiz Capitulino52bbff72013-09-10 17:15:49 -040027You can use the -qmp option to enable QMP. For example, the following
28makes QMP available on localhost port 4444:
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020029
Luiz Capitulino52bbff72013-09-10 17:15:49 -040030$ qemu [...] -qmp tcp:localhost:4444,server,nowait
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020031
Luiz Capitulino52bbff72013-09-10 17:15:49 -040032However, for more flexibility and to make use of more options, the -mon
33command-line option should be used. For instance, the following example
34creates one HMP instance (human monitor) on stdio and one QMP instance
35on localhost port 4444:
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020036
Luiz Capitulino52bbff72013-09-10 17:15:49 -040037$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
38 -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
39 -mon chardev=mon1,mode=control,pretty=on
Luiz Capitulinod29f3192010-08-20 16:42:32 -030040
41Please, refer to QEMU's manpage for more information.
Luiz Capitulino052f1b92009-12-18 13:25:02 -020042
43Simple Testing
44--------------
45
Luiz Capitulinod29f3192010-08-20 16:42:32 -030046To manually test QMP one can connect with telnet and issue commands by hand:
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020047
48$ telnet localhost 4444
Luiz Capitulino052f1b92009-12-18 13:25:02 -020049Trying 127.0.0.1...
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020050Connected to localhost.
51Escape character is '^]'.
Luiz Capitulino52bbff72013-09-10 17:15:49 -040052{
53 "QMP": {
54 "version": {
55 "qemu": {
56 "micro": 50,
57 "minor": 6,
58 "major": 1
59 },
60 "package": ""
61 },
62 "capabilities": [
63 ]
64 }
65}
66
Luiz Capitulinoca9567e2010-02-04 18:10:04 -020067{ "execute": "qmp_capabilities" }
Luiz Capitulino52bbff72013-09-10 17:15:49 -040068{
69 "return": {
70 }
71}
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020072
Luiz Capitulino52bbff72013-09-10 17:15:49 -040073{ "execute": "query-status" }
74{
75 "return": {
76 "status": "prelaunch",
77 "singlestep": false,
78 "running": false
79 }
80}
Luiz Capitulinod29f3192010-08-20 16:42:32 -030081
Luiz Capitulino52bbff72013-09-10 17:15:49 -040082Please, refer to the qapi-schema.json file for a complete command reference.
Luiz Capitulinod29f3192010-08-20 16:42:32 -030083
Luiz Capitulino52bbff72013-09-10 17:15:49 -040084QMP wiki page
85-------------
Luiz Capitulino26d5a1c2009-11-26 22:59:06 -020086
Stefan Hajnoczi85938982013-10-11 14:52:38 +020087http://wiki.qemu-project.org/QMP