QMP: Update spec file
- Remove "draft" status - Change default success response to be json-object - Change error and event data member to be a json-object - Update examples - Add new section "Compatibility Considerations" - Other fixes and clarifications Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
This commit is contained in:
parent
052f1b9be5
commit
940489824e
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue