root / QMP / README @ 9bed0d0d
History | View | Annotate | Download (2.9 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 | 26d5a1cd | Luiz Capitulino | There are also two simple Python scripts available: |
23 | 26d5a1cd | Luiz Capitulino | |
24 | d29f3196 | Luiz Capitulino | o qmp-shell A shell |
25 | d29f3196 | Luiz Capitulino | o vm-info Show some information about the Virtual Machine |
26 | d29f3196 | Luiz Capitulino | |
27 | d29f3196 | Luiz Capitulino | IMPORTANT: It's strongly recommended to read the 'Stability Considerations' |
28 | d29f3196 | Luiz Capitulino | section in the qmp-commands.txt file before making any serious use of QMP. |
29 | d29f3196 | Luiz Capitulino | |
30 | 26d5a1cd | Luiz Capitulino | |
31 | 26d5a1cd | Luiz Capitulino | [1] http://www.json.org |
32 | 26d5a1cd | Luiz Capitulino | |
33 | 26d5a1cd | Luiz Capitulino | Usage |
34 | 26d5a1cd | Luiz Capitulino | ----- |
35 | 26d5a1cd | Luiz Capitulino | |
36 | d29f3196 | Luiz Capitulino | To enable QMP, you need a QEMU monitor instance in "control mode". There are |
37 | d29f3196 | Luiz Capitulino | two ways of doing this. |
38 | d29f3196 | Luiz Capitulino | |
39 | d29f3196 | Luiz Capitulino | The simplest one is using the '-qmp' command-line option. The following |
40 | d29f3196 | Luiz Capitulino | example makes QMP available on localhost port 4444: |
41 | 26d5a1cd | Luiz Capitulino | |
42 | d29f3196 | Luiz Capitulino | $ qemu [...] -qmp tcp:localhost:4444,server |
43 | 26d5a1cd | Luiz Capitulino | |
44 | d29f3196 | Luiz Capitulino | However, in order to have more complex combinations, like multiple monitors, |
45 | d29f3196 | Luiz Capitulino | the '-mon' command-line option should be used along with the '-chardev' one. |
46 | d29f3196 | Luiz Capitulino | For instance, the following example creates one user monitor on stdio and one |
47 | d29f3196 | Luiz Capitulino | QMP monitor on localhost port 4444. |
48 | 26d5a1cd | Luiz Capitulino | |
49 | d29f3196 | Luiz Capitulino | $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \ |
50 | d29f3196 | Luiz Capitulino | -chardev socket,id=mon1,host=localhost,port=4444,server \ |
51 | d29f3196 | Luiz Capitulino | -mon chardev=mon1,mode=control |
52 | 26d5a1cd | Luiz Capitulino | |
53 | d29f3196 | Luiz Capitulino | Please, refer to QEMU's manpage for more information. |
54 | 052f1b9b | Luiz Capitulino | |
55 | 052f1b9b | Luiz Capitulino | Simple Testing |
56 | 052f1b9b | Luiz Capitulino | -------------- |
57 | 052f1b9b | Luiz Capitulino | |
58 | d29f3196 | Luiz Capitulino | To manually test QMP one can connect with telnet and issue commands by hand: |
59 | 26d5a1cd | Luiz Capitulino | |
60 | 26d5a1cd | Luiz Capitulino | $ telnet localhost 4444 |
61 | 052f1b9b | Luiz Capitulino | Trying 127.0.0.1... |
62 | 26d5a1cd | Luiz Capitulino | Connected to localhost. |
63 | 26d5a1cd | Luiz Capitulino | Escape character is '^]'. |
64 | d29f3196 | Luiz Capitulino | {"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}} |
65 | ca9567e2 | Luiz Capitulino | { "execute": "qmp_capabilities" } |
66 | ca9567e2 | Luiz Capitulino | {"return": {}} |
67 | 26d5a1cd | Luiz Capitulino | { "execute": "query-version" } |
68 | d29f3196 | Luiz Capitulino | {"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}} |
69 | d29f3196 | Luiz Capitulino | |
70 | d29f3196 | Luiz Capitulino | Development Process |
71 | d29f3196 | Luiz Capitulino | ------------------- |
72 | d29f3196 | Luiz Capitulino | |
73 | d29f3196 | Luiz Capitulino | When changing QMP's interface (by adding new commands, events or modifying |
74 | d29f3196 | Luiz Capitulino | existing ones) it's mandatory to update the relevant documentation, which is |
75 | d29f3196 | Luiz Capitulino | one (or more) of the files listed in the 'Introduction' section*. |
76 | d29f3196 | Luiz Capitulino | |
77 | d29f3196 | Luiz Capitulino | Also, it's strongly recommended to send the documentation patch first, before |
78 | d29f3196 | Luiz Capitulino | doing any code change. This is so because: |
79 | d29f3196 | Luiz Capitulino | |
80 | d29f3196 | Luiz Capitulino | 1. Avoids the code dictating the interface |
81 | d29f3196 | Luiz Capitulino | |
82 | d29f3196 | Luiz Capitulino | 2. Review can improve your interface. Letting that happen before |
83 | d29f3196 | Luiz Capitulino | you implement it can save you work. |
84 | d29f3196 | Luiz Capitulino | |
85 | 82a56f0d | Luiz Capitulino | * The qmp-commands.txt file is generated from the qmp-commands.hx one, which |
86 | d29f3196 | Luiz Capitulino | is the file that should be edited. |
87 | 26d5a1cd | Luiz Capitulino | |
88 | d29f3196 | Luiz Capitulino | Homepage |
89 | d29f3196 | Luiz Capitulino | -------- |
90 | 26d5a1cd | Luiz Capitulino | |
91 | a18b2ce2 | Luiz Capitulino | http://wiki.qemu.org/QMP |