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.
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,