[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 5/7] QMP: Update spec file
From: |
Luiz Capitulino |
Subject: |
[Qemu-devel] [PATCH 5/7] QMP: Update spec file |
Date: |
Fri, 18 Dec 2009 13:25:03 -0200 |
- 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 <address@hidden>
---
QMP/qmp-spec.txt | 69 +++++++++++++++++++++++++++++++++--------------------
1 files changed, 43 insertions(+), 26 deletions(-)
diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index 1cbd21c..3d25156 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,34 @@ 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, the following
+changes are forbidden in newer versions of the Server:
-4.2 It is recommended to always check the capabilities json-array, issued
- with the greeting message, at connection time
+- Removal of commands
+- Removal of command arguments
+- Addition of extra mandatory arguments for commands
+- Modification of arguments types
+- Modification of arguments, commands, events or error names
+- Modification of arguments in replies, events or errors
-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.
+Likewise, Clients must not assume any particular:
-4.4 No particular order of json-objects members should be assumed, they
- can change at any 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
+
+Additionally, Clients should always:
+
+- 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
--
1.6.6.rc3
- [Qemu-devel] [FOR 0.12 0/7]: More QMP related fixes, Luiz Capitulino, 2009/12/18
- [Qemu-devel] [PATCH 1/7] QMP: Only handle converted commands, Luiz Capitulino, 2009/12/18
- [Qemu-devel] [PATCH 2/7] QMP: Return an empty dict by default, Luiz Capitulino, 2009/12/18
- [Qemu-devel] [PATCH 3/7] QMP: Assure that returned data is a QDict, Luiz Capitulino, 2009/12/18
- [Qemu-devel] [PATCH 4/7] QMP: Update README file, Luiz Capitulino, 2009/12/18
- [Qemu-devel] [PATCH 5/7] QMP: Update spec file,
Luiz Capitulino <=
- Re: [Qemu-devel] [PATCH 5/7] QMP: Update spec file, Luiz Capitulino, 2009/12/18
- Re: [Qemu-devel] [PATCH 5/7] QMP: Update spec file, Markus Armbruster, 2009/12/18
[Qemu-devel] [PATCH 6/7] monitor: Introduce 'M' argument type, Luiz Capitulino, 2009/12/18
[Qemu-devel] [PATCH 7/7] monitor: do_balloon(): Use 'M' argument type, Luiz Capitulino, 2009/12/18
Re: [Qemu-devel] [FOR 0.12 0/7]: More QMP related fixes, Markus Armbruster, 2009/12/18