Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 273 lines (191 sloc) 9.436 kb
9404898 QMP: Update spec file
Luiz Capitulino authored
1 QEMU Monitor Protocol Specification - Version 0.1
f544d17 QMP: Introduce specification
Luiz Capitulino authored
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
9404898 QMP: Update spec file
Luiz Capitulino authored
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.
f544d17 QMP: Introduce specification
Luiz Capitulino authored
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
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
47 ready for capabilities negotiation (for more information refer to section
48 '4. Capabilities Negotiation').
f544d17 QMP: Introduce specification
Luiz Capitulino authored
49
50 The format is:
51
ca9567e QMP: Add QEMU's version to the greeting message
Luiz Capitulino authored
52 { "QMP": { "version": json-object, "capabilities": json-array } }
f544d17 QMP: Introduce specification
Luiz Capitulino authored
53
54 Where,
55
ca9567e QMP: Add QEMU's version to the greeting message
Luiz Capitulino authored
56 - The "version" member contains the Server's version information (the format
57 is the same of the 'query-version' command)
f544d17 QMP: Introduce specification
Luiz Capitulino authored
58 - The "capabilities" member specify the availability of features beyond the
59 baseline specification
60
61 2.3 Issuing Commands
62 --------------------
63
64 The format for command execution is:
65
66 { "execute": json-string, "arguments": json-object, "id": json-value }
67
68 Where,
69
70 - The "execute" member identifies the command to be executed by the Server
71 - The "arguments" member is used to pass any arguments required for the
72 execution of the command, it is optional when no arguments are required
73 - The "id" member is a transaction identification associated with the
74 command execution, it is optional and will be part of the response if
75 provided
76
77 2.4 Commands Responses
78 ----------------------
79
80 There are two possible responses which the Server will issue as the result
81 of a command execution: success or error.
82
83 2.4.1 success
84 -------------
85
86 The success response is issued when the command execution has finished
87 without errors.
88
89 The format is:
90
9404898 QMP: Update spec file
Luiz Capitulino authored
91 { "return": json-object, "id": json-value }
f544d17 QMP: Introduce specification
Luiz Capitulino authored
92
93 Where,
94
95 - The "return" member contains the command returned data, which is defined
9404898 QMP: Update spec file
Luiz Capitulino authored
96 in a per-command basis or an empty json-object if the command does not
97 return data
f544d17 QMP: Introduce specification
Luiz Capitulino authored
98 - The "id" member contains the transaction identification associated
99 with the command execution (if issued by the Client)
100
101 2.4.2 error
102 -----------
103
104 The error response is issued when the command execution could not be
105 completed because of an error condition.
106
107 The format is:
108
9404898 QMP: Update spec file
Luiz Capitulino authored
109 { "error": { "class": json-string, "data": json-object, "desc": json-string },
77e595e QMP: add human-readable description to error response
Markus Armbruster authored
110 "id": json-value }
f544d17 QMP: Introduce specification
Luiz Capitulino authored
111
112 Where,
113
114 - The "class" member contains the error class name (eg. "ServiceUnavailable")
115 - The "data" member contains specific error data and is defined in a
116 per-command basis, it will be an empty json-object if the error has no data
9404898 QMP: Update spec file
Luiz Capitulino authored
117 - The "desc" member is a human-readable error message. Clients should
77e595e QMP: add human-readable description to error response
Markus Armbruster authored
118 not attempt to parse this message.
f544d17 QMP: Introduce specification
Luiz Capitulino authored
119 - The "id" member contains the transaction identification associated with
120 the command execution (if issued by the Client)
121
122 NOTE: Some errors can occur before the Server is able to read the "id" member,
123 in these cases the "id" member will not be part of the error response, even
124 if provided by the client.
125
126 2.5 Asynchronous events
127 -----------------------
128
129 As a result of state changes, the Server may send messages unilaterally
130 to the Client at any time. They are called 'asynchronous events'.
131
132 The format is:
133
9404898 QMP: Update spec file
Luiz Capitulino authored
134 { "event": json-string, "data": json-object,
f544d17 QMP: Introduce specification
Luiz Capitulino authored
135 "timestamp": { "seconds": json-number, "microseconds": json-number } }
136
137 Where,
138
139 - The "event" member contains the event's name
140 - The "data" member contains event specific data, which is defined in a
141 per-event basis, it is optional
9404898 QMP: Update spec file
Luiz Capitulino authored
142 - The "timestamp" member contains the exact time of when the event occurred
f544d17 QMP: Introduce specification
Luiz Capitulino authored
143 in the Server. It is a fixed json-object with time in seconds and
144 microseconds
145
146 For a listing of supported asynchronous events, please, refer to the
147 qmp-events.txt file.
148
149 3. QMP Examples
150 ===============
151
152 This section provides some examples of real QMP usage, in all of them
153 'C' stands for 'Client' and 'S' stands for 'Server'.
154
155 3.1 Server greeting
156 -------------------
157
ca9567e QMP: Add QEMU's version to the greeting message
Luiz Capitulino authored
158 S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
f544d17 QMP: Introduce specification
Luiz Capitulino authored
159
160 3.2 Simple 'stop' execution
161 ---------------------------
162
163 C: { "execute": "stop" }
9404898 QMP: Update spec file
Luiz Capitulino authored
164 S: {"return": {}}
f544d17 QMP: Introduce specification
Luiz Capitulino authored
165
166 3.3 KVM information
167 -------------------
168
9404898 QMP: Update spec file
Luiz Capitulino authored
169 C: { "execute": "query-kvm", "id": "example" }
170 S: {"return": {"enabled": true, "present": true}, "id": "example"}
f544d17 QMP: Introduce specification
Luiz Capitulino authored
171
172 3.4 Parsing error
173 ------------------
174
175 C: { "execute": }
9404898 QMP: Update spec file
Luiz Capitulino authored
176 S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
177 {}}}
f544d17 QMP: Introduce specification
Luiz Capitulino authored
178
179 3.5 Powerdown event
180 -------------------
181
182 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
183 "POWERDOWN"}
184
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
185 4. Capabilities Negotiation
186 ----------------------------
f544d17 QMP: Introduce specification
Luiz Capitulino authored
187
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
188 When a Client successfully establishes a connection, the Server is in
189 Capabilities Negotiation mode.
f544d17 QMP: Introduce specification
Luiz Capitulino authored
190
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
191 In this mode only the 'qmp_capabilities' command is allowed to run, all
192 other commands will return the CommandNotFound error. Asynchronous messages
193 are not delivered either.
194
195 Clients should use the 'qmp_capabilities' command to enable capabilities
196 advertised in the Server's greeting (section '2.2 Server Greeting') they
197 support.
f544d17 QMP: Introduce specification
Luiz Capitulino authored
198
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
199 When the 'qmp_capabilities' command is issued, and if it does not return an
200 error, the Server enters in Command mode where capabilities changes take
201 effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
202 messages are delivered.
f544d17 QMP: Introduce specification
Luiz Capitulino authored
203
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
204 5 Compatibility Considerations
205 ------------------------------
9404898 QMP: Update spec file
Luiz Capitulino authored
206
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
207 All protocol changes or new features which modify the protocol format in an
208 incompatible way are disabled by default and will be advertised by the
209 capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
210 that array and enable the capabilities they support.
9404898 QMP: Update spec file
Luiz Capitulino authored
211
5307d7d QMP: spec: Capability negotiation updates
Luiz Capitulino authored
212 Additionally, Clients must not assume any particular:
213
214 - Size of json-objects or length of json-arrays
215 - Order of json-object members or json-array elements
216 - Amount of errors generated by a command, that is, new errors can be added
217 to any existing command in newer versions of the Server
b3e5e3e QMP: Add "Downstream extension of QMP" to spec
Markus Armbruster authored
218
219 6. Downstream extension of QMP
220 ------------------------------
221
222 We recommend that downstream consumers of QEMU do *not* modify QMP.
223 Management tools should be able to support both upstream and downstream
224 versions of QMP without special logic, and downstream extensions are
225 inherently at odds with that.
226
227 However, we recognize that it is sometimes impossible for downstreams to
228 avoid modifying QMP. Both upstream and downstream need to take care to
229 preserve long-term compatibility and interoperability.
230
231 To help with that, QMP reserves JSON object member names beginning with
232 '__' (double underscore) for downstream use ("downstream names"). This
233 means upstream will never use any downstream names for its commands,
234 arguments, errors, asynchronous events, and so forth.
235
236 Any new names downstream wishes to add must begin with '__'. To
237 ensure compatibility with other downstreams, it is strongly
238 recommended that you prefix your downstram names with '__RFQDN_' where
239 RFQDN is a valid, reverse fully qualified domain name which you
240 control. For example, a qemu-kvm specific monitor command would be:
241
242 (qemu) __org.linux-kvm_enable_irqchip
243
244 Downstream must not change the server greeting (section 2.2) other than
245 to offer additional capabilities. But see below for why even that is
246 discouraged.
247
248 Section '5 Compatibility Considerations' applies to downstream as well
249 as to upstream, obviously. It follows that downstream must behave
250 exactly like upstream for any input not containing members with
251 downstream names ("downstream members"), except it may add members
252 with downstream names to its output.
253
254 Thus, a client should not be able to distinguish downstream from
255 upstream as long as it doesn't send input with downstream members, and
256 properly ignores any downstream members in the output it receives.
257
258 Advice on downstream modifications:
259
260 1. Introducing new commands is okay. If you want to extend an existing
261 command, consider introducing a new one with the new behaviour
262 instead.
263
264 2. Introducing new asynchronous messages is okay. If you want to extend
265 an existing message, consider adding a new one instead.
266
267 3. Introducing new errors for use in new commands is okay. Adding new
268 errors to existing commands counts as extension, so 1. applies.
269
270 4. New capabilities are strongly discouraged. Capabilities are for
271 evolving the basic protocol, and multiple diverging basic protocol
272 dialects are most undesirable.
Something went wrong with that request. Please try again.