[Qemu-devel] [PATCH v2 16/25] qmp: update qmp-spec about async capability

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <address@hidden>
---
 docs/qmp-spec.txt | 48 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/docs/qmp-spec.txt b/docs/qmp-spec.txt
index f8b5356015..b45c0700b6 100644
--- a/docs/qmp-spec.txt
+++ b/docs/qmp-spec.txt
@@ -83,9 +83,41 @@ The greeting message format is:
 2.2.1 Capabilities
 ------------------
 
-As of the date this document was last revised, no server or client
-capability strings have been defined.
+The "capabilities" member of the greeting message and qmp_capabilities
+is a json-array of json-string of the following values:
 
+- "async"
+
+This capability indicates asynchronous commands support.
+
+An async command is a regular client message request with the "id"
+member mandatory (see 2.3), but the reply may be delivered
+asynchronously and out of order by the server if the client supports
+it too.
+
+If both the server and the client have the "async" capability, the
+client can make requests while previous async requests are being
+processed.
+
+If the client doesn't have the "async" capability, it may still call
+an async command, and make multiple outstanding calls. In this case,
+the commands are processed in order, so the replies will also be in
+order (this is sometime called 'pipelining'). The "id" member isn't
+mandatory in this case.
+
+The client should match the replies with the "id" member associated
+with the requests.
+
+When a client is disconnected, the pending commands are not
+necessarily canceled. But the future clients will not get replies from
+commands they didn't make (they might, however, receive side-effects
+events).
+
+Note that without "async" support, a client may still receive
+asynchronous messages (or events) from the server between the time a
+request is handled by the server and the reply is received. It must
+thus be prepared to handle dispatching both events and reply after
+sending a request.
 
 2.3 Issuing Commands
 --------------------
@@ -102,10 +134,11 @@ The format for command execution is:
   required. Each command documents what contents will be considered
   valid when handling the json-argument
 - The "id" member is a transaction identification associated with the
-  command execution, it is optional and will be part of the response if
-  provided. The "id" member can be any json-value, although most
+  command execution and will be part of the response if provided.
+  If "async" is negotiated (see 2.2.1), it is mandatory, optional
+  otherwise. The "id" member can be any json-value, although most
   clients merely use a json-number incremented for each successive
-  command
+  command.
 
 2.4 Commands Responses
 ----------------------
@@ -202,11 +235,12 @@ This section provides some examples of real QMP usage, in 
all of them
 -------------------
 
 S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
-     "package": ""}, "capabilities": []}}
+     "package": ""}, "capabilities": [ "async" ]}}
 
 3.2 Client QMP negotiation
 --------------------------
-C: { "execute": "qmp_capabilities" }
+C: { "execute": "qmp_capabilities",
+     "arguments": { "capabilities": [ "async" ] } }
 S: { "return": {}}
 
 3.3 Simple 'stop' execution
-- 
2.11.0.295.gd7dffce1c