diff options
author | Markus Armbruster <armbru@redhat.com> | 2018-07-03 10:53:58 +0200 |
---|---|---|
committer | Markus Armbruster <armbru@redhat.com> | 2018-07-03 23:18:56 +0200 |
commit | 153d73f320f422ecb5807ac3a93547b9f819599b (patch) | |
tree | dc0b6e312320a5c27df7591461b7d7e7cc4ec162 /docs/devel/qapi-code-gen.txt | |
parent | 774a6b67a409edf23a9b4b02da9ccbfc62e27cae (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/devel/qapi-code-gen.txt')
-rw-r--r-- | docs/devel/qapi-code-gen.txt | 61 |
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, |