jcs.org
qemu with hax to log dma reads & writes
jcs.org/2018/11/12/vfio
docs/interop/qmp: Improve OOB documentation
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 <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20180703085358.13941-4-armbru@redhat.com>
[Whitespace tidied up]
+56
-31
+7
-6
docs/interop/qmp-intro.txt
+7
-6
docs/interop/qmp-intro.txt
+49
-25
docs/interop/qmp-spec.txt
+49
-25
docs/interop/qmp-spec.txt
···
77
77
is the same of the query-version command)
78
78
- The "capabilities" member specify the availability of features beyond the
79
79
baseline specification; the order of elements in this array has no
80
-
particular significance, so a client must search the entire array
81
-
when looking for a particular capability
80
+
particular significance.
82
81
83
82
2.2.1 Capabilities
84
83
------------------
···
86
85
Currently supported capabilities are:
87
86
88
87
- "oob": the QMP server supports "out-of-band" (OOB) command
89
-
execution. For more details, please see the "run-oob" parameter in
90
-
the "Issuing Commands" section below. Not all commands allow this
91
-
"oob" execution. The "query-qmp-schema" command can be used to
92
-
inspect which commands support "oob" execution.
93
-
94
-
QMP clients can get a list of supported QMP capabilities of the QMP
95
-
server in the greeting message mentioned above. By default, all the
96
-
capabilities are off. To enable any QMP capabilities, the QMP client
97
-
needs to send the "qmp_capabilities" command with an extra parameter
98
-
for the requested capabilities.
88
+
execution, as described in section "2.3.1 Out-of-band execution".
99
89
100
90
2.3 Issuing Commands
101
91
--------------------
···
115
105
- The "id" member is a transaction identification associated with the
116
106
command execution. It is required for all commands if the OOB -
117
107
capability was enabled at startup, and optional otherwise. The same
118
-
"id" field will be part of the response if provided. The "id" member
119
-
can be any json-value, although most clients merely use a
120
-
json-number incremented for each successive command
121
-
- The "control" member is optional, and currently only used for
122
-
out-of-band execution. The handling or response of an "oob" command
123
-
can overtake prior in-band commands. To enable "oob" handling of a
124
-
particular command, just provide a control field with: { "control":
125
-
{ "run-oob": true } }
108
+
"id" field will be part of the response if provided. The "id"
109
+
member can be any json-value. A json-number incremented for each
110
+
successive command works fine.
111
+
- The optional "control" member further specifies how the command is
112
+
to be executed. Currently, its only member is optional "run-oob".
113
+
See section "2.3.1 Out-of-band execution" for details.
114
+
115
+
116
+
2.3.1 Out-of-band execution
117
+
---------------------------
118
+
119
+
The server normally reads, executes and responds to one command after
120
+
the other. The client therefore receives command responses in issue
121
+
order.
122
+
123
+
With out-of-band execution enabled via capability negotiation (section
124
+
4.), the server reads and queues commands as they arrive. It executes
125
+
commands from the queue one after the other. Commands executed
126
+
out-of-band jump the queue: the command get executed right away,
127
+
possibly overtaking prior in-band commands. The client may therefore
128
+
receive such a command's response before responses from prior in-band
129
+
commands.
130
+
131
+
To execute a command out-of-band, the client puts "run-oob": true into
132
+
execute's member "control".
133
+
134
+
If the client sends in-band commands faster than the server can
135
+
execute them, the server will eventually drop commands to limit the
136
+
queue length. The sever sends event COMMAND_DROPPED then.
137
+
138
+
Only a few commands support out-of-band execution. The ones that do
139
+
have "allow-oob": true in output of query-qmp-schema.
126
140
127
141
2.4 Commands Responses
128
142
----------------------
···
223
237
3.1 Server greeting
224
238
-------------------
225
239
226
-
S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
227
-
"package": ""}, "capabilities": []}}
240
+
S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
241
+
"package": "v3.0.0"}, "capabilities": ["oob"] } }
242
+
243
+
3.2 Capabilities negotiation
244
+
----------------------------
228
245
229
-
3.2 Client QMP negotiation
230
-
--------------------------
231
-
C: { "execute": "qmp_capabilities" }
246
+
C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
232
247
S: { "return": {}}
233
248
234
249
3.3 Simple 'stop' execution
···
254
269
255
270
S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
256
271
"event": "POWERDOWN" }
272
+
273
+
3.7 Out-of-band execution
274
+
-------------------------
275
+
276
+
C: { "execute": "migrate-pause", "id": 42, "control": { "run-oob": true } }
277
+
S: { "id": 42,
278
+
"error": { "class": "GenericError",
279
+
"desc": "migrate-pause is currently only supported during postcopy-active state" } }
280
+
257
281
258
282
4. Capabilities Negotiation
259
283
===========================