docs/interop/qmp-spec.rst

2     Copyright (C) 2009-2016 Red Hat, Inc.
4     This work is licensed under the terms of the GNU GPL, version 2 or
5     later. See the COPYING file in the top-level directory.
12 The QEMU Machine Protocol (QMP) is a JSON-based
14 machine-level.  It is also in use by the QEMU Guest Agent (QGA), which
16 operating system. This page specifies the general format of
17 the protocol; details of the commands and data structures can
18 be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`.
25 This section details the protocol format. For the purpose of this
32     json-DATA-STRUCTURE-NAME
34 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
37 The server expects its input to be encoded in UTF-8, and sends its
40 For convenience, json-object members mentioned in this document will
43 hand, use of json-array elements presumes that preserving order is
45 within a json-object gives unpredictable results.
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
54 -------------------
56 All interactions transmitted by the Server are json-objects, always
59 All json-objects members are mandatory when not specified otherwise.
62 ---------------
73   { "QMP": { "version": json-object, "capabilities": json-array } }
77 - The ``version`` member contains the Server's version information (the format
78   is the same as for the query-version command).
79 - The ``capabilities`` member specifies the availability of features beyond the
80   baseline specification; the order of elements in this array has no
84 ------------
89   the QMP server supports "out-of-band" (OOB) command
90   execution, as described in section `Out-of-band execution`_.
93 ----------------
99   { "execute": json-string, "arguments": json-object, "id": json-value }
105   { "exec-oob": json-string, "arguments": json-object, "id": json-value }
109 - The ``execute`` or ``exec-oob`` member identifies the command to be
110   executed by the server.  The latter requests out-of-band execution.
111 - The ``arguments`` member is used to pass any arguments required for the
112   execution of the command, it is optional when no arguments are
114   valid when handling the json-argument.
115 - The ``id`` member is a transaction identification associated with the
116   command execution, it is optional and will be part of the response
117   if provided.  The ``id`` member can be any json-value.  A json-number
120 The actual commands are documented in the :doc:`qemu-qmp-ref`.
122 Out-of-band execution
123 ---------------------
129 With out-of-band execution enabled via `capabilities negotiation`_,
132 out-of-band jump the queue: the command get executed right away,
133 possibly overtaking prior in-band commands.  The client may therefore
134 receive such a command's response before responses from prior in-band
138 to pass ``id`` with out-of-band commands.  Passing it with all commands
141 If the client sends in-band commands faster than the server can
145 To ensure commands to be executed out-of-band get read and executed,
146 the client should have at most eight in-band commands in flight.
148 Only a few commands support out-of-band execution.  The ones that do
149 have ``"allow-oob": true`` in the output of ``query-qmp-schema``.
152 ------------------
155 of a command execution: success or error.
163 -------
165 The format of a success response is:
169   { "return": json-value, "id": json-value }
173 - The ``return`` member contains the data returned by the command, which
174   is defined on a per-command basis (usually a json-object or
175   json-array of json-objects, but sometimes a json-number, json-string,
176   or json-array of json-strings); it is an empty json-object if the
178 - The ``id`` member contains the transaction identification associated
182 -----
184 The format of an error response is:
188   { "error": { "class": json-string, "desc": json-string }, "id": json-value }
192 - The ``class`` member contains the error class name (eg. ``"GenericError"``).
193 - The ``desc`` member is a human-readable error message. Clients should
195 - The ``id`` member contains the transaction identification associated with
199 in these cases the ``id`` member will not be part of the error response, even
203 -------------------
205 As a result of state changes, the Server may send messages unilaterally
206 to the Client at any time, when not in the middle of any other
209 The format of asynchronous events is:
213   { "event": json-string, "data": json-object,
214     "timestamp": { "seconds": json-number, "microseconds": json-number } }
218 - The ``event`` member contains the event's name.
219 - The ``data`` member contains event specific data, which is defined in a
220   per-event basis. It is optional.
221 - The ``timestamp`` member contains the exact time of when the event
222   occurred in the Server. It is a fixed json-object with time in
224   there is a failure to retrieve host time, both members of the
225   timestamp will be set to -1.
227 The actual asynchronous events are documented in the :doc:`qemu-qmp-ref`.
229 Some events are rate-limited to at most one per second.  If additional
234 Forcing the JSON parser into known-good state
235 ---------------------------------------------
239 known-good state, the client should provoke a lexical error.
245 Sadly, older versions of QEMU can fail to flag this as an error.  If a
249 -------------------
252 connection semantics such as virtio-serial, QGA may have read partial
254 into known-good state using the previous section's technique.
257 ``guest-sync-delimited`` command.  Refer to its documentation for
264 This section provides some examples of real QMP usage, in all of them
265 ``->`` marks text sent by the Client and ``<-`` marks replies by the Server.
271   .. code-block:: QMP
273     <- { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
280   .. code-block:: QMP
282     -> { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
283     <- { "return": {}}
289   .. code-block:: QMP
291     -> { "execute": "stop" }
292     <- { "return": {} }
298   .. code-block:: QMP
300     -> { "execute": "query-kvm", "id": "example" }
301     <- { "return": { "enabled": true, "present": true }, "id": "example"}
307   .. code-block:: QMP
309     -> { "execute": }
310     <- { "error": { "class": "GenericError", "desc": "JSON parse error, expecting value" } }
316   .. code-block:: QMP
318     <- { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
323   Out-of-band execution
325   .. code-block:: QMP
327     -> { "exec-oob": "migrate-pause", "id": 42 }
328     <- { "id": 42,
330           "desc": "migrate-pause is currently only supported during postcopy-active state" } }
362 strictness of the Server catches wrong assumptions of Clients about
369 - Length of json-arrays
370 - Size of json-objects; in particular, future versions of QEMU may add
372 - Order of json-object members or json-array elements
373 - Amount of errors generated by a command, that is, new errors can be added
374   to any existing command in newer versions of the Server
376 Any command or member name beginning with ``x-`` is deemed experimental,
380 Of course, the Server does guarantee to send valid JSON.  But apart from
384 Downstream extension of QMP
387 We recommend that downstream consumers of QEMU do *not* modify QMP.
389 versions of QMP without special logic, and downstream extensions are
394 preserve long-term compatibility and interoperability.
405 control.  For example, a qemu-kvm specific monitor command would be:
409     (qemu) __org.linux-kvm_enable_irqchip