aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2018-07-03 10:53:58 +0200
committerMarkus Armbruster <armbru@redhat.com>2018-07-03 23:18:56 +0200
commit153d73f320f422ecb5807ac3a93547b9f819599b (patch)
treedc0b6e312320a5c27df7591461b7d7e7cc4ec162 /docs
parent774a6b67a409edf23a9b4b02da9ccbfc62e27cae (diff)
qapi: Polish command flags documentation in qapi-code-gen.txt
Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20180703085358.13941-33-armbru@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/devel/qapi-code-gen.txt61
1 files changed, 25 insertions, 36 deletions
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index f020f6bab2..8decd6f17d 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -624,60 +624,48 @@ its return value.
In rare cases, QAPI cannot express a type-safe representation of a
corresponding Client JSON Protocol command. You then have to suppress
generation of a marshalling function by including a key 'gen' with
-boolean value false, and instead write your own function. Please try
-to avoid adding new commands that rely on this, and instead use
-type-safe unions. For an example of this usage:
+boolean value false, and instead write your own function. For
+example:
{ 'command': 'netdev_add',
'data': {'type': 'str', 'id': 'str'},
'gen': false }
+Please try to avoid adding new commands that rely on this, and instead
+use type-safe unions.
+
Normally, the QAPI schema is used to describe synchronous exchanges,
where a response is expected. But in some cases, the action of a
command is expected to change state in a way that a successful
response is not possible (although the command will still return a
normal dictionary error on failure). When a successful reply is not
-possible, the command expression should include the optional key
+possible, the command expression includes the optional key
'success-response' with boolean value false. So far, only QGA makes
use of this member.
-A command can be declared to support out-of-band (OOB) execution. By
-default, commands do not support OOB. To declare a command that
-supports it, the schema includes an extra 'allow-oob' field. For
-example:
+Key 'allow-oob' declares whether the command supports out-of-band
+(OOB) execution. It defaults to false. For example:
{ 'command': 'migrate_recover',
'data': { 'uri': 'str' }, 'allow-oob': true }
-To execute a command with out-of-band priority, the client uses key
-"exec-oob" instead of "execute". Example:
-
- => { "exec-oob": "migrate-recover",
- "arguments": { "uri": "tcp:192.168.1.200:12345" } }
- <= { "return": { } }
-
-Without it, even the commands that support out-of-band execution will
-still be run in-band.
+See qmp-spec.txt for out-of-band execution syntax and semantics.
-Under normal QMP command execution, the following apply to each
-command:
+Commands supporting out-of-band execution can still be executed
+in-band.
-- They are executed in order,
-- They run only in main thread of QEMU,
-- They run with the BQL held.
+When a command is executed in-band, its handler runs in the main
+thread with the BQL held.
-When a command is executed with OOB, the following changes occur:
+When a command is executed out-of-band, its handler runs in a
+dedicated monitor I/O thread with the BQL *not* held.
-- They can be completed before a pending in-band command,
-- They run in a dedicated monitor thread,
-- They run with the BQL not held.
+An OOB-capable command handler must satisfy the following conditions:
-OOB command handlers must satisfy the following conditions:
-
-- It terminates quickly,
-- It does not invoke system calls that may block,
+- It terminates quickly.
+- It does not invoke system calls that may block.
- It does not access guest RAM that may block when userfaultfd is
- enabled for postcopy live migration,
+ enabled for postcopy live migration.
- It takes only "fast" locks, i.e. all critical sections protected by
any lock it takes also satisfy the conditions for OOB command
handler code.
@@ -686,17 +674,18 @@ The restrictions on locking limit access to shared state. Such access
requires synchronization, but OOB commands can't take the BQL or any
other "slow" lock.
-If in doubt, do not implement OOB execution support.
+When in doubt, do not implement OOB execution support.
-A command may use the optional 'allow-preconfig' key to permit its execution
-at early runtime configuration stage (preconfig runstate).
-If not specified then a command defaults to 'allow-preconfig': false.
+Key 'allow-preconfig' declares whether the command is available before
+the machine is built. It defaults to false. For example:
-An example of declaring a command that is enabled during preconfig:
{ 'command': 'qmp_capabilities',
'data': { '*enable': [ 'QMPCapability' ] },
'allow-preconfig': true }
+QMP is available before the machine is built only when QEMU was
+started with --preconfig.
+
=== Events ===
Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,