meson: convert hw/vfio
[qemu.git] / docs / interop / qmp-spec.txt
1                       QEMU Machine Protocol Specification
2
3 0. About This Document
4 ======================
5
6 Copyright (C) 2009-2016 Red Hat, Inc.
7
8 This work is licensed under the terms of the GNU GPL, version 2 or
9 later. See the COPYING file in the top-level directory.
10
11 1. Introduction
12 ===============
13
14 This document specifies the QEMU Machine Protocol (QMP), a JSON-based
15 protocol which is available for applications to operate QEMU at the
16 machine-level.  It is also in use by the QEMU Guest Agent (QGA), which
17 is available for host applications to interact with the guest
18 operating system.
19
20 2. Protocol Specification
21 =========================
22
23 This section details the protocol format. For the purpose of this
24 document, "Server" is either QEMU or the QEMU Guest Agent, and
25 "Client" is any application communicating with it via QMP.
26
27 JSON data structures, when mentioned in this document, are always in the
28 following format:
29
30     json-DATA-STRUCTURE-NAME
31
32 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
33 by the JSON standard:
34
35 http://www.ietf.org/rfc/rfc8259.txt
36
37 The server expects its input to be encoded in UTF-8, and sends its
38 output encoded in ASCII.
39
40 For convenience, json-object members mentioned in this document will
41 be in a certain order. However, in real protocol usage they can be in
42 ANY order, thus no particular order should be assumed. On the other
43 hand, use of json-array elements presumes that preserving order is
44 important unless specifically documented otherwise.  Repeating a key
45 within a json-object gives unpredictable results.
46
47 Also for convenience, the server will accept an extension of
48 'single-quoted' strings in place of the usual "double-quoted"
49 json-string, and both input forms of strings understand an additional
50 escape sequence of "\'" for a single quote. The server will only use
51 double quoting on output.
52
53 2.1 General Definitions
54 -----------------------
55
56 2.1.1 All interactions transmitted by the Server are json-objects, always
57       terminating with CRLF
58
59 2.1.2 All json-objects members are mandatory when not specified otherwise
60
61 2.2 Server Greeting
62 -------------------
63
64 Right when connected the Server will issue a greeting message, which signals
65 that the connection has been successfully established and that the Server is
66 ready for capabilities negotiation (for more information refer to section
67 '4. Capabilities Negotiation').
68
69 The greeting message format is:
70
71 { "QMP": { "version": json-object, "capabilities": json-array } }
72
73  Where,
74
75 - The "version" member contains the Server's version information (the format
76   is the same of the query-version command)
77 - The "capabilities" member specify the availability of features beyond the
78   baseline specification; the order of elements in this array has no
79   particular significance.
80
81 2.2.1 Capabilities
82 ------------------
83
84 Currently supported capabilities are:
85
86 - "oob": the QMP server supports "out-of-band" (OOB) command
87   execution, as described in section "2.3.1 Out-of-band execution".
88
89 2.3 Issuing Commands
90 --------------------
91
92 The format for command execution is:
93
94 { "execute": json-string, "arguments": json-object, "id": json-value }
95
96 or
97
98 { "exec-oob": json-string, "arguments": json-object, "id": json-value }
99
100  Where,
101
102 - The "execute" or "exec-oob" member identifies the command to be
103   executed by the server.  The latter requests out-of-band execution.
104 - The "arguments" member is used to pass any arguments required for the
105   execution of the command, it is optional when no arguments are
106   required. Each command documents what contents will be considered
107   valid when handling the json-argument
108 - The "id" member is a transaction identification associated with the
109   command execution, it is optional and will be part of the response
110   if provided.  The "id" member can be any json-value.  A json-number
111   incremented for each successive command works fine.
112
113 2.3.1 Out-of-band execution
114 ---------------------------
115
116 The server normally reads, executes and responds to one command after
117 the other.  The client therefore receives command responses in issue
118 order.
119
120 With out-of-band execution enabled via capability negotiation (section
121 4.), the server reads and queues commands as they arrive.  It executes
122 commands from the queue one after the other.  Commands executed
123 out-of-band jump the queue: the command get executed right away,
124 possibly overtaking prior in-band commands.  The client may therefore
125 receive such a command's response before responses from prior in-band
126 commands.
127
128 To be able to match responses back to their commands, the client needs
129 to pass "id" with out-of-band commands.  Passing it with all commands
130 is recommended for clients that accept capability "oob".
131
132 If the client sends in-band commands faster than the server can
133 execute them, the server will stop reading the requests from the QMP
134 channel until the request queue length is reduced to an acceptable
135 range.
136
137 Only a few commands support out-of-band execution.  The ones that do
138 have "allow-oob": true in output of query-qmp-schema.
139
140 2.4 Commands Responses
141 ----------------------
142
143 There are two possible responses which the Server will issue as the result
144 of a command execution: success or error.
145
146 As long as the commands were issued with a proper "id" field, then the
147 same "id" field will be attached in the corresponding response message
148 so that requests and responses can match.  Clients should drop all the
149 responses that have an unknown "id" field.
150
151 2.4.1 success
152 -------------
153
154 The format of a success response is:
155
156 { "return": json-value, "id": json-value }
157
158  Where,
159
160 - The "return" member contains the data returned by the command, which
161   is defined on a per-command basis (usually a json-object or
162   json-array of json-objects, but sometimes a json-number, json-string,
163   or json-array of json-strings); it is an empty json-object if the
164   command does not return data
165 - The "id" member contains the transaction identification associated
166   with the command execution if issued by the Client
167
168 2.4.2 error
169 -----------
170
171 The format of an error response is:
172
173 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
174
175  Where,
176
177 - The "class" member contains the error class name (eg. "GenericError")
178 - The "desc" member is a human-readable error message. Clients should
179   not attempt to parse this message.
180 - The "id" member contains the transaction identification associated with
181   the command execution if issued by the Client
182
183 NOTE: Some errors can occur before the Server is able to read the "id" member,
184 in these cases the "id" member will not be part of the error response, even
185 if provided by the client.
186
187 2.5 Asynchronous events
188 -----------------------
189
190 As a result of state changes, the Server may send messages unilaterally
191 to the Client at any time, when not in the middle of any other
192 response. They are called "asynchronous events".
193
194 The format of asynchronous events is:
195
196 { "event": json-string, "data": json-object,
197   "timestamp": { "seconds": json-number, "microseconds": json-number } }
198
199  Where,
200
201 - The "event" member contains the event's name
202 - The "data" member contains event specific data, which is defined in a
203   per-event basis, it is optional
204 - The "timestamp" member contains the exact time of when the event
205   occurred in the Server. It is a fixed json-object with time in
206   seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
207   there is a failure to retrieve host time, both members of the
208   timestamp will be set to -1.
209
210 For a listing of supported asynchronous events, please, refer to the
211 qmp-events.txt file.
212
213 Some events are rate-limited to at most one per second.  If additional
214 "similar" events arrive within one second, all but the last one are
215 dropped, and the last one is delayed.  "Similar" normally means same
216 event type.  See qmp-events.txt for details.
217
218 2.6 Forcing the JSON parser into known-good state
219 -------------------------------------------------
220
221 Incomplete or invalid input can leave the server's JSON parser in a
222 state where it can't parse additional commands.  To get it back into
223 known-good state, the client should provoke a lexical error.
224
225 The cleanest way to do that is sending an ASCII control character
226 other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new
227 line).
228
229 Sadly, older versions of QEMU can fail to flag this as an error.  If a
230 client needs to deal with them, it should send a 0xFF byte.
231
232 2.7 QGA Synchronization
233 -----------------------
234
235 When a client connects to QGA over a transport lacking proper
236 connection semantics such as virtio-serial, QGA may have read partial
237 input from a previous client.  The client needs to force QGA's parser
238 into known-good state using the previous section's technique.
239 Moreover, the client may receive output a previous client didn't read.
240 To help with skipping that output, QGA provides the
241 'guest-sync-delimited' command.  Refer to its documentation for
242 details.
243
244
245 3. QMP Examples
246 ===============
247
248 This section provides some examples of real QMP usage, in all of them
249 "C" stands for "Client" and "S" stands for "Server".
250
251 3.1 Server greeting
252 -------------------
253
254 S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
255      "package": "v3.0.0"}, "capabilities": ["oob"] } }
256
257 3.2 Capabilities negotiation
258 ----------------------------
259
260 C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
261 S: { "return": {}}
262
263 3.3 Simple 'stop' execution
264 ---------------------------
265
266 C: { "execute": "stop" }
267 S: { "return": {} }
268
269 3.4 KVM information
270 -------------------
271
272 C: { "execute": "query-kvm", "id": "example" }
273 S: { "return": { "enabled": true, "present": true }, "id": "example"}
274
275 3.5 Parsing error
276 ------------------
277
278 C: { "execute": }
279 S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
280
281 3.6 Powerdown event
282 -------------------
283
284 S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
285     "event": "POWERDOWN" }
286
287 3.7 Out-of-band execution
288 -------------------------
289
290 C: { "exec-oob": "migrate-pause", "id": 42 }
291 S: { "id": 42,
292      "error": { "class": "GenericError",
293       "desc": "migrate-pause is currently only supported during postcopy-active state" } }
294
295
296 4. Capabilities Negotiation
297 ===========================
298
299 When a Client successfully establishes a connection, the Server is in
300 Capabilities Negotiation mode.
301
302 In this mode only the qmp_capabilities command is allowed to run, all
303 other commands will return the CommandNotFound error. Asynchronous
304 messages are not delivered either.
305
306 Clients should use the qmp_capabilities command to enable capabilities
307 advertised in the Server's greeting (section '2.2 Server Greeting') they
308 support.
309
310 When the qmp_capabilities command is issued, and if it does not return an
311 error, the Server enters in Command mode where capabilities changes take
312 effect, all commands (except qmp_capabilities) are allowed and asynchronous
313 messages are delivered.
314
315 5 Compatibility Considerations
316 ==============================
317
318 All protocol changes or new features which modify the protocol format in an
319 incompatible way are disabled by default and will be advertised by the
320 capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
321 that array and enable the capabilities they support.
322
323 The QMP Server performs a type check on the arguments to a command.  It
324 generates an error if a value does not have the expected type for its
325 key, or if it does not understand a key that the Client included.  The
326 strictness of the Server catches wrong assumptions of Clients about
327 the Server's schema.  Clients can assume that, when such validation
328 errors occur, they will be reported before the command generated any
329 side effect.
330
331 However, Clients must not assume any particular:
332
333 - Length of json-arrays
334 - Size of json-objects; in particular, future versions of QEMU may add
335   new keys and Clients should be able to ignore them.
336 - Order of json-object members or json-array elements
337 - Amount of errors generated by a command, that is, new errors can be added
338   to any existing command in newer versions of the Server
339
340 Any command or member name beginning with "x-" is deemed experimental,
341 and may be withdrawn or changed in an incompatible manner in a future
342 release.
343
344 Of course, the Server does guarantee to send valid JSON.  But apart from
345 this, a Client should be "conservative in what they send, and liberal in
346 what they accept".
347
348 6. Downstream extension of QMP
349 ==============================
350
351 We recommend that downstream consumers of QEMU do *not* modify QMP.
352 Management tools should be able to support both upstream and downstream
353 versions of QMP without special logic, and downstream extensions are
354 inherently at odds with that.
355
356 However, we recognize that it is sometimes impossible for downstreams to
357 avoid modifying QMP.  Both upstream and downstream need to take care to
358 preserve long-term compatibility and interoperability.
359
360 To help with that, QMP reserves JSON object member names beginning with
361 '__' (double underscore) for downstream use ("downstream names").  This
362 means upstream will never use any downstream names for its commands,
363 arguments, errors, asynchronous events, and so forth.
364
365 Any new names downstream wishes to add must begin with '__'.  To
366 ensure compatibility with other downstreams, it is strongly
367 recommended that you prefix your downstream names with '__RFQDN_' where
368 RFQDN is a valid, reverse fully qualified domain name which you
369 control.  For example, a qemu-kvm specific monitor command would be:
370
371     (qemu) __org.linux-kvm_enable_irqchip
372
373 Downstream must not change the server greeting (section 2.2) other than
374 to offer additional capabilities.  But see below for why even that is
375 discouraged.
376
377 Section '5 Compatibility Considerations' applies to downstream as well
378 as to upstream, obviously.  It follows that downstream must behave
379 exactly like upstream for any input not containing members with
380 downstream names ("downstream members"), except it may add members
381 with downstream names to its output.
382
383 Thus, a client should not be able to distinguish downstream from
384 upstream as long as it doesn't send input with downstream members, and
385 properly ignores any downstream members in the output it receives.
386
387 Advice on downstream modifications:
388
389 1. Introducing new commands is okay.  If you want to extend an existing
390    command, consider introducing a new one with the new behaviour
391    instead.
392
393 2. Introducing new asynchronous messages is okay.  If you want to extend
394    an existing message, consider adding a new one instead.
395
396 3. Introducing new errors for use in new commands is okay.  Adding new
397    errors to existing commands counts as extension, so 1. applies.
398
399 4. New capabilities are strongly discouraged.  Capabilities are for
400    evolving the basic protocol, and multiple diverging basic protocol
401    dialects are most undesirable.