* [PULL 00/13] QAPI patches patches for 2025-06-03
@ 2025-06-03 6:36 Markus Armbruster
2025-06-03 6:36 ` [PULL 01/13] qapi: Tidy up run-together sentences in doc comments Markus Armbruster
` (13 more replies)
0 siblings, 14 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha
The following changes since commit 6322b753f798337835e205b6d805356bea582c86:
Merge tag 'for_upstream' of https://git.kernel.org/pub/scm/virt/kvm/mst/qemu into staging (2025-06-02 14:52:45 -0400)
are available in the Git repository at:
https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2025-06-03
for you to fetch changes up to 8fa2020647041e9f01bc308589bb7fa00355ac9b:
qapi: Improve documentation around job state @concluded (2025-06-03 08:34:57 +0200)
----------------------------------------------------------------
QAPI patches patches for 2025-06-03
----------------------------------------------------------------
Markus Armbruster (13):
qapi: Tidy up run-together sentences in doc comments
qapi: Tidy up whitespace in doc comments
qapi: Move (since X.Y) to end of description
qapi: Avoid breaking lines within (since X.Y)
qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus
qapi: Correct spelling of QEMU in doc comments
qapi: Fix capitalization in doc comments
qapi: Use proper markup instead of CAPS for emphasis in doc comments
qapi: Spell JSON null correctly in blockdev-reopen documentation
qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs
qapi: Mention both job-cancel and block-job-cancel in doc comments
qapi: Tidy up references to job state CONCLUDED
qapi: Improve documentation around job state @concluded
qapi/acpi.json | 2 +-
qapi/audio.json | 8 +--
qapi/block-core.json | 184 ++++++++++++++++++++++++-------------------------
qapi/block-export.json | 6 +-
qapi/block.json | 2 +-
qapi/char.json | 8 +--
qapi/crypto.json | 21 +++---
qapi/cryptodev.json | 2 +-
qapi/cxl.json | 2 +-
qapi/dump.json | 6 +-
qapi/introspect.json | 8 +--
qapi/job.json | 28 ++++----
qapi/machine.json | 14 ++--
qapi/migration.json | 100 +++++++++++++--------------
qapi/misc-i386.json | 2 +-
qapi/misc.json | 4 +-
qapi/net.json | 18 ++---
qapi/qom.json | 2 +-
qapi/run-state.json | 12 ++--
qapi/transaction.json | 4 +-
qapi/uefi.json | 2 +-
qapi/ui.json | 8 +--
22 files changed, 219 insertions(+), 224 deletions(-)
--
2.48.1
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PULL 01/13] qapi: Tidy up run-together sentences in doc comments
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 02/13] qapi: Tidy up whitespace " Markus Armbruster
` (12 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
Fixes: a937b6aa739f (qapi: Reformat doc comments to conform to current conventions)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/acpi.json | 2 +-
qapi/block-core.json | 14 +++++++-------
qapi/crypto.json | 18 +++++++++---------
qapi/machine.json | 4 ++--
qapi/migration.json | 18 +++++++++---------
5 files changed, 28 insertions(+), 28 deletions(-)
diff --git a/qapi/acpi.json b/qapi/acpi.json
index 045dab6228..2d53b82365 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -80,7 +80,7 @@
##
# @ACPIOSTInfo:
#
-# OSPM Status Indication for a device For description of possible
+# OSPM Status Indication for a device. For description of possible
# values of @source and @status fields see "_OST (OSPM Status
# Indication)" chapter of ACPI5.0 spec.
#
diff --git a/qapi/block-core.json b/qapi/block-core.json
index b4115113d4..29d7c1c2c9 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2667,7 +2667,7 @@
# @iops-total-max: I/O operations burst
#
# @iops-total-max-length: length of the iops-total-max burst period,
-# in seconds It must only be set if @iops-total-max is set as
+# in seconds. It must only be set if @iops-total-max is set as
# well.
#
# @iops-read: limit read operations per second
@@ -2675,14 +2675,14 @@
# @iops-read-max: I/O operations read burst
#
# @iops-read-max-length: length of the iops-read-max burst period, in
-# seconds It must only be set if @iops-read-max is set as well.
+# seconds. It must only be set if @iops-read-max is set as well.
#
# @iops-write: limit write operations per second
#
# @iops-write-max: I/O operations write burst
#
# @iops-write-max-length: length of the iops-write-max burst period,
-# in seconds It must only be set if @iops-write-max is set as
+# in seconds. It must only be set if @iops-write-max is set as
# well.
#
# @bps-total: limit total bytes per second
@@ -2697,14 +2697,14 @@
# @bps-read-max: total bytes read burst
#
# @bps-read-max-length: length of the bps-read-max burst period, in
-# seconds It must only be set if @bps-read-max is set as well.
+# seconds. It must only be set if @bps-read-max is set as well.
#
# @bps-write: limit write bytes per second
#
# @bps-write-max: total bytes write burst
#
# @bps-write-max-length: length of the bps-write-max burst period, in
-# seconds It must only be set if @bps-write-max is set as well.
+# seconds. It must only be set if @bps-write-max is set as well.
#
# @iops-size: when limiting by iops max size of an I/O in bytes
#
@@ -5580,7 +5580,7 @@
# @x-blockdev-amend:
#
# Starts a job to amend format specific options of an existing open
-# block device The job is automatically finalized, but a manual
+# block device. The job is automatically finalized, but a manual
# job-dismiss is required.
#
# @job-id: Identifier for the newly created job.
@@ -5589,7 +5589,7 @@
#
# @options: Options (driver specific)
#
-# @force: Allow unsafe operations, format specific For luks that
+# @force: Allow unsafe operations, format specific. For luks that
# allows erase of the last active keyslot (permanent loss of
# data), and replacement of an active keyslot (possible loss of
# data if IO error happens)
diff --git a/qapi/crypto.json b/qapi/crypto.json
index c9d967d782..fc7e294966 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -202,19 +202,19 @@
#
# The options that apply to LUKS encryption format initialization
#
-# @cipher-alg: the cipher algorithm for data encryption Currently
+# @cipher-alg: the cipher algorithm for data encryption. Currently
# defaults to 'aes-256'.
#
-# @cipher-mode: the cipher mode for data encryption Currently defaults
-# to 'xts'
+# @cipher-mode: the cipher mode for data encryption. Currently
+# defaults to 'xts'
#
-# @ivgen-alg: the initialization vector generator Currently defaults
+# @ivgen-alg: the initialization vector generator. Currently defaults
# to 'plain64'
#
-# @ivgen-hash-alg: the initialization vector generator hash Currently
-# defaults to 'sha256'
+# @ivgen-hash-alg: the initialization vector generator hash.
+# Currently defaults to 'sha256'
#
-# @hash-alg: the master key hash algorithm Currently defaults to
+# @hash-alg: the master key hash algorithm. Currently defaults to
# 'sha256'
#
# @iter-time: number of milliseconds to spend in PBKDF passphrase
@@ -370,11 +370,11 @@
# @new-secret: The ID of a QCryptoSecret object providing the password
# to be written into added active keyslots
#
-# @old-secret: Optional (for deactivation only) If given will
+# @old-secret: Optional (for deactivation only). If given will
# deactivate all keyslots that match password located in
# QCryptoSecret with this ID
#
-# @iter-time: Optional (for activation only) Number of milliseconds to
+# @iter-time: Optional (for activation only). Number of milliseconds to
# spend in PBKDF passphrase processing for the newly activated
# keyslot. Currently defaults to 2000.
#
diff --git a/qapi/machine.json b/qapi/machine.json
index 5373e1368c..0af2e1e0bb 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1160,7 +1160,7 @@
#
# Information about the guest balloon device.
#
-# @actual: the logical size of the VM in bytes Formula used:
+# @actual: the logical size of the VM in bytes. Formula used:
# logical_vm_size = vm_ram_size - balloon_size
#
# Since: 0.14
@@ -1199,7 +1199,7 @@
# is equivalent to the @actual field return by the 'query-balloon'
# command
#
-# @actual: the logical size of the VM in bytes Formula used:
+# @actual: the logical size of the VM in bytes. Formula used:
# logical_vm_size = vm_ram_size - balloon_size
#
# .. note:: This event is rate-limited.
diff --git a/qapi/migration.json b/qapi/migration.json
index 41826bde45..f5a6b35de4 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -760,9 +760,9 @@
# auto-converge detects that migration is not making progress.
# The default value is 10. (Since 2.7)
#
-# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
-# the tail stage of throttling, the Guest is very sensitive to CPU
-# percentage while the @cpu-throttle -increment is excessive
+# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage.
+# At the tail stage of throttling, the Guest is very sensitive to
+# CPU percentage while the @cpu-throttle -increment is excessive
# usually at tail stage. If this parameter is true, we will
# compute the ideal CPU percentage used by the Guest, which may
# exactly make the dirty rate match the dirty rate threshold.
@@ -941,9 +941,9 @@
# auto-converge detects that migration is not making progress.
# The default value is 10. (Since 2.7)
#
-# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
-# the tail stage of throttling, the Guest is very sensitive to CPU
-# percentage while the @cpu-throttle -increment is excessive
+# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage.
+# At the tail stage of throttling, the Guest is very sensitive to
+# CPU percentage while the @cpu-throttle -increment is excessive
# usually at tail stage. If this parameter is true, we will
# compute the ideal CPU percentage used by the Guest, which may
# exactly make the dirty rate match the dirty rate threshold.
@@ -1155,9 +1155,9 @@
# auto-converge detects that migration is not making progress.
# (Since 2.7)
#
-# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
-# the tail stage of throttling, the Guest is very sensitive to CPU
-# percentage while the @cpu-throttle -increment is excessive
+# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage.
+# At the tail stage of throttling, the Guest is very sensitive to
+# CPU percentage while the @cpu-throttle -increment is excessive
# usually at tail stage. If this parameter is true, we will
# compute the ideal CPU percentage used by the Guest, which may
# exactly make the dirty rate match the dirty rate threshold.
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 02/13] qapi: Tidy up whitespace in doc comments
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
2025-06-03 6:36 ` [PULL 01/13] qapi: Tidy up run-together sentences in doc comments Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 03/13] qapi: Move (since X.Y) to end of description Markus Armbruster
` (11 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-3-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 16 ++++++++--------
qapi/block-export.json | 4 ++--
qapi/char.json | 2 +-
qapi/crypto.json | 3 ++-
qapi/job.json | 8 ++++----
qapi/machine.json | 2 +-
qapi/migration.json | 12 ++++++------
qapi/qom.json | 2 +-
8 files changed, 25 insertions(+), 24 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 29d7c1c2c9..13223df9b4 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -488,7 +488,7 @@
#
# @active: true if the backend is active; typical cases for inactive backends
# are on the migration source instance after migration completes and on the
-# destination before it completes. (since: 10.0)
+# destination before it completes. (since: 10.0)
#
# @encrypted: true if the backing device is encrypted
#
@@ -3030,10 +3030,10 @@
# state. Completing the job in any other state is an error.
#
# This is supported only for drive mirroring, where it also switches
-# the device to write to the target path only. Note that drive
+# the device to write to the target path only. Note that drive
# 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
+# is used by the guest). The ability to complete is signaled with a
# BLOCK_JOB_READY event.
#
# This command completes an active background block operation
@@ -3068,10 +3068,10 @@
#
# 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
+# 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
+# block-stream. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
@@ -4737,7 +4737,7 @@
# @active: whether the block node should be activated (default: true).
# Having inactive block nodes is useful primarily for migration because it
# allows opening an image on the destination while the source is still
-# holding locks for it. (Since 10.0)
+# holding locks for it. (Since 10.0)
#
# @read-only: whether the block device should be read-only (default:
# false). Note that some block drivers support only read-only
@@ -4999,14 +4999,14 @@
##
# @blockdev-set-active:
#
-# Activate or inactivate a block device. Use this to manage the handover of
+# Activate or inactivate a block device. Use this to manage the handover of
# block devices on migration with qemu-storage-daemon.
#
# Activating a node automatically activates all of its child nodes first.
# Inactivating a node automatically inactivates any of its child nodes that are
# not in use by a still active node.
#
-# @node-name: Name of the graph node to activate or inactivate. By default, all
+# @node-name: Name of the graph node to activate or inactivate. By default, all
# nodes are affected by the operation.
#
# @active: true if the nodes should be active when the command returns success,
diff --git a/qapi/block-export.json b/qapi/block-export.json
index c783e01a53..04190b503c 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -373,9 +373,9 @@
# (since: 5.2)
#
# @allow-inactive: If true, the export allows the exported node to be inactive.
-# If it is created for an inactive block node, the node remains inactive. If
+# If it is created for an inactive block node, the node remains inactive. If
# the export type doesn't support running on an inactive node, an error is
-# returned. If false, inactive block nodes are automatically activated before
+# returned. If false, inactive block nodes are automatically activated before
# creating the export and trying to inactivate them later fails.
# (since: 10.0; default: false)
#
diff --git a/qapi/char.json b/qapi/char.json
index 447c10b91a..f79216e4d2 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -274,7 +274,7 @@
# @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. The use of this member is
-# deprecated, use @reconnect-ms instead. (default: 0) (Since: 2.2)
+# deprecated, use @reconnect-ms instead. (default: 0) (Since: 2.2)
#
# @reconnect-ms: For a client socket, if a socket is disconnected,
# then attempt a reconnect after the given number of milliseconds.
diff --git a/qapi/crypto.json b/qapi/crypto.json
index fc7e294966..9ec6301e18 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -55,7 +55,8 @@
# @sha512: SHA-512. (since 2.7)
#
# @ripemd160: RIPEMD-160. (since 2.7)
-# @sm3: SM3. (since 9.2.0)
+#
+# @sm3: SM3. (since 9.2.0)
#
# Since: 2.6
##
diff --git a/qapi/job.json b/qapi/job.json
index b03f80bc84..c53c96cce8 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -191,10 +191,10 @@
# state. Completing the job in any other state is an error.
#
# This is supported only for drive mirroring, where it also switches
-# the device to write to the target path only. Note that drive
+# the device to write to the target path only. Note that drive
# 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
+# is used by the guest). The ability to complete is signaled with a
# BLOCK_JOB_READY event.
#
# This command completes an active background block operation
@@ -216,10 +216,10 @@
#
# 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
+# 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
+# block-stream. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
diff --git a/qapi/machine.json b/qapi/machine.json
index 0af2e1e0bb..069e87d16a 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -694,7 +694,7 @@
# Structure of HMAT (Heterogeneous Memory Attribute Table)
#
# For more information about @HmatLBDataType, see chapter 5.2.27.4:
-# Table 5-146: Field "Data Type" of ACPI 6.3 spec.
+# Table 5-146: Field "Data Type" of ACPI 6.3 spec.
#
# @access-latency: access latency (nanoseconds)
#
diff --git a/qapi/migration.json b/qapi/migration.json
index f5a6b35de4..7c7b09c341 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -842,9 +842,9 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
-# migration. The level is an integer between 1 and 9, where 1 means
+# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@@ -1023,9 +1023,9 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
-# migration. The level is an integer between 1 and 9, where 1 means
+# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@@ -1233,9 +1233,9 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
-# migration. The level is an integer between 1 and 9, where 1 means
+# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
diff --git a/qapi/qom.json b/qapi/qom.json
index 45cd47508b..3e8debf78c 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -870,7 +870,7 @@
# information read from devices and switches in conjunction with
# link characteristics read from PCIe Configuration space.
# To get the full path latency from CPU to CXL attached DRAM
-# CXL device: Add the latency from CPU to Generic Port (from
+# CXL device: Add the latency from CPU to Generic Port (from
# HMAT indexed via the node ID in this SRAT structure) to
# that for CXL bus links, the latency across intermediate switches
# and from the EP port to the actual memory. Bandwidth is more
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 03/13] qapi: Move (since X.Y) to end of description
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
2025-06-03 6:36 ` [PULL 01/13] qapi: Tidy up run-together sentences in doc comments Markus Armbruster
2025-06-03 6:36 ` [PULL 02/13] qapi: Tidy up whitespace " Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 04/13] qapi: Avoid breaking lines within (since X.Y) Markus Armbruster
` (10 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
By convention, we put (since X.Y) at the end of the description. Move
the ones that somehow ended up in the middle of the description to the
end.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-4-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 18 +++++++++---------
qapi/net.json | 6 +++---
2 files changed, 12 insertions(+), 12 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 13223df9b4..0700bd3d46 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1322,8 +1322,8 @@
# @incremental: only copy data described by the dirty bitmap.
# (since: 2.4)
#
-# @bitmap: only copy data described by the dirty bitmap. (since: 4.2)
-# Behavior on completion is determined by the BitmapSyncMode.
+# @bitmap: only copy data described by the dirty bitmap. Behavior on
+# completion is determined by the BitmapSyncMode. (since: 4.2)
#
# Since: 1.3
##
@@ -3415,8 +3415,8 @@
# Driver specific block device options for LUKS.
#
# @key-secret: the ID of a QCryptoSecret object providing the
-# decryption key (since 2.6). Mandatory except when doing a
-# metadata-only probe of the image.
+# decryption key. Mandatory except when doing a metadata-only
+# probe of the image. (since 2.6)
#
# @header: block device holding a detached LUKS header. (since 9.0)
#
@@ -4724,11 +4724,11 @@
#
# @driver: block driver name
#
-# @node-name: the node name of the new node (Since 2.0). This option
-# is required 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.
+# @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
+# an alphabetic character and may contain only alphanumeric
+# characters, '-', '.' and '_'. Their maximum length is 31
+# characters. (Since 2.0)
#
# @discard: discard-related options (default: ignore)
#
diff --git a/qapi/net.json b/qapi/net.json
index 310cc4fd19..e670efd6b0 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -150,9 +150,9 @@
# @domainname: guest-visible domain name of the virtual nameserver
# (since 3.0)
#
-# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since 2.6).
-# The network prefix is given in the usual hexadecimal IPv6
-# address notation.
+# @ipv6-prefix: IPv6 network prefix (default is fec0::). The network
+# prefix is given in the usual hexadecimal IPv6 address notation.
+# (since 2.6)
#
# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since
# 2.6)
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 04/13] qapi: Avoid breaking lines within (since X.Y)
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (2 preceding siblings ...)
2025-06-03 6:36 ` [PULL 03/13] qapi: Move (since X.Y) to end of description Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 05/13] qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus Markus Armbruster
` (9 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
Easier on the eyes and for grep.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-5-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 56 ++++++++++++++++++++++----------------------
qapi/introspect.json | 4 ++--
qapi/job.json | 12 +++++-----
qapi/machine.json | 4 ++--
qapi/migration.json | 36 ++++++++++++++--------------
qapi/net.json | 12 +++++-----
qapi/run-state.json | 4 ++--
qapi/ui.json | 4 ++--
8 files changed, 66 insertions(+), 66 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 0700bd3d46..cc48fc7122 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -31,8 +31,8 @@
# @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 (since
-# 5.2)
+# counter may be obtained through @query-replay command
+# (since 5.2)
#
# Since: 1.3
##
@@ -510,11 +510,11 @@
#
# @bps_max: total throughput limit during bursts, in bytes (Since 1.7)
#
-# @bps_rd_max: read throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_rd_max: read throughput limit during bursts, in bytes
+# (Since 1.7)
#
-# @bps_wr_max: write throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_wr_max: write throughput limit during bursts, in bytes
+# (Since 1.7)
#
# @iops_max: total I/O operations per second during bursts, in bytes
# (Since 1.7)
@@ -951,11 +951,11 @@
# @unmap_operations: The number of unmap operations performed by the
# device (Since 4.2)
#
-# @rd_total_time_ns: Total time spent on reads in nanoseconds (since
-# 0.15).
+# @rd_total_time_ns: Total time spent on reads in nanoseconds
+# (since 0.15)
#
-# @wr_total_time_ns: Total time spent on writes in nanoseconds (since
-# 0.15).
+# @wr_total_time_ns: Total time spent on writes in nanoseconds
+# (since 0.15)
#
# @zone_append_total_time_ns: Total time spent on zone append writes
# in nanoseconds (since 8.1)
@@ -1502,15 +1502,15 @@
#
# @device: the name of the device to take a snapshot of.
#
-# @node-name: graph node name to generate the snapshot from (Since
-# 2.0)
+# @node-name: graph node name to generate the snapshot from
+# (Since 2.0)
#
# @snapshot-file: the target of the new overlay image. If the file
# exists, or if it is a device, the overlay will be created in the
# existing file/device. Otherwise, a new file will be created.
#
-# @snapshot-node-name: the graph node name of the new image (Since
-# 2.0)
+# @snapshot-node-name: the graph node name of the new image
+# (Since 2.0)
#
# @format: the format of the overlay image, default is 'qcow2'.
#
@@ -1785,8 +1785,8 @@
# 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
-# block-job-complete command after getting the ready event. (Since
-# 2.0)
+# block-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
@@ -2169,8 +2169,8 @@
# @format: the format of the new destination, default is to probe if
# @mode is 'existing', else the format of the source
#
-# @node-name: the new block driver state node name in the graph (Since
-# 2.1)
+# @node-name: the new block driver state node name in the graph
+# (Since 2.1)
#
# @replaces: with sync=full graph node name to be replaced by the new
# image when a whole image copy is done. This can be used to
@@ -2593,11 +2593,11 @@
#
# @bps_max: total throughput limit during bursts, in bytes (Since 1.7)
#
-# @bps_rd_max: read throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_rd_max: read throughput limit during bursts, in bytes
+# (Since 1.7)
#
-# @bps_wr_max: write throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_wr_max: write throughput limit during bursts, in bytes
+# (Since 1.7)
#
# @iops_max: total I/O operations per second during bursts, in bytes
# (Since 1.7)
@@ -3655,8 +3655,8 @@
# this feature. (since 2.5)
#
# @encrypt: Image decryption options. Mandatory for encrypted images,
-# except when doing a metadata-only probe of the image. (since
-# 2.10)
+# except when doing a metadata-only probe of the image.
+# (since 2.10)
#
# @data-file: reference to or definition of the external data file.
# This may only be specified for images that require an external
@@ -4326,8 +4326,8 @@
# @user: Ceph id name.
#
# @auth-client-required: Acceptable authentication modes. This maps
-# to Ceph configuration option "auth_client_required". (Since
-# 3.0)
+# to Ceph configuration option "auth_client_required".
+# (Since 3.0)
#
# @key-secret: ID of a QCryptoSecret object providing a key for cephx
# authentication. This maps to Ceph configuration option "key".
@@ -4581,8 +4581,8 @@
# error. During the first @reconnect-delay seconds, all requests
# are paused and will be rerun on a successful reconnect. After
# that time, any delayed requests and all future requests before a
-# successful reconnect will immediately fail. Default 0 (Since
-# 4.2)
+# successful reconnect will immediately fail. Default 0
+# (Since 4.2)
#
# @open-timeout: In seconds. If zero, the nbd driver tries the
# connection only once, and fails to open if the connection fails.
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 01bb242947..95724ee2d2 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -154,8 +154,8 @@
#
# Additional SchemaInfo members for meta-type 'enum'.
#
-# @members: the enum type's members, in no particular order (since
-# 6.2).
+# @members: the enum type's members, in no particular order.
+# (since 6.2)
#
# @values: the enumeration type's member names, in no particular
# order. Redundant with @members. Just for backward
diff --git a/qapi/job.json b/qapi/job.json
index c53c96cce8..9ddba537db 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -20,14 +20,14 @@
#
# @create: image creation job type, see "blockdev-create" (since 3.0)
#
-# @amend: image options amend job type, see "x-blockdev-amend" (since
-# 5.1)
+# @amend: image options amend job type, see "x-blockdev-amend"
+# (since 5.1)
#
-# @snapshot-load: snapshot load job type, see "snapshot-load" (since
-# 6.0)
+# @snapshot-load: snapshot load job type, see "snapshot-load"
+# (since 6.0)
#
-# @snapshot-save: snapshot save job type, see "snapshot-save" (since
-# 6.0)
+# @snapshot-save: snapshot save job type, see "snapshot-save"
+# (since 6.0)
#
# @snapshot-delete: snapshot delete job type, see "snapshot-delete"
# (since 6.0)
diff --git a/qapi/machine.json b/qapi/machine.json
index 069e87d16a..5eb67fc4e9 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -182,8 +182,8 @@
# @default-cpu-type: default CPU model typename if none is requested
# via the -cpu argument. (since 4.2)
#
-# @default-ram-id: the default ID of initial RAM memory backend (since
-# 5.2)
+# @default-ram-id: the default ID of initial RAM memory backend
+# (since 5.2)
#
# @acpi: machine type supports ACPI (since 8.0)
#
diff --git a/qapi/migration.json b/qapi/migration.json
index 7c7b09c341..7d1ec06605 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -57,8 +57,8 @@
#
# @dirty-sync-missed-zero-copy: Number of times dirty RAM
# synchronization could not avoid copying dirty pages. This is
-# between 0 and @dirty-sync-count * @multifd-channels. (since
-# 7.1)
+# between 0 and @dirty-sync-count * @multifd-channels.
+# (since 7.1)
#
# Since: 0.14
##
@@ -137,16 +137,16 @@
#
# @active: in the process of doing migration.
#
-# @postcopy-active: like active, but now in postcopy mode. (since
-# 2.5)
+# @postcopy-active: like active, but now in postcopy mode.
+# (since 2.5)
#
# @postcopy-paused: during postcopy but paused. (since 3.0)
#
# @postcopy-recover-setup: setup phase for a postcopy recovery
# process, preparing for a recovery phase to start. (since 9.1)
#
-# @postcopy-recover: trying to recover from a paused postcopy. (since
-# 3.0)
+# @postcopy-recover: trying to recover from a paused postcopy.
+# (since 3.0)
#
# @completed: migration is finished.
#
@@ -422,8 +422,8 @@
# for precopy. (since 2.10)
#
# @pause-before-switchover: Pause outgoing migration before
-# serialising device state and before disabling block IO (since
-# 2.11)
+# serialising device state and before disabling block IO
+# (since 2.11)
#
# @multifd: Use more than one fd for migration (since 4.0)
#
@@ -697,8 +697,8 @@
# @alias: An alias name for migration (for example the bitmap name on
# the opposite site).
#
-# @transform: Allows the modification of the migrated bitmap. (since
-# 6.0)
+# @transform: Allows the modification of the migrated bitmap.
+# (since 6.0)
#
# Since: 5.2
##
@@ -770,8 +770,8 @@
# specified by @cpu-throttle-increment and the one generated by
# ideal CPU percentage. Therefore, it is compatible to
# traditional throttling, meanwhile the throttle increment won't
-# be excessive at tail stage. The default value is false. (Since
-# 5.1)
+# be excessive at tail stage. The default value is false.
+# (Since 5.1)
#
# @tls-creds: ID of the 'tls-creds' object that provides credentials
# for establishing a TLS connection over the migration data
@@ -951,8 +951,8 @@
# specified by @cpu-throttle-increment and the one generated by
# ideal CPU percentage. Therefore, it is compatible to
# traditional throttling, meanwhile the throttle increment won't
-# be excessive at tail stage. The default value is false. (Since
-# 5.1)
+# be excessive at tail stage. The default value is false.
+# (Since 5.1)
#
# @tls-creds: ID of the 'tls-creds' object that provides credentials
# for establishing a TLS connection over the migration data
@@ -1148,8 +1148,8 @@
# percentage. The default value is 50. (Since 5.0)
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are
-# throttled when migration auto-converge is activated. (Since
-# 2.7)
+# throttled when migration auto-converge is activated.
+# (Since 2.7)
#
# @cpu-throttle-increment: throttle percentage increase each time
# auto-converge detects that migration is not making progress.
@@ -1165,8 +1165,8 @@
# specified by @cpu-throttle-increment and the one generated by
# ideal CPU percentage. Therefore, it is compatible to
# traditional throttling, meanwhile the throttle increment won't
-# be excessive at tail stage. The default value is false. (Since
-# 5.1)
+# be excessive at tail stage. The default value is false.
+# (Since 5.1)
#
# @tls-creds: ID of the 'tls-creds' object that provides credentials
# for establishing a TLS connection over the migration data
diff --git a/qapi/net.json b/qapi/net.json
index e670efd6b0..97ea183981 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -154,8 +154,8 @@
# prefix is given in the usual hexadecimal IPv6 address notation.
# (since 2.6)
#
-# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since
-# 2.6)
+# @ipv6-prefixlen: IPv6 network prefix length (default is 64)
+# (since 2.6)
#
# @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
#
@@ -387,8 +387,8 @@
#
# @hubid: hub identifier number
#
-# @netdev: used to connect hub to a netdev instead of a device (since
-# 2.12)
+# @netdev: used to connect hub to a netdev instead of a device
+# (since 2.12)
#
# Since: 1.2
##
@@ -510,8 +510,8 @@
# @queues: number of queues to be created for multiqueue vhost-vdpa
# (default: 1)
#
-# @x-svq: Start device with (experimental) shadow virtqueue. (Since
-# 7.1) (default: false)
+# @x-svq: Start device with (experimental) shadow virtqueue.
+# (Since 7.1) (default: false)
#
# Features:
#
diff --git a/qapi/run-state.json b/qapi/run-state.json
index ee11adc508..ebfeb669ab 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -365,8 +365,8 @@
# @shutdown: Shutdown the VM and exit, according to the shutdown
# action
#
-# @exit-failure: Shutdown the VM and exit with nonzero status (since
-# 7.1)
+# @exit-failure: Shutdown the VM and exit with nonzero status
+# (since 7.1)
#
# Since: 6.0
##
diff --git a/qapi/ui.json b/qapi/ui.json
index 3d0c853c9a..7cfedb3914 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -175,8 +175,8 @@
# @filename: the path of a new file to store the image
#
# @device: ID of the display device that should be dumped. If this
-# parameter is missing, the primary display will be used. (Since
-# 2.12)
+# parameter is missing, the primary display will be used.
+# (Since 2.12)
#
# @head: head to use in case the device supports multiple heads. If
# this parameter is missing, head #0 will be used. Also note that
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 05/13] qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (3 preceding siblings ...)
2025-06-03 6:36 ` [PULL 04/13] qapi: Avoid breaking lines within (since X.Y) Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 06/13] qapi: Correct spelling of QEMU in doc comments Markus Armbruster
` (8 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, David Hildenbrand, Eric Blake
There is a (Since: 2.11) in a query-hotpluggable-cpus example.
Versioning information ought to be in the command description, not
examples. The command description is basically empty (there is a TODO
about it).
What exactly didn't work before 2.11 is not quite clear from the
documentation. The example was added in commit 4dc3b151882 (s390x:
implement query-hotpluggable-cpus), which suggests the command failed
for the s390x target until then. This was almost eight years ago, and
I doubt anyone still cares about this detail. Simply delete
the problematic (Since: 2.11).
Cc: David Hildenbrand <david@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-6-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/machine.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qapi/machine.json b/qapi/machine.json
index 5eb67fc4e9..230b9b20dd 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1089,7 +1089,7 @@
# :annotated:
#
# For s390x-virtio-ccw machine type started with
-# ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11)::
+# ``-smp 1,maxcpus=2 -cpu qemu``::
#
# -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 06/13] qapi: Correct spelling of QEMU in doc comments
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (4 preceding siblings ...)
2025-06-03 6:36 ` [PULL 05/13] qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 07/13] qapi: Fix capitalization " Markus Armbruster
` (7 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
Improve awkward phrasing in migrate-incoming While there.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-7-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/audio.json | 8 ++++----
qapi/block-core.json | 10 +++++-----
qapi/block-export.json | 2 +-
qapi/char.json | 6 +++---
qapi/introspect.json | 4 ++--
qapi/migration.json | 8 ++++----
qapi/run-state.json | 6 +++---
qapi/transaction.json | 2 +-
qapi/uefi.json | 2 +-
qapi/ui.json | 4 ++--
10 files changed, 26 insertions(+), 26 deletions(-)
diff --git a/qapi/audio.json b/qapi/audio.json
index 8de4430578..16de231f6d 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -309,9 +309,9 @@
#
# @name: name of the sink/source to use
#
-# @stream-name: name of the PulseAudio stream created by qemu. Can be
+# @stream-name: name of the PulseAudio stream created by QEMU. Can be
# used to identify the stream in PulseAudio when you create
-# multiple PulseAudio devices or run multiple qemu instances
+# multiple PulseAudio devices or run multiple QEMU instances
# (default: audiodev's id, since 4.2)
#
# @latency: latency you want PulseAudio to achieve in microseconds
@@ -353,9 +353,9 @@
#
# @name: name of the sink/source to use
#
-# @stream-name: name of the PipeWire stream created by qemu. Can be
+# @stream-name: name of the PipeWire stream created by QEMU. Can be
# used to identify the stream in PipeWire when you create multiple
-# PipeWire devices or run multiple qemu instances (default:
+# PipeWire devices or run multiple QEMU instances (default:
# audiodev's id)
#
# @latency: latency you want PipeWire to achieve in microseconds
diff --git a/qapi/block-core.json b/qapi/block-core.json
index cc48fc7122..b6447e847e 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2030,7 +2030,7 @@
#
# @id: Block graph node identifier. This @id is generated only for
# x-debug-query-block-graph and does not relate to any other
-# identifiers in Qemu.
+# identifiers in QEMU.
#
# @type: Type of graph node. Can be one of block-backend, block-job
# or block-driver-state.
@@ -2794,7 +2794,7 @@
# 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;
# see below) and can be specified using its device or node name.
-# Earlier qemu versions only allowed 'device' to name the top level
+# Earlier QEMU versions only allowed 'device' to name the top level
# node; presence of the 'base-node' parameter during introspection can
# be used as a witness of the enhanced semantics of 'device'.
#
@@ -3196,7 +3196,7 @@
#
# Selects the AIO backend to handle I/O requests
#
-# @threads: Use qemu's thread pool
+# @threads: Use QEMU's thread pool
#
# @native: Use native AIO backend (only Linux and Windows)
#
@@ -5157,10 +5157,10 @@
##
# @BlockdevQcow2Version:
#
-# @v2: The original QCOW2 format as introduced in qemu 0.10 (version
+# @v2: The original QCOW2 format as introduced in QEMU 0.10 (version
# 2)
#
-# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3)
+# @v3: The extended QCOW2 format as introduced in QEMU 1.1 (version 3)
#
# Since: 2.12
##
diff --git a/qapi/block-export.json b/qapi/block-export.json
index 04190b503c..ed4deb54db 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -169,7 +169,7 @@
# @growable: Whether writes beyond the EOF should grow the block node
# accordingly. (default: false)
#
-# @allow-other: If this is off, only qemu's user is allowed access to
+# @allow-other: If this is off, only QEMU's user is allowed access to
# this export. That cannot be changed even with chmod or chown.
# Enabling this option will allow other users access to the export
# with the FUSE mount option "allow_other". Note that using
diff --git a/qapi/char.json b/qapi/char.json
index f79216e4d2..df6e325e2e 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -351,7 +351,7 @@
# Configuration info for stdio chardevs.
#
# @signal: Allow signals (such as SIGINT triggered by ^C) be delivered
-# to qemu. Default: true.
+# to QEMU. Default: true.
#
# Since: 1.5
##
@@ -443,7 +443,7 @@
##
# @ChardevQemuVDAgent:
#
-# Configuration info for qemu vdagent implementation.
+# Configuration info for QEMU vdagent implementation.
#
# @mouse: enable/disable mouse, default is enabled.
#
@@ -656,7 +656,7 @@
##
# @ChardevQemuVDAgentWrapper:
#
-# @data: Configuration info for qemu vdagent implementation
+# @data: Configuration info for QEMU vdagent implementation
#
# Since: 6.1
##
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 95724ee2d2..e9e0297282 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -26,9 +26,9 @@
# the QAPI schema.
#
# Furthermore, while we strive to keep the QMP wire format
-# backwards-compatible across qemu versions, the introspection output
+# backwards-compatible across QEMU versions, the introspection output
# is not guaranteed to have the same stability. For example, one
-# version of qemu may list an object member as an optional
+# version of QEMU may list an object member as an optional
# non-variant, while another lists the same member only through the
# object's variants; or the type of a member may change from a generic
# string into a specific enum or from one specific type into an
diff --git a/qapi/migration.json b/qapi/migration.json
index 7d1ec06605..84edcf81e4 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -415,7 +415,7 @@
# 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
+# @release-ram: if enabled, QEMU will free the migrated ram pages on
# the source during postcopy-ram migration. (since 2.9)
#
# @return-path: If enabled, migration will use the return path even
@@ -1500,7 +1500,7 @@
##
# @x-colo-lost-heartbeat:
#
-# Tell qemu that heartbeat is lost, request it to do takeover
+# Tell QEMU that heartbeat is lost, request it to do takeover
# procedures. If this command is sent to the PVM, the Primary side
# will exit COLO mode. If sent to the Secondary, the Secondary side
# will run failover work, then takes over server operation to become
@@ -1729,8 +1729,8 @@
##
# @migrate-incoming:
#
-# Start an incoming migration, the qemu must have been started with
-# -incoming defer
+# Start an incoming migration. QEMU must have been started with
+# -incoming defer.
#
# @uri: The Uniform Resource Identifier identifying the source or
# address to listen on
diff --git a/qapi/run-state.json b/qapi/run-state.json
index ebfeb669ab..fcc00c805b 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -135,19 +135,19 @@
##
# @SHUTDOWN:
#
-# Emitted when the virtual machine has shut down, indicating that qemu
+# Emitted when the virtual machine has shut down, indicating that QEMU
# is 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)
+# 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
+# specified, QEMU will not exit, and a STOP event will eventually
# follow the SHUTDOWN event.
#
# Since: 0.12
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 021e383496..5c3394919e 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -223,7 +223,7 @@
# exists, the request will be rejected. Only some image formats
# support it, for example, qcow2, and rbd,
#
-# On failure, qemu will try delete the newly created internal snapshot
+# On failure, QEMU will try delete the newly created internal snapshot
# in the transaction. When an I/O error occurs during deletion, the
# user needs to fix it later with qemu-img or other command.
#
diff --git a/qapi/uefi.json b/qapi/uefi.json
index bdfcabe1df..6592183d6c 100644
--- a/qapi/uefi.json
+++ b/qapi/uefi.json
@@ -5,7 +5,7 @@
##
# = UEFI Variable Store
#
-# The qemu efi variable store implementation (hw/uefi/) uses this to
+# The QEMU efi variable store implementation (hw/uefi/) uses this to
# store non-volatile variables in json format on disk.
#
# This is an existing format already supported by (at least) two other
diff --git a/qapi/ui.json b/qapi/ui.json
index 7cfedb3914..514fa159b1 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1526,12 +1526,12 @@
#
# Display (user interface) options.
#
-# @type: Which DisplayType qemu should use.
+# @type: Which DisplayType QEMU should use.
#
# @full-screen: Start user interface in fullscreen mode
# (default: off).
#
-# @window-close: Allow to quit qemu with window close button
+# @window-close: Allow to quit QEMU with window close button
# (default: on).
#
# @show-cursor: Force showing the mouse cursor (default: off).
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 07/13] qapi: Fix capitalization in doc comments
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (5 preceding siblings ...)
2025-06-03 6:36 ` [PULL 06/13] qapi: Correct spelling of QEMU in doc comments Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 08/13] qapi: Use proper markup instead of CAPS for emphasis " Markus Armbruster
` (6 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-8-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 6 +++---
qapi/block.json | 2 +-
qapi/cryptodev.json | 2 +-
qapi/cxl.json | 2 +-
qapi/machine.json | 2 +-
qapi/misc-i386.json | 2 +-
qapi/run-state.json | 2 +-
qapi/transaction.json | 2 +-
8 files changed, 10 insertions(+), 10 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index b6447e847e..f0faca1054 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1337,7 +1337,7 @@
# bitmap when used for data copy operations.
#
# @on-success: The bitmap is only synced when the operation is
-# successful. This is the behavior always used for 'INCREMENTAL'
+# successful. This is the behavior always used for incremental
# backups.
#
# @never: The bitmap is never synchronized with the operation, and is
@@ -1589,7 +1589,7 @@
#
# @bitmap-mode: Specifies the type of data the bitmap should contain
# after the operation concludes. Must be present if a bitmap was
-# provided, Must NOT be present otherwise. (Since 4.2)
+# provided, must NOT be present otherwise. (Since 4.2)
#
# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
@@ -1840,7 +1840,7 @@
# @speed: the maximum speed, in bytes per second
#
# @on-error: the action to take on an error. 'ignore' means that the
-# request should be retried. (default: report; Since: 5.0)
+# request should be retried. (default: report; since: 5.0)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the commit job inserts into the graph above
diff --git a/qapi/block.json b/qapi/block.json
index f5374bd86c..1490a1a17f 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -48,7 +48,7 @@
##
# @FloppyDriveType:
#
-# Type of Floppy drive to be emulated by the Floppy Disk Controller.
+# Type of floppy drive to be emulated by the Floppy Disk Controller.
#
# @144: 1.44MB 3.5" drive
#
diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index 28b97eb3da..b13db26403 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -15,7 +15,7 @@
#
# @sym: symmetric encryption
#
-# @asym: asymmetric Encryption
+# @asym: asymmetric encryption
#
# Since: 8.0
##
diff --git a/qapi/cxl.json b/qapi/cxl.json
index dd947d3bbc..8f2e9237b1 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -117,7 +117,7 @@
# @nibble-mask: Identifies one or more nibbles that the error affects
#
# @bank-group: Bank group of the memory event location, incorporating
-# a number of Banks.
+# a number of banks.
#
# @bank: Bank of the memory event location. A single bank is accessed
# per read or write of the memory.
diff --git a/qapi/machine.json b/qapi/machine.json
index 230b9b20dd..0650b8de71 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -811,7 +811,7 @@
#
# @policy: the write policy, none/write-back/write-through.
#
-# @line: the cache Line size in bytes.
+# @line: the cache line size in bytes.
#
# Since: 5.0
##
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 3b5346425a..5fefa0a484 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -195,7 +195,7 @@
#
# @cbitpos: C-bit location in page table entry
#
-# @reduced-phys-bits: Number of physical Address bit reduction when
+# @reduced-phys-bits: Number of physical address bit reduction when
# SEV is enabled
#
# Since: 2.12
diff --git a/qapi/run-state.json b/qapi/run-state.json
index fcc00c805b..fd09beb35c 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -62,7 +62,7 @@
##
# @ShutdownCause:
#
-# An enumeration of reasons for a Shutdown.
+# An enumeration of reasons for a shutdown.
#
# @none: No shutdown request pending
#
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 5c3394919e..9d9e7af26c 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -21,7 +21,7 @@
##
# @ActionCompletionMode:
#
-# An enumeration of Transactional completion modes.
+# An enumeration of transactional completion modes.
#
# @individual: Do not attempt to cancel any other Actions if any
# Actions fail after the Transaction request succeeds. All
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 08/13] qapi: Use proper markup instead of CAPS for emphasis in doc comments
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (6 preceding siblings ...)
2025-06-03 6:36 ` [PULL 07/13] qapi: Fix capitalization " Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 09/13] qapi: Spell JSON null correctly in blockdev-reopen documentation Markus Armbruster
` (5 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-9-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 2 +-
qapi/dump.json | 6 +++---
qapi/migration.json | 26 +++++++++++++-------------
qapi/misc.json | 4 ++--
4 files changed, 19 insertions(+), 19 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index f0faca1054..7b0548dc2e 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1589,7 +1589,7 @@
#
# @bitmap-mode: Specifies the type of data the bitmap should contain
# after the operation concludes. Must be present if a bitmap was
-# provided, must NOT be present otherwise. (Since 4.2)
+# provided, must **not** be present otherwise. (Since 4.2)
#
# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
diff --git a/qapi/dump.json b/qapi/dump.json
index f2835c0b47..d0ba1f0596 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -54,9 +54,9 @@
# @paging: if true, do paging to get guest's memory mapping. This
# allows 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.
+# **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.
#
# Also, paging=true has the following limitations:
#
diff --git a/qapi/migration.json b/qapi/migration.json
index 84edcf81e4..4963f6ca12 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -407,7 +407,7 @@
# @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
+# 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
@@ -801,10 +801,10 @@
# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
-# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations
-# when making decisions to switchover. By default, this value is
-# zero, which means QEMU will estimate the bandwidth
+# migration can use during switchover phase. **Note:** this does
+# not limit the bandwidth during switchover, but only for
+# calculations when making decisions to switchover. By default,
+# this value is zero, which means QEMU will estimate the bandwidth
# automatically. This can be set when the estimated value is not
# accurate, while the user is able to guarantee such bandwidth is
# available when switching over. When specified correctly, this
@@ -982,10 +982,10 @@
# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
-# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations
-# when making decisions to switchover. By default, this value is
-# zero, which means QEMU will estimate the bandwidth
+# migration can use during switchover phase. **Note:** this does
+# not limit the bandwidth during switchover, but only for
+# calculations when making decisions to switchover. By default,
+# this value is zero, which means QEMU will estimate the bandwidth
# automatically. This can be set when the estimated value is not
# accurate, while the user is able to guarantee such bandwidth is
# available when switching over. When specified correctly, this
@@ -1192,10 +1192,10 @@
# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
-# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations
-# when making decisions to switchover. By default, this value is
-# zero, which means QEMU will estimate the bandwidth
+# migration can use during switchover phase. **Note:** this does
+# not limit the bandwidth during switchover, but only for
+# calculations when making decisions to switchover. By default,
+# this value is zero, which means QEMU will estimate the bandwidth
# automatically. This can be set when the estimated value is not
# accurate, while the user is able to guarantee such bandwidth is
# available when switching over. When specified correctly, this
diff --git a/qapi/misc.json b/qapi/misc.json
index dcf9f7df5b..4b9e601cfa 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -222,8 +222,8 @@
# .. note:: This command only exists as a stop-gap. Its use is highly
# discouraged. The semantics of this command are not guaranteed:
# this means that command names, arguments and responses can change
-# or be removed at ANY time. Applications that rely on long term
-# stability guarantees should NOT use this command.
+# or be removed at **any** time. Applications that rely on long
+# term stability guarantees should **not** use this command.
#
# Known limitations:
#
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 09/13] qapi: Spell JSON null correctly in blockdev-reopen documentation
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (7 preceding siblings ...)
2025-06-03 6:36 ` [PULL 08/13] qapi: Use proper markup instead of CAPS for emphasis " Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 10/13] qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs Markus Armbruster
` (4 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Kevin Wolf, Eric Blake
The doc comment misspells JSON null as NULL. Fix that.
Cc: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-10-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 7b0548dc2e..f8f89ee2d7 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -4947,7 +4947,7 @@
# 3) A reference to a different node: the current child is replaced
# with the specified one.
#
-# 4) NULL: the current child (if any) is detached.
+# 4) null: the current child (if any) is detached.
#
# Options (1) and (2) are supported in all cases. Option (3) is
# supported for @file and @backing, and option (4) for @backing only.
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 10/13] qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (8 preceding siblings ...)
2025-06-03 6:36 ` [PULL 09/13] qapi: Spell JSON null correctly in blockdev-reopen documentation Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 11/13] qapi: Mention both job-cancel and block-job-cancel in doc comments Markus Armbruster
` (3 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
We deprecated several block-job-FOO commands in commit
b836bf2ab68 (qapi/block-core: deprecate some block-job- APIs). Update
the doc comments to refer to their replacements instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-11-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 57 ++++++++++++++++++++++----------------------
1 file changed, 28 insertions(+), 29 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index f8f89ee2d7..6e5b90d5df 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1606,16 +1606,16 @@
# 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 @block-job-finalize
-# before making any block graph changes. When true, this job will
+# 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
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 2.12)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 2.12)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the backup job inserts into the graph above
@@ -1785,8 +1785,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
-# block-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
@@ -1848,16 +1847,16 @@
# autogenerated. (Since: 2.9)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# 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
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# Features:
#
@@ -2212,16 +2211,16 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# 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
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# Since: 1.3
##
@@ -2531,16 +2530,16 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# 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
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# @target-is-zero: Assume the destination reads as all zeroes before
# the mirror started. Setting this to true can speed up the
@@ -2859,16 +2858,16 @@
# autogenerated. (Since: 6.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# 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
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# Errors:
# - If @device does not exist, DeviceNotFound.
@@ -3077,7 +3076,7 @@
# This command will refuse to operate on any job that has not yet
# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
# make use of the BLOCK_JOB_READY event, block-job-cancel or
-# block-job-complete will still need to be used as appropriate.
+# job-complete will still need to be used as appropriate.
#
# @id: The job identifier.
#
@@ -5866,7 +5865,7 @@
# @BLOCK_JOB_PENDING:
#
# Emitted when a block job is awaiting explicit authorization to
-# finalize graph changes via @block-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.
#
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 11/13] qapi: Mention both job-cancel and block-job-cancel in doc comments
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (9 preceding siblings ...)
2025-06-03 6:36 ` [PULL 10/13] qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 12/13] qapi: Tidy up references to job state CONCLUDED Markus Armbruster
` (2 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
Several doc comments mention block-job-cancel where the more generic
job-cancel would also work. Adjust them to mention both.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-12-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 6e5b90d5df..ad6de151c8 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1894,7 +1894,7 @@
# 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 block-job-cancel command.
+# using the job-cancel or block-job-cancel command.
#
# Features:
#
@@ -1925,7 +1925,7 @@
# 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 block-job-cancel command.
+# using the job-cancel or block-job-cancel command.
#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
@@ -2788,7 +2788,7 @@
# immediately once streaming has started. The status of ongoing block
# streaming operations can be checked with query-block-jobs. The
# operation can be stopped before it has completed using the
-# 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;
@@ -3075,8 +3075,8 @@
#
# This command will refuse to operate on any job that has not yet
# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
-# make use of the BLOCK_JOB_READY event, block-job-cancel or
-# job-complete will still need to be used as appropriate.
+# make use of 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.
#
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 12/13] qapi: Tidy up references to job state CONCLUDED
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (10 preceding siblings ...)
2025-06-03 6:36 ` [PULL 11/13] qapi: Mention both job-cancel and block-job-cancel in doc comments Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 6:36 ` [PULL 13/13] qapi: Improve documentation around job state @concluded Markus Armbruster
2025-06-03 15:52 ` [PULL 00/13] QAPI patches patches for 2025-06-03 Stefan Hajnoczi
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
When talking about the job state machine, we refer to the states like
READY, ABORTING, CONCLUDED, and so forth. Except in two places, where
we use JOB_STATUS_CONCLUDED. Replace by CONCLUDED for consistency.
We should arguably use the JobStatus enum values instead. Left for
another day.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-13-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 6 +++---
qapi/job.json | 6 +++---
2 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index ad6de151c8..da390f85ac 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -3074,9 +3074,9 @@
# jobs.
#
# This command will refuse to operate on any job that has not yet
-# reached its terminal state, JOB_STATUS_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.
+# 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.
#
# @id: The job identifier.
#
diff --git a/qapi/job.json b/qapi/job.json
index 9ddba537db..441cd7772b 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -223,9 +223,9 @@
# jobs.
#
# This command will refuse to operate on any job that has not yet
-# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
-# make use of JOB_READY event, job-cancel or job-complete will still
-# need to be used as appropriate.
+# reached its terminal state, CONCLUDED. For jobs that make use of
+# the JOB_READY event, job-cancel or job-complete will still need to
+# be used as appropriate.
#
# @id: The job identifier.
#
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 13/13] qapi: Improve documentation around job state @concluded
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (11 preceding siblings ...)
2025-06-03 6:36 ` [PULL 12/13] qapi: Tidy up references to job state CONCLUDED Markus Armbruster
@ 2025-06-03 6:36 ` Markus Armbruster
2025-06-03 15:52 ` [PULL 00/13] QAPI patches patches for 2025-06-03 Stefan Hajnoczi
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:36 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Eric Blake
We use "the query list" in a few places. It's not entirely obvious
what that means. It's actually the output of query-jobs or
query-block-jobs.
Documentation of @auto-dismiss talks about the job disappearing from
the query list when it reaches state @concluded. This is less than
precise. The job doesn't merely disappear from the query list, it
disappears, period.
Documentation of JobStatus @concluded explains "the job will remain in
the query list until it is dismissed". Again less than precise. It
remains in state @concluded until dismissed.
Rephrase without use of "the query list" for clarity and precision.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-14-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 19 +++++++------------
qapi/job.json | 2 +-
2 files changed, 8 insertions(+), 13 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index da390f85ac..1df6644f0d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1417,8 +1417,8 @@
# @auto-finalize: Job will finalize itself when PENDING, moving to the
# CONCLUDED state. (since 2.12)
#
-# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the
-# NULL state and disappearing from the query list. (since 2.12)
+# @auto-dismiss: Job will dismiss itself when CONCLUDED, and
+# disappear. (since 2.12)
#
# @error: Error information if the job did not complete successfully.
# Not set if the job completed successfully. (since 2.12.1)
@@ -1614,8 +1614,7 @@
# @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
-# from the query list without user intervention. Defaults to
-# true. (Since 2.12)
+# without user intervention. Defaults to true. (Since 2.12)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the backup job inserts into the graph above
@@ -1855,8 +1854,7 @@
# @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
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Features:
#
@@ -2219,8 +2217,7 @@
# @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
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Since: 1.3
##
@@ -2538,8 +2535,7 @@
# @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
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# @target-is-zero: Assume the destination reads as all zeroes before
# the mirror started. Setting this to true can speed up the
@@ -2866,8 +2862,7 @@
# @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
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Errors:
# - If @device does not exist, DeviceNotFound.
diff --git a/qapi/job.json b/qapi/job.json
index 441cd7772b..126fa5ce60 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -74,7 +74,7 @@
# process.
#
# @concluded: The job has finished all work. If auto-dismiss was set
-# to false, the job will remain in the query list until it is
+# to false, the job will remain in this state until it is
# dismissed via @job-dismiss.
#
# @null: The job is in the process of being dismantled. This state
--
2.48.1
^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PULL 00/13] QAPI patches patches for 2025-06-03
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
` (12 preceding siblings ...)
2025-06-03 6:36 ` [PULL 13/13] qapi: Improve documentation around job state @concluded Markus Armbruster
@ 2025-06-03 15:52 ` Stefan Hajnoczi
13 siblings, 0 replies; 15+ messages in thread
From: Stefan Hajnoczi @ 2025-06-03 15:52 UTC (permalink / raw)
To: Markus Armbruster; +Cc: qemu-devel, stefanha
[-- Attachment #1: Type: text/plain, Size: 116 bytes --]
Applied, thanks.
Please update the changelog at https://wiki.qemu.org/ChangeLog/10.1 for any user-visible changes.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2025-06-03 18:49 UTC | newest]
Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-06-03 6:36 [PULL 00/13] QAPI patches patches for 2025-06-03 Markus Armbruster
2025-06-03 6:36 ` [PULL 01/13] qapi: Tidy up run-together sentences in doc comments Markus Armbruster
2025-06-03 6:36 ` [PULL 02/13] qapi: Tidy up whitespace " Markus Armbruster
2025-06-03 6:36 ` [PULL 03/13] qapi: Move (since X.Y) to end of description Markus Armbruster
2025-06-03 6:36 ` [PULL 04/13] qapi: Avoid breaking lines within (since X.Y) Markus Armbruster
2025-06-03 6:36 ` [PULL 05/13] qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus Markus Armbruster
2025-06-03 6:36 ` [PULL 06/13] qapi: Correct spelling of QEMU in doc comments Markus Armbruster
2025-06-03 6:36 ` [PULL 07/13] qapi: Fix capitalization " Markus Armbruster
2025-06-03 6:36 ` [PULL 08/13] qapi: Use proper markup instead of CAPS for emphasis " Markus Armbruster
2025-06-03 6:36 ` [PULL 09/13] qapi: Spell JSON null correctly in blockdev-reopen documentation Markus Armbruster
2025-06-03 6:36 ` [PULL 10/13] qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs Markus Armbruster
2025-06-03 6:36 ` [PULL 11/13] qapi: Mention both job-cancel and block-job-cancel in doc comments Markus Armbruster
2025-06-03 6:36 ` [PULL 12/13] qapi: Tidy up references to job state CONCLUDED Markus Armbruster
2025-06-03 6:36 ` [PULL 13/13] qapi: Improve documentation around job state @concluded Markus Armbruster
2025-06-03 15:52 ` [PULL 00/13] QAPI patches patches for 2025-06-03 Stefan Hajnoczi
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).