QMP: spec: Capability negotiation updates

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>

1 files changed, 29 insertions, 17 deletions

diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index b2617bb2f..f3c032770 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