docs/interop/qmp-spec.rst

2     Copyright (C) 2009-2016 Red Hat, Inc.
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
18 be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`.
29 JSON data structures, when mentioned in this document, are always in the
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
38 output encoded in ASCII.
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
43 hand, use of json-array elements presumes that preserving order is
45 within a json-object gives unpredictable results.
48 ``'single-quoted'`` strings in place of the usual ``"double-quoted"``
49 json-string, and both input forms of strings understand an additional
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
114   valid when handling the json-argument.
115 - The ``id`` member is a transaction identification associated with the
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 ---------------------
126 the other.  The client therefore receives command responses in issue
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 ------------------
158 same ``id`` field will be attached in the corresponding response message
163 -------
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 -----
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 -------------------
206 to the Client at any time, when not in the middle of any other
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
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 ---------------------------------------------
237 Incomplete or invalid input can leave the server's JSON parser in a
239 known-good state, the client should provoke a lexical error.
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" } }
336 When a Client successfully establishes a connection, the Server is in
339 In this mode only the ``qmp_capabilities`` command is allowed to run; all
344 advertised in the `Server Greeting`_ which they support.
354 All protocol changes or new features which modify the protocol format in an
356 capabilities array (in the `Server Greeting`_). Thus, Clients can check
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,
377 and may be withdrawn or changed in an incompatible manner in a future
381 this, a Client should be "conservative in what they send, and liberal in
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
423 properly ignores any downstream members in the output it receives.
434 3. Introducing new errors for use in new commands is okay.  Adding new