From patchwork Thu Feb 4 14:24:44 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Capitulino X-Patchwork-Id: 44498 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 60D32B7D09 for ; Fri, 5 Feb 2010 01:35:38 +1100 (EST) Received: from localhost ([127.0.0.1]:39131 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Nd2nv-0001eN-G6 for incoming@patchwork.ozlabs.org; Thu, 04 Feb 2010 09:35:35 -0500 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Nd2dp-0001I2-TN for qemu-devel@nongnu.org; Thu, 04 Feb 2010 09:25:09 -0500 Received: from [199.232.76.173] (port=54686 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Nd2dn-0001FW-LN for qemu-devel@nongnu.org; Thu, 04 Feb 2010 09:25:07 -0500 Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1Nd2dk-0008Ij-Ji for qemu-devel@nongnu.org; Thu, 04 Feb 2010 09:25:07 -0500 Received: from mx1.redhat.com ([209.132.183.28]:50601) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1Nd2di-0008I0-LX for qemu-devel@nongnu.org; Thu, 04 Feb 2010 09:25:03 -0500 Received: from int-mx04.intmail.prod.int.phx2.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.17]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o14EP15X026543 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 4 Feb 2010 09:25:01 -0500 Received: from localhost (vpn-9-202.rdu.redhat.com [10.11.9.202]) by int-mx04.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o14EOxeu004849; Thu, 4 Feb 2010 09:25:00 -0500 From: Luiz Capitulino To: qemu-devel@nongnu.org Date: Thu, 4 Feb 2010 12:24:44 -0200 Message-Id: <1265293484-30677-5-git-send-email-lcapitulino@redhat.com> In-Reply-To: <1265293484-30677-1-git-send-email-lcapitulino@redhat.com> References: <1265293484-30677-1-git-send-email-lcapitulino@redhat.com> X-Scanned-By: MIMEDefang 2.67 on 10.5.11.17 X-detected-operating-system: by monty-python.gnu.org: Genre and OS details not recognized. Cc: aliguori@us.ibm.com, armbru@redhat.com Subject: [Qemu-devel] [PATCH 4/4] QMP: spec: Capability negotiation updates 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 Signed-off-by: Luiz Capitulino --- QMP/qmp-spec.txt | 46 +++++++++++++++++++++++++++++----------------- 1 files changed, 29 insertions(+), 17 deletions(-) diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt index b2617bb..f3c0327 100644 --- a/QMP/qmp-spec.txt +++ b/QMP/qmp-spec.txt @@ -44,7 +44,8 @@ they can be in ANY order, thus no particular order should be assumed. Right when connected the Server will issue a greeting message, which signals that the connection has been successfully established and that the Server is -waiting for commands. +ready for capabilities negotiation (for more information refer to section +'4. Capabilities Negotiation'). The format is: @@ -181,25 +182,36 @@ S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": "POWERDOWN"} -4. Compatibility Considerations --------------------------------- +4. Capabilities Negotiation +---------------------------- -In order to achieve maximum compatibility between versions, Clients must not -assume any particular: +When a Client successfully establishes a connection, the Server is in +Capabilities Negotiation mode. -- 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 +In this mode only the 'qmp_capabilities' command is allowed to run, all +other commands will return the CommandNotFound error. Asynchronous messages +are not delivered either. + +Clients should use the 'qmp_capabilities' command to enable capabilities +advertised in the Server's greeting (section '2.2 Server Greeting') they +support. -Additionally, Clients should always: +When the 'qmp_capabilities' command is issued, and if it does not return an +error, the Server enters in Command mode where capabilities changes take +effect, all commands (except 'qmp_capabilities') are allowed and asynchronous +messages are delivered. -- Check the capabilities json-array at connection time -- Check the availability of commands with 'query-commands' before issuing them +5 Compatibility Considerations +------------------------------ -5. Recommendations to Client implementors ------------------------------------------ +All protocol changes or new features which modify the protocol format in an +incompatible way are disabled by default and will be advertised by the +capabilities array (section '2.2 Server Greeting'). Thus, Clients can check +that array and enable the capabilities they support. -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 +Additionally, Clients must not assume any particular: + +- 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