diff options
Diffstat (limited to 'docs/interop/qmp-spec.rst')
| -rw-r--r-- | docs/interop/qmp-spec.rst | 439 |
1 files changed, 439 insertions, 0 deletions
diff --git a/docs/interop/qmp-spec.rst b/docs/interop/qmp-spec.rst new file mode 100644 index 0000000..45d6c98 --- /dev/null +++ b/docs/interop/qmp-spec.rst @@ -0,0 +1,439 @@ +.. + Copyright (C) 2009-2016 Red Hat, Inc. + + This work is licensed under the terms of the GNU GPL, version 2 or + later. See the COPYING file in the top-level directory. + + +=================================== +QEMU Machine Protocol Specification +=================================== + +The QEMU Machine Protocol (QMP) is a JSON-based +protocol which is available for applications to operate QEMU at the +machine-level. It is also in use by the QEMU Guest Agent (QGA), which +is available for host applications to interact with the guest +operating system. This page specifies the general format of +the protocol; details of the commands and data structures can +be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`. + +.. contents:: + +Protocol Specification +====================== + +This section details the protocol format. For the purpose of this +document, "Server" is either QEMU or the QEMU Guest Agent, and +"Client" is any application communicating with it via QMP. + +JSON data structures, when mentioned in this document, are always in the +following format: + + json-DATA-STRUCTURE-NAME + +Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined +by the `JSON standard <http://www.ietf.org/rfc/rfc8259.txt>`_. + +The server expects its input to be encoded in UTF-8, and sends its +output encoded in ASCII. + +For convenience, json-object members mentioned in this document will +be in a certain order. However, in real protocol usage they can be in +ANY order, thus no particular order should be assumed. On the other +hand, use of json-array elements presumes that preserving order is +important unless specifically documented otherwise. Repeating a key +within a json-object gives unpredictable results. + +Also for convenience, the server will accept an extension of +``'single-quoted'`` strings in place of the usual ``"double-quoted"`` +json-string, and both input forms of strings understand an additional +escape sequence of ``\'`` for a single quote. The server will only use +double quoting on output. + +General Definitions +------------------- + +All interactions transmitted by the Server are json-objects, always +terminating with CRLF. + +All json-objects members are mandatory when not specified otherwise. + +Server Greeting +--------------- + +Right when connected the Server will issue a greeting message, which signals +that the connection has been successfully established and that the Server is +ready for capabilities negotiation (for more information refer to section +`Capabilities Negotiation`_). + +The greeting message format is: + +:: + + { "QMP": { "version": json-object, "capabilities": json-array } } + +Where: + +- The ``version`` member contains the Server's version information (the format + is the same as for the query-version command). +- The ``capabilities`` member specifies the availability of features beyond the + baseline specification; the order of elements in this array has no + particular significance. + +Capabilities +------------ + +Currently supported capabilities are: + +``oob`` + the QMP server supports "out-of-band" (OOB) command + execution, as described in section `Out-of-band execution`_. + +Issuing Commands +---------------- + +The format for command execution is: + +:: + + { "execute": json-string, "arguments": json-object, "id": json-value } + +or + +:: + + { "exec-oob": json-string, "arguments": json-object, "id": json-value } + +Where: + +- The ``execute`` or ``exec-oob`` member identifies the command to be + executed by the server. The latter requests out-of-band execution. +- The ``arguments`` member is used to pass any arguments required for the + execution of the command, it is optional when no arguments are + required. Each command documents what contents will be considered + valid when handling the json-argument. +- The ``id`` member is a transaction identification associated with the + command execution, it is optional and will be part of the response + if provided. The ``id`` member can be any json-value. A json-number + incremented for each successive command works fine. + +The actual commands are documented in the :doc:`qemu-qmp-ref`. + +Out-of-band execution +--------------------- + +The server normally reads, executes and responds to one command after +the other. The client therefore receives command responses in issue +order. + +With out-of-band execution enabled via `capabilities negotiation`_, +the server reads and queues commands as they arrive. It executes +commands from the queue one after the other. Commands executed +out-of-band jump the queue: the command get executed right away, +possibly overtaking prior in-band commands. The client may therefore +receive such a command's response before responses from prior in-band +commands. + +To be able to match responses back to their commands, the client needs +to pass ``id`` with out-of-band commands. Passing it with all commands +is recommended for clients that accept capability ``oob``. + +If the client sends in-band commands faster than the server can +execute them, the server will stop reading requests until the request +queue length is reduced to an acceptable range. + +To ensure commands to be executed out-of-band get read and executed, +the client should have at most eight in-band commands in flight. + +Only a few commands support out-of-band execution. The ones that do +have ``"allow-oob": true`` in the output of ``query-qmp-schema``. + +Commands Responses +------------------ + +There are two possible responses which the Server will issue as the result +of a command execution: success or error. + +As long as the commands were issued with a proper ``id`` field, then the +same ``id`` field will be attached in the corresponding response message +so that requests and responses can match. Clients should drop all the +responses that have an unknown ``id`` field. + +Success +------- + +The format of a success response is: + +:: + + { "return": json-value, "id": json-value } + +Where: + +- The ``return`` member contains the data returned by the command, which + is defined on a per-command basis (usually a json-object or + json-array of json-objects, but sometimes a json-number, json-string, + or json-array of json-strings); it is an empty json-object if the + command does not return data. +- The ``id`` member contains the transaction identification associated + with the command execution if issued by the Client. + +Error +----- + +The format of an error response is: + +:: + + { "error": { "class": json-string, "desc": json-string }, "id": json-value } + +Where: + +- The ``class`` member contains the error class name (eg. ``"GenericError"``). +- The ``desc`` member is a human-readable error message. Clients should + not attempt to parse this message. +- The ``id`` member contains the transaction identification associated with + the command execution if issued by the Client. + +NOTE: Some errors can occur before the Server is able to read the ``id`` member; +in these cases the ``id`` member will not be part of the error response, even +if provided by the client. + +Asynchronous events +------------------- + +As a result of state changes, the Server may send messages unilaterally +to the Client at any time, when not in the middle of any other +response. They are called "asynchronous events". + +The format of asynchronous events is: + +:: + + { "event": json-string, "data": json-object, + "timestamp": { "seconds": json-number, "microseconds": json-number } } + +Where: + +- The ``event`` member contains the event's name. +- The ``data`` member contains event specific data, which is defined in a + per-event basis. It is optional. +- The ``timestamp`` member contains the exact time of when the event + occurred in the Server. It is a fixed json-object with time in + seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if + there is a failure to retrieve host time, both members of the + timestamp will be set to -1. + +The actual asynchronous events are documented in the :doc:`qemu-qmp-ref`. + +Some events are rate-limited to at most one per second. If additional +"similar" events arrive within one second, all but the last one are +dropped, and the last one is delayed. "Similar" normally means same +event type. + +Forcing the JSON parser into known-good state +--------------------------------------------- + +Incomplete or invalid input can leave the server's JSON parser in a +state where it can't parse additional commands. To get it back into +known-good state, the client should provoke a lexical error. + +The cleanest way to do that is sending an ASCII control character +other than ``\t`` (horizontal tab), ``\r`` (carriage return), or +``\n`` (new line). + +Sadly, older versions of QEMU can fail to flag this as an error. If a +client needs to deal with them, it should send a 0xFF byte. + +QGA Synchronization +------------------- + +When a client connects to QGA over a transport lacking proper +connection semantics such as virtio-serial, QGA may have read partial +input from a previous client. The client needs to force QGA's parser +into known-good state using the previous section's technique. +Moreover, the client may receive output a previous client didn't read. +To help with skipping that output, QGA provides the +``guest-sync-delimited`` command. Refer to its documentation for +details. + + +QMP Examples +============ + +This section provides some examples of real QMP usage, in all of them +``->`` marks text sent by the Client and ``<-`` marks replies by the Server. + +.. admonition:: Example + + Server greeting + + .. code-block:: QMP + + <- { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3}, + "package": "v3.0.0"}, "capabilities": ["oob"] } } + +.. admonition:: Example + + Capabilities negotiation + + .. code-block:: QMP + + -> { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } } + <- { "return": {}} + +.. admonition:: Example + + Simple 'stop' execution + + .. code-block:: QMP + + -> { "execute": "stop" } + <- { "return": {} } + +.. admonition:: Example + + KVM information + + .. code-block:: QMP + + -> { "execute": "query-kvm", "id": "example" } + <- { "return": { "enabled": true, "present": true }, "id": "example"} + +.. admonition:: Example + + Parsing error + + .. code-block:: QMP + + -> { "execute": } + <- { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } } + +.. admonition:: Example + + Powerdown event + + .. code-block:: QMP + + <- { "timestamp": { "seconds": 1258551470, "microseconds": 802384 }, + "event": "POWERDOWN" } + +.. admonition:: Example + + Out-of-band execution + + .. code-block:: QMP + + -> { "exec-oob": "migrate-pause", "id": 42 } + <- { "id": 42, + "error": { "class": "GenericError", + "desc": "migrate-pause is currently only supported during postcopy-active state" } } + + +Capabilities Negotiation +======================== + +When a Client successfully establishes a connection, the Server is in +Capabilities Negotiation mode. + +In this mode only the ``qmp_capabilities`` command is allowed to run; all +other commands will return the ``CommandNotFound`` error. Asynchronous +messages are not delivered either. + +Clients should use the ``qmp_capabilities`` command to enable capabilities +advertised in the `Server Greeting`_ which they support. + +When the ``qmp_capabilities`` command is issued, and if it does not return an +error, the Server enters Command mode where capabilities changes take +effect, all commands (except ``qmp_capabilities``) are allowed and asynchronous +messages are delivered. + +Compatibility Considerations +============================ + +All protocol changes or new features which modify the protocol format in an +incompatible way are disabled by default and will be advertised by the +capabilities array (in the `Server Greeting`_). Thus, Clients can check +that array and enable the capabilities they support. + +The QMP Server performs a type check on the arguments to a command. It +generates an error if a value does not have the expected type for its +key, or if it does not understand a key that the Client included. The +strictness of the Server catches wrong assumptions of Clients about +the Server's schema. Clients can assume that, when such validation +errors occur, they will be reported before the command generated any +side effect. + +However, Clients must not assume any particular: + +- Length of json-arrays +- Size of json-objects; in particular, future versions of QEMU may add + new keys and Clients should be able to ignore them +- Order of json-object members or json-array elements +- Amount of errors generated by a command, that is, new errors can be added + to any existing command in newer versions of the Server + +Any command or member name beginning with ``x-`` is deemed experimental, +and may be withdrawn or changed in an incompatible manner in a future +release. + +Of course, the Server does guarantee to send valid JSON. But apart from +this, a Client should be "conservative in what they send, and liberal in +what they accept". + +Downstream extension of QMP +=========================== + +We recommend that downstream consumers of QEMU do *not* modify QMP. +Management tools should be able to support both upstream and downstream +versions of QMP without special logic, and downstream extensions are +inherently at odds with that. + +However, we recognize that it is sometimes impossible for downstreams to +avoid modifying QMP. Both upstream and downstream need to take care to +preserve long-term compatibility and interoperability. + +To help with that, QMP reserves JSON object member names beginning with +``__`` (double underscore) for downstream use ("downstream names"). This +means upstream will never use any downstream names for its commands, +arguments, errors, asynchronous events, and so forth. + +Any new names downstream wishes to add must begin with ``__``. To +ensure compatibility with other downstreams, it is strongly +recommended that you prefix your downstream names with ``__RFQDN_`` where +RFQDN is a valid, reverse fully qualified domain name which you +control. For example, a qemu-kvm specific monitor command would be: + +:: + + (qemu) __org.linux-kvm_enable_irqchip + +Downstream must not change the `server greeting`_ other than +to offer additional capabilities. But see below for why even that is +discouraged. + +The section `Compatibility Considerations`_ applies to downstream as well +as to upstream, obviously. It follows that downstream must behave +exactly like upstream for any input not containing members with +downstream names ("downstream members"), except it may add members +with downstream names to its output. + +Thus, a client should not be able to distinguish downstream from +upstream as long as it doesn't send input with downstream members, and +properly ignores any downstream members in the output it receives. + +Advice on downstream modifications: + +1. Introducing new commands is okay. If you want to extend an existing + command, consider introducing a new one with the new behaviour + instead. + +2. Introducing new asynchronous messages is okay. If you want to extend + an existing message, consider adding a new one instead. + +3. Introducing new errors for use in new commands is okay. Adding new + errors to existing commands counts as extension, so 1. applies. + +4. New capabilities are strongly discouraged. Capabilities are for + evolving the basic protocol, and multiple diverging basic protocol + dialects are most undesirable. |