From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Nd826-0000BN-1G for qemu-devel@nongnu.org; Thu, 04 Feb 2010 15:10:34 -0500 Received: from [199.232.76.173] (port=33049 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Nd825-0000Ar-EM for qemu-devel@nongnu.org; Thu, 04 Feb 2010 15:10:33 -0500 Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1Nd824-0008IB-3o for qemu-devel@nongnu.org; Thu, 04 Feb 2010 15:10:33 -0500 Received: from mx1.redhat.com ([209.132.183.28]:43176) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1Nd823-0008Ht-N3 for qemu-devel@nongnu.org; Thu, 04 Feb 2010 15:10:31 -0500 From: Luiz Capitulino Date: Thu, 4 Feb 2010 18:10:07 -0200 Message-Id: <1265314207-6323-5-git-send-email-lcapitulino@redhat.com> In-Reply-To: <1265314207-6323-1-git-send-email-lcapitulino@redhat.com> References: <1265314207-6323-1-git-send-email-lcapitulino@redhat.com> Subject: [Qemu-devel] [PATCH 4/4] QMP: spec: Capability negotiation updates List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: aliguori@us.ibm.com, armbru@redhat.com 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 -- 1.6.6