hw/arm/virt: pass VirtMachineState instead of VirtGuestInfo
[qemu.git] / docs / 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 document
24 "Client" is any application which is using QMP to communicate with QEMU and
25 "Server" is QEMU itself.
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/rfc7159.txt
36
37 The protocol is always encoded in UTF-8 except for synchronization
38 bytes (documented below); although thanks to json-string escape
39 sequences, the server will reply using only the strict ASCII subset.
40
41 For convenience, json-object members mentioned in this document will
42 be in a certain order. However, in real protocol usage they can be in
43 ANY order, thus no particular order should be assumed. On the other
44 hand, use of json-array elements presumes that preserving order is
45 important unless specifically documented otherwise.  Repeating a key
46 within a json-object gives unpredictable results.
47
48 Also for convenience, the server will accept an extension of
49 'single-quoted' strings in place of the usual "double-quoted"
50 json-string, and both input forms of strings understand an additional
51 escape sequence of "\'" for a single quote. The server will only use
52 double quoting on output.
53
54 2.1 General Definitions
55 -----------------------
56
57 2.1.1 All interactions transmitted by the Server are json-objects, always
58       terminating with CRLF
59
60 2.1.2 All json-objects members are mandatory when not specified otherwise
61
62 2.2 Server Greeting
63 -------------------
64
65 Right when connected the Server will issue a greeting message, which signals
66 that the connection has been successfully established and that the Server is
67 ready for capabilities negotiation (for more information refer to section
68 '4. Capabilities Negotiation').
69
70 The greeting message format is:
71
72 { "QMP": { "version": json-object, "capabilities": json-array } }
73
74  Where,
75
76 - The "version" member contains the Server's version information (the format
77   is the same of the query-version command)
78 - The "capabilities" member specify the availability of features beyond the
79   baseline specification; the order of elements in this array has no
80   particular significance, so a client must search the entire array
81   when looking for a particular capability
82
83 2.2.1 Capabilities
84 ------------------
85
86 As of the date this document was last revised, no server or client
87 capability strings have been defined.
88
89
90 2.3 Issuing Commands
91 --------------------
92
93 The format for command execution is:
94
95 { "execute": json-string, "arguments": json-object, "id": json-value }
96
97  Where,
98
99 - The "execute" member identifies the command to be executed by the Server
100 - The "arguments" member is used to pass any arguments required for the
101   execution of the command, it is optional when no arguments are
102   required. Each command documents what contents will be considered
103   valid when handling the json-argument
104 - The "id" member is a transaction identification associated with the
105   command execution, it is optional and will be part of the response if
106   provided. The "id" member can be any json-value, although most
107   clients merely use a json-number incremented for each successive
108   command
109
110 2.4 Commands Responses
111 ----------------------
112
113 There are two possible responses which the Server will issue as the result
114 of a command execution: success or error.
115
116 2.4.1 success
117 -------------
118
119 The format of a success response is:
120
121 { "return": json-value, "id": json-value }
122
123  Where,
124
125 - The "return" member contains the data returned by the command, which
126   is defined on a per-command basis (usually a json-object or
127   json-array of json-objects, but sometimes a json-number, json-string,
128   or json-array of json-strings); it is an empty json-object if the
129   command does not return data
130 - The "id" member contains the transaction identification associated
131   with the command execution if issued by the Client
132
133 2.4.2 error
134 -----------
135
136 The format of an error response is:
137
138 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
139
140  Where,
141
142 - The "class" member contains the error class name (eg. "GenericError")
143 - The "desc" member is a human-readable error message. Clients should
144   not attempt to parse this message.
145 - The "id" member contains the transaction identification associated with
146   the command execution if issued by the Client
147
148 NOTE: Some errors can occur before the Server is able to read the "id" member,
149 in these cases the "id" member will not be part of the error response, even
150 if provided by the client.
151
152 2.5 Asynchronous events
153 -----------------------
154
155 As a result of state changes, the Server may send messages unilaterally
156 to the Client at any time, when not in the middle of any other
157 response. They are called "asynchronous events".
158
159 The format of asynchronous events is:
160
161 { "event": json-string, "data": json-object,
162   "timestamp": { "seconds": json-number, "microseconds": json-number } }
163
164  Where,
165
166 - The "event" member contains the event's name
167 - The "data" member contains event specific data, which is defined in a
168   per-event basis, it is optional
169 - The "timestamp" member contains the exact time of when the event
170   occurred in the Server. It is a fixed json-object with time in
171   seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
172   there is a failure to retrieve host time, both members of the
173   timestamp will be set to -1.
174
175 For a listing of supported asynchronous events, please, refer to the
176 qmp-events.txt file.
177
178 Some events are rate-limited to at most one per second.  If additional
179 "similar" events arrive within one second, all but the last one are
180 dropped, and the last one is delayed.  "Similar" normally means same
181 event type.  See qmp-events.txt for details.
182
183 2.6 QGA Synchronization
184 -----------------------
185
186 When using QGA, an additional synchronization feature is built into
187 the protocol.  If the Client sends a raw 0xFF sentinel byte (not valid
188 JSON), then the Server will reset its state and discard all pending
189 data prior to the sentinel.  Conversely, if the Client makes use of
190 the 'guest-sync-delimited' command, the Server will send a raw 0xFF
191 sentinel byte prior to its response, to aid the Client in discarding
192 any data prior to the sentinel.
193
194
195 3. QMP Examples
196 ===============
197
198 This section provides some examples of real QMP usage, in all of them
199 "C" stands for "Client" and "S" stands for "Server".
200
201 3.1 Server greeting
202 -------------------
203
204 S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
205      "package": ""}, "capabilities": []}}
206
207 3.2 Client QMP negotiation
208 --------------------------
209 C: { "execute": "qmp_capabilities" }
210 S: { "return": {}}
211
212 3.3 Simple 'stop' execution
213 ---------------------------
214
215 C: { "execute": "stop" }
216 S: { "return": {} }
217
218 3.4 KVM information
219 -------------------
220
221 C: { "execute": "query-kvm", "id": "example" }
222 S: { "return": { "enabled": true, "present": true }, "id": "example"}
223
224 3.5 Parsing error
225 ------------------
226
227 C: { "execute": }
228 S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
229
230 3.6 Powerdown event
231 -------------------
232
233 S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
234     "event": "POWERDOWN" }
235
236 4. Capabilities Negotiation
237 ===========================
238
239 When a Client successfully establishes a connection, the Server is in
240 Capabilities Negotiation mode.
241
242 In this mode only the qmp_capabilities command is allowed to run, all
243 other commands will return the CommandNotFound error. Asynchronous
244 messages are not delivered either.
245
246 Clients should use the qmp_capabilities command to enable capabilities
247 advertised in the Server's greeting (section '2.2 Server Greeting') they
248 support.
249
250 When the qmp_capabilities command is issued, and if it does not return an
251 error, the Server enters in Command mode where capabilities changes take
252 effect, all commands (except qmp_capabilities) are allowed and asynchronous
253 messages are delivered.
254
255 5 Compatibility Considerations
256 ==============================
257
258 All protocol changes or new features which modify the protocol format in an
259 incompatible way are disabled by default and will be advertised by the
260 capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
261 that array and enable the capabilities they support.
262
263 The QMP Server performs a type check on the arguments to a command.  It
264 generates an error if a value does not have the expected type for its
265 key, or if it does not understand a key that the Client included.  The
266 strictness of the Server catches wrong assumptions of Clients about
267 the Server's schema.  Clients can assume that, when such validation
268 errors occur, they will be reported before the command generated any
269 side effect.
270
271 However, Clients must not assume any particular:
272
273 - Length of json-arrays
274 - Size of json-objects; in particular, future versions of QEMU may add
275   new keys and Clients should be able to ignore them.
276 - Order of json-object members or json-array elements
277 - Amount of errors generated by a command, that is, new errors can be added
278   to any existing command in newer versions of the Server
279
280 Any command or member name beginning with "x-" is deemed experimental,
281 and may be withdrawn or changed in an incompatible manner in a future
282 release.
283
284 Of course, the Server does guarantee to send valid JSON.  But apart from
285 this, a Client should be "conservative in what they send, and liberal in
286 what they accept".
287
288 6. Downstream extension of QMP
289 ==============================
290
291 We recommend that downstream consumers of QEMU do *not* modify QMP.
292 Management tools should be able to support both upstream and downstream
293 versions of QMP without special logic, and downstream extensions are
294 inherently at odds with that.
295
296 However, we recognize that it is sometimes impossible for downstreams to
297 avoid modifying QMP.  Both upstream and downstream need to take care to
298 preserve long-term compatibility and interoperability.
299
300 To help with that, QMP reserves JSON object member names beginning with
301 '__' (double underscore) for downstream use ("downstream names").  This
302 means upstream will never use any downstream names for its commands,
303 arguments, errors, asynchronous events, and so forth.
304
305 Any new names downstream wishes to add must begin with '__'.  To
306 ensure compatibility with other downstreams, it is strongly
307 recommended that you prefix your downstream names with '__RFQDN_' where
308 RFQDN is a valid, reverse fully qualified domain name which you
309 control.  For example, a qemu-kvm specific monitor command would be:
310
311     (qemu) __org.linux-kvm_enable_irqchip
312
313 Downstream must not change the server greeting (section 2.2) other than
314 to offer additional capabilities.  But see below for why even that is
315 discouraged.
316
317 Section '5 Compatibility Considerations' applies to downstream as well
318 as to upstream, obviously.  It follows that downstream must behave
319 exactly like upstream for any input not containing members with
320 downstream names ("downstream members"), except it may add members
321 with downstream names to its output.
322
323 Thus, a client should not be able to distinguish downstream from
324 upstream as long as it doesn't send input with downstream members, and
325 properly ignores any downstream members in the output it receives.
326
327 Advice on downstream modifications:
328
329 1. Introducing new commands is okay.  If you want to extend an existing
330    command, consider introducing a new one with the new behaviour
331    instead.
332
333 2. Introducing new asynchronous messages is okay.  If you want to extend
334    an existing message, consider adding a new one instead.
335
336 3. Introducing new errors for use in new commands is okay.  Adding new
337    errors to existing commands counts as extension, so 1. applies.
338
339 4. New capabilities are strongly discouraged.  Capabilities are for
340    evolving the basic protocol, and multiple diverging basic protocol
341    dialects are most undesirable.