Signed-off-by: Luiz Capitulino <lcapitul...@redhat.com>
---
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
