mirrors/qemu
0
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2024-11-25 03:43:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

qapi: Fix indent level on doc comments in json files

Browse Source 
The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.

Make the doc comments more strongly consistent about indentation
for multiline constructs like:

@arg: description line 1
      description line 2

Returns: line one
         line 2

so that there is always exactly one space after the colon, and
subsequent lines align with the first.

This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace).  This does mean that we end up with some
over-length lines.

Note that when the documentation for an argument fits on a single
line like this:

@arg: one line only

then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
Peter Maydell 2020-02-13 17:56:26 +00:00 committed by Markus Armbruster
parent f56275064e
commit 26ec4e53f2
20 changed files with 664 additions and 664 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

776
qapi/block-core.json
View File

File diff suppressed because it is too large Load Diff

14
qapi/block.json
View File

@ -190,12 +190,12 @@
#
# Ejects a device from a removable drive.
#
# @device: Block device name (deprecated, use @id instead)
# @device: Block device name (deprecated, use @id instead)
#
# @id: The name or QOM path of the guest device (since: 2.8)
# @id: The name or QOM path of the guest device (since: 2.8)
#
# @force: If true, eject regardless of whether the drive is locked.
# If not specified, the default value is false.
# @force: If true, eject regardless of whether the drive is locked.
# If not specified, the default value is false.
#
# Returns: Nothing on success
#
@ -254,7 +254,7 @@
# (Since 5.0)
#
# @writable: Whether clients should be able to write to the device via the
# NBD connection (default false).
# NBD connection (default false).
#
# @bitmap: Also export the dirty bitmap reachable from @device, so the
# NBD client can use NBD_OPT_SET_META_CONTEXT with
@ -281,10 +281,10 @@
# Potential additional modes to be added in the future:
#
# hide: Just hide export from new clients, leave existing connections as is.
# Remove export after all clients are disconnected.
# Remove export after all clients are disconnected.
#
# soft: Hide export from new clients, answer with ESHUTDOWN for all further
# requests from existing clients.
# requests from existing clients.
#
# Since: 2.12
##

8
qapi/char.json
View File

@ -262,11 +262,11 @@
# @tn3270: enable tn3270 protocol on server
# sockets (default: false) (Since: 2.10)
# @websocket: enable websocket protocol on server
# sockets (default: false) (Since: 3.1)
# sockets (default: false) (Since: 3.1)
# @reconnect: For a client socket, if a socket is disconnected,
# then attempt a reconnect after the given number of seconds.
# Setting this to zero disables this function. (default: 0)
# (Since: 2.2)
# then attempt a reconnect after the given number of seconds.
# Setting this to zero disables this function. (default: 0)
# (Since: 2.2)
#
# Since: 1.4
##

4
qapi/dump.json
View File

@ -38,8 +38,8 @@
# using gdb to process the core file.
#
# IMPORTANT: this option can make QEMU allocate several gigabytes
# of RAM. This can happen for a large guest, or a
# malicious guest pretending to be large.
# of RAM. This can happen for a large guest, or a
# malicious guest pretending to be large.
#
# Also, paging=true has the following limitations:
#

12
qapi/introspect.json
View File

@ -34,15 +34,15 @@
# alternate that includes the original type alongside something else.
#
# Returns: array of @SchemaInfo, where each element describes an
# entity in the ABI: command, event, type, ...
# entity in the ABI: command, event, type, ...
#
# The order of the various SchemaInfo is unspecified; however, all
# names are guaranteed to be unique (no name will be duplicated with
# different meta-types).
# The order of the various SchemaInfo is unspecified; however, all
# names are guaranteed to be unique (no name will be duplicated with
# different meta-types).
#
# Note: the QAPI schema is also used to help define *internal*
# interfaces, by defining QAPI types. These are not part of the QMP
# wire ABI, and therefore not returned by this command.
# interfaces, by defining QAPI types. These are not part of the QMP
# wire ABI, and therefore not returned by this command.
#
# Since: 2.5
##

32
qapi/job.json
View File

@ -214,28 +214,28 @@
#
# Information about a job.
#
# @id: The job identifier
# @id: The job identifier
#
# @type: The kind of job that is being performed
# @type: The kind of job that is being performed
#
# @status: Current job state/status
# @status: Current job state/status
#
# @current-progress: Progress made until now. The unit is arbitrary and the
# value can only meaningfully be used for the ratio of
# @current-progress to @total-progress. The value is
# monotonically increasing.
# @current-progress: Progress made until now. The unit is arbitrary and the
# value can only meaningfully be used for the ratio of
# @current-progress to @total-progress. The value is
# monotonically increasing.
#
# @total-progress: Estimated @current-progress value at the completion of
# the job. This value can arbitrarily change while the
# job is running, in both directions.
# @total-progress: Estimated @current-progress value at the completion of
# the job. This value can arbitrarily change while the
# job is running, in both directions.
#
# @error: If this field is present, the job failed; if it is
# still missing in the CONCLUDED state, this indicates
# successful completion.
# @error: If this field is present, the job failed; if it is
# still missing in the CONCLUDED state, this indicates
# successful completion.
#
# The value is a human-readable error message to describe
# the reason for the job failure. It should not be parsed
# by applications.
# The value is a human-readable error message to describe
# the reason for the job failure. It should not be parsed
# by applications.
#
# Since: 3.0
##

18
qapi/machine-target.json
View File

@ -40,13 +40,13 @@
# model details.
#
# Note: When a non-migration-safe CPU model is expanded in static mode, some
# features enabled by the CPU model may be omitted, because they can't be
# implemented by a static CPU model definition (e.g. cache info passthrough and
# PMU passthrough in x86). If you need an accurate representation of the
# features enabled by a non-migration-safe CPU model, use @full. If you need a
# static representation that will keep ABI compatibility even when changing QEMU
# version or machine-type, use @static (but keep in mind that some features may
# be omitted).
# features enabled by the CPU model may be omitted, because they can't be
# implemented by a static CPU model definition (e.g. cache info passthrough and
# PMU passthrough in x86). If you need an accurate representation of the
# features enabled by a non-migration-safe CPU model, use @full. If you need a
# static representation that will keep ABI compatibility even when changing QEMU
# version or machine-type, use @static (but keep in mind that some features may
# be omitted).
#
# Since: 2.8.0
##
@ -148,7 +148,7 @@
# with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
# on this architecture currently.
# on this architecture currently.
#
# Since: 2.8.0
##
@ -191,7 +191,7 @@
# with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
# on this architecture currently.
# on this architecture currently.
#
# Since: 2.8.0
##

12
qapi/machine.json
View File

@ -680,7 +680,7 @@
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @none: None (no memory side cache in this proximity domain,
# or cache write policy unknown)
# or cache write policy unknown)
#
# @write-back: Write Back (WB)
#
@ -706,7 +706,7 @@
# @level: the cache level described in this structure.
#
# @associativity: the cache associativity,
# none/direct-mapped/complex(complex cache indexing).
# none/direct-mapped/complex(complex cache indexing).
#
# @policy: the write policy, none/write-back/write-through.
#
@ -823,10 +823,10 @@
# @core-id: core number within die the CPU belongs to# @thread-id: thread number within core the CPU belongs to
#
# Note: currently there are 5 properties that could be present
# but management should be prepared to pass through other
# properties with device_add command to allow for future
# interface extension. This also requires the filed names to be kept in
# sync with the properties passed to -device/device_add.
# but management should be prepared to pass through other
# properties with device_add command to allow for future
# interface extension. This also requires the filed names to be kept in
# sync with the properties passed to -device/device_add.
#
# Since: 2.7
##

198
qapi/migration.json
View File

@ -28,22 +28,22 @@
# @normal-bytes: number of normal bytes sent (since 1.2)
#
# @dirty-pages-rate: number of pages dirtied by second by the
# guest (since 1.3)
# guest (since 1.3)
#
# @mbps: throughput in megabits/sec. (since 1.6)
#
# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
#
# @postcopy-requests: The number of page requests received from the destination
# (since 2.7)
# (since 2.7)
#
# @page-size: The number of bytes per page for the various page-based
# statistics (since 2.10)
# statistics (since 2.10)
#
# @multifd-bytes: The number of bytes sent through multifd (since 3.0)
#
# @pages-per-second: the number of memory pages transferred per second
# (Since 4.0)
# (Since 4.0)
#
# Since: 0.14.0
##
@ -131,7 +131,7 @@
# @pre-switchover: Paused before device serialisation. (since 2.11)
#
# @device: During device serialisation when pause-before-switchover is enabled
# (since 2.11)
# (since 2.11)
#
# @wait-unplug: wait for device unplug request by guest OS to be completed.
# (since 4.2)
@ -167,41 +167,41 @@
# status is 'active' or 'completed' (since 1.2)
#
# @total-time: total amount of milliseconds since migration started.
# If migration has ended, it returns the total migration
# time. (since 1.2)
# If migration has ended, it returns the total migration
# time. (since 1.2)
#
# @downtime: only present when migration finishes correctly
# total downtime in milliseconds for the guest.
# (since 1.3)
# total downtime in milliseconds for the guest.
# (since 1.3)
#
# @expected-downtime: only present while migration is active
# expected downtime in milliseconds for the guest in last walk
# of the dirty bitmap. (since 1.3)
# expected downtime in milliseconds for the guest in last walk
# of the dirty bitmap. (since 1.3)
#
# @setup-time: amount of setup time in milliseconds _before_ the
# iterations begin but _after_ the QMP command is issued. This is designed
# to provide an accounting of any activities (such as RDMA pinning) which
# may be expensive, but do not actually occur during the iterative
# migration rounds themselves. (since 1.6)
# iterations begin but _after_ the QMP command is issued. This is designed
# to provide an accounting of any activities (such as RDMA pinning) which
# may be expensive, but do not actually occur during the iterative
# migration rounds themselves. (since 1.6)
#
# @cpu-throttle-percentage: percentage of time guest cpus are being
# throttled during auto-converge. This is only present when auto-converge
# has started throttling guest cpus. (Since 2.7)
# throttled during auto-converge. This is only present when auto-converge
# has started throttling guest cpus. (Since 2.7)
#
# @error-desc: the human readable error description string, when
# @status is 'failed'. Clients should not attempt to parse the
# error strings. (Since 2.7)
#
# @postcopy-blocktime: total time when all vCPU were blocked during postcopy
# live migration. This is only present when the postcopy-blocktime
# migration capability is enabled. (Since 3.0)
# live migration. This is only present when the postcopy-blocktime
# migration capability is enabled. (Since 3.0)
#
# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
# only present when the postcopy-blocktime migration capability
# is enabled. (Since 3.0)
# only present when the postcopy-blocktime migration capability
# is enabled. (Since 3.0)
#
# @compression: migration compression statistics, only returned if compression
# feature is on and status is 'active' or 'completed' (Since 3.1)
# feature is on and status is 'active' or 'completed' (Since 3.1)
#
# @socket-address: Only used for tcp, to know what the real port is (Since 4.0)
#
@ -355,54 +355,54 @@
# loads, by sending compressed difference of the pages
#
# @rdma-pin-all: Controls whether or not the entire VM memory footprint is
# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
# Disabled by default. (since 2.0)
# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
# Disabled by default. (since 2.0)
#
# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
# essentially saves 1MB of zeroes per block on the wire. Enabling requires
# source and target VM to support this feature. To enable it is sufficient
# to enable the capability on the source VM. The feature is disabled by
# default. (since 1.6)
# essentially saves 1MB of zeroes per block on the wire. Enabling requires
# source and target VM to support this feature. To enable it is sufficient
# to enable the capability on the source VM. The feature is disabled by
# default. (since 1.6)
#
# @compress: Use multiple compression threads to accelerate live migration.
# This feature can help to reduce the migration traffic, by sending
# compressed pages. Please note that if compress and xbzrle are both
# on, compress only takes effect in the ram bulk stage, after that,
# it will be disabled and only xbzrle takes effect, this can help to
# minimize migration traffic. The feature is disabled by default.
# (since 2.4 )
# This feature can help to reduce the migration traffic, by sending
# compressed pages. Please note that if compress and xbzrle are both
# on, compress only takes effect in the ram bulk stage, after that,
# it will be disabled and only xbzrle takes effect, this can help to
# minimize migration traffic. The feature is disabled by default.
# (since 2.4 )
#
# @events: generate events for each migration state change
# (since 2.4 )
#
# @auto-converge: If enabled, QEMU will automatically throttle down the guest
# to speed up convergence of RAM migration. (since 1.6)
# to speed up convergence of RAM migration. (since 1.6)
#
# @postcopy-ram: Start executing on the migration target before all of RAM has
# been migrated, pulling the remaining pages along as needed. The
# capacity must have the same setting on both source and target
# or migration will not even start. NOTE: If the migration fails during
# postcopy the VM will fail. (since 2.6)
# been migrated, pulling the remaining pages along as needed. The
# capacity must have the same setting on both source and target
# or migration will not even start. NOTE: If the migration fails during
# postcopy the VM will fail. (since 2.6)
#
# @x-colo: If enabled, migration will never end, and the state of the VM on the
# primary side will be migrated continuously to the VM on secondary
# side, this process is called COarse-Grain LOck Stepping (COLO) for
# Non-stop Service. (since 2.8)
# primary side will be migrated continuously to the VM on secondary
# side, this process is called COarse-Grain LOck Stepping (COLO) for
# Non-stop Service. (since 2.8)
#
# @release-ram: if enabled, qemu will free the migrated ram pages on the source
# during postcopy-ram migration. (since 2.9)
# during postcopy-ram migration. (since 2.9)
#
# @block: If enabled, QEMU will also migrate the contents of all block
# devices. Default is disabled. A possible alternative uses
# mirror jobs to a builtin NBD server on the destination, which
# offers more flexibility.
# (Since 2.10)
# devices. Default is disabled. A possible alternative uses
# mirror jobs to a builtin NBD server on the destination, which
# offers more flexibility.
# (Since 2.10)
#
# @return-path: If enabled, migration will use the return path even
# for precopy. (since 2.10)
#
# @pause-before-switchover: Pause outgoing migration before serialising device
# state and before disabling block IO (since 2.11)
# state and before disabling block IO (since 2.11)
#
# @multifd: Use more than one fd for migration (since 4.0)
#
@ -410,11 +410,11 @@
# (since 2.12)
#
# @postcopy-blocktime: Calculate downtime for postcopy live migration
# (since 3.0)
# (since 3.0)
#
# @late-block-activate: If enabled, the destination will not activate block
# devices (and thus take locks) immediately at the end of migration.
# (since 3.0)
# devices (and thus take locks) immediately at the end of migration.
# (since 3.0)
#
# @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0)
#
@ -494,24 +494,24 @@
# Migration parameters enumeration
#
# @announce-initial: Initial delay (in milliseconds) before sending the first
# announce (Since 4.0)
# announce (Since 4.0)
#
# @announce-max: Maximum delay (in milliseconds) between packets in the
# announcement (Since 4.0)
# announcement (Since 4.0)
#
# @announce-rounds: Number of self-announce packets sent after migration
# (Since 4.0)
# (Since 4.0)
#
# @announce-step: Increase in delay (in milliseconds) between subsequent
# packets in the announcement (Since 4.0)
# packets in the announcement (Since 4.0)
#
# @compress-level: Set the compression level to be used in live migration,
# the compression level is an integer between 0 and 9, where 0 means
# no compression, 1 means the best compression speed, and 9 means best
# compression ratio which will consume more CPU.
# the compression level is an integer between 0 and 9, where 0 means
# no compression, 1 means the best compression speed, and 9 means best
# compression ratio which will consume more CPU.
#
# @compress-threads: Set compression thread count to be used in live migration,
# the compression thread count is an integer between 1 and 255.
# the compression thread count is an integer between 1 and 255.
#
# @compress-wait-thread: Controls behavior when all compression threads are
# currently busy. If true (default), wait for a free
@ -519,10 +519,10 @@
# send the page uncompressed. (Since 3.1)
#
# @decompress-threads: Set decompression thread count to be used in live
# migration, the decompression thread count is an integer between 1
# and 255. Usually, decompression is at least 4 times as fast as
# compression, so set the decompress-threads to the number about 1/4
# of compress-threads is adequate.
# migration, the decompression thread count is an integer between 1
# and 255. Usually, decompression is at least 4 times as fast as
# compression, so set the decompress-threads to the number about 1/4
# of compress-threads is adequate.
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
# when migration auto-converge is activated. The
@ -560,14 +560,14 @@
# downtime in milliseconds (Since 2.8)
#
# @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
# periodic mode. (Since 2.8)
# periodic mode. (Since 2.8)
#
# @block-incremental: Affects how much storage is migrated when the
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
#
# @multifd-channels: Number of channels used to migrate data in
# parallel. This is the same number that the
@ -580,8 +580,8 @@
# (Since 2.11)
#
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
#
# @max-cpu-throttle: maximum cpu throttle percentage.
# Defaults to 99. (Since 3.1)
@ -604,16 +604,16 @@
# @MigrateSetParameters:
#
# @announce-initial: Initial delay (in milliseconds) before sending the first
# announce (Since 4.0)
# announce (Since 4.0)
#
# @announce-max: Maximum delay (in milliseconds) between packets in the
# announcement (Since 4.0)
# announcement (Since 4.0)
#
# @announce-rounds: Number of self-announce packets sent after migration
# (Since 4.0)
# (Since 4.0)
#
# @announce-step: Increase in delay (in milliseconds) between subsequent
# packets in the announcement (Since 4.0)
# packets in the announcement (Since 4.0)
#
# @compress-level: compression level
#
@ -665,11 +665,11 @@
# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
#
# @block-incremental: Affects how much storage is migrated when the
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
#
# @multifd-channels: Number of channels used to migrate data in
# parallel. This is the same number that the
@ -682,8 +682,8 @@
# (Since 2.11)
#
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
#
# @max-cpu-throttle: maximum cpu throttle percentage.
# The default value is 99. (Since 3.1)
@ -737,16 +737,16 @@
# The optional members aren't actually optional.
#
# @announce-initial: Initial delay (in milliseconds) before sending the
# first announce (Since 4.0)
# first announce (Since 4.0)
#
# @announce-max: Maximum delay (in milliseconds) between packets in the
# announcement (Since 4.0)
# announcement (Since 4.0)
#
# @announce-rounds: Number of self-announce packets sent after migration
# (Since 4.0)
# (Since 4.0)
#
# @announce-step: Increase in delay (in milliseconds) between subsequent
# packets in the announcement (Since 4.0)
# packets in the announcement (Since 4.0)
#
# @compress-level: compression level
#
@ -799,11 +799,11 @@
# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
#
# @block-incremental: Affects how much storage is migrated when the
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
#
# @multifd-channels: Number of channels used to migrate data in
# parallel. This is the same number that the
@ -816,12 +816,12 @@
# (Since 2.11)
#
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
#
# @max-cpu-throttle: maximum cpu throttle percentage.
# Defaults to 99.
# (Since 3.1)
# (Since 3.1)
#
# Since: 2.4
##
@ -1047,8 +1047,8 @@
# The reason for a COLO exit.
#
# @none: failover has never happened. This state does not occur
# in the COLO_EXIT event, and is only visible in the result of
# query-colo-status.
# in the COLO_EXIT event, and is only visible in the result of
# query-colo-status.
#
# @request: COLO exit is due to an external request.
#
@ -1281,11 +1281,11 @@
# of the VM are not saved by this command.
#
# @filename: the file to save the state of the devices to as binary
# data. See xen-save-devices-state.txt for a description of the binary
# format.
# data. See xen-save-devices-state.txt for a description of the binary
# format.
#
# @live: Optional argument to ask QEMU to treat this command as part of a live
# migration. Default to true. (since 2.11)
# migration. Default to true. (since 2.11)
#
# Returns: Nothing on success
#

8
qapi/misc-target.json
View File

@ -230,14 +230,14 @@
# QEMU/KVM software version, but also decided by the hardware that
# the program is running upon.
#
# @version: version of GIC to be described. Currently, only 2 and 3
# are supported.
# @version: version of GIC to be described. Currently, only 2 and 3
# are supported.
#
# @emulated: whether current QEMU/hardware supports emulated GIC
# device in user space.
#
# @kernel: whether current QEMU/hardware supports hardware
# accelerated GIC device in kernel.
# @kernel: whether current QEMU/hardware supports hardware
# accelerated GIC device in kernel.
#
# Since: 2.6
##

102
qapi/misc.json
View File

@ -14,11 +14,11 @@
#
# Arguments:
#
# @enable: An optional list of QMPCapability values to enable. The
# client must not enable any capability that is not
# mentioned in the QMP greeting message. If the field is not
# provided, it means no QMP capabilities will be enabled.
# (since 2.12)
# @enable: An optional list of QMPCapability values to enable. The
# client must not enable any capability that is not
# mentioned in the QMP greeting message. If the field is not
# provided, it means no QMP capabilities will be enabled.
# (since 2.12)
#
# Example:
#
@ -27,11 +27,11 @@
# <- { "return": {} }
#
# Notes: This command is valid exactly when first connecting: it must be
# issued before any other command will be accepted, and will fail once the
# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
# issued before any other command will be accepted, and will fail once the
# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
#
# The QMP client needs to explicitly enable QMP capabilities, otherwise
# all the QMP capabilities will be turned off by default.
# The QMP client needs to explicitly enable QMP capabilities, otherwise
# all the QMP capabilities will be turned off by default.
#
# Since: 0.13
#
@ -46,8 +46,8 @@
# Enumeration of capabilities to be advertised during initial client
# connection, used for agreeing on particular QMP extension behaviors.
#
# @oob: QMP ability to support out-of-band requests.
# (Please refer to qmp-spec.txt for more information on OOB)
# @oob: QMP ability to support out-of-band requests.
# (Please refer to qmp-spec.txt for more information on OOB)
#
# Since: 2.12
#
@ -60,11 +60,11 @@
#
# A three-part version number.
#
# @major: The major version number.
# @major: The major version number.
#
# @minor: The minor version number.
# @minor: The minor version number.
#
# @micro: The micro version number.
# @micro: The micro version number.
#
# Since: 2.4
##
@ -77,16 +77,16 @@
#
# A description of QEMU's version.
#
# @qemu: The version of QEMU. By current convention, a micro
# version of 50 signifies a development branch. A micro version
# greater than or equal to 90 signifies a release candidate for
# the next minor version. A micro version of less than 50
# signifies a stable release.
# @qemu: The version of QEMU. By current convention, a micro
# version of 50 signifies a development branch. A micro version
# greater than or equal to 90 signifies a release candidate for
# the next minor version. A micro version of less than 50
# signifies a stable release.
#
# @package: QEMU will always set this field to an empty string. Downstream
# versions of QEMU should set this to a non-empty string. The
# exact format depends on the downstream however it highly
# recommended that a unique name is used.
# @package: QEMU will always set this field to an empty string. Downstream
# versions of QEMU should set this to a non-empty string. The
# exact format depends on the downstream however it highly
# recommended that a unique name is used.
#
# Since: 0.14.0
##
@ -98,7 +98,7 @@
#
# Returns the current version of QEMU.
#
# Returns: A @VersionInfo object describing the current version of QEMU.
# Returns: A @VersionInfo object describing the current version of QEMU.
#
# Since: 0.14.0
#
@ -333,7 +333,7 @@
# Since: 1.2.0
#
# Note: This command is deprecated, because its output doesn't reflect
# compile-time configuration. Use query-qmp-schema instead.
# compile-time configuration. Use query-qmp-schema instead.
#
# Example:
#
@ -387,8 +387,8 @@
# Returns a list of information about each iothread.
#
# Note: this list excludes the QEMU main loop thread, which is not declared
# using the -object iothread command-line option. It is always the main thread
# of the process.
# using the -object iothread command-line option. It is always the main thread
# of the process.
#
# Returns: a list of @IOThreadInfo for each iothread
#
@ -636,9 +636,9 @@
# Return information about the PCI bus topology of the guest.
#
# Returns: a list of @PciInfo for each PCI bus. Each bus is
# represented by a json-object, which has a key with a json-array of
# all PCI devices attached to it. Each device is represented by a
# json-object.
# represented by a json-object, which has a key with a json-array of
# all PCI devices attached to it. Each device is represented by a
# json-object.
#
# Since: 0.14.0
#
@ -800,10 +800,10 @@
#
# Since: 0.14.0
#
# Notes: This function will succeed even if the guest is already in the stopped
# state. In "inmigrate" state, it will ensure that the guest
# remains paused once migration finishes, as if the -S option was
# passed on the command line.
# Notes: This function will succeed even if the guest is already in the stopped
# state. In "inmigrate" state, it will ensure that the guest
# remains paused once migration finishes, as if the -S option was
# passed on the command line.
#
# Example:
#
@ -859,7 +859,7 @@
# @filename: the file to save the memory to as binary data
#
# @cpu-index: the index of the virtual CPU to use for translating the
# virtual address (defaults to CPU 0)
# virtual address (defaults to CPU 0)
#
# Returns: Nothing on success
#
@ -917,11 +917,11 @@
#
# Returns: If successful, nothing
#
# Notes: This command will succeed if the guest is currently running. It
# will also succeed if the guest is in the "inmigrate" state; in
# this case, the effect of the command is to make sure the guest
# starts once migration finishes, removing the effect of the -S
# command line option if it was passed.
# Notes: This command will succeed if the guest is currently running. It
# will also succeed if the guest is in the "inmigrate" state; in
# this case, the effect of the command is to make sure the guest
# starts once migration finishes, removing the effect of the -S
# command line option if it was passed.
#
# Example:
#
@ -967,7 +967,7 @@
# Returns: nothing.
#
# Note: prior to 4.0, this command does nothing in case the guest
# isn't suspended.
# isn't suspended.
#
# Example:
#
@ -1081,18 +1081,18 @@
# change password command. Otherwise, this specifies a new server URI
# address to listen to for VNC connections.
#
# @arg: If @device is a block device, then this is an optional format to open
# the device with.
# If @device is 'vnc' and @target is 'password', this is the new VNC
# password to set. See change-vnc-password for additional notes.
# @arg: If @device is a block device, then this is an optional format to open
# the device with.
# If @device is 'vnc' and @target is 'password', this is the new VNC
# password to set. See change-vnc-password for additional notes.
#
# Returns: Nothing on success.
# If @device is not a valid block device, DeviceNotFound
#
# Notes: This interface is deprecated, and it is strongly recommended that you
# avoid using it. For changing block devices, use
# blockdev-change-medium; for changing VNC parameters, use
# change-vnc-password.
# Notes: This interface is deprecated, and it is strongly recommended that you
# avoid using it. For changing block devices, use
# blockdev-change-medium; for changing VNC parameters, use
# change-vnc-password.
#
# Since: 0.14.0
#
@ -1731,8 +1731,8 @@
# of the VM are not loaded by this command.
#
# @filename: the file to load the state of the devices from as binary
# data. See xen-save-devices-state.txt for a description of the binary
# format.
# data. See xen-save-devices-state.txt for a description of the binary
# format.
#
# Since: 2.7
#

22
qapi/net.json
View File

@ -47,9 +47,9 @@
# Additional arguments depend on the type.
#
# TODO: This command effectively bypasses QAPI completely due to its
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
#
# Since: 0.14.0
#
@ -213,7 +213,7 @@
# @fd: file descriptor of an already opened tap
#
# @fds: multiple file descriptors of already opened multiqueue capable
# tap
# tap
#
# @script: script to initialize the interface
#
@ -232,14 +232,14 @@
# @vhostfd: file descriptor of an already opened vhost net device
#
# @vhostfds: file descriptors of multiple already opened vhost net
# devices
# devices
#
# @vhostforce: vhost on for non-MSIX virtio guests
#
# @queues: number of queues to be created for multiqueue capable tap
#
# @poll-us: maximum number of microseconds that could
# be spent on busy polling for tap (since 2.7)
# be spent on busy polling for tap (since 2.7)
#
# Since: 1.2
##
@ -464,7 +464,7 @@
#
# Since: 1.2
#
# 'l2tpv3' - since 2.1
# 'l2tpv3' - since 2.1
##
{ 'union': 'Netdev',
'base': { 'id': 'str', 'type': 'NetClientDriver' },
@ -691,7 +691,7 @@
# Parameters for self-announce timers
#
# @initial: Initial delay (in ms) before sending the first GARP/RARP
# announcement
# announcement
#
# @max: Maximum delay (in ms) between GARP/RARP announcement packets
#
@ -700,11 +700,11 @@
# @step: Delay increase (in ms) after each self-announcement attempt
#
# @interfaces: An optional list of interface names, which restricts the
# announcement to the listed interfaces. (Since 4.1)
# announcement to the listed interfaces. (Since 4.1)
#
# @id: A name to be used to identify an instance of announce-timers
# and to allow it to modified later. Not for use as
# part of the migration parameters. (Since 4.1)
# and to allow it to modified later. Not for use as
# part of the migration parameters. (Since 4.1)
#
# Since: 4.0
##

10
qapi/qdev.json
View File

@ -19,8 +19,8 @@
# Returns: a list of ObjectPropertyInfo describing a devices properties
#
# Note: objects can create properties at runtime, for example to describe
# links between different devices and/or objects. These properties
# are not included in the output of this command.
# links between different devices and/or objects. These properties
# are not included in the output of this command.
#
# Since: 1.2
##
@ -58,9 +58,9 @@
# <- { "return": {} }
#
# TODO: This command effectively bypasses QAPI completely due to its
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
#
# Since: 0.13
##

4
qapi/qom.json
View File

@ -189,8 +189,8 @@
# @typename: the type name of an object
#
# Note: objects can create properties at runtime, for example to describe
# links between different devices and/or objects. These properties
# are not included in the output of this command.
# links between different devices and/or objects. These properties
# are not included in the output of this command.
#
# Returns: a list of ObjectPropertyInfo describing object properties
#

12
qapi/rocker.json
View File

@ -140,7 +140,7 @@
# @ip-dst: IP header destination address
#
# Note: optional members may or may not appear in the flow key
# depending if they're relevant to the flow key.
# depending if they're relevant to the flow key.
#
# Since: 2.4
##
@ -170,7 +170,7 @@
# @ip-tos: IP header TOS field
#
# Note: optional members may or may not appear in the flow mask
# depending if they're relevant to the flow mask.
# depending if they're relevant to the flow mask.
#
# Since: 2.4
##
@ -197,7 +197,7 @@
# @out-pport: physical output port
#
# Note: optional members may or may not appear in the flow action
# depending if they're relevant to the flow action.
# depending if they're relevant to the flow action.
#
# Since: 2.4
##
@ -235,7 +235,7 @@
# @name: switch name
#
# @tbl-id: flow table ID. If tbl-id is not specified, returns
# flow information for all tables.
# flow information for all tables.
#
# Returns: rocker OF-DPA flow information
#
@ -291,7 +291,7 @@
# @ttl-check: perform TTL check
#
# Note: optional members may or may not appear in the group depending
# if they're relevant to the group type.
# if they're relevant to the group type.
#
# Since: 2.4
##
@ -311,7 +311,7 @@
# @name: switch name
#
# @type: group type. If type is not specified, returns
# group information for all group types.
# group information for all group types.
#
# Returns: rocker OF-DPA group information
#

34
qapi/run-state.json
View File

@ -15,16 +15,16 @@
# @finish-migrate: guest is paused to finish the migration process
#
# @inmigrate: guest is paused waiting for an incoming migration. Note
# that this state does not tell whether the machine will start at the
# end of the migration. This depends on the command-line -S option and
# any invocation of 'stop' or 'cont' that has happened since QEMU was
# started.
# that this state does not tell whether the machine will start at the
# end of the migration. This depends on the command-line -S option and
# any invocation of 'stop' or 'cont' that has happened since QEMU was
# started.
#
# @internal-error: An internal error that prevents further guest execution
# has occurred
# has occurred
#
# @io-error: the last IOP has failed and the device is configured to pause
# on I/O errors
# on I/O errors
#
# @paused: guest has been paused via the 'stop' command
#
@ -85,8 +85,8 @@
# @guest-panic: Guest panicked, and command line turns that into a shutdown
#
# @subsystem-reset: Partial guest reset that does not trigger QMP events and
# ignores --no-reboot. This is useful for sanitizing
# hypercalls on s390 that are used during kexec/kdump/boot
# ignores --no-reboot. This is useful for sanitizing
# hypercalls on s390 that are used during kexec/kdump/boot
#
##
{ 'enum': 'ShutdownCause',
@ -140,13 +140,13 @@
# about to exit.
#
# @guest: If true, the shutdown was triggered by a guest request (such as
# a guest-initiated ACPI shutdown request or other hardware-specific action)
# rather than a host request (such as sending qemu a SIGINT). (since 2.10)
# a guest-initiated ACPI shutdown request or other hardware-specific action)
# rather than a host request (such as sending qemu a SIGINT). (since 2.10)
#
# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
#
# Note: If the command-line option "-no-shutdown" has been specified, qemu will
# not exit, and a STOP event will eventually follow the SHUTDOWN event
# not exit, and a STOP event will eventually follow the SHUTDOWN event
#
# Since: 0.12.0
#
@ -180,9 +180,9 @@
# Emitted when the virtual machine is reset
#
# @guest: If true, the reset was triggered by a guest request (such as
# a guest-initiated ACPI reboot request or other hardware-specific action)
# rather than a host request (such as the QMP command system_reset).
# (since 2.10)
# a guest-initiated ACPI reboot request or other hardware-specific action)
# rather than a host request (such as the QMP command system_reset).
# (since 2.10)
#
# @reason: The @ShutdownCause of the RESET. (since 4.0)
#
@ -283,7 +283,7 @@
# @action: action that has been taken
#
# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
# followed respectively by the RESET, SHUTDOWN, or STOP events
# followed respectively by the RESET, SHUTDOWN, or STOP events
#
# Note: This event is rate-limited.
#
@ -441,12 +441,12 @@
# @disabled-wait: the CPU has entered a disabled wait state
#
# @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled
# for external interrupts
# for external interrupts
#
# @pgmint-loop: program interrupt with BAD new PSW
#
# @opint-loop: operation exception interrupt with invalid code at the program
# interrupt new PSW
# interrupt new PSW
#
# Since: 2.12
##

8
qapi/sockets.json
View File

@ -89,7 +89,7 @@
# @port: port
#
# Note: string types are used to allow for possible future hostname or
# service resolution support.
# service resolution support.
#
# Since: 2.8
##
@ -104,9 +104,9 @@
# Captures the address of a socket, which could also be a named file descriptor
#
# Note: This type is deprecated in favor of SocketAddress. The
# difference between SocketAddressLegacy and SocketAddress is that the
# latter is a flat union rather than a simple union. Flat is nicer
# because it avoids nesting on the wire, i.e. that form has fewer {}.
# difference between SocketAddressLegacy and SocketAddress is that the
# latter is a flat union rather than a simple union. Flat is nicer
# because it avoids nesting on the wire, i.e. that form has fewer {}.
#
# Since: 1.3

14
qapi/trace.json
View File

@ -52,14 +52,14 @@
#
# Returns: a list of @TraceEventInfo for the matching events
#
# An event is returned if:
# - its name matches the @name pattern, and
# - if @vcpu is given, the event has the "vcpu" property.
# An event is returned if:
# - its name matches the @name pattern, and
# - if @vcpu is given, the event has the "vcpu" property.
#
# Therefore, if @vcpu is given, the operation will only match per-vCPU events,
# returning their state on the specified vCPU. Special case: if @name is an
# exact match, @vcpu is given and the event does not have the "vcpu" property,
# an error is returned.
# Therefore, if @vcpu is given, the operation will only match per-vCPU events,
# returning their state on the specified vCPU. Special case: if @name is an
# exact match, @vcpu is given and the event does not have the "vcpu" property,
# an error is returned.
#
# Since: 2.2
#

4
qapi/transaction.json
View File

@ -132,8 +132,8 @@
# Errors depend on the operations of the transaction
#
# Note: The transaction aborts on the first failure. Therefore, there will be
# information on only one failed operation returned in an error condition, and
# subsequent actions will not have been attempted.
# information on only one failed operation returned in an error condition, and
# subsequent actions will not have been attempted.
#
# Since: 1.1
#

36
qapi/ui.json
View File

@ -18,10 +18,10 @@
# @password: the new password
#
# @connected: how to handle existing clients when changing the
# password. If nothing is specified, defaults to `keep'
# `fail' to fail the command if clients are connected
# `disconnect' to disconnect existing clients
# `keep' to maintain existing clients
# password. If nothing is specified, defaults to `keep'
# `fail' to fail the command if clients are connected
# `disconnect' to disconnect existing clients
# `keep' to maintain existing clients
#
# Returns: Nothing on success
# If Spice is not enabled, DeviceNotFound
@ -591,12 +591,12 @@
#
# Change the VNC server password.
#
# @password: the new password to use with VNC authentication
# @password: the new password to use with VNC authentication
#
# Since: 1.1
#
# Notes: An empty password in this command will set the password to the empty
# string. Existing clients are unaffected by executing this command.
# Notes: An empty password in this command will set the password to the empty
# string. Existing clients are unaffected by executing this command.
##
{ 'command': 'change-vnc-password',
'data': { 'password': 'str' },
@ -612,7 +612,7 @@
# @client: client information
#
# Note: This event is emitted before any authentication takes place, thus
# the authentication ID is not provided
# the authentication ID is not provided
#
# Since: 0.13.0
#
@ -915,9 +915,9 @@
#
# Pointer motion input event.
#
# @axis: Which axis is referenced by @value.
# @value: Pointer position. For absolute coordinates the
# valid range is 0 -> 0x7ffff
# @axis: Which axis is referenced by @value.
# @value: Pointer position. For absolute coordinates the
# valid range is 0 -> 0x7ffff
#
# Since: 2.0
##
@ -931,10 +931,10 @@
# Input event union.
#
# @type: the input type, one of:
# - 'key': Input event of Keyboard
# - 'btn': Input event of pointer buttons
# - 'rel': Input event of relative pointer motion
# - 'abs': Input event of absolute pointer motion
# - 'key': Input event of Keyboard
# - 'btn': Input event of pointer buttons
# - 'rel': Input event of relative pointer motion
# - 'abs': Input event of absolute pointer motion
#
# Since: 2.0
##
@ -970,9 +970,9 @@
# Since: 2.6
#
# Note: The consoles are visible in the qom tree, under
# /backend/console[$index]. They have a device link and head property,
# so it is possible to map which console belongs to which device and
# display.
# /backend/console[$index]. They have a device link and head property,
# so it is possible to map which console belongs to which device and
# display.
#
# Example:
#