diff options
Diffstat (limited to 'qemu/docs/qmp/qmp-spec.txt')
| -rw-r--r-- | qemu/docs/qmp/qmp-spec.txt | 336 |
1 files changed, 0 insertions, 336 deletions
diff --git a/qemu/docs/qmp/qmp-spec.txt b/qemu/docs/qmp/qmp-spec.txt deleted file mode 100644 index 4c28cd943..000000000 --- a/qemu/docs/qmp/qmp-spec.txt +++ /dev/null @@ -1,336 +0,0 @@ - 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. |