root / QMP / qmp-spec.txt @ ca9567e2
History | View | Annotate | Download (6.2 kB)
1 |
QEMU Monitor Protocol Specification - Version 0.1 |
---|---|
2 |
|
3 |
1. Introduction |
4 |
=============== |
5 |
|
6 |
This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol |
7 |
which is available for applications to control QEMU at the machine-level. |
8 |
|
9 |
To enable QMP support, QEMU has to be run in "control mode". This is done by |
10 |
starting QEMU with the appropriate command-line options. Please, refer to the |
11 |
QEMU manual page for more information. |
12 |
|
13 |
2. Protocol Specification |
14 |
========================= |
15 |
|
16 |
This section details the protocol format. For the purpose of this document |
17 |
"Client" is any application which is communicating with QEMU in control mode, |
18 |
and "Server" is QEMU itself. |
19 |
|
20 |
JSON data structures, when mentioned in this document, are always in the |
21 |
following format: |
22 |
|
23 |
json-DATA-STRUCTURE-NAME |
24 |
|
25 |
Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by |
26 |
the JSON standard: |
27 |
|
28 |
http://www.ietf.org/rfc/rfc4627.txt |
29 |
|
30 |
For convenience, json-object members and json-array elements mentioned in |
31 |
this document will be in a certain order. However, in real protocol usage |
32 |
they can be in ANY order, thus no particular order should be assumed. |
33 |
|
34 |
2.1 General Definitions |
35 |
----------------------- |
36 |
|
37 |
2.1.1 All interactions transmitted by the Server are json-objects, always |
38 |
terminating with CRLF |
39 |
|
40 |
2.1.2 All json-objects members are mandatory when not specified otherwise |
41 |
|
42 |
2.2 Server Greeting |
43 |
------------------- |
44 |
|
45 |
Right when connected the Server will issue a greeting message, which signals |
46 |
that the connection has been successfully established and that the Server is |
47 |
waiting for commands. |
48 |
|
49 |
The format is: |
50 |
|
51 |
{ "QMP": { "version": json-object, "capabilities": json-array } } |
52 |
|
53 |
Where, |
54 |
|
55 |
- The "version" member contains the Server's version information (the format |
56 |
is the same of the 'query-version' command) |
57 |
- The "capabilities" member specify the availability of features beyond the |
58 |
baseline specification |
59 |
|
60 |
2.3 Issuing Commands |
61 |
-------------------- |
62 |
|
63 |
The format for command execution is: |
64 |
|
65 |
{ "execute": json-string, "arguments": json-object, "id": json-value } |
66 |
|
67 |
Where, |
68 |
|
69 |
- The "execute" member identifies the command to be executed by the Server |
70 |
- The "arguments" member is used to pass any arguments required for the |
71 |
execution of the command, it is optional when no arguments are required |
72 |
- The "id" member is a transaction identification associated with the |
73 |
command execution, it is optional and will be part of the response if |
74 |
provided |
75 |
|
76 |
2.4 Commands Responses |
77 |
---------------------- |
78 |
|
79 |
There are two possible responses which the Server will issue as the result |
80 |
of a command execution: success or error. |
81 |
|
82 |
2.4.1 success |
83 |
------------- |
84 |
|
85 |
The success response is issued when the command execution has finished |
86 |
without errors. |
87 |
|
88 |
The format is: |
89 |
|
90 |
{ "return": json-object, "id": json-value } |
91 |
|
92 |
Where, |
93 |
|
94 |
- The "return" member contains the command returned data, which is defined |
95 |
in a per-command basis or an empty json-object if the command does not |
96 |
return data |
97 |
- The "id" member contains the transaction identification associated |
98 |
with the command execution (if issued by the Client) |
99 |
|
100 |
2.4.2 error |
101 |
----------- |
102 |
|
103 |
The error response is issued when the command execution could not be |
104 |
completed because of an error condition. |
105 |
|
106 |
The format is: |
107 |
|
108 |
{ "error": { "class": json-string, "data": json-object, "desc": json-string }, |
109 |
"id": json-value } |
110 |
|
111 |
Where, |
112 |
|
113 |
- The "class" member contains the error class name (eg. "ServiceUnavailable") |
114 |
- The "data" member contains specific error data and is defined in a |
115 |
per-command basis, it will be an empty json-object if the error has no data |
116 |
- The "desc" member is a human-readable error message. Clients should |
117 |
not attempt to parse this message. |
118 |
- The "id" member contains the transaction identification associated with |
119 |
the command execution (if issued by the Client) |
120 |
|
121 |
NOTE: Some errors can occur before the Server is able to read the "id" member, |
122 |
in these cases the "id" member will not be part of the error response, even |
123 |
if provided by the client. |
124 |
|
125 |
2.5 Asynchronous events |
126 |
----------------------- |
127 |
|
128 |
As a result of state changes, the Server may send messages unilaterally |
129 |
to the Client at any time. They are called 'asynchronous events'. |
130 |
|
131 |
The format is: |
132 |
|
133 |
{ "event": json-string, "data": json-object, |
134 |
"timestamp": { "seconds": json-number, "microseconds": json-number } } |
135 |
|
136 |
Where, |
137 |
|
138 |
- The "event" member contains the event's name |
139 |
- The "data" member contains event specific data, which is defined in a |
140 |
per-event basis, it is optional |
141 |
- The "timestamp" member contains the exact time of when the event occurred |
142 |
in the Server. It is a fixed json-object with time in seconds and |
143 |
microseconds |
144 |
|
145 |
For a listing of supported asynchronous events, please, refer to the |
146 |
qmp-events.txt file. |
147 |
|
148 |
3. QMP Examples |
149 |
=============== |
150 |
|
151 |
This section provides some examples of real QMP usage, in all of them |
152 |
'C' stands for 'Client' and 'S' stands for 'Server'. |
153 |
|
154 |
3.1 Server greeting |
155 |
------------------- |
156 |
|
157 |
S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}} |
158 |
|
159 |
3.2 Simple 'stop' execution |
160 |
--------------------------- |
161 |
|
162 |
C: { "execute": "stop" } |
163 |
S: {"return": {}} |
164 |
|
165 |
3.3 KVM information |
166 |
------------------- |
167 |
|
168 |
C: { "execute": "query-kvm", "id": "example" } |
169 |
S: {"return": {"enabled": true, "present": true}, "id": "example"} |
170 |
|
171 |
3.4 Parsing error |
172 |
------------------ |
173 |
|
174 |
C: { "execute": } |
175 |
S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": |
176 |
{}}} |
177 |
|
178 |
3.5 Powerdown event |
179 |
------------------- |
180 |
|
181 |
S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": |
182 |
"POWERDOWN"} |
183 |
|
184 |
4. Compatibility Considerations |
185 |
-------------------------------- |
186 |
|
187 |
In order to achieve maximum compatibility between versions, Clients must not |
188 |
assume any particular: |
189 |
|
190 |
- Size of json-objects or length of json-arrays |
191 |
- Order of json-object members or json-array elements |
192 |
- Amount of errors generated by a command, that is, new errors can be added |
193 |
to any existing command in newer versions of the Server |
194 |
|
195 |
Additionally, Clients should always: |
196 |
|
197 |
- Check the capabilities json-array at connection time |
198 |
- Check the availability of commands with 'query-commands' before issuing them |
199 |
|
200 |
5. Recommendations to Client implementors |
201 |
----------------------------------------- |
202 |
|
203 |
5.1 The Server should be always started in pause mode, thus the Client is |
204 |
able to perform any setup procedure without the risk of race conditions |
205 |
and related problems |