2. Protocol Specification
=========================
-This section details the protocol format. For the purpose of this document
-"Client" is any application which is using QMP to communicate with QEMU and
-"Server" is QEMU itself.
+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:
Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
by the JSON standard:
-http://www.ietf.org/rfc/rfc7159.txt
+http://www.ietf.org/rfc/rfc8259.txt
-The protocol is always encoded in UTF-8 except for synchronization
-bytes (documented below); although thanks to json-string escape
-sequences, the server will reply using only the strict ASCII subset.
+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
is the same of the query-version command)
- The "capabilities" member specify the availability of features beyond the
baseline specification; the order of elements in this array has no
- particular significance, so a client must search the entire array
- when looking for a particular capability
+ particular significance.
2.2.1 Capabilities
------------------
Currently supported capabilities are:
-- "oob": the QMP server supports "Out-Of-Band" (OOB) command
- execution. For more details, please see the "run-oob" parameter in
- the "Issuing Commands" section below. Not all commands allow this
- "oob" execution. The "query-qmp-schema" command can be used to
- inspect which commands support "oob" execution.
-
-QMP clients can get a list of supported QMP capabilities of the QMP
-server in the greeting message mentioned above. By default, all the
-capabilities are off. To enable any QMP capabilities, the QMP client
-needs to send the "qmp_capabilities" command with an extra parameter
-for the requested capabilities.
+- "oob": the QMP server supports "out-of-band" (OOB) command
+ execution, as described in section "2.3.1 Out-of-band execution".
2.3 Issuing Commands
--------------------
The format for command execution is:
-{ "execute": json-string, "arguments": json-object, "id": json-value,
- "control": json-object }
+{ "execute": json-string, "arguments": json-object, "id": json-value }
+
+or
+
+{ "exec-oob": json-string, "arguments": json-object, "id": json-value }
Where,
-- The "execute" member identifies the command to be executed by the Server
+- 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 required for all commands if the OOB -
- capability was enabled at startup, and optional otherwise. The same
- "id" field will be part of the response if provided. The "id" member
- can be any json-value, although most clients merely use a
- json-number incremented for each successive command
-- The "control" member is optional, and currently only used for
- out-of-band execution. The handling or response of an "oob" command
- can overtake prior in-band commands. To enable "oob" handling of a
- particular command, just provide a control field with: { "control":
- { "run-oob": true } }
+ 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.
+
+2.3.1 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 capability negotiation (section
+4.), 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 the requests from the QMP
+channel until the request queue length is reduced to an acceptable
+range.
+
+Only a few commands support out-of-band execution. The ones that do
+have "allow-oob": true in output of query-qmp-schema.
2.4 Commands Responses
----------------------
dropped, and the last one is delayed. "Similar" normally means same
event type. See qmp-events.txt for details.
-2.6 QGA Synchronization
+2.6 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.
+
+2.7 QGA Synchronization
-----------------------
-When using QGA, an additional synchronization feature is built into
-the protocol. If the Client sends a raw 0xFF sentinel byte (not valid
-JSON), then the Server will reset its state and discard all pending
-data prior to the sentinel. Conversely, if the Client makes use of
-the 'guest-sync-delimited' command, the Server will send a raw 0xFF
-sentinel byte prior to its response, to aid the Client in discarding
-any data prior to the sentinel.
+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.
3. QMP Examples
3.1 Server greeting
-------------------
-S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
- "package": ""}, "capabilities": []}}
+S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
+ "package": "v3.0.0"}, "capabilities": ["oob"] } }
-3.2 Client QMP negotiation
---------------------------
-C: { "execute": "qmp_capabilities" }
+3.2 Capabilities negotiation
+----------------------------
+
+C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
S: { "return": {}}
3.3 Simple 'stop' execution
S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
"event": "POWERDOWN" }
+3.7 Out-of-band execution
+-------------------------
+
+C: { "exec-oob": "migrate-pause", "id": 42 }
+S: { "id": 42,
+ "error": { "class": "GenericError",
+ "desc": "migrate-pause is currently only supported during postcopy-active state" } }
+
+
4. Capabilities Negotiation
===========================
projects / qemu.git / blobdiff