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