Commit 4d8bb958fa0..231aaf3a821 integrated the contents of docs/qmp-events.txt into QAPI schema doc comments. It left dangling references to qmp-events.txt behind. Fix to point to the QEMU QMP reference manual generated from the QAPI schema. Add a similar reference for commands. Cc: Marc-André Lureau <marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200806081147.3123652-2-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
405 lines
15 KiB
Plaintext
405 lines
15 KiB
Plaintext
QEMU Machine Protocol Specification
|
|
|
|
0. About This Document
|
|
======================
|
|
|
|
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.
|
|
|
|
1. Introduction
|
|
===============
|
|
|
|
This document specifies the QEMU Machine Protocol (QMP), 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.
|
|
|
|
2. 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.
|
|
|
|
2.1 General Definitions
|
|
-----------------------
|
|
|
|
2.1.1 All interactions transmitted by the Server are json-objects, always
|
|
terminating with CRLF
|
|
|
|
2.1.2 All json-objects members are mandatory when not specified otherwise
|
|
|
|
2.2 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
|
|
'4. 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 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.
|
|
|
|
2.2.1 Capabilities
|
|
------------------
|
|
|
|
Currently supported capabilities are:
|
|
|
|
- "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 }
|
|
|
|
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 QEMU QMP reference manual
|
|
docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
|
|
|
|
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
|
|
----------------------
|
|
|
|
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.
|
|
|
|
2.4.1 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
|
|
|
|
2.4.2 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.
|
|
|
|
2.5 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 QEMU QMP
|
|
reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
|
|
|
|
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.
|
|
|
|
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 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
|
|
===============
|
|
|
|
This section provides some examples of real QMP usage, in all of them
|
|
"C" stands for "Client" and "S" stands for "Server".
|
|
|
|
3.1 Server greeting
|
|
-------------------
|
|
|
|
S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
|
|
"package": "v3.0.0"}, "capabilities": ["oob"] } }
|
|
|
|
3.2 Capabilities negotiation
|
|
----------------------------
|
|
|
|
C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
|
|
S: { "return": {}}
|
|
|
|
3.3 Simple 'stop' execution
|
|
---------------------------
|
|
|
|
C: { "execute": "stop" }
|
|
S: { "return": {} }
|
|
|
|
3.4 KVM information
|
|
-------------------
|
|
|
|
C: { "execute": "query-kvm", "id": "example" }
|
|
S: { "return": { "enabled": true, "present": true }, "id": "example"}
|
|
|
|
3.5 Parsing error
|
|
------------------
|
|
|
|
C: { "execute": }
|
|
S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
|
|
|
|
3.6 Powerdown event
|
|
-------------------
|
|
|
|
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
|
|
===========================
|
|
|
|
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's greeting (section '2.2 Server Greeting') they
|
|
support.
|
|
|
|
When the qmp_capabilities command is issued, and if it does not return an
|
|
error, the Server enters in Command mode where capabilities changes take
|
|
effect, all commands (except qmp_capabilities) are allowed and asynchronous
|
|
messages are delivered.
|
|
|
|
5 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 (section '2.2 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".
|
|
|
|
6. 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 (section 2.2) other than
|
|
to offer additional capabilities. But see below for why even that is
|
|
discouraged.
|
|
|
|
Section '5 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.
|