+++ /dev/null
- QEMU Machine Protocol Specification
-
-0. About This Document
-======================
-
-Copyright (C) 2009-2015 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.
-
-2.5 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 field 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.
Code Review / kvmfornfv.git / blobdiff