OOB documentation is spread over qmp-spec.txt sections 2.2.1
Capabilities and 2.3 Issuing Commands. The amount of detail is a bit
distracting there. Move the meat of the matter to new section 2.3.1
Out of band execution.
Throw in a few other improvements while there:
* 2.2 Server Greeting: Drop advice to search entire capabilities
array; should be obvious.
* 3. QMP Examples
- 3.1 Server Greeting: Update greeting to the one we expect for the
release. Now shows capability "oob". Update qmp-intro.txt
likewise.
- 3.2 Capabilities negotiation: Show client accepting capability
"oob".
- 3.7 Out-of-band execution: New.
Signed-off-by: Markus Armbruster
Reviewed-by: Eric Blake
---
docs/interop/qmp-intro.txt | 13 +++
docs/interop/qmp-spec.txt | 74 +-
2 files changed, 56 insertions(+), 31 deletions(-)
diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
index 900d69d612..af2124e3ec 100644
--- a/docs/interop/qmp-intro.txt
+++ b/docs/interop/qmp-intro.txt
@@ -52,13 +52,14 @@ Escape character is '^]'.
"QMP": {
"version": {
"qemu": {
-"micro": 50,
-"minor": 6,
-"major": 1
-},
-"package": ""
-},
+"micro": 0,
+"minor": 0 ,
+"major": 3
+},
+"package": "v3.0.0"
+},
"capabilities": [
+"oob"
]
}
}
diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.txt
index 2bb492d1ea..6b72b69cb1 100644
--- a/docs/interop/qmp-spec.txt
+++ b/docs/interop/qmp-spec.txt
@@ -77,8 +77,7 @@ The greeting message format is:
is the same of the query-version command)
- The "capabilities" member specify the availability of features beyond the
baseline specification; the order of elements in this array has no
- particular significance, so a client must search the entire array
- when looking for a particular capability
+ particular significance.
2.2.1 Capabilities
--
@@ -86,16 +85,7 @@ The greeting message format is:
Currently supported capabilities are:
- "oob": the QMP server supports "out-of-band" (OOB) command
- execution. For more details, please see the "run-oob" parameter in
- the "Issuing Commands" section below. Not all commands allow this
- "oob" execution. The "query-qmp-schema" command can be used to
- inspect which commands support "oob" execution.
-
-QMP clients can get a list of supported QMP capabilities of the QMP
-server in the greeting message mentioned above. By default, all the
-capabilities are off. To enable any QMP capabilities, the QMP client
-needs to send the "qmp_capabilities" command with an extra parameter
-for the requested capabilities.
+ execution, as described in section "2.3.1 Out-of-band execution".
2.3 Issuing Commands
@@ -115,14 +105,38 @@ The format for command execution is:
- The "id" member is a transaction identification associated with the
command execution. It is required for all commands if the OOB -
capability was enabled at startup, and optional otherwise. The same
- "id" field will be part of the response if provided. The "id" member
- can be any json-value, although most clients merely use a
- json-number incremented for each successive command
-- The "control" member is optional, and currently only used for
- out-of-band execution. The handling or response of an "oob" command
- can overtake prior in-band commands. To enable "oob" handling of a
- particular command, just provide a control field with: { "control":
- { "run-oob": true } }
+ "id" field will be part of the response if provided. The "id"
+ member can be any json-value. A json-number incremented for each
+ successive command works fine.
+- The optional "control" member further specifies how the command is
+ to be executed. Currently, its only member is optional "run-oob".
+ See section "2.3.1 Out-of-band execution" for details.
+
+
+2.3.1 Out-of-band execution
+---
+
+The server normally reads, executes and responds to one command after
+the other. The client therefore receives command responses in issue
+order.
+
+With out-of-band execution enabled via capability negotiation (section
+4.), the server reads and queues commands as they arrive. It executes
+commands from the queue one after the other. Commands executed
+out-of-band jump the queue: the command get executed right away,
+possibly overtaking prior in-band commands. The client may therefore
+receive such a command's response before responses from prior in-band
+commands.
+
+To execute a command out-of-band, the client puts "run-oob": true into
+execute's member "control".
+
+If the client sends in-band commands faster than the server can
+execute them, the server will eventually drop commands to limit the
+queue length. The sever sends event
