QMP: spec: Capability negotiation updates
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
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 @@
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: {"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.
+
+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.
+
+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.
+
+5 Compatibility Considerations
+------------------------------
+
+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.
+
+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
