OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

QMP: Update spec file

Browse Source 
- 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:
Luiz Capitulino 2009-12-18 13:25:03 -02:00 committed by Anthony Liguori
parent 052f1b9be5
commit 940489824e
1 changed files with 34 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
QMP/qmp-spec.txt
View File

@ -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