[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v2 32/32] qapi: Polish command flags documentation i
From: |
Markus Armbruster |
Subject: |
[Qemu-devel] [PATCH v2 32/32] qapi: Polish command flags documentation in qapi-code-gen.txt |
Date: |
Tue, 3 Jul 2018 10:53:58 +0200 |
Signed-off-by: Markus Armbruster <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
---
docs/devel/qapi-code-gen.txt | 61 +++++++++++++++---------------------
1 file 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:
+See qmp-spec.txt for out-of-band execution syntax and semantics.
- => { "exec-oob": "migrate-recover",
- "arguments": { "uri": "tcp:192.168.1.200:12345" } }
- <= { "return": { } }
+Commands supporting out-of-band execution can still be executed
+in-band.
-Without it, even the commands that support out-of-band execution will
-still be run in-band.
+When a command is executed in-band, its handler runs in the main
+thread with the BQL held.
-Under normal QMP command execution, the following apply to each
-command:
+When a command is executed out-of-band, its handler runs in a
+dedicated monitor I/O thread with the BQL *not* held.
-- They are executed in order,
-- They run only in main thread of QEMU,
-- They run with the BQL held.
+An OOB-capable command handler must satisfy the following conditions:
-When a command is executed with OOB, the following changes occur:
-
-- They can be completed before a pending in-band command,
-- They run in a dedicated monitor thread,
-- They run with the BQL not held.
-
-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,
--
2.17.1
- [Qemu-devel] [PATCH v2 17/32] qmp: Don't let malformed in-band commands jump the queue, (continued)
- [Qemu-devel] [PATCH v2 17/32] qmp: Don't let malformed in-band commands jump the queue, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 27/32] qmp: Add some comments around null responses, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 24/32] qmp: Replace monitor_json_emitter{, raw}() by qmp_{queue, send}_response(), Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 07/32] qmp: Make "id" optional again even in "oob" monitors, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 12/32] qmp: Redo how the client requests out-of-band execution, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 31/32] monitor: Improve some comments, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 20/32] monitor: Peel off @mon_global wrapper, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 23/32] qmp: Use QDict * instead of QObject * for response objects, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 32/32] qapi: Polish command flags documentation in qapi-code-gen.txt,
Markus Armbruster <=
- [Qemu-devel] [PATCH v2 19/32] monitor: Rename use_io_thr to use_io_thread, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 30/32] qmp: Clean up capability negotiation after commit 02130314d8c, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 14/32] qmp: Always free QMPRequest with qmp_request_free(), Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 04/32] qmp: Document COMMAND_DROPPED design flaw, Markus Armbruster, 2018/07/03
- [Qemu-devel] [PATCH v2 21/32] qobject: New qdict_from_jsonf_nofail(), Markus Armbruster, 2018/07/03