[Qemu-devel] [PATCH 8/8] QMP: spec: Feature negotiation related changes

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <address@hidden>
---
 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