Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 1 | QEMU Machine Protocol |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 2 | ===================== |
| 3 | |
| 4 | Introduction |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 5 | ------------ |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 6 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 7 | The QEMU Machine Protocol (QMP) allows applications to operate a |
| 8 | QEMU instance. |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 9 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 10 | QMP is JSON[1] based and features the following: |
Luiz Capitulino | 052f1b9 | 2009-12-18 13:25:02 -0200 | [diff] [blame] | 11 | |
| 12 | - Lightweight, text-based, easy to parse data format |
Luiz Capitulino | d29f319 | 2010-08-20 16:42:32 -0300 | [diff] [blame] | 13 | - Asynchronous messages support (ie. events) |
| 14 | - Capabilities Negotiation |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 15 | |
Luiz Capitulino | d29f319 | 2010-08-20 16:42:32 -0300 | [diff] [blame] | 16 | For detailed information on QMP's usage, please, refer to the following files: |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 17 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 18 | o qmp-spec.txt QEMU Machine Protocol current specification |
Luiz Capitulino | d29f319 | 2010-08-20 16:42:32 -0300 | [diff] [blame] | 19 | o qmp-commands.txt QMP supported commands (auto-generated at build-time) |
Jan Kiszka | b40292e | 2010-05-31 14:43:31 -0300 | [diff] [blame] | 20 | o qmp-events.txt List of available asynchronous events |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 21 | |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 22 | [1] http://www.json.org |
| 23 | |
| 24 | Usage |
| 25 | ----- |
| 26 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 27 | You can use the -qmp option to enable QMP. For example, the following |
| 28 | makes QMP available on localhost port 4444: |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 29 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 30 | $ qemu [...] -qmp tcp:localhost:4444,server,nowait |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 31 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 32 | However, for more flexibility and to make use of more options, the -mon |
| 33 | command-line option should be used. For instance, the following example |
| 34 | creates one HMP instance (human monitor) on stdio and one QMP instance |
| 35 | on localhost port 4444: |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 36 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 37 | $ 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 Capitulino | d29f319 | 2010-08-20 16:42:32 -0300 | [diff] [blame] | 40 | |
| 41 | Please, refer to QEMU's manpage for more information. |
Luiz Capitulino | 052f1b9 | 2009-12-18 13:25:02 -0200 | [diff] [blame] | 42 | |
| 43 | Simple Testing |
| 44 | -------------- |
| 45 | |
Luiz Capitulino | d29f319 | 2010-08-20 16:42:32 -0300 | [diff] [blame] | 46 | To manually test QMP one can connect with telnet and issue commands by hand: |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 47 | |
| 48 | $ telnet localhost 4444 |
Luiz Capitulino | 052f1b9 | 2009-12-18 13:25:02 -0200 | [diff] [blame] | 49 | Trying 127.0.0.1... |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 50 | Connected to localhost. |
| 51 | Escape character is '^]'. |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 52 | { |
| 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 Capitulino | ca9567e | 2010-02-04 18:10:04 -0200 | [diff] [blame] | 67 | { "execute": "qmp_capabilities" } |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 68 | { |
| 69 | "return": { |
| 70 | } |
| 71 | } |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 72 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 73 | { "execute": "query-status" } |
| 74 | { |
| 75 | "return": { |
| 76 | "status": "prelaunch", |
| 77 | "singlestep": false, |
| 78 | "running": false |
| 79 | } |
| 80 | } |
Luiz Capitulino | d29f319 | 2010-08-20 16:42:32 -0300 | [diff] [blame] | 81 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 82 | Please, refer to the qapi-schema.json file for a complete command reference. |
Luiz Capitulino | d29f319 | 2010-08-20 16:42:32 -0300 | [diff] [blame] | 83 | |
Luiz Capitulino | 52bbff7 | 2013-09-10 17:15:49 -0400 | [diff] [blame] | 84 | QMP wiki page |
| 85 | ------------- |
Luiz Capitulino | 26d5a1c | 2009-11-26 22:59:06 -0200 | [diff] [blame] | 86 | |
Stefan Hajnoczi | 8593898 | 2013-10-11 14:52:38 +0200 | [diff] [blame] | 87 | http://wiki.qemu-project.org/QMP |