# @icount: Current instruction count. Appears when execution
# record/replay is enabled. Used for "time-traveling" to match
# the moment in the recorded execution with the snapshots. This
-# counter may be obtained through @query-replay command
+# counter may be obtained through `query-replay` command
# (since 5.2)
#
# Since: 1.3
{ 'struct': 'ImageInfoSpecificLUKSWrapper',
'data': { 'data': 'QCryptoBlockInfoLUKS' } }
# If we need to add block driver specific parameters for
-# LUKS in future, then we'll subclass QCryptoBlockInfoLUKS
+# LUKS in future, then we'll subclass `QCryptoBlockInfoLUKS`
# to define a ImageInfoSpecificLUKS
##
# node, annotated with information about that node in relation to its
# parent.
#
-# @name: Child name of the root node in the BlockGraphInfo struct, in
+# @name: Child name of the root node in the `BlockGraphInfo` struct, in
# its role as the child of some undescribed parent node
#
# @info: Block graph information starting at this node
# @BlockGraphInfo:
#
# Information about all nodes in a block (sub)graph in the form of
-# BlockNodeInfo data. The base BlockNodeInfo struct contains the
+# `BlockNodeInfo` data. The base `BlockNodeInfo` struct contains the
# information for the (sub)graph's root node.
#
# @children: Array of links to this node's child nodes' information
# @inconsistent: true if this is a persistent bitmap that was
# improperly stored. Implies @persistent to be true; @recording
# and @busy to be false. This bitmap cannot be used. To remove
-# it, use @block-dirty-bitmap-remove. (Since 4.0)
+# it, use `block-dirty-bitmap-remove`. (Since 4.0)
#
# Since: 1.3
##
# @tray_open: True if the device's tray is open (only present if it
# has a tray)
#
-# @io-status: @BlockDeviceIoStatus. Only present if the device
+# @io-status: `BlockDeviceIoStatus`. Only present if the device
# supports it and the VM is configured to stop on errors
# (supported device models: virtio-blk, IDE, SCSI except
# scsi-generic)
#
-# @inserted: @BlockDeviceInfo describing the device if media is
+# @inserted: `BlockDeviceInfo` describing the device if media is
# present
#
# Since: 0.14
##
# @query-block:
#
-# Get a list of BlockInfo for all virtual block devices.
+# Get a list of `BlockInfo` for all virtual block devices.
#
# Returns: a list describing each virtual block device.
# Filter nodes that were created implicitly are skipped over.
# @timed_stats: Statistics specific to the set of previously defined
# intervals of time (Since 2.5)
#
-# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
+# @rd_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0)
#
-# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
+# @wr_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0)
#
-# @zone_append_latency_histogram: @BlockLatencyHistogramInfo.
+# @zone_append_latency_histogram: `BlockLatencyHistogramInfo`.
# (since 8.1)
#
-# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
+# @flush_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0)
#
# Since: 0.14
##
# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the
# block device. (since 3.0)
#
-# @stats: A @BlockDeviceStats for the device.
+# @stats: A `BlockDeviceStats` for the device.
#
# @driver-specific: Optional driver-specific stats. (Since 4.2)
#
##
# @query-blockstats:
#
-# Query the @BlockStats for all virtual block devices.
+# Query the `BlockStats` for all virtual block devices.
#
# @query-nodes: If true, the command will query all the block nodes
# that have a node name, in a list which will include "parent"
# @report: for guest operations, report the error to the guest; for
# jobs, cancel the job
#
-# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
-# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs
+# @ignore: ignore the error, only report a QMP event (`BLOCK_IO_ERROR`
+# or `BLOCK_JOB_ERROR`). The backup, mirror and commit block jobs
# retry the failing request later and may still complete
# successfully. The stream block job continues to stream and will
# complete with an error.
# (since: 2.4)
#
# @bitmap: only copy data described by the dirty bitmap. Behavior on
-# completion is determined by the BitmapSyncMode. (since: 4.2)
+# completion is determined by the `BitmapSyncMode`. (since: 4.2)
#
# Since: 1.3
##
# @overlay: reference to the existing block device that will become
# the overlay of @node, as part of taking the snapshot. It must
# not have a current backing file (this can be achieved by passing
-# "backing": null to blockdev-add).
+# "backing": null to `blockdev-add`).
#
# Since: 2.5
##
# @bitmap: The name of a dirty bitmap to use. Must be present if sync
# is "bitmap" or "incremental". Can be present if sync is "full"
# or "top". Must not be present otherwise.
-# (Since 2.4 (drive-backup), 3.1 (blockdev-backup))
+# (Since 2.4 (`drive-backup`), 3.1 (`blockdev-backup`))
#
# @bitmap-mode: Specifies the type of data the bitmap should contain
# after the operation concludes. Must be present if a bitmap was
#
# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used if the
-# block device supports io-status (see BlockInfo).
+# block device supports io-status (see `BlockInfo`).
#
# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to a
# copy-before-write jobs; defaults to break-guest-write. (Since 10.1)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @job-finalize before
+# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 2.12)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @job-dismiss. When true, this job will automatically disappear
+# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 2.12)
#
# @filter-node-name: the node name that should be assigned to the
#
# @allow-write-only-overlay: If present, the check whether this
# operation is safe was relaxed so that it can be used to change
-# backing file of a destination of a blockdev-mirror. (since 5.0)
+# backing file of a destination of a `blockdev-mirror`. (since 5.0)
#
# Since: 2.5
#
# If top == base, that is an error. If top has no overlays on top of
# it, or if it is in use by a writer, the job will not be completed by
# itself. The user needs to complete the job with the
-# job-complete command after getting the ready event. (Since 2.0)
+# `job-complete` command after getting the ready event. (Since 2.0)
#
# If the base image is smaller than top, then the base image will be
# resized to be the same size as top. If top is smaller than the base
# autogenerated. (Since: 2.9)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @job-finalize before
+# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @job-dismiss. When true, this job will automatically disappear
+# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# Features:
# @drive-backup:
#
# Start a point-in-time copy of a block device to a new destination.
-# The status of ongoing drive-backup operations can be checked with
-# query-block-jobs where the BlockJobInfo.type field has the value
+# The status of ongoing `drive-backup` operations can be checked with
+# `query-block-jobs` where the `BlockJobInfo`.type field has the value
# 'backup'. The operation can be stopped before it has completed
-# using the job-cancel or block-job-cancel command.
+# using the `job-cancel` or `block-job-cancel` command.
#
# Features:
#
-# @deprecated: This command is deprecated. Use @blockdev-backup
+# @deprecated: This command is deprecated. Use `blockdev-backup`
# instead.
#
# Errors:
# @blockdev-backup:
#
# Start a point-in-time copy of a block device to a new destination.
-# The status of ongoing blockdev-backup operations can be checked with
-# query-block-jobs where the BlockJobInfo.type field has the value
+# The status of ongoing `blockdev-backup` operations can be checked with
+# `query-block-jobs` where the `BlockJobInfo`.type field has the value
# 'backup'. The operation can be stopped before it has completed
-# using the job-cancel or block-job-cancel command.
+# using the `job-cancel` or `block-job-cancel` command.
#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
# @XDbgBlockGraphNode:
#
# @id: Block graph node identifier. This @id is generated only for
-# x-debug-query-block-graph and does not relate to any other
+# `x-debug-query-block-graph` and does not relate to any other
# identifiers in QEMU.
#
# @type: Type of graph node. Can be one of block-backend, block-job
##
# @XDbgBlockGraphEdge:
#
-# Block Graph edge description for x-debug-query-block-graph.
+# Block Graph edge description for `x-debug-query-block-graph`.
#
# @parent: parent id
#
#
# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used if the
-# block device supports io-status (see BlockInfo).
+# block device supports io-status (see `BlockInfo`).
#
# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to a
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @job-finalize before
+# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @job-dismiss. When true, this job will automatically disappear
+# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# Since: 1.3
# @name: name of the dirty bitmap (must be less than 1024 bytes)
#
# @granularity: the bitmap granularity, default is 64k for
-# block-dirty-bitmap-add
+# `block-dirty-bitmap-add`
#
# @persistent: the bitmap is persistent, i.e. it will be saved to the
# corresponding block device image file on its close. For now
# only Qcow2 disks support persistent bitmaps. Default is false
-# for block-dirty-bitmap-add. (Since: 2.10)
+# for `block-dirty-bitmap-add`. (Since: 2.10)
#
# @disabled: the bitmap is created in the disabled state, which means
# that it will not track drive changes. The bitmap may be enabled
-# with block-dirty-bitmap-enable. Default is false. (Since: 4.0)
+# with `block-dirty-bitmap-enable`. Default is false. (Since: 4.0)
#
# Since: 2.4
##
# @target: name of the destination dirty bitmap
#
# @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or
-# fully specified BlockDirtyBitmap elements. The latter are
+# fully specified `BlockDirtyBitmap` elements. The latter are
# supported since 4.1.
#
# Since: 4.0
# @block-dirty-bitmap-remove:
#
# Stop write tracking and remove the dirty bitmap that was created
-# with block-dirty-bitmap-add. If the bitmap is persistent, remove it
+# with `block-dirty-bitmap-add`. If the bitmap is persistent, remove it
# from its storage too.
#
# Errors:
#
# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used if the
-# block device supports io-status (see BlockInfo).
+# block device supports io-status (see `BlockInfo`).
#
# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to a
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @job-finalize before
+# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @job-dismiss. When true, this job will automatically disappear
+# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# @target-is-zero: Assume the destination reads as all zeroes before
# The block streaming operation is performed in the background until
# the entire backing file has been copied. This command returns
# immediately once streaming has started. The status of ongoing block
-# streaming operations can be checked with query-block-jobs. The
+# streaming operations can be checked with `query-block-jobs`. The
# operation can be stopped before it has completed using the
-# job-cancel or block-job-cancel command.
+# `job-cancel` or `block-job-cancel` command.
#
# The node that receives the data is called the top image, can be
# located in any part of the chain (but always above the base image;
# will be the new backing file.
#
# On successful completion the image file is updated to drop the
-# backing file and the BLOCK_JOB_COMPLETED event is emitted.
+# backing file and the `BLOCK_JOB_COMPLETED` event is emitted.
#
-# In case @device is a filter node, block-stream modifies the first
+# In case @device is a filter node, `block-stream` modifies the first
# non-filter overlay node below it to point to the new backing node
# instead of modifying @device itself.
#
#
# @on-error: the action to take on an error (default report). 'stop'
# and 'enospc' can only be used if the block device supports
-# io-status (see BlockInfo). (Since 1.3)
+# io-status (see `BlockInfo`). (Since 1.3)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the stream job inserts into the graph above
# autogenerated. (Since: 6.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @job-finalize before
+# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @job-dismiss. When true, this job will automatically disappear
+# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# Errors:
# command if no operation is in progress.
#
# The operation will cancel as soon as possible and then emit the
-# BLOCK_JOB_CANCELLED event. Before that happens the job is still
-# visible when enumerated using query-block-jobs.
+# `BLOCK_JOB_CANCELLED` event. Before that happens the job is still
+# visible when enumerated using `query-block-jobs`.
#
-# Note that if you issue 'block-job-cancel' after 'drive-mirror' has
-# indicated (via the event BLOCK_JOB_READY) that the source and
+# Note that if you issue `block-job-cancel` after `drive-mirror` has
+# indicated (via the event `BLOCK_JOB_READY`) that the source and
# destination are synchronized, then the event triggered by this
-# command changes to BLOCK_JOB_COMPLETED, to indicate that the
+# command changes to `BLOCK_JOB_COMPLETED`, to indicate that the
# mirroring has ended and the destination now has a point-in-time copy
# tied to the time of the cancellation.
#
# values.
#
# @force: If true, and the job has already emitted the event
-# BLOCK_JOB_READY, abandon the job immediately (even if it is
+# `BLOCK_JOB_READY`, abandon the job immediately (even if it is
# paused) instead of waiting for the destination to complete its
# final synchronization (since 1.3)
#
#
# The job will pause as soon as possible, which means transitioning
# into the PAUSED state if it was RUNNING, or into STANDBY if it was
-# READY. The corresponding JOB_STATUS_CHANGE event will be emitted.
+# READY. The corresponding `JOB_STATUS_CHANGE` event will be emitted.
#
# Cancelling a paused job automatically resumes it.
#
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-pause
+# @deprecated: This command is deprecated. Use `job-pause`
# instead.
#
# Errors:
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-resume
+# @deprecated: This command is deprecated. Use `job-resume`
# instead.
#
# Errors:
#
# This is supported only for drive mirroring, where it also switches
# the device to write to the target path only. Note that drive
-# mirroring includes drive-mirror, blockdev-mirror and block-commit
+# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit`
# job (only in case of "active commit", when the node being commited
# is used by the guest). The ability to complete is signaled with a
-# BLOCK_JOB_READY event.
+# `BLOCK_JOB_READY` event.
#
# This command completes an active background block operation
# synchronously. The ordering of this command's return with the
-# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
+# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error
# occurs during the processing of this command: 1) the command itself
# will fail; 2) the error will be processed according to the
# rerror/werror arguments that were specified when starting the
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-complete
+# @deprecated: This command is deprecated. Use `job-complete`
# instead.
#
# Errors:
# Deletes a job that is in the CONCLUDED state. This command only
# needs to be run explicitly for jobs that don't have automatic
# dismiss enabled. In turn, automatic dismiss may be enabled only
-# for jobs that have @auto-dismiss option, which are drive-backup,
-# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and
-# block-stream. @auto-dismiss is enabled by default for these
+# for jobs that have @auto-dismiss option, which are `drive-backup`,
+# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
+# `block-stream`. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
# reached its terminal state, CONCLUDED. For jobs that make use of
-# the BLOCK_JOB_READY event, job-cancel, block-job-cancel or
-# job-complete will still need to be used as appropriate.
+# the `BLOCK_JOB_READY` event, `job-cancel`, `block-job-cancel` or
+# `job-complete` will still need to be used as appropriate.
#
# @id: The job identifier.
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-dismiss
+# @deprecated: This command is deprecated. Use `job-dismiss`
# instead.
#
# Since: 2.12
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-finalize
+# @deprecated: This command is deprecated. Use `job-finalize`
# instead.
#
# Since: 2.12
# @on: Enabled
#
# @unmap: Enabled and even try to unmap blocks if possible. This
-# requires also that @BlockdevDiscardOptions is set to unmap for
+# requires also that `BlockdevDiscardOptions` is set to unmap for
# this device.
#
# Since: 2.1
# @driver: block driver name
#
# @node-name: the node name of the new node. This option is required
-# on the top level of blockdev-add. Valid node names start with
+# on the top level of `blockdev-add`. Valid node names start with
# an alphabetic character and may contain only alphanumeric
# characters, '-', '.' and '_'. Their maximum length is 31
# characters. (Since 2.0)
# cancelled.
#
# The command receives a list of block devices to reopen. For each
-# one of them, the top-level @node-name option (from BlockdevOptions)
+# one of them, the top-level @node-name option (from `BlockdevOptions`)
# must be specified and is used to select the block device to be
# reopened. Other @node-name options must be either omitted or set to
# the current name of the appropriate node. This command won't change
# In the case of options that refer to child nodes, the behavior of
# this command depends on the value:
#
-# 1) A set of options (BlockdevOptions): the child is reopened with
+# 1) A set of options (`BlockdevOptions`): the child is reopened with
# the specified set of options.
#
# 2) A reference to the current child: the child is reopened using
# Options (1) and (2) are supported in all cases. Option (3) is
# supported for @file and @backing, and option (4) for @backing only.
#
-# Unlike with blockdev-add, the @backing option must always be present
+# Unlike with `blockdev-add`, the @backing option must always be present
# unless the node being reopened does not have a backing file and its
# image does not have a default backing file name as part of its
# metadata.
##
# @blockdev-del:
#
-# Deletes a block device that has been added using blockdev-add. The
+# Deletes a block device that has been added using `blockdev-add`. The
# command will fail if the node is attached to a device or is
# otherwise being used.
#
# @blockdev-create:
#
# Starts a job to create an image format on a given node. The job is
-# automatically finalized, but a manual job-dismiss is required.
+# automatically finalized, but a manual `job-dismiss` is required.
#
# @job-id: Identifier for the newly created job.
#
#
# Starts a job to amend format specific options of an existing open
# block device. The job is automatically finalized, but a manual
-# job-dismiss is required.
+# `job-dismiss` is required.
#
# @job-id: Identifier for the newly created job.
#
#
# @fatal: if set, the image is marked corrupt and therefore unusable
# after this event and must be repaired (Since 2.2; before, every
-# BLOCK_IMAGE_CORRUPTED event was fatal)
+# `BLOCK_IMAGE_CORRUPTED` event was fatal)
#
-# .. note:: If action is "stop", a STOP event will eventually follow
-# the BLOCK_IO_ERROR event.
+# .. note:: If action is "stop", a `STOP` event will eventually follow
+# the `BLOCK_IO_ERROR` event.
#
# .. qmp-example::
#
#
# @nospace: true if I/O error was caused due to a no-space condition.
# This key is only present if query-block's io-status is present,
-# please see query-block documentation for more information
+# please see `query-block` documentation for more information
# (since: 2.2)
#
# @reason: human readable string describing the error cause. (This
# field is a debugging aid for humans, it should not be parsed by
# applications) (since: 2.2)
#
-# .. note:: If action is "stop", a STOP event will eventually follow
-# the BLOCK_IO_ERROR event.
+# .. note:: If action is "stop", a `STOP` event will eventually follow
+# the `BLOCK_IO_ERROR` event.
#
# .. note:: This event is rate-limited.
#
# @speed: rate limit, bytes per second
#
# .. note:: The "ready to complete" status is always reset by a
-# @BLOCK_JOB_ERROR event.
+# `BLOCK_JOB_ERROR` event.
#
# Since: 1.3
#
# @BLOCK_JOB_PENDING:
#
# Emitted when a block job is awaiting explicit authorization to
-# finalize graph changes via @job-finalize. If this job is part
+# finalize graph changes via `job-finalize`. If this job is part
# of a transaction, it will not emit this event until the transaction
# has converged first.
#
# configured write threshold. For thin-provisioned devices, this
# means the device should be extended to avoid pausing for disk
# exhaustion. The event is one shot. Once triggered, it needs to be
-# re-registered with another block-set-write-threshold command.
+# re-registered with another `block-set-write-threshold` command.
#
# @node-name: graph node name on which the threshold was exceeded.
#
#
# TODO: Removing children from a quorum node means introducing
# gaps in the child indices. This cannot be represented in the
-# 'children' list of BlockdevOptionsQuorum, as returned by
+# 'children' list of `BlockdevOptionsQuorum`, as returned by
# .bdrv_refresh_filename().
#
# Since: 2.7
# Synchronously delete an internal snapshot of a block device, when
# the format of the image used support it. The snapshot is identified
# by name or id or both. One of the name or id is required. Return
-# SnapshotInfo for the successfully deleted snapshot.
+# `SnapshotInfo` for the successfully deleted snapshot.
#
# @device: the device name or node-name of a root node to delete the
# snapshot from
projects / thirdparty / qemu.git / commitdiff
