diff options
Diffstat (limited to 'QMP')
| -rw-r--r-- | QMP/qmp-spec.txt | 60 |
1 files changed, 34 insertions, 26 deletions
diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt index 1cbd21cd45..56f388c3b3 100644 --- a/QMP/qmp-spec.txt +++ b/QMP/qmp-spec.txt @@ -1,4 +1,4 @@ - QEMU Monitor Protocol Draft Specification - Version 0.1 + QEMU Monitor Protocol Specification - Version 0.1 1. Introduction =============== @@ -27,9 +27,9 @@ the JSON standard: http://www.ietf.org/rfc/rfc4627.txt -For convenience, json-objects mentioned in this document will have its members -in a certain order. However, in real protocol usage json-objects members can -be in ANY order, thus no particular order should be assumed. +For convenience, json-object members and json-array elements 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. 2.1 General Definitions ----------------------- @@ -85,12 +85,13 @@ without errors. The format is: -{ "return": json-value, "id": json-value } +{ "return": json-object, "id": json-value } Where, - The "return" member contains the command returned data, which is defined - in a per-command basis or "OK" if the command does not return data + in a per-command basis or 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) @@ -102,7 +103,7 @@ completed because of an error condition. The format is: -{ "error": { "class": json-string, "data": json-value, "desc": json-string }, +{ "error": { "class": json-string, "data": json-object, "desc": json-string }, "id": json-value } Where, @@ -110,7 +111,7 @@ The format is: - The "class" member contains the error class name (eg. "ServiceUnavailable") - The "data" member contains specific error data and is defined in a per-command basis, it will be an empty json-object if the error has no data -- The "desc" member is a human-readable error message. Clients should +- 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) @@ -127,7 +128,7 @@ to the Client at any time. They are called 'asynchronous events'. The format is: -{ "event": json-string, "data": json-value, +{ "event": json-string, "data": json-object, "timestamp": { "seconds": json-number, "microseconds": json-number } } Where, @@ -135,7 +136,7 @@ The format is: - 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 ocurred +- 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 @@ -157,19 +158,20 @@ S: {"QMP": {"capabilities": []}} --------------------------- C: { "execute": "stop" } -S: {"return": "OK"} +S: {"return": {}} 3.3 KVM information ------------------- -C: {"execute": "query-kvm", "id": "example"} -S: {"return": "enabled", "id": "example"} +C: { "execute": "query-kvm", "id": "example" } +S: {"return": {"enabled": true, "present": true}, "id": "example"} 3.4 Parsing error ------------------ C: { "execute": } -S: {"error": {"class": "JSONParsing", "data": {}}} +S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": +{}}} 3.5 Powerdown event ------------------- @@ -177,19 +179,25 @@ S: {"error": {"class": "JSONParsing", "data": {}}} S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": "POWERDOWN"} -4. Notes to Client implementors -------------------------------- +4. Compatibility Considerations +-------------------------------- -4.1 It is recommended to always start the Server in pause mode, thus the - Client is able to perform any setup procedure without the risk of - race conditions and related problems +In order to achieve maximum compatibility between versions, Clients must not +assume any particular: -4.2 It is recommended to always check the capabilities json-array, issued - with the greeting message, at connection time +- Size of json-objects or length of json-arrays +- 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 -4.3 Json-objects or json-arrays mentioned in this document are not fixed - and no particular size or number of members/elements should be assumed. - New members/elements can be added at any time. +Additionally, Clients should always: -4.4 No particular order of json-objects members should be assumed, they - can change at any time +- Check the capabilities json-array at connection time +- Check the availability of commands with 'query-commands' before issuing them + +5. Recommendations to Client implementors +----------------------------------------- + +5.1 The Server should be always started in pause mode, thus the Client is + able to perform any setup procedure without the risk of race conditions + and related problems |