From patchwork Fri Dec 18 15:25:03 2009 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Capitulino X-Patchwork-Id: 41410 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 31621B6EEF for ; Sat, 19 Dec 2009 02:34:03 +1100 (EST) Received: from localhost ([127.0.0.1]:38976 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NLeq8-0004GX-00 for incoming@patchwork.ozlabs.org; Fri, 18 Dec 2009 10:34:00 -0500 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NLehu-00017T-GT for qemu-devel@nongnu.org; Fri, 18 Dec 2009 10:25:30 -0500 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NLehp-00012K-8f for qemu-devel@nongnu.org; Fri, 18 Dec 2009 10:25:29 -0500 Received: from [199.232.76.173] (port=57998 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NLeho-00012D-KG for qemu-devel@nongnu.org; Fri, 18 Dec 2009 10:25:24 -0500 Received: from mx1.redhat.com ([209.132.183.28]:11691) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NLeho-0006HI-4S for qemu-devel@nongnu.org; Fri, 18 Dec 2009 10:25:24 -0500 Received: from int-mx01.intmail.prod.int.phx2.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id nBIFPNLq024250 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 18 Dec 2009 10:25:23 -0500 Received: from localhost (vpn-10-146.rdu.redhat.com [10.11.10.146]) by int-mx01.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id nBIFPMOK023125; Fri, 18 Dec 2009 10:25:22 -0500 From: Luiz Capitulino To: qemu-devel@nongnu.org Date: Fri, 18 Dec 2009 13:25:03 -0200 Message-Id: <1261149905-7622-6-git-send-email-lcapitulino@redhat.com> In-Reply-To: <1261149905-7622-1-git-send-email-lcapitulino@redhat.com> References: <1261149905-7622-1-git-send-email-lcapitulino@redhat.com> X-Scanned-By: MIMEDefang 2.67 on 10.5.11.11 X-detected-operating-system: by monty-python.gnu.org: Genre and OS details not recognized. Cc: aliguori@us.ibm.com Subject: [Qemu-devel] [PATCH 5/7] QMP: Update spec file X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org - 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 --- 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