Signed-off-by: John Snow <jsnow@redhat.com>
---
qapi/block-core.json | 186 ++++++++++++++++++++---------------------
qapi/block-export.json | 36 ++++----
qapi/block.json | 14 ++--
qapi/transaction.json | 20 ++---
4 files changed, 128 insertions(+), 128 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index f18db3149a3..74e6a81a5e9 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -31,7 +31,7 @@
# @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
@@ -223,7 +223,7 @@
{ '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
##
@@ -332,7 +332,7 @@
# 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
@@ -349,7 +349,7 @@
# @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
@@ -614,7 +614,7 @@
# @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
##
@@ -709,12 +709,12 @@
# @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
@@ -761,7 +761,7 @@
##
# @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.
@@ -1026,14 +1026,14 @@
# @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
##
@@ -1134,7 +1134,7 @@
# @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)
#
@@ -1158,7 +1158,7 @@
##
# @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"
@@ -1289,8 +1289,8 @@
# @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.
@@ -1323,7 +1323,7 @@
# (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
##
@@ -1530,7 +1530,7 @@
# @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
##
@@ -1585,7 +1585,7 @@
# @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
@@ -1596,7 +1596,7 @@
#
# @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
@@ -1606,14 +1606,14 @@
# 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
@@ -1719,7 +1719,7 @@
#
# @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
#
@@ -1784,7 +1784,7 @@
# 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
@@ -1846,14 +1846,14 @@
# 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:
@@ -1889,14 +1889,14 @@
# @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:
@@ -1920,10 +1920,10 @@
# @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
@@ -2024,7 +2024,7 @@
# @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
@@ -2073,7 +2073,7 @@
##
# @XDbgBlockGraphEdge:
#
-# Block Graph edge description for x-debug-query-block-graph.
+# Block Graph edge description for `x-debug-query-block-graph`.
#
# @parent: parent id
#
@@ -2191,7 +2191,7 @@
#
# @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
@@ -2207,14 +2207,14 @@
# '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
@@ -2249,16 +2249,16 @@
# @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
##
@@ -2288,7 +2288,7 @@
# @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
@@ -2323,7 +2323,7 @@
# @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:
@@ -2507,7 +2507,7 @@
#
# @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
@@ -2522,14 +2522,14 @@
# '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
@@ -2777,9 +2777,9 @@
# 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;
@@ -2798,9 +2798,9 @@
# 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.
#
@@ -2841,7 +2841,7 @@
#
# @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
@@ -2849,14 +2849,14 @@
# 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:
@@ -2917,13 +2917,13 @@
# 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
+# 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.
#
@@ -2937,7 +2937,7 @@
# 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)
#
@@ -2960,7 +2960,7 @@
#
# 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.
#
@@ -2970,7 +2970,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-pause
+# @deprecated: This command is deprecated. Use `job-pause`
# instead.
#
# Errors:
@@ -2999,7 +2999,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-resume
+# @deprecated: This command is deprecated. Use `job-resume`
# instead.
#
# Errors:
@@ -3020,14 +3020,14 @@
#
# 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
@@ -3039,7 +3039,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-complete
+# @deprecated: This command is deprecated. Use `job-complete`
# instead.
#
# Errors:
@@ -3058,21 +3058,21 @@
# 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
@@ -3089,7 +3089,7 @@
# necessary cleanup. This command requires that all involved jobs are
# in the PENDING state.
#
-# For jobs in a transaction, instructing one job to finalize will
+# For jobs in a :qapi:cmd:`transaction`, instructing one job to finalize will
# force ALL jobs in the transaction to finalize, so it is only
# necessary to instruct a single member job to finalize.
#
@@ -3100,7 +3100,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-finalize
+# @deprecated: This command is deprecated. Use `job-finalize`
# instead.
#
# Since: 2.12
@@ -3172,7 +3172,7 @@
# @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
@@ -4714,7 +4714,7 @@
# @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)
@@ -4918,7 +4918,7 @@
# 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
@@ -4927,7 +4927,7 @@
# 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
@@ -4941,7 +4941,7 @@
# 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.
@@ -4955,7 +4955,7 @@
##
# @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.
#
@@ -5510,7 +5510,7 @@
# @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.
#
@@ -5570,7 +5570,7 @@
#
# 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.
#
@@ -5639,10 +5639,10 @@
#
# @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::
#
@@ -5683,15 +5683,15 @@
#
# @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.
#
@@ -5833,7 +5833,7 @@
# @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
#
@@ -5855,8 +5855,8 @@
# @BLOCK_JOB_PENDING:
#
# Emitted when a block job is awaiting explicit authorization to
-# finalize graph changes via @job-finalize. If this job is part
-# of a transaction, it will not emit this event until the transaction
+# finalize graph changes via `job-finalize`. If this job is part
+# of a :qapi:cmd:`transaction`, it will not emit this event until the transaction
# has converged first.
#
# @type: job type
@@ -5904,7 +5904,7 @@
# 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.
#
@@ -5975,7 +5975,7 @@
#
# 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
@@ -6188,7 +6188,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
diff --git a/qapi/block-export.json b/qapi/block-export.json
index 3edbc5436a3..776740fe6fd 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -37,9 +37,9 @@
##
# @NbdServerOptions:
#
-# Keep this type consistent with the NbdServerOptionsLegacy type. The
-# only intended difference is using SocketAddress instead of
-# SocketAddressLegacy.
+# Keep this type consistent with the `NbdServerOptionsLegacy` type. The
+# only intended difference is using `SocketAddress` instead of
+# `SocketAddressLegacy`.
#
# @addr: Address on which to listen (since 4.2).
##
@@ -50,9 +50,9 @@
##
# @NbdServerOptionsLegacy:
#
-# Keep this type consistent with the NbdServerOptions type. The only
-# intended difference is using SocketAddressLegacy instead of
-# SocketAddress.
+# Keep this type consistent with the `NbdServerOptions` type. The only
+# intended difference is using `SocketAddressLegacy` instead of
+# `SocketAddress`.
#
# @addr: Address on which to listen (since 1.3).
##
@@ -64,7 +64,7 @@
# @nbd-server-start:
#
# Start an NBD server listening on the given host and port. Block
-# devices can then be exported using @nbd-server-add. The NBD server
+# devices can then be exported using `nbd-server-add`. The NBD server
# will present them as named exports; for example, another QEMU
# instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
#
@@ -80,8 +80,8 @@
##
# @BlockExportOptionsNbdBase:
#
-# An NBD block export (common options shared between nbd-server-add
-# and the NBD branch of block-export-add).
+# An NBD block export (common options shared between `nbd-server-add`
+# and the NBD branch of `block-export-add`).
#
# @name: Export name. If unspecified, the @device parameter is used
# as the export name. (Since 2.12)
@@ -98,7 +98,7 @@
# @BlockExportOptionsNbd:
#
# An NBD block export (distinct options used in the NBD branch of
-# block-export-add).
+# `block-export-add`).
#
# @bitmaps: Also export each of the named dirty bitmaps reachable from
# @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
@@ -124,7 +124,7 @@
# A vhost-user-blk block export.
#
# @addr: The vhost-user socket on which to listen. Both 'unix' and
-# 'fd' SocketAddress types are supported. Passed fds must be UNIX
+# 'fd' `SocketAddress` types are supported. Passed fds must be UNIX
# domain sockets.
#
# @logical-block-size: Logical block size in bytes. Defaults to 512
@@ -216,7 +216,7 @@
##
# @NbdServerAddOptions:
#
-# An NBD block export, per legacy nbd-server-add command.
+# An NBD block export, per legacy `nbd-server-add` command.
#
# @device: The device name or node name of the node to be exported
#
@@ -245,7 +245,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @block-export-add
+# @deprecated: This command is deprecated. Use `block-export-add`
# instead.
#
# Errors:
@@ -288,12 +288,12 @@
#
# @name: Block export id.
#
-# @mode: Mode of command operation. See @BlockExportRemoveMode
+# @mode: Mode of command operation. See `BlockExportRemoveMode`
# description. Default is 'safe'.
#
# Features:
#
-# @deprecated: This command is deprecated. Use @block-export-del
+# @deprecated: This command is deprecated. Use `block-export-del`
# instead.
#
# Errors:
@@ -312,7 +312,7 @@
# @nbd-server-stop:
#
# Stop QEMU's embedded NBD server, and unregister all devices
-# previously added via @nbd-server-add.
+# previously added via `nbd-server-add`.
#
# Since: 1.3
##
@@ -421,7 +421,7 @@
#
# @id: Block export id.
#
-# @mode: Mode of command operation. See @BlockExportRemoveMode
+# @mode: Mode of command operation. See `BlockExportRemoveMode`
# description. Default is 'safe'.
#
# Errors:
@@ -459,7 +459,7 @@
# @node-name: The node name of the block node that is exported
#
# @shutting-down: True if the export is shutting down (e.g. after a
-# block-export-del command, but before the shutdown has completed)
+# `block-export-del` command, but before the shutdown has completed)
#
# Since: 5.2
##
diff --git a/qapi/block.json b/qapi/block.json
index d288344c648..13f717cd8e8 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -137,7 +137,7 @@
#
# If the tray was already open before, this will be a no-op.
#
-# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There
+# Once the tray opens, a `DEVICE_TRAY_MOVED` event is emitted. There
# are cases in which no such event will be generated, these include:
#
# - if the guest has locked the tray, @force is false and the guest
@@ -296,7 +296,7 @@
# @BlockdevChangeReadOnlyMode:
#
# Specifies the new read-only mode of a block device subject to the
-# @blockdev-change-medium command.
+# `blockdev-change-medium` command.
#
# @retain: Retains the current read-only mode
#
@@ -314,9 +314,9 @@
#
# Changes the medium inserted into a block device by ejecting the
# current medium and loading a new image file which is inserted as the
-# new medium (this command combines blockdev-open-tray,
-# blockdev-remove-medium, blockdev-insert-medium and
-# blockdev-close-tray).
+# new medium (this command combines `blockdev-open-tray`,
+# `blockdev-remove-medium`, `blockdev-insert-medium` and
+# `blockdev-close-tray`).
#
# @device: Block device name
#
@@ -331,7 +331,7 @@
# to 'retain'
#
# @force: if false (the default), an eject request through
-# blockdev-open-tray will be sent to the guest if it has locked
+# `blockdev-open-tray` will be sent to the guest if it has locked
# the tray (and the tray will not be opened immediately); if true,
# the tray will be opened regardless of whether it is locked.
# (since 7.1)
@@ -519,7 +519,7 @@
# @id: The name or QOM path of the guest device.
#
# @boundaries: list of interval boundary values (see description in
-# BlockLatencyHistogramInfo definition). If specified, all
+# `BlockLatencyHistogramInfo` definition). If specified, all
# latency histograms are removed, and empty ones created for all
# io types with intervals corresponding to @boundaries (except for
# io types, for which specific boundaries are set through the
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 9d9e7af26cb..c02e402790e 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -11,7 +11,7 @@
##
# @Abort:
#
-# This action can be used to test transaction failure.
+# This action can be used to test `transaction` failure.
#
# Since: 1.6
##
@@ -67,8 +67,8 @@
#
# Features:
#
-# @deprecated: Member @drive-backup is deprecated. Use member
-# @blockdev-backup instead.
+# @deprecated: Member `drive-backup` is deprecated. Use member
+# `blockdev-backup` instead.
#
# Since: 1.1
##
@@ -156,7 +156,7 @@
# @TransactionAction:
#
# A discriminated record of operations that can be performed with
-# @transaction.
+# `transaction`.
#
# @type: the operation to be performed
#
@@ -187,7 +187,7 @@
#
# @completion-mode: Controls how jobs launched asynchronously by
# Actions will complete or fail as a group. See
-# @ActionCompletionMode for details.
+# `ActionCompletionMode` for details.
#
# Since: 2.5
##
@@ -224,20 +224,20 @@
# support it, for example, qcow2, and rbd,
#
# On failure, QEMU will try delete the newly created internal snapshot
-# in the transaction. When an I/O error occurs during deletion, the
+# in the `transaction`. When an I/O error occurs during deletion, the
# user needs to fix it later with qemu-img or other command.
#
-# @actions: List of @TransactionAction; information needed for the
+# @actions: List of `TransactionAction`; information needed for the
# respective operations.
#
# @properties: structure of additional options to control the
-# execution of the transaction. See @TransactionProperties for
+# execution of the `transaction`. See `TransactionProperties` for
# additional detail.
#
# Errors:
-# - Any errors from commands in the transaction
+# - Any errors from commands in the `transaction`
#
-# .. note:: The transaction aborts on the first failure. Therefore,
+# .. 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.
--
2.48.1John Snow <jsnow@redhat.com> writes:
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
> qapi/block-core.json | 186 ++++++++++++++++++++---------------------
> qapi/block-export.json | 36 ++++----
> qapi/block.json | 14 ++--
> qapi/transaction.json | 20 ++---
> 4 files changed, 128 insertions(+), 128 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index f18db3149a3..74e6a81a5e9 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
[...]
> @@ -3089,7 +3089,7 @@
> # necessary cleanup. This command requires that all involved jobs are
> # in the PENDING state.
> #
> -# For jobs in a transaction, instructing one job to finalize will
> +# For jobs in a :qapi:cmd:`transaction`, instructing one job to finalize will
Why and when do we need :qapi:cmd:?
> # force ALL jobs in the transaction to finalize, so it is only
> # necessary to instruct a single member job to finalize.
> #
[...]
> @@ -5855,8 +5855,8 @@
> # @BLOCK_JOB_PENDING:
> #
> # Emitted when a block job is awaiting explicit authorization to
> -# finalize graph changes via @job-finalize. If this job is part
> -# of a transaction, it will not emit this event until the transaction
> +# finalize graph changes via `job-finalize`. If this job is part
> +# of a :qapi:cmd:`transaction`, it will not emit this event until the transaction
> # has converged first.
> #
> # @type: job type
[...]
> diff --git a/qapi/transaction.json b/qapi/transaction.json
> index 9d9e7af26cb..c02e402790e 100644
> --- a/qapi/transaction.json
> +++ b/qapi/transaction.json
> @@ -11,7 +11,7 @@
> ##
> # @Abort:
> #
> -# This action can be used to test transaction failure.
> +# This action can be used to test `transaction` failure.
I have doubts about this one.
The comment isn't great to begin with. It's from commit 78b18b78aa8
(blockdev: add Abort transaction):
blockdev: add Abort transaction
The Abort action can be used to test QMP 'transaction' failure. Add it
as the last action to exercise the .abort() and .cleanup() code paths
for all previous actions.
So, Abort for testing transactionable commands' handling of transaction
failure, not for testing failure of the transaction command. But the
link points to the command, and thus suggests it's about command failure.
Ideally, we'd point to some "introduction to transactions" text. We
don't have one.
The other occurences of `transaction` are similarly problematic, except
for one noted below. Let's leave the problematic ones alone in this
patch, to keep it mechanical and uncontroversial.
Not this patch's problem: the transaction command's doc comment is
*crap*. Most of it discusses about snapshots, as if snapshots where the
only transactionable commands. It talks about "the dictionary", and the
reader can only guess what that might mean.
> #
> # Since: 1.6
> ##
> @@ -67,8 +67,8 @@
> #
> # Features:
> #
> -# @deprecated: Member @drive-backup is deprecated. Use member
> -# @blockdev-backup instead.
> +# @deprecated: Member `drive-backup` is deprecated. Use member
> +# `blockdev-backup` instead.
> #
> # Since: 1.1
> ##
> @@ -156,7 +156,7 @@
> # @TransactionAction:
> #
> # A discriminated record of operations that can be performed with
> -# @transaction.
> +# `transaction`.
This link is a keeper.
> #
> # @type: the operation to be performed
> #
> @@ -187,7 +187,7 @@
> #
> # @completion-mode: Controls how jobs launched asynchronously by
> # Actions will complete or fail as a group. See
> -# @ActionCompletionMode for details.
> +# `ActionCompletionMode` for details.
> #
> # Since: 2.5
> ##
> @@ -224,20 +224,20 @@
> # support it, for example, qcow2, and rbd,
> #
> # On failure, QEMU will try delete the newly created internal snapshot
> -# in the transaction. When an I/O error occurs during deletion, the
> +# in the `transaction`. When an I/O error occurs during deletion, the
> # user needs to fix it later with qemu-img or other command.
> #
> -# @actions: List of @TransactionAction; information needed for the
> +# @actions: List of `TransactionAction`; information needed for the
> # respective operations.
> #
> # @properties: structure of additional options to control the
> -# execution of the transaction. See @TransactionProperties for
> +# execution of the `transaction`. See `TransactionProperties` for
> # additional detail.
> #
> # Errors:
> -# - Any errors from commands in the transaction
> +# - Any errors from commands in the `transaction`
> #
> -# .. note:: The transaction aborts on the first failure. Therefore,
> +# .. 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.
On Fri, Jun 13, 2025 at 04:36:05PM -0400, John Snow wrote: > Signed-off-by: John Snow <jsnow@redhat.com> > --- > qapi/block-core.json | 186 ++++++++++++++++++++--------------------- > qapi/block-export.json | 36 ++++---- > qapi/block.json | 14 ++-- > qapi/transaction.json | 20 ++--- > 4 files changed, 128 insertions(+), 128 deletions(-) Detecting whether you missed links is harder; but for the links you include here... Reviewed-by: Eric Blake <eblake@redhat.com> -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org
On Mon, Jun 16, 2025, 12:31 PM Eric Blake <eblake@redhat.com> wrote: > On Fri, Jun 13, 2025 at 04:36:05PM -0400, John Snow wrote: > > Signed-off-by: John Snow <jsnow@redhat.com> > > --- > > qapi/block-core.json | 186 ++++++++++++++++++++--------------------- > > qapi/block-export.json | 36 ++++---- > > qapi/block.json | 14 ++-- > > qapi/transaction.json | 20 ++--- > > 4 files changed, 128 insertions(+), 128 deletions(-) > > Detecting whether you missed links is harder; but for the links you > include here... > I can share my script in a little bit, though it's very inefficient and at times stupid. It is at best "semi-manual", but perhaps there's worth in improving it so that we can run conversions elsewhere in the docs, or re-run it periodically? 1. I modified qapi-schema to output a list of identifiers to a text file. I exclude anything ending in "List". 2. I manually removed built-in types like str and so on. I could update the above to just do this part automatically ... 3. I ran a python script that loads all of these words and then runs through all of the qapi .json files, replacing each occurrence with `occurrence`. The regex is a little rudimentary ... 4. I use "git add -p" to (quickly) review each change as it goes in. Sometimes I need to make edits to remove the leading @ or remove surrounding quotes. On occasion I need to disambiguate the reference. I may need to reflow the text. 5. I skip committing most things for "stop", "eject", "transaction", etc as they are common words and don't necessarily refer to the QMP command or event enum, etc. If there are mistakes, I'd bet money it's around runstates, eject, stop, or "transaction". It's possible some things are not capitalized "correctly" in the documentation and therefore missed getting hit by the cross-ref beam, too. > Reviewed-by: Eric Blake <eblake@redhat.com> > Thank you very much! Hopefully you like this change and it makes browsing the block documentation much more pleasant. > -- > Eric Blake, Principal Software Engineer > Red Hat, Inc. > Virtualization: qemu.org | libguestfs.org > >
© 2016 - 2026 Red Hat, Inc.