This is for the future interoperability & management guide. It includes the QAPI docs, including the automatically generated ones, other socket protocols (vhost-user, VNC), and the qcow2 file format. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
342 lines
12 KiB
Plaintext
342 lines
12 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
|
|
"Client" is any application which is using QMP to communicate with QEMU and
|
|
"Server" is QEMU itself.
|
|
|
|
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/rfc7159.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.
|
|
|
|
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, so a client must search the entire array
|
|
when looking for a particular capability
|
|
|
|
2.2.1 Capabilities
|
|
------------------
|
|
|
|
As of the date this document was last revised, no server or client
|
|
capability strings have been defined.
|
|
|
|
|
|
2.3 Issuing Commands
|
|
--------------------
|
|
|
|
The format for command execution is:
|
|
|
|
{ "execute": json-string, "arguments": json-object, "id": json-value }
|
|
|
|
Where,
|
|
|
|
- The "execute" member identifies the command to be executed by the Server
|
|
- 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, although most
|
|
clients merely use a json-number incremented for each successive
|
|
command
|
|
|
|
2.4 Commands Responses
|
|
----------------------
|
|
|
|
There are two possible responses which the Server will issue as the result
|
|
of a command execution: success or error.
|
|
|
|
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.
|
|
|
|
For a listing of supported asynchronous events, please, refer to the
|
|
qmp-events.txt file.
|
|
|
|
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. See qmp-events.txt for details.
|
|
|
|
2.6 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.
|
|
|
|
|
|
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": 50, "minor": 6, "major": 1 },
|
|
"package": ""}, "capabilities": []}}
|
|
|
|
3.2 Client QMP negotiation
|
|
--------------------------
|
|
C: { "execute": "qmp_capabilities" }
|
|
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" }
|
|
|
|
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.
|