From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NaUen-0000PK-Bi for qemu-devel@nongnu.org; Thu, 28 Jan 2010 08:43:37 -0500 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NaUei-0000Mx-Hi for qemu-devel@nongnu.org; Thu, 28 Jan 2010 08:43:37 -0500 Received: from [199.232.76.173] (port=57180 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NaUei-0000Mn-1t for qemu-devel@nongnu.org; Thu, 28 Jan 2010 08:43:32 -0500 Received: from mx1.redhat.com ([209.132.183.28]:30783) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NaUeg-0003zn-KV for qemu-devel@nongnu.org; Thu, 28 Jan 2010 08:43:30 -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 o0SDhTP3000383 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Thu, 28 Jan 2010 08:43:29 -0500 Received: from localhost (vpn-10-249.rdu.redhat.com [10.11.10.249]) by int-mx04.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o0SDhSnT028319 for ; Thu, 28 Jan 2010 08:43:29 -0500 From: Luiz Capitulino Date: Thu, 28 Jan 2010 11:43:00 -0200 Message-Id: <1264686180-29845-9-git-send-email-lcapitulino@redhat.com> In-Reply-To: <1264686180-29845-1-git-send-email-lcapitulino@redhat.com> References: <1264686180-29845-1-git-send-email-lcapitulino@redhat.com> Subject: [Qemu-devel] [PATCH 8/8] QMP: spec: Feature negotiation related changes List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Signed-off-by: Luiz Capitulino --- QMP/qmp-spec.txt | 60 ++++++++++++++++++++++++++++++++++------------------- 1 files changed, 38 insertions(+), 22 deletions(-) diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt index 56f388c..5aea09d 100644 --- a/QMP/qmp-spec.txt +++ b/QMP/qmp-spec.txt @@ -39,14 +39,20 @@ they can be in ANY order, thus no particular order should be assumed. 2.1.2 All json-objects members are mandatory when not specified otherwise -2.2 Server Greeting -------------------- +2.2 Server Modes +---------------- -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. +The Server supports two modes of operation: handshake and operational. -The format is: +2.2.1 Handshake mode +-------------------- + +When a Client establishes a connection to the Server, the greeting message +is issued and the Server is in handshake mode. In this mode only a subset of +the Server's commands are available, most of them deals exclusively with +capabilities negotiation. + +The format of the greeting message is: { "QMP": { "capabilities": json-array } } @@ -55,6 +61,17 @@ The format is: - The "capabilities" member specify the availability of features beyond the baseline specification +Clients should use the handshake mode to enable protocol features they support. + +2.2.2 Operational mode +---------------------- + +In operational mode the full set of Server's commands are available, the only +exceptions are commands which deal exclusively with capabilities negotiation. + +Clients can switch from handshake mode to operational mode at any time, +section 3.6 contains an example. + 2.3 Issuing Commands -------------------- @@ -123,8 +140,9 @@ if provided by the client. 2.5 Asynchronous events ----------------------- -As a result of state changes, the Server may send messages unilaterally -to the Client at any time. They are called 'asynchronous events'. +When in operational mode, as a result of state changes, the Server may send +messages unilaterally to the Client at any time. Theses messages are called +'asynchronous events'. The format is: @@ -179,25 +197,23 @@ S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": "POWERDOWN"} +3.6 Mode switch +---------------- + +C: { "execute": "qmp_switch_mode", "arguments": { "mode": "operational" } } +S: {"return": {}} + 4. Compatibility Considerations -------------------------------- -In order to achieve maximum compatibility between versions, Clients must not -assume any particular: +All protocol changes or new features which modify the protocol format in an +incompatible way are disabled by default and will be listed in the capabilities +array (section 2.2.1). Thus, Clients can enable new features they support at +handshake mode. + +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 - -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