* [PATCH v2 1/9] qapi/audio: Fix description markup of AudiodevDBusOptions @nsamples
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 2/9] qapi: Refill doc comments to conform to conventions Markus Armbruster
` (8 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
The description of Member @nsamples is indented incorrectly. Comes
out like
Members:
[...]
nsamples (int, optional) – set the number of samples per
read/write calls (default to 480,
10ms at 48kHz).
Fixing the indentation makes it come out like
Members:
[...]
nsamples (int, optional) – set the number of samples per
read/write calls (default to 480, 10ms at 48kHz).
Fixes: 19c628f2f579 (dbus: add -audio dbus nsamples option)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
qapi/audio.json | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/qapi/audio.json b/qapi/audio.json
index 53142080f7..2df87b9710 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -76,8 +76,8 @@
#
# @out: options of the playback stream
#
-# @nsamples: set the number of samples per read/write calls (default to 480,
-# 10ms at 48kHz).
+# @nsamples: set the number of samples per read/write calls
+# (default to 480, 10ms at 48kHz).
#
# Since: 10.0
##
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 2/9] qapi: Refill doc comments to conform to conventions
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 1/9] qapi/audio: Fix description markup of AudiodevDBusOptions @nsamples Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 3/9] qapi: Clean up whitespace between definitions Markus Armbruster
` (7 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
Sweep the entire documentation again. Last done in commit
01bed0ff14b (qapi: Refill doc comments to conform to conventions).
To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3". Finds no
differences. Comparing with diff is not useful, as the reflown
paragraphs are visible there.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
qapi/accelerator.json | 3 +-
qapi/acpi-hest.json | 4 +-
qapi/block-core.json | 158 ++++++++++++++++++++-------------------
qapi/block-export.json | 26 ++++---
qapi/crypto.json | 7 +-
qapi/introspect.json | 8 +-
qapi/job.json | 30 ++++----
qapi/machine-common.json | 4 +-
qapi/machine-s390x.json | 4 +-
qapi/machine.json | 49 ++++++------
qapi/migration.json | 123 +++++++++++++++---------------
qapi/net.json | 23 +++---
qapi/qdev.json | 4 +-
qapi/qom.json | 44 +++++------
qapi/run-state.json | 19 ++---
qapi/sockets.json | 30 ++++----
qapi/stats.json | 4 +-
qapi/ui.json | 15 ++--
qapi/virtio.json | 4 +-
19 files changed, 293 insertions(+), 266 deletions(-)
diff --git a/qapi/accelerator.json b/qapi/accelerator.json
index 2b92060884..0cf5e0f9d9 100644
--- a/qapi/accelerator.json
+++ b/qapi/accelerator.json
@@ -87,7 +87,8 @@
#
# @enabled: the accelerator that is in use
#
-# @present: the list of accelerators that are built into this executable
+# @present: the list of accelerators that are built into this
+# executable
#
# Since: 10.2.0
##
diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json
index 28af1266a7..88c53eaf1b 100644
--- a/qapi/acpi-hest.json
+++ b/qapi/acpi-hest.json
@@ -5,8 +5,8 @@
##
# == GHESv2 CPER Error Injection
#
-# Defined since ACPI Specification 6.1,
-# section 18.3.2.8 Generic Hardware Error Source version 2. See:
+# Defined since ACPI Specification 6.1, section 18.3.2.8 Generic
+# Hardware Error Source version 2. See:
#
# https://uefi.org/sites/default/files/resources/ACPI_6_1.pdf
##
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 2c037183f0..b82af74256 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -159,14 +159,15 @@
##
# @ImageInfoSpecificRbd:
#
-# @encryption-format: Image encryption format. If encryption is enabled for the
-# image (see encrypted in BlockNodeInfo), this is the actual format in which the
-# image is accessed. If encryption is not enabled, this is the result of
-# probing when the image was opened, to give a suggestion which encryption
-# format could be enabled. Note that probing results can be changed by the
-# guest by writing a (possibly partial) encryption format header to the
-# image, so don't treat this information as trusted if the guest is not
-# trusted.
+# @encryption-format: Image encryption format. If encryption is
+# enabled for the image (see encrypted in BlockNodeInfo), this is
+# the actual format in which the image is accessed. If encryption
+# is not enabled, this is the result of probing when the image was
+# opened, to give a suggestion which encryption format could be
+# enabled. Note that probing results can be changed by the guest
+# by writing a (possibly partial) encryption format header to the
+# image, so don't treat this information as trusted if the guest
+# is not trusted.
#
# Since: 6.1
##
@@ -406,8 +407,8 @@
# node, annotated with information about that node in relation to its
# parent.
#
-# @name: Child name of the root node in the `BlockGraphInfo` struct, in
-# its role as the child of some undescribed parent node
+# @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
#
@@ -573,11 +574,12 @@
# @backing_file_depth: number of files in the backing file chain
# (since: 1.2)
#
-# @children: Information about child block nodes. (since: 10.1)
+# @children: Information about child block nodes. (since: 10.1)
#
-# @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)
+# @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)
#
# @encrypted: true if the backing device is encrypted
#
@@ -853,8 +855,8 @@
#
# 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.
+# Returns: a list describing each virtual block device. Filter nodes
+# that were created implicitly are skipped over.
#
# Since: 0.14
#
@@ -1693,11 +1695,12 @@
# different block device than @device).
#
# @on-cbw-error: policy defining behavior on I/O errors in
-# copy-before-write jobs; defaults to break-guest-write. (Since 10.1)
+# 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
-# 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)
#
@@ -1809,7 +1812,8 @@
#
# @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
#
@@ -1873,8 +1877,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
-# `job-complete` command after getting the ready event. (Since 2.0)
+# itself. The user needs to complete the job with the `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
@@ -1936,8 +1940,8 @@
# 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
-# 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)
#
@@ -2010,10 +2014,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
-# 'backup'. The operation can be stopped before it has completed
-# using the `job-cancel` or `block-job-cancel` command.
+# 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.
#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
@@ -2297,8 +2301,8 @@
# '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
-# 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)
#
@@ -2348,7 +2352,8 @@
#
# @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
##
@@ -2413,8 +2418,8 @@
# @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
-# from its storage too.
+# with `block-dirty-bitmap-add`. If the bitmap is persistent, remove
+# it from its storage too.
#
# Errors:
# - If @node is not a valid block device or node, DeviceNotFound
@@ -2612,8 +2617,8 @@
# '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
-# 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)
#
@@ -2939,8 +2944,8 @@
# 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
-# 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)
#
@@ -3110,16 +3115,16 @@
#
# 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`
-# 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.
+# 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.
#
# 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
-# occurs during the processing of this command: 1) the command itself
-# will fail; 2) the error will be processed according to the
+# `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
# operation.
#
@@ -3147,10 +3152,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
-# 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
+# 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
# jobs.
#
# This command will refuse to operate on any job that has not yet
@@ -3183,8 +3188,8 @@
# force ALL jobs in the transaction to finalize, so it is only
# necessary to instruct a single member job to finalize.
#
-# The command is applicable only to jobs which have @auto-finalize option
-# and only when this option is set to false.
+# The command is applicable only to jobs which have @auto-finalize
+# option and only when this option is set to false.
#
# @id: The job identifier.
#
@@ -4814,9 +4819,9 @@
# @cache: cache-related options
#
# @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)
+# 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)
#
# @read-only: whether the block device should be read-only (default:
# false). Note that some block drivers support only read-only
@@ -5008,11 +5013,12 @@
# cancelled.
#
# The command receives a list of block devices to reopen. For each
-# 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
-# any node name and any attempt to do it will result in an error.
+# 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 any node name and any attempt to do it will
+# result in an error.
#
# In the case of options that refer to child nodes, the behavior of
# this command depends on the value:
@@ -5031,10 +5037,10 @@
# 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
-# 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.
+# 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.
#
# Since: 6.1
##
@@ -5045,8 +5051,8 @@
##
# @blockdev-del:
#
-# 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
+# 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.
#
# @node-name: Name of the graph node to delete.
@@ -5078,18 +5084,18 @@
##
# @blockdev-set-active:
#
-# Activate or inactivate a block device. Use this to manage the handover of
-# block devices on migration with qemu-storage-daemon.
+# 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.
+# 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
-# nodes are affected by the operation.
+# @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,
-# false if they should be inactive.
+# @active: true if the nodes should be active when the command returns
+# success, false if they should be inactive.
#
# Since: 10.0
#
@@ -5945,9 +5951,9 @@
# @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
-# has converged first.
+# 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.
#
# @type: job type
#
diff --git a/qapi/block-export.json b/qapi/block-export.json
index 6878b89dcf..076954ef1a 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -38,8 +38,8 @@
##
# @NbdServerOptions:
#
-# Keep this type consistent with the `NbdServerOptionsLegacy` type. The
-# only intended difference is using `SocketAddress` instead of
+# 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).
@@ -51,8 +51,8 @@
##
# @NbdServerOptionsLegacy:
#
-# Keep this type consistent with the `NbdServerOptions` type. The only
-# intended difference is using `SocketAddressLegacy` instead of
+# 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).
@@ -125,8 +125,8 @@
# 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
-# domain sockets.
+# 'fd' `SocketAddress` types are supported. Passed fds must be
+# UNIX domain sockets.
#
# @logical-block-size: Logical block size in bytes. Defaults to 512
# bytes.
@@ -373,11 +373,12 @@
# cannot be moved to the iothread. The default is false.
# (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
-# the export type doesn't support running on an inactive node, an error is
-# returned. If false, inactive block nodes are automatically activated before
-# creating the export and trying to inactivate them later fails.
+# @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 the export type doesn't support running on
+# an inactive node, an error is 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)
#
# Since: 4.2
@@ -460,7 +461,8 @@
# @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/crypto.json b/qapi/crypto.json
index ab6eda4c2f..72ac718147 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -46,7 +46,8 @@
#
# @md5: MD5. Should not be used in any new code, legacy compat only
#
-# @sha1: SHA-1. Should not be used in any new code, legacy compat only
+# @sha1: SHA-1. Should not be used in any new code, legacy compat
+# only
#
# @sha224: SHA-224. (since 2.7)
#
@@ -377,8 +378,8 @@
# deactivate all keyslots that match password located in
# QCryptoSecret with this ID
#
-# @iter-time: Optional (for activation only). Number of milliseconds to
-# spend in PBKDF passphrase processing for the newly activated
+# @iter-time: Optional (for activation only). Number of milliseconds
+# to spend in PBKDF passphrase processing for the newly activated
# keyslot. Currently defaults to 2000.
#
# @keyslot: Optional. ID of the keyslot to activate/deactivate. For
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 53100714a8..c8432c8ed8 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -22,10 +22,10 @@
# `SchemaInfo`. This lets QMP clients figure out what commands and
# events are available in this QEMU, and their parameters and results.
#
-# However, the `SchemaInfo` can't reflect all the rules and restrictions
-# that apply to QMP. It's interface introspection (figuring out
-# what's there), not interface specification. The specification is in
-# the QAPI schema.
+# However, the `SchemaInfo` can't reflect all the rules and
+# restrictions that apply to QMP. It's interface introspection
+# (figuring out what's there), not interface specification. The
+# specification is in the QAPI schema.
#
# Furthermore, while we strive to keep the QMP wire format
# backwards-compatible across QEMU versions, the introspection output
diff --git a/qapi/job.json b/qapi/job.json
index 8b08350af2..0a301fc094 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -194,16 +194,16 @@
#
# 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`
-# 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.
+# 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.
#
# 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
-# occurs during the processing of this command: 1) the command itself
-# will fail; 2) the error will be processed according to the
+# `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
# operation.
#
@@ -218,16 +218,16 @@
#
# 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
+# 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
# 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 JOB_READY event, `job-cancel` or `job-complete` will still need to
-# be used as appropriate.
+# the JOB_READY event, `job-cancel` or `job-complete` will still need
+# to be used as appropriate.
#
# @id: The job identifier.
#
@@ -247,8 +247,8 @@
# force ALL jobs in the transaction to finalize, so it is only
# necessary to instruct a single member job to finalize.
#
-# The command is applicable only to jobs which have @auto-finalize option
-# and only when this option is set to false.
+# The command is applicable only to jobs which have @auto-finalize
+# option and only when this option is set to false.
#
# @id: The identifier of any job in the transaction, or of a job that
# is not part of any transaction.
diff --git a/qapi/machine-common.json b/qapi/machine-common.json
index ed3d20a2fb..92e84dfb14 100644
--- a/qapi/machine-common.json
+++ b/qapi/machine-common.json
@@ -87,8 +87,8 @@
#
# Cache information for SMP system.
#
-# @cache: Cache name, which is the combination of cache level
-# and cache type.
+# @cache: Cache name, which is the combination of cache level and
+# cache type.
#
# @topology: Cache topology level. It accepts the CPU topology
# enumeration as the parameter, i.e., CPUs in the same
diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json
index 8412668b67..ea430e1b88 100644
--- a/qapi/machine-s390x.json
+++ b/qapi/machine-s390x.json
@@ -123,8 +123,8 @@
##
# @SCLP_CPI_INFO_AVAILABLE:
#
-# Emitted when the Control-Program Identification data is available
-# in the QOM tree.
+# Emitted when the Control-Program Identification data is available in
+# the QOM tree.
#
# Features:
#
diff --git a/qapi/machine.json b/qapi/machine.json
index c6dc6fe69b..907cb25f75 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -620,8 +620,8 @@
##
# @NumaCpuOptions:
#
-# Option "-numa cpu" overrides default cpu to node mapping. It accepts
-# the same set of cpu properties as returned by
+# Option "-numa cpu" overrides default cpu to node mapping. It
+# accepts the same set of cpu properties as returned by
# `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where
# node-id could be used to override default node mapping.
#
@@ -686,8 +686,8 @@
# Set the system locality latency and bandwidth information between
# Initiator and Target proximity Domains.
#
-# For more information about `NumaHmatLBOptions`, see chapter 5.2.27.4:
-# Table 5-146 of ACPI 6.3 spec.
+# For more information about `NumaHmatLBOptions`, see chapter
+# 5.2.27.4: Table 5-146 of ACPI 6.3 spec.
#
# @initiator: the Initiator Proximity Domain.
#
@@ -743,8 +743,8 @@
# Cache write policy in the Memory Side Cache Information Structure of
# HMAT
#
-# For more information of `HmatCacheWritePolicy`, see chapter 5.2.27.5:
-# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
+# For more information of `HmatCacheWritePolicy`, see chapter
+# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @none: None (no memory side cache in this proximity domain, or cache
# write policy unknown)
@@ -763,8 +763,8 @@
#
# Set the memory side cache information for a given memory domain.
#
-# For more information of `NumaHmatCacheOptions`, see chapter 5.2.27.5:
-# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
+# For more information of `NumaHmatCacheOptions`, see chapter
+# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @node-id: the memory proximity domain to which the memory belongs.
#
@@ -959,7 +959,7 @@
# belongs to (since 7.1)
#
# @module-id: module number within the parent container the CPU
-# belongs to (since 9.1)
+# belongs to (since 9.1)
#
# @core-id: core number within the parent container the CPU belongs to
#
@@ -1090,7 +1090,7 @@
# @value: the target logical size of the VM in bytes. We can deduce
# the size of the balloon using this formula:
#
-# logical_vm_size = vm_ram_size - balloon_size
+# logical_vm_size = vm_ram_size - balloon_size
#
# From it we have: balloon_size = vm_ram_size - @value
#
@@ -1845,7 +1845,7 @@
# @version: Firmware version.
#
# @log: Firmware debug log, in base64 encoding. First and last log
-# line might be incomplete.
+# line might be incomplete.
#
# Since: 10.2
##
@@ -1859,8 +1859,8 @@
# Find firmware memory log buffer in guest memory, return content.
#
# @max-size: limit the amount of log data returned. Up to 1 MiB of
-# log data is allowed. In case the amount of log data is
-# larger than @max-size the tail of the log is returned.
+# log data is allowed. In case the amount of log data is larger
+# than @max-size the tail of the log is returned.
#
# Since: 10.2
##
@@ -2004,11 +2004,11 @@
# @query-cpu-model-comparison:
#
# Compares two CPU models, @modela and @modelb, returning how they
-# compare in a specific configuration. The results indicates how
-# both models compare regarding runnability. This result can be
-# used by tooling to make decisions if a certain CPU model will
-# run in a certain configuration or if a compatible CPU model has
-# to be created by baselining.
+# compare in a specific configuration. The results indicates how both
+# models compare regarding runnability. This result can be used by
+# tooling to make decisions if a certain CPU model will run in a
+# certain configuration or if a compatible CPU model has to be created
+# by baselining.
#
# Usually, a CPU model is compared against the maximum possible CPU
# model of a certain configuration (e.g. the "host" model for KVM).
@@ -2029,7 +2029,8 @@
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
-# Using `query-cpu-model-expansion` while using these is not advised.
+# Using `query-cpu-model-expansion` while using these is not
+# advised.
#
# Some architectures may not support comparing CPU models. s390x
# supports comparing CPU models.
@@ -2083,7 +2084,8 @@
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
-# Using `query-cpu-model-expansion` while using these is not advised.
+# Using `query-cpu-model-expansion` while using these is not
+# advised.
#
# Some architectures may not support baselining CPU models. s390x
# supports baselining CPU models.
@@ -2114,8 +2116,8 @@
#
# @model: the expanded `CpuModelInfo`.
#
-# @deprecated-props: an optional list of properties that are flagged as
-# deprecated by the CPU vendor. The list depends on the
+# @deprecated-props: an optional list of properties that are flagged
+# as deprecated by the CPU vendor. The list depends on the
# `CpuModelExpansionType`: "static" properties are a subset of the
# enabled-properties for the expanded model; "full" properties are
# a set of properties that are deprecated across all models for
@@ -2151,7 +2153,8 @@
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
-# Using `query-cpu-model-expansion` while using these is not advised.
+# Using `query-cpu-model-expansion` while using these is not
+# advised.
#
# Some architectures may not support all expansion types. s390x
# supports "full" and "static". Arm only supports "full".
diff --git a/qapi/migration.json b/qapi/migration.json
index be0f3fcc12..4dd1098219 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -160,11 +160,11 @@
#
# @pre-switchover: Paused before device serialisation. (since 2.11)
#
-# @device: During device serialisation (also known as switchover phase).
-# Before 9.2, this is only used when (1) in precopy, and (2) when
-# pre-switchover capability is enabled. After 10.0, this state will
-# always be present for every migration procedure as the switchover
-# phase. (since 2.11)
+# @device: During device serialisation (also known as switchover
+# phase). Before 9.2, this is only used when (1) in precopy, and
+# (2) when pre-switchover capability is enabled. After 10.0, this
+# state will always be present for every migration procedure as
+# the switchover phase. (since 2.11)
#
# @wait-unplug: wait for device unplug request by guest OS to be
# completed. (since 4.2)
@@ -238,31 +238,34 @@
# This is only present when the postcopy-blocktime migration
# capability is enabled. (Since 3.0)
#
-# @postcopy-latency: average remote page fault latency (in ns). Note that
-# this doesn't include all faults, but only the ones that require a
-# remote page request. So it should be always bigger than the real
-# average page fault latency. This is only present when the
-# postcopy-blocktime migration capability is enabled. (Since 10.1)
-#
-# @postcopy-latency-dist: remote page fault latency distributions. Each
-# element of the array is the number of faults that fall into the
-# bucket period. For the N-th bucket (N>=0), the latency window is
-# [2^Nus, 2^(N+1)us). For example, the 8th element stores how many
-# remote faults got resolved within [256us, 512us) window. This is only
-# present when the postcopy-blocktime migration capability is enabled.
+# @postcopy-latency: average remote page fault latency (in ns). Note
+# that this doesn't include all faults, but only the ones that
+# require a remote page request. So it should be always bigger
+# than the real average page fault latency. This is only present
+# when the postcopy-blocktime migration capability is enabled.
# (Since 10.1)
#
-# @postcopy-vcpu-latency: average remote page fault latency per vCPU (in
-# ns). It has the same definition of @postcopy-latency, but instead
-# this is the per-vCPU statistics. This is only present when the
-# postcopy-blocktime migration capability is enabled. (Since 10.1)
-#
-# @postcopy-non-vcpu-latency: average remote page fault latency for all
-# faults happend in non-vCPU threads (in ns). It has the same
-# definition of @postcopy-latency but this only provides statistics to
-# non-vCPU faults. This is only present when the postcopy-blocktime
+# @postcopy-latency-dist: remote page fault latency distributions.
+# Each element of the array is the number of faults that fall into
+# the bucket period. For the N-th bucket (N>=0), the latency
+# window is [2^Nus, 2^(N+1)us). For example, the 8th element
+# stores how many remote faults got resolved within [256us, 512us)
+# window. This is only present when the postcopy-blocktime
# migration capability is enabled. (Since 10.1)
#
+# @postcopy-vcpu-latency: average remote page fault latency per vCPU
+# (in ns). It has the same definition of @postcopy-latency, but
+# instead this is the per-vCPU statistics. This is only present
+# when the postcopy-blocktime migration capability is enabled.
+# (Since 10.1)
+#
+# @postcopy-non-vcpu-latency: average remote page fault latency for
+# all faults happend in non-vCPU threads (in ns). It has the same
+# definition of @postcopy-latency but this only provides
+# statistics to non-vCPU faults. This is only present when the
+# postcopy-blocktime migration capability is enabled.
+# (Since 10.1)
+#
# @socket-address: Only used for tcp, to know what the real port is
# (Since 4.0)
#
@@ -290,7 +293,8 @@
# Features:
#
# @unstable: Members @postcopy-latency, @postcopy-vcpu-latency,
-# @postcopy-latency-dist, @postcopy-non-vcpu-latency are experimental.
+# @postcopy-latency-dist, @postcopy-non-vcpu-latency are
+# experimental.
#
# Since: 0.14
##
@@ -322,9 +326,8 @@
##
# @query-migrate:
#
-# Return information about current migration process. If migration
-# is active there will be another json-object with RAM migration
-# status.
+# Return information about current migration process. If migration is
+# active there will be another json-object with RAM migration status.
#
# Since: 0.14
#
@@ -627,8 +630,8 @@
#
# @normal: the original form of migration. (since 8.2)
#
-# @cpr-reboot: The `migrate` command stops the VM and saves state to the
-# URI. After quitting QEMU, the user resumes by running QEMU
+# @cpr-reboot: The `migrate` command stops the VM and saves state to
+# the URI. After quitting QEMU, the user resumes by running QEMU
# -incoming.
#
# This mode allows the user to quit QEMU, optionally update and
@@ -659,15 +662,15 @@
# time by preserving guest RAM in place.
#
# Devices and their pinned pages are also preserved for VFIO and
-# IOMMUFD. (since 10.1)
+# IOMMUFD. (since 10.1)
#
# The user starts new QEMU on the same host as old QEMU, with
# command-line arguments to create the same machine, plus the
# -incoming option for the main migration channel, like normal
# live migration. In addition, the user adds a second -incoming
# option with channel type "cpr". This CPR channel must support
-# file descriptor transfer with SCM_RIGHTS, i.e. it must be a
-# UNIX domain socket.
+# file descriptor transfer with SCM_RIGHTS, i.e. it must be a UNIX
+# domain socket.
#
# To initiate CPR, the user issues a migrate command to old QEMU,
# adding a second migration channel of type "cpr" in the channels
@@ -708,8 +711,8 @@
# QEMU binary.
#
# Because old QEMU terminates when new QEMU starts, one cannot
-# stream data between the two, so the channel must be a type,
-# such as a file, that accepts all data before old QEMU exits.
+# stream data between the two, so the channel must be a type, such
+# as a file, that accepts all data before old QEMU exits.
# Otherwise, old QEMU may quietly block writing to the channel.
#
# Memory-backend objects must have the share=on attribute, but
@@ -903,9 +906,10 @@
# 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
-# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# 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)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@@ -939,8 +943,8 @@
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
-# @zero-page-detection: Whether and how to detect zero pages.
-# See description in `ZeroPageDetection`. Default is 'multifd'.
+# @zero-page-detection: Whether and how to detect zero pages. See
+# description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@@ -1089,9 +1093,10 @@
# 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
-# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# 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)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@@ -1125,8 +1130,8 @@
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
-# @zero-page-detection: Whether and how to detect zero pages.
-# See description in `ZeroPageDetection`. Default is 'multifd'.
+# @zero-page-detection: Whether and how to detect zero pages. See
+# description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@@ -1304,9 +1309,10 @@
# 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
-# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# 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)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@@ -1340,8 +1346,8 @@
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
-# @zero-page-detection: Whether and how to detect zero pages.
-# See description in `ZeroPageDetection`. Default is 'multifd'.
+# @zero-page-detection: Whether and how to detect zero pages. See
+# description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@@ -1813,9 +1819,9 @@
# list connected to a destination interface endpoint.
#
# @exit-on-error: Exit on incoming migration failure. Default true.
-# When set to false, the failure triggers a :qapi:event:`MIGRATION`
-# event, and error details could be retrieved with `query-migrate`.
-# (since 9.1)
+# When set to false, the failure triggers a
+# :qapi:event:`MIGRATION` event, and error details could be
+# retrieved with `query-migrate`. (since 9.1)
#
# Since: 2.3
#
@@ -2368,8 +2374,7 @@
##
# @query-vcpu-dirty-limit:
#
-# Return information about virtual CPU dirty page rate limits, if
-# any.
+# Return information about virtual CPU dirty page rate limits, if any.
#
# Since: 7.1
#
@@ -2507,8 +2512,8 @@
# time it takes to load the snapshot.
#
# It is strongly recommended that @devices contain all writable block
-# device nodes that can have changed since the original `snapshot-save`
-# command execution.
+# device nodes that can have changed since the original
+# `snapshot-save` command execution.
#
# .. qmp-example::
#
diff --git a/qapi/net.json b/qapi/net.json
index 7f62f8cc39..4c6cc5ca8d 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -119,9 +119,11 @@
#
# Unprivileged user-mode network connectivity using passt
#
-# @path: Filename of the passt program to run (by default 'passt', and use PATH)
+# @path: Filename of the passt program to run (by default 'passt', and
+# use PATH)
#
-# @quiet: don't print informational messages (default, passed as '--quiet')
+# @quiet: don't print informational messages (default, passed as
+# '--quiet')
#
# @vhost-user: enable vhost-user
#
@@ -281,8 +283,8 @@
#
# @smbserver: IP address of the built-in SMB server
#
-# @hostfwd: redirect incoming TCP, UDP or UNIX host connections to guest
-# endpoints
+# @hostfwd: redirect incoming TCP, UDP or UNIX host connections to
+# guest endpoints
#
# @guestfwd: forward guest TCP connections
#
@@ -569,7 +571,8 @@
# (default: 0).
#
# @inhibit: Don't load a default XDP program, use one already loaded
-# to the interface (default: false). Requires @sock-fds or @map-path.
+# to the interface (default: false). Requires @sock-fds or
+# @map-path.
#
# @sock-fds: A colon (:) separated list of file descriptors for
# already open but not bound AF_XDP sockets in the queue order.
@@ -582,7 +585,8 @@
# mutually exclusive. Requires @inhibit. (Since 10.1)
#
# @map-start-index: Use @map-path to insert xsk sockets starting from
-# this index number (default: 0). Requires @map-path. (Since 10.1)
+# this index number (default: 0). Requires @map-path.
+# (Since 10.1)
#
# Since: 8.2
##
@@ -770,9 +774,10 @@
#
# @server: create server socket (default: false)
#
-# @reconnect-ms: For a client socket, if a socket is disconnected, then
-# attempt a reconnect after the given number of milliseconds. Setting
-# this to zero disables this function. (default: 0) (Since: 9.2)
+# @reconnect-ms: For a client socket, if a socket is disconnected,
+# then attempt a reconnect after the given number of milliseconds.
+# Setting this to zero disables this function.
+# (default: 0) (Since: 9.2)
#
# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported.
#
diff --git a/qapi/qdev.json b/qapi/qdev.json
index e14a0c9259..974cf9c583 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -100,8 +100,8 @@
# process is signaled with a `DEVICE_DELETED` event. Guest reset
# will automatically complete removal for all devices. If a
# guest-side error in the hot removal process is detected, the
-# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` event
-# is sent. Some errors cannot be detected.
+# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR`
+# event is sent. Some errors cannot be detected.
#
# Since: 0.14
#
diff --git a/qapi/qom.json b/qapi/qom.json
index 830cb2ffe7..d7dceaf2f8 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -52,7 +52,8 @@
#
# @name: the name of the property.
#
-# @type: the type of the property, as described in `ObjectPropertyInfo`.
+# @type: the type of the property, as described in
+# `ObjectPropertyInfo`.
#
# @value: the value of the property. Absent when the property cannot
# be read.
@@ -112,7 +113,7 @@
# Absolute paths are derived from the root object and can follow
# child<> or link<> properties. Since they can follow link<>
# properties, they can be arbitrarily long. Absolute paths look
-# like absolute filenames and are prefixed with a leading slash.
+# like absolute filenames and are prefixed with a leading slash.
#
# Partial paths look like relative filenames. They do not begin
# with a prefix. The matching rules for partial paths are subtle
@@ -917,14 +918,14 @@
# combined with information retrieved from the discoverable part
# of the path. An example would use CDAT (see UEFI.org)
# 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
-# 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
-# complex as there may be interleaving across multiple devices
-# and shared links in the path.
+# 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 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 complex as there may be
+# interleaving across multiple devices and shared links in the
+# path.
#
# Since: 9.2
##
@@ -1040,8 +1041,7 @@
# behave identically to 'on', but will automatically switch to
# using KVM_SEV_INIT2 if the user specifies any additional options
# that require it. If set to 'off', QEMU will require
-# KVM_SEV_INIT2 unconditionally.
-# (default: off) (since 9.1)
+# KVM_SEV_INIT2 unconditionally. (default: off) (since 9.1)
#
# Since: 2.12
##
@@ -1082,8 +1082,8 @@
# Authentication Information Structure' for the SNP_LAUNCH_FINISH
# command defined in the SEV-SNP firmware ABI (default: all-zero)
#
-# @author-key-enabled: true if 'id-auth' blob contains the 'AUTHOR_KEY'
-# field defined SEV-SNP firmware ABI (default: false)
+# @author-key-enabled: true if 'id-auth' blob contains the
+# 'AUTHOR_KEY' field defined SEV-SNP firmware ABI (default: false)
#
# @host-data: 32-byte, base64-encoded, user-defined blob to provide to
# the guest, as documented for the 'HOST_DATA' parameter of the
@@ -1117,17 +1117,17 @@
# @attributes: The 'attributes' of a TD guest that is passed to
# KVM_TDX_INIT_VM
#
-# @sept-ve-disable: toggle bit 28 of TD attributes to control disabling
-# of EPT violation conversion to #VE on guest TD access of PENDING
-# pages. Some guest OS (e.g., Linux TD guest) may require this to
-# be set, otherwise they refuse to boot.
+# @sept-ve-disable: toggle bit 28 of TD attributes to control
+# disabling of EPT violation conversion to #VE on guest TD access
+# of PENDING pages. Some guest OS (e.g., Linux TD guest) may
+# require this to be set, otherwise they refuse to boot.
#
# @mrconfigid: ID for non-owner-defined configuration of the guest TD,
-# e.g., run-time or OS configuration (base64 encoded SHA384 digest).
-# Defaults to all zeros.
+# e.g., run-time or OS configuration (base64 encoded SHA384
+# digest). Defaults to all zeros.
#
-# @mrowner: ID for the guest TD’s owner (base64 encoded SHA384 digest).
-# Defaults to all zeros.
+# @mrowner: ID for the guest TD’s owner (base64 encoded SHA384
+# digest). Defaults to all zeros.
#
# @mrownerconfig: ID for owner-defined configuration of the guest TD,
# e.g., specific to the workload rather than the run-time or OS
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 4757947ca6..2872bee06e 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -247,8 +247,8 @@
# saved on disk, for example, S4 state, which is sometimes called
# hibernate state
#
-# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when entering
-# this state.
+# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when
+# entering this state.
#
# Since: 1.2
#
@@ -281,9 +281,9 @@
#
# @action: action that has been taken
#
-# .. note:: If action is "reset", "shutdown", or "pause" the `WATCHDOG`
-# event is followed respectively by the `RESET`, `SHUTDOWN`, or `STOP`
-# events.
+# .. note:: If action is "reset", "shutdown", or "pause" the
+# `WATCHDOG` event is followed respectively by the `RESET`,
+# `SHUTDOWN`, or `STOP` events.
#
# .. note:: This event is rate-limited.
#
@@ -402,7 +402,8 @@
#
# @panic: `PanicAction` action taken on guest panic.
#
-# @watchdog: `WatchdogAction` action taken when watchdog timer expires.
+# @watchdog: `WatchdogAction` action taken when watchdog timer
+# expires.
#
# Since: 6.0
#
@@ -542,8 +543,8 @@
# @arg4: for Windows, third argument of the `STOP`. For Linux, the
# RAX register (x86) or the stack pointer (aarch64) of the guest.
#
-# @arg5: for Windows, fourth argument of the `STOP`. For x86 Linux, the
-# stack pointer of the guest.
+# @arg5: for Windows, fourth argument of the `STOP`. For x86 Linux,
+# the stack pointer of the guest.
#
# Since: 2.9
##
@@ -610,7 +611,7 @@
#
# @error-code: TD-specific error code
#
-# @message: Human-readable error message provided by the guest. Not
+# @message: Human-readable error message provided by the guest. Not
# to be trusted.
#
# @gpa: guest-physical address of a page that contains more verbose
diff --git a/qapi/sockets.json b/qapi/sockets.json
index 32fac51728..473be2ac58 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -58,24 +58,26 @@
# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and
# IPv6
#
-# @keep-alive: enable keep-alive when connecting to/listening on this socket.
+# @keep-alive: enable keep-alive when connecting to/listening on this
+# socket.
# (Since 4.2, not supported for listening sockets until 10.1)
#
-# @keep-alive-count: number of keep-alive packets sent before the connection is
-# closed. Only supported for TCP sockets on systems where TCP_KEEPCNT
-# socket option is defined (this includes Linux, Windows, macOS, FreeBSD,
-# but not OpenBSD). When set to 0, system setting is used. (Since 10.1)
+# @keep-alive-count: number of keep-alive packets sent before the
+# connection is closed. Only supported for TCP sockets on systems
+# where TCP_KEEPCNT socket option is defined (this includes Linux,
+# Windows, macOS, FreeBSD, but not OpenBSD). When set to 0,
+# system setting is used. (Since 10.1)
#
-# @keep-alive-idle: time in seconds the connection needs to be idle before
-# sending a keepalive packet. Only supported for TCP sockets on systems
-# where TCP_KEEPIDLE socket option is defined (this includes Linux,
-# Windows, macOS, FreeBSD, but not OpenBSD). When set to 0, system setting
-# is used. (Since 10.1)
+# @keep-alive-idle: time in seconds the connection needs to be idle
+# before sending a keepalive packet. Only supported for TCP
+# sockets on systems where TCP_KEEPIDLE socket option is defined
+# (this includes Linux, Windows, macOS, FreeBSD, but not OpenBSD).
+# When set to 0, system setting is used. (Since 10.1)
#
-# @keep-alive-interval: time in seconds between keep-alive packets. Only
-# supported for TCP sockets on systems where TCP_KEEPINTVL is defined (this
-# includes Linux, Windows, macOS, FreeBSD, but not OpenBSD). When set to
-# 0, system setting is used. (Since 10.1)
+# @keep-alive-interval: time in seconds between keep-alive packets.
+# Only supported for TCP sockets on systems where TCP_KEEPINTVL is
+# defined (this includes Linux, Windows, macOS, FreeBSD, but not
+# OpenBSD). When set to 0, system setting is used. (Since 10.1)
#
# @mptcp: enable multi-path TCP. (Since 6.1)
#
diff --git a/qapi/stats.json b/qapi/stats.json
index 151ac43c48..a98624531c 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -185,8 +185,8 @@
# Return runtime-collected statistics for objects such as the VM or
# its vCPUs.
#
-# The arguments are a `StatsFilter` and specify the provider and objects
-# to return statistics about.
+# The arguments are a `StatsFilter` and specify the provider and
+# objects to return statistics about.
#
# Returns: a list of statistics, one for each provider and object
# (e.g., for each vCPU).
diff --git a/qapi/ui.json b/qapi/ui.json
index 1b2f4a4769..804b1ecc3b 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1023,10 +1023,10 @@
#
# Send keys to guest.
#
-# @keys: An array of `KeyValue` elements. All @KeyValues in this array
-# are simultaneously sent to the guest. A `KeyValue`.number value
-# is sent directly to the guest, while `KeyValue`.qcode must be a
-# valid `QKeyCode` value
+# @keys: An array of `KeyValue` elements. All @KeyValues in this
+# array are simultaneously sent to the guest. A `KeyValue`.number
+# value is sent directly to the guest, while `KeyValue`.qcode must
+# be a valid `QKeyCode` value
#
# @hold-time: time to delay key up events, milliseconds. Defaults to
# 100
@@ -1335,10 +1335,11 @@
# @show-menubar: Display the main window menubar. Defaults to "on".
# (Since 8.0)
#
-# @keep-aspect-ratio: Keep width/height aspect ratio of guest content when
-# resizing host window. Defaults to "on". (Since 10.1)
+# @keep-aspect-ratio: Keep width/height aspect ratio of guest content
+# when resizing host window. Defaults to "on". (Since 10.1)
#
-# @scale: Set preferred scale of the display. Defaults to 1.0. (Since 10.1)
+# @scale: Set preferred scale of the display. Defaults to 1.0.
+# (Since 10.1)
#
# Since: 2.12
##
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 05295ab665..72790bcfb0 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -984,8 +984,8 @@
##
# @DummyVirtioForceArrays:
#
-# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
-# and VirtIOGPUOutputList internally
+# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList and
+# VirtIOGPUOutputList internally
#
# Since: 9.0
##
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 3/9] qapi: Clean up whitespace between definitions
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 1/9] qapi/audio: Fix description markup of AudiodevDBusOptions @nsamples Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 2/9] qapi: Refill doc comments to conform to conventions Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 4/9] qga/qapi-schema: Refill doc comments to conform to conventions Markus Armbruster
` (6 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
Consistently separate definitions with a single blank line.
Consistently separate member descriptions with a blank line.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
qapi/acpi-hest.json | 1 -
qapi/char.json | 1 -
qapi/crypto.json | 1 +
qapi/cxl.json | 1 -
qapi/migration.json | 3 +++
qapi/misc-i386.json | 2 --
qapi/net.json | 3 ---
qapi/qom.json | 3 ---
qapi/run-state.json | 1 -
qapi/ui.json | 2 +-
qapi/virtio.json | 2 --
11 files changed, 5 insertions(+), 15 deletions(-)
diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json
index 88c53eaf1b..a01f1dee09 100644
--- a/qapi/acpi-hest.json
+++ b/qapi/acpi-hest.json
@@ -11,7 +11,6 @@
# https://uefi.org/sites/default/files/resources/ACPI_6_1.pdf
##
-
##
# @inject-ghes-v2-error:
#
diff --git a/qapi/char.json b/qapi/char.json
index b07e3bb827..140614f82c 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -681,7 +681,6 @@
{ 'struct': 'ChardevRingbufWrapper',
'data': { 'data': 'ChardevRingbuf' } }
-
##
# @ChardevPtyWrapper:
#
diff --git a/qapi/crypto.json b/qapi/crypto.json
index 72ac718147..2b55befef9 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -547,6 +547,7 @@
'base': 'TlsCredsProperties',
'data': { '*sanity-check': 'bool',
'*passwordid': 'str' } }
+
##
# @QCryptoAkCipherAlgo:
#
diff --git a/qapi/cxl.json b/qapi/cxl.json
index 52cc5d4f33..eeddb58d1d 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -262,7 +262,6 @@
#
# Since: 8.0
##
-
{ 'enum': 'CxlUncorErrorType',
'data': ['cache-data-parity',
'cache-address-parity',
diff --git a/qapi/migration.json b/qapi/migration.json
index 4dd1098219..022ac0c4ed 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -177,6 +177,7 @@
'postcopy-recover-setup',
'postcopy-recover', 'completed', 'failed', 'colo',
'pre-switchover', 'device', 'wait-unplug' ] }
+
##
# @VfioStats:
#
@@ -523,6 +524,7 @@
# Features:
#
# @unstable: Members @x-colo and @x-ignore-shared are experimental.
+#
# @deprecated: Member @zero-blocks is deprecated as being part of
# block migration which was already removed.
#
@@ -1702,6 +1704,7 @@
# The migration channel-type request options.
#
# @main: Main outbound migration channel.
+#
# @cpr: Checkpoint and restart state channel.
#
# Since: 8.1
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index d1ce8caf25..05a94d6c41 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -122,7 +122,6 @@
'sev': 'SevGuestInfo',
'sev-snp': 'SevSnpGuestInfo' } }
-
##
# @query-sev:
#
@@ -418,7 +417,6 @@
'pending': 'bool',
'masked': 'bool'} }
-
##
# @xen-event-list:
#
diff --git a/qapi/net.json b/qapi/net.json
index 4c6cc5ca8d..118bd34965 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -1055,7 +1055,6 @@
#
# Since: 4.0
##
-
{ 'struct': 'AnnounceParameters',
'data': { 'initial': 'int',
'max': 'int',
@@ -1171,7 +1170,6 @@
# <- { "timestamp": {"seconds": 1739538638, "microseconds": 354181 },
# "event": "NETDEV_VHOST_USER_CONNECTED",
# "data": { "netdev-id": "netdev0", "chardev-id": "chr0" } }
-#
##
{ 'event': 'NETDEV_VHOST_USER_CONNECTED',
'data': { 'netdev-id': 'str', 'chardev-id': 'str' } }
@@ -1190,7 +1188,6 @@
# <- { "timestamp": { "seconds": 1739538634, "microseconds": 920450 },
# "event": "NETDEV_VHOST_USER_DISCONNECTED",
# "data": { "netdev-id": "netdev0" } }
-#
##
{ 'event': 'NETDEV_VHOST_USER_DISCONNECTED',
'data': { 'netdev-id': 'str' } }
diff --git a/qapi/qom.json b/qapi/qom.json
index d7dceaf2f8..6f5c9de0f0 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -75,7 +75,6 @@
{ 'struct': 'ObjectPropertiesValues',
'data': { 'properties': [ 'ObjectPropertyValue' ] }}
-
##
# @qom-list:
#
@@ -244,7 +243,6 @@
#
# @typename: the type name of an object
#
-#
# .. note:: Objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These
# properties are not included in the output of this command.
@@ -1169,7 +1167,6 @@
'data': { '*cpu-affinity': ['uint16'],
'*node-affinity': ['uint16'] } }
-
##
# @ObjectType:
#
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 2872bee06e..a6bc94a44b 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -618,7 +618,6 @@
# error information, as zero-terminated string. Present when the
# "GPA valid" bit (bit 63) is set in @error-code.
#
-#
# Since: 10.1
##
{'struct': 'GuestPanicInformationTdx',
diff --git a/qapi/ui.json b/qapi/ui.json
index 804b1ecc3b..e3da77632a 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -682,6 +682,7 @@
##
{ 'command': 'query-vnc', 'returns': 'VncInfo',
'if': 'CONFIG_VNC' }
+
##
# @query-vnc-servers:
#
@@ -1094,7 +1095,6 @@
{ 'enum' : 'InputMultiTouchType',
'data' : [ 'begin', 'update', 'end', 'cancel', 'data' ] }
-
##
# @InputKeyEvent:
#
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 72790bcfb0..cd67c4f52e 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -964,7 +964,6 @@
#
# Since: 9.0
##
-
{ 'struct': 'IOThreadVirtQueueMapping',
'data': { 'iothread': 'str', '*vqs': ['uint16'] } }
@@ -989,7 +988,6 @@
#
# Since: 9.0
##
-
{ 'struct': 'DummyVirtioForceArrays',
'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'],
'unused-virtio-gpu-output': ['VirtIOGPUOutput'] } }
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 4/9] qga/qapi-schema: Refill doc comments to conform to conventions
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
` (2 preceding siblings ...)
2025-11-03 8:23 ` [PATCH v2 3/9] qapi: Clean up whitespace between definitions Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 5/9] qga/qapi-schema: Clean up whitespace between definitions Markus Armbruster
` (5 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
Sweep the entire documentation again. Last done in commit
7270819384c (qga/qapi-schema: Refill doc comments to conform to
current conventions).
To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3". Finds no
differences. Comparing with diff is not useful, as the reflown
paragraphs are visible there.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
qga/qapi-schema.json | 87 ++++++++++++++++++++++++--------------------
1 file changed, 47 insertions(+), 40 deletions(-)
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 8162d888bb..af75f12a28 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -2,8 +2,8 @@
# vim: filetype=python
##
-# This manual describes the commands supported by the QEMU Guest
-# Agent Protocol.
+# This manual describes the commands supported by the QEMU Guest Agent
+# Protocol.
#
# For locating a particular item, please see the `qapi-qga-index`.
#
@@ -96,8 +96,8 @@
# In cases where a partial stale response was previously received by
# the client, this cannot always be done reliably. One particular
# scenario being if qemu-ga responses are fed character-by-character
-# into a JSON parser. In these situations, using `guest-sync-delimited`
-# may be optimal.
+# into a JSON parser. In these situations, using
+# `guest-sync-delimited` may be optimal.
#
# For clients that fetch responses line by line and convert them to
# JSON objects, `guest-sync` should be sufficient, but note that in
@@ -153,9 +153,9 @@
# This command tries to set guest's System Time to the given value,
# then sets the Hardware Clock (RTC) to the current System Time. This
# will make it easier for a guest to resynchronize without waiting for
-# NTP. If no @time is specified, then the time to set is read from
-# RTC. However, this may not be supported on all platforms (i.e.
-# Windows). If that's the case users are advised to always pass a
+# NTP. If no @time is specified, then the time to set is read from
+# RTC. However, this may not be supported on all platforms (i.e.
+# Windows). If that's the case users are advised to always pass a
# value.
#
# @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in
@@ -444,8 +444,8 @@
# Returns: Number of file systems currently frozen.
#
# .. note:: On Windows, the command is implemented with the help of a
-# Volume Shadow-copy Service DLL helper. The frozen state is limited
-# for up to 10 seconds by VSS.
+# Volume Shadow-copy Service DLL helper. The frozen state is
+# limited for up to 10 seconds by VSS.
#
# Since: 0.15.0
##
@@ -482,9 +482,9 @@
# Returns: Number of file systems thawed by this call
#
# .. note:: If the return value does not match the previous call to
-# `guest-fsfreeze-freeze`, this likely means some freezable filesystems
-# were unfrozen before this call, and that the filesystem state may
-# have changed before issuing this command.
+# `guest-fsfreeze-freeze`, this likely means some freezable
+# filesystems were unfrozen before this call, and that the
+# filesystem state may have changed before issuing this command.
#
# Since: 0.15.0
##
@@ -513,7 +513,8 @@
##
# @GuestFilesystemTrimResponse:
#
-# @paths: list of `GuestFilesystemTrimResult` per path that was trimmed
+# @paths: list of `GuestFilesystemTrimResult` per path that was
+# trimmed
#
# Since: 2.4
##
@@ -557,16 +558,16 @@
#
# This command does NOT return a response on success. There is a high
# chance the command succeeded if the VM exits with a zero exit status
-# or, when running with --no-shutdown, by issuing the `query-status` QMP
-# command to to confirm the VM status is "shutdown". However, the VM
-# could also exit (or set its status to "shutdown") due to other
+# or, when running with --no-shutdown, by issuing the `query-status`
+# QMP command to to confirm the VM status is "shutdown". However, the
+# VM could also exit (or set its status to "shutdown") due to other
# reasons.
#
# Errors:
# - If suspend to disk is not supported, Unsupported
#
-# .. note:: It's strongly recommended to issue the `guest-sync` command
-# before sending commands when the guest resumes.
+# .. note:: It's strongly recommended to issue the `guest-sync`
+# command before sending commands when the guest resumes.
#
# Since: 1.1
##
@@ -586,7 +587,7 @@
# - manual write into sysfs
#
# IMPORTANT: `guest-suspend-ram` requires working wakeup support in
-# QEMU. You should check QMP command `query-current-machine` returns
+# QEMU. You should check QMP command `query-current-machine` returns
# wakeup-suspend-support: true before issuing this command. Failure
# in doing so can result in a suspended guest that QEMU will not be
# able to awaken, forcing the user to power cycle the guest to bring
@@ -602,8 +603,8 @@
# Errors:
# - If suspend to ram is not supported, Unsupported
#
-# .. note:: It's strongly recommended to issue the `guest-sync` command
-# before sending commands when the guest resumes.
+# .. note:: It's strongly recommended to issue the `guest-sync`
+# command before sending commands when the guest resumes.
#
# Since: 1.1
##
@@ -622,7 +623,7 @@
# - pm-utils (via pm-suspend-hybrid)
#
# IMPORTANT: `guest-suspend-hybrid` requires working wakeup support in
-# QEMU. You should check QMP command `query-current-machine` returns
+# QEMU. You should check QMP command `query-current-machine` returns
# wakeup-suspend-support: true before issuing this command. Failure
# in doing so can result in a suspended guest that QEMU will not be
# able to awaken, forcing the user to power cycle the guest to bring
@@ -638,8 +639,8 @@
# Errors:
# - If hybrid suspend is not supported, Unsupported
#
-# .. note:: It's strongly recommended to issue the `guest-sync` command
-# before sending commands when the guest resumes.
+# .. note:: It's strongly recommended to issue the `guest-sync`
+# command before sending commands when the guest resumes.
#
# Since: 1.1
##
@@ -1048,10 +1049,11 @@
#
# @used-bytes: file system used bytes (since 3.0)
#
-# @total-bytes: filesystem capacity in bytes for unprivileged users (since 3.0)
+# @total-bytes: filesystem capacity in bytes for unprivileged users
+# (since 3.0)
#
-# @total-bytes-privileged: filesystem capacity in bytes for privileged users
-# (since 9.1)
+# @total-bytes-privileged: filesystem capacity in bytes for privileged
+# users (since 9.1)
#
# @disk: an array of disk hardware information that the volume lies
# on, which may be empty if the disk type is not supported
@@ -1171,7 +1173,8 @@
##
# @GuestMemoryBlockResponse:
#
-# @phys-index: same with the 'phys-index' member of `GuestMemoryBlock`.
+# @phys-index: same with the 'phys-index' member of
+# `GuestMemoryBlock`.
#
# @response: the result of memory block operation.
#
@@ -1491,10 +1494,11 @@
#
# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
# @version, @version-id, @variant and @variant-id follow the
-# definition specified in os-release(5). Refer to the manual page for
-# exact description of the fields. Their values are taken from the
-# os-release file. If the file is not present in the system, or the
-# values are not present in the file, the fields are not included.
+# definition specified in os-release(5). Refer to the manual page
+# for exact description of the fields. Their values are taken from
+# the os-release file. If the file is not present in the system,
+# or the values are not present in the file, the fields are not
+# included.
#
# On Windows the values are filled from information gathered from
# the system.
@@ -1639,7 +1643,7 @@
# @guest-ssh-remove-authorized-keys:
#
# Remove public keys from the user .ssh/authorized_keys on Unix
-# systems (not implemented for other systems). It's not an error if
+# systems (not implemented for other systems). It's not an error if
# the key is already missing.
#
# @username: the user account to remove the authorized keys
@@ -1862,10 +1866,10 @@
#
# Retrieve CPU process load information
#
-# .. note:: Windows does not have load average API, so QGA emulates it by
-# calculating the average CPU usage in the last 1, 5, 15 minutes
-# similar as Linux does this.
-# Calculation starts from the first time this command is called.
+# .. note:: Windows does not have load average API, so QGA emulates it
+# by calculating the average CPU usage in the last 1, 5, 15 minutes
+# similar as Linux does this. Calculation starts from the first
+# time this command is called.
#
# Returns: load information
#
@@ -1881,9 +1885,11 @@
#
# Route information, currently, only linux supported.
#
-# @iface: The destination network or host's egress network interface in the routing table
+# @iface: The destination network or host's egress network interface
+# in the routing table
#
-# @destination: The IP address of the target network or host, The final destination of the packet
+# @destination: The IP address of the target network or host, The
+# final destination of the packet
#
# @metric: Route metric
#
@@ -1899,7 +1905,8 @@
#
# @use: Route usage count (not for windows)
#
-# @window: TCP window size, used for flow control (not for windows, IPv4 only)
+# @window: TCP window size, used for flow control (not for windows,
+# IPv4 only)
#
# @mtu: Data link layer maximum packet size (not for windows)
#
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 5/9] qga/qapi-schema: Clean up whitespace between definitions
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
` (3 preceding siblings ...)
2025-11-03 8:23 ` [PATCH v2 4/9] qga/qapi-schema: Refill doc comments to conform to conventions Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 6/9] docs/interop: Refill QAPI doc comments to conform to conventions Markus Armbruster
` (4 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
Consistently separate definitions with a single blank line.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
qga/qapi-schema.json | 9 ++-------
1 file changed, 2 insertions(+), 7 deletions(-)
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index af75f12a28..5791b49dde 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -197,6 +197,7 @@
{ 'struct': 'GuestAgentInfo',
'data': { 'version': 'str',
'supported_commands': ['GuestAgentCommandInfo'] } }
+
##
# @guest-info:
#
@@ -322,7 +323,6 @@
'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
'returns': 'GuestFileWrite' }
-
##
# @GuestFileSeek:
#
@@ -876,7 +876,6 @@
'sas', 'mmc', 'virtual', 'file-backed-virtual', 'nvme' ],
'if': { 'any': [ 'CONFIG_WIN32', 'CONFIG_LINUX' ] } }
-
##
# @GuestPCIAddress:
#
@@ -1276,6 +1275,7 @@
'data': { 'exited': 'bool', '*exitcode': 'int', '*signal': 'int',
'*out-data': 'str', '*err-data': 'str',
'*out-truncated': 'bool', '*err-truncated': 'bool' }}
+
##
# @guest-exec-status:
#
@@ -1365,7 +1365,6 @@
'*input-data': 'str', '*capture-output': 'GuestExecCaptureOutput' },
'returns': 'GuestExec' }
-
##
# @GuestHostName:
#
@@ -1392,7 +1391,6 @@
{ 'command': 'guest-get-host-name',
'returns': 'GuestHostName' }
-
##
# @GuestUser:
#
@@ -1763,7 +1761,6 @@
'data': [ 'linux' ],
'if': 'CONFIG_LINUX' }
-
##
# @GuestLinuxCpuStats:
#
@@ -1838,7 +1835,6 @@
'if': 'CONFIG_LINUX'
}
-
##
# @GuestLoadAverage:
#
@@ -1921,7 +1917,6 @@
# @version: IP version (4 or 6)
#
# Since: 9.1
-
##
{ 'struct': 'GuestNetworkRoute',
'data': {'iface': 'str',
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 6/9] docs/interop: Refill QAPI doc comments to conform to conventions
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
` (4 preceding siblings ...)
2025-11-03 8:23 ` [PATCH v2 5/9] qga/qapi-schema: Clean up whitespace between definitions Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 7/9] docs/interop/firmware: Belatedly convert "Example" section Markus Armbruster
` (3 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
For legibility, wrap text paragraphs so every line is at most 70
characters long. Consistently separate sentences with two spaces.
Consistently separate member descriptions with a blank line.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
docs/interop/firmware.json | 440 +++++++++++++++++------------------
docs/interop/vhost-user.json | 57 +++--
2 files changed, 252 insertions(+), 245 deletions(-)
diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index ccbfaf828d..7ffa7697e4 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -27,18 +27,18 @@
# Lists the firmware-OS interface types provided by various firmware
# that is commonly used with QEMU virtual machines.
#
-# @bios: Traditional x86 BIOS interface. For example, firmware built
-# from the SeaBIOS project usually provides this interface.
+# @bios: Traditional x86 BIOS interface. For example, firmware built
+# from the SeaBIOS project usually provides this interface.
#
# @openfirmware: The interface is defined by the (historical) IEEE
-# 1275-1994 standard. Examples for firmware projects that
-# provide this interface are: OpenBIOS and SLOF.
+# 1275-1994 standard. Examples for firmware projects that provide
+# this interface are: OpenBIOS and SLOF.
#
# @uboot: Firmware interface defined by the U-Boot project.
#
-# @uefi: Firmware interface defined by the UEFI specification. For
-# example, firmware built from the edk2 (EFI Development Kit II)
-# project usually provides this interface.
+# @uefi: Firmware interface defined by the UEFI specification. For
+# example, firmware built from the edk2 (EFI Development Kit II)
+# project usually provides this interface.
#
# Since: 3.0
##
@@ -50,21 +50,21 @@
#
# Defines the device types that firmware can be mapped into.
#
-# @flash: The firmware executable and its accompanying NVRAM file are to
-# be mapped into a pflash chip each.
+# @flash: The firmware executable and its accompanying NVRAM file are
+# to be mapped into a pflash chip each.
#
-# @kernel: The firmware is to be loaded like a Linux kernel. This is
-# similar to @memory but may imply additional processing that
-# is specific to the target architecture and machine type.
+# @kernel: The firmware is to be loaded like a Linux kernel. This is
+# similar to @memory but may imply additional processing that is
+# specific to the target architecture and machine type.
#
# @memory: The firmware is to be mapped into memory.
#
# @igvm: The firmware is defined by a file conforming to the IGVM
-# specification and mapped into memory according to directives
-# defined in the file. This is similar to @memory but may
-# include additional processing defined by the IGVM file
-# including initial CPU state or population of metadata into
-# the guest address space. Since: 10.1
+# specification and mapped into memory according to directives
+# defined in the file. This is similar to @memory but may include
+# additional processing defined by the IGVM file including initial
+# CPU state or population of metadata into the guest address
+# space. Since: 10.1
#
# Since: 3.0
##
@@ -74,8 +74,8 @@
##
# @FirmwareArchitecture:
#
-# Enumeration of architectures for which Qemu uses additional
-# firmware files.
+# Enumeration of architectures for which Qemu uses additional firmware
+# files.
#
# @aarch64: 64-bit Arm.
#
@@ -83,7 +83,7 @@
#
# @i386: 32-bit x86.
#
-# @loongarch64: 64-bit LoongArch. (since: 7.1)
+# @loongarch64: 64-bit LoongArch. (since: 7.1)
#
# @riscv64: 64-bit RISC-V.
#
@@ -100,17 +100,16 @@
# Defines the machine types that firmware may execute on.
#
# @architecture: Determines the emulation target (the QEMU system
-# emulator) that can execute the firmware.
+# emulator) that can execute the firmware.
#
# @machines: Lists the machine types (known by the emulator that is
-# specified through @architecture) that can execute the
-# firmware. Elements of @machines are supposed to be concrete
-# machine types, not aliases. Glob patterns are understood,
-# which is especially useful for versioned machine types.
-# (For example, the glob pattern "pc-i440fx-*" matches
-# "pc-i440fx-2.12".) On the QEMU command line, "-machine
-# type=..." specifies the requested machine type (but that
-# option does not accept glob patterns).
+# specified through @architecture) that can execute the firmware.
+# Elements of @machines are supposed to be concrete machine types,
+# not aliases. Glob patterns are understood, which is especially
+# useful for versioned machine types. (For example, the glob
+# pattern "pc-i440fx-*" matches "pc-i440fx-2.12".) On the QEMU
+# command line, "-machine type=..." specifies the requested
+# machine type (but that option does not accept glob patterns).
#
# Since: 3.0
##
@@ -124,115 +123,104 @@
# Defines the features that firmware may support, and the platform
# requirements that firmware may present.
#
-# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as defined
-# in the ACPI specification. On the "pc-i440fx-*" machine
-# types of the @i386 and @x86_64 emulation targets, S3 can be
-# enabled with "-global PIIX4_PM.disable_s3=0" and disabled
-# with "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*"
-# machine types of the @i386 and @x86_64 emulation targets, S3
-# can be enabled with "-global ICH9-LPC.disable_s3=0" and
-# disabled with "-global ICH9-LPC.disable_s3=1".
+# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as
+# defined in the ACPI specification. On the "pc-i440fx-*" machine
+# types of the @i386 and @x86_64 emulation targets, S3 can be
+# enabled with "-global PIIX4_PM.disable_s3=0" and disabled with
+# "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*" machine
+# types of the @i386 and @x86_64 emulation targets, S3 can be
+# enabled with "-global ICH9-LPC.disable_s3=0" and disabled with
+# "-global ICH9-LPC.disable_s3=1".
#
# @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as
-# defined in the ACPI specification. On the "pc-i440fx-*"
-# machine types of the @i386 and @x86_64 emulation targets, S4
-# can be enabled with "-global PIIX4_PM.disable_s4=0" and
-# disabled with "-global PIIX4_PM.disable_s4=1". On the
-# "pc-q35-*" machine types of the @i386 and @x86_64 emulation
-# targets, S4 can be enabled with "-global
-# ICH9-LPC.disable_s4=0" and disabled with "-global
-# ICH9-LPC.disable_s4=1".
+# defined in the ACPI specification. On the "pc-i440fx-*" machine
+# types of the @i386 and @x86_64 emulation targets, S4 can be
+# enabled with "-global PIIX4_PM.disable_s4=0" and disabled with
+# "-global PIIX4_PM.disable_s4=1". On the "pc-q35-*" machine
+# types of the @i386 and @x86_64 emulation targets, S4 can be
+# enabled with "-global ICH9-LPC.disable_s4=0" and disabled with
+# "-global ICH9-LPC.disable_s4=1".
#
# @amd-sev: The firmware supports running under AMD Secure Encrypted
-# Virtualization, as specified in the AMD64 Architecture
-# Programmer's Manual. QEMU command line options related to
-# this feature are documented in
-# "docs/system/i386/amd-memory-encryption.rst".
+# Virtualization, as specified in the AMD64 Architecture
+# Programmer's Manual. QEMU command line options related to this
+# feature are documented in
+# "docs/system/i386/amd-memory-encryption.rst".
#
-# @amd-sev-es: The firmware supports running under AMD Secure Encrypted
-# Virtualization - Encrypted State, as specified in the AMD64
-# Architecture Programmer's Manual. QEMU command line options
-# related to this feature are documented in
-# "docs/system/i386/amd-memory-encryption.rst".
+# @amd-sev-es: The firmware supports running under AMD Secure
+# Encrypted Virtualization - Encrypted State, as specified in the
+# AMD64 Architecture Programmer's Manual. QEMU command line
+# options related to this feature are documented in
+# "docs/system/i386/amd-memory-encryption.rst".
#
-# @amd-sev-snp: The firmware supports running under AMD Secure Encrypted
-# Virtualization - Secure Nested Paging, as specified in the
-# AMD64 Architecture Programmer's Manual. QEMU command line
-# options related to this feature are documented in
-# "docs/system/i386/amd-memory-encryption.rst".
+# @amd-sev-snp: The firmware supports running under AMD Secure
+# Encrypted Virtualization - Secure Nested Paging, as specified in
+# the AMD64 Architecture Programmer's Manual. QEMU command line
+# options related to this feature are documented in
+# "docs/system/i386/amd-memory-encryption.rst".
#
# @intel-tdx: The firmware supports running under Intel Trust Domain
-# Extensions (TDX).
+# Extensions (TDX).
#
# @enrolled-keys: The variable store (NVRAM) template associated with
-# the firmware binary has the UEFI Secure Boot
-# operational mode turned on, with certificates
-# enrolled.
+# the firmware binary has the UEFI Secure Boot operational mode
+# turned on, with certificates enrolled.
#
# @requires-smm: The firmware requires the platform to emulate SMM
-# (System Management Mode), as defined in the AMD64
-# Architecture Programmer's Manual, and in the Intel(R)64
-# and IA-32 Architectures Software Developer's Manual. On
-# the "pc-q35-*" machine types of the @i386 and @x86_64
-# emulation targets, SMM emulation can be enabled with
-# "-machine smm=on". (On the "pc-q35-*" machine types of
-# the @i386 emulation target, @requires-smm presents
-# further CPU requirements; one combination known to work
-# is "-cpu coreduo,nx=off".) If the firmware is marked as
-# both @secure-boot and @requires-smm, then write
-# accesses to the pflash chip (NVRAM) that holds the UEFI
-# variable store must be restricted to code that executes
-# in SMM, using the additional option "-global
-# driver=cfi.pflash01,property=secure,value=on".
-# Furthermore, a large guest-physical address space
-# (comprising guest RAM, memory hotplug range, and 64-bit
-# PCI MMIO aperture), and/or a high VCPU count, may
-# present high SMRAM requirements from the firmware. On
-# the "pc-q35-*" machine types of the @i386 and @x86_64
-# emulation targets, the SMRAM size may be increased
-# above the default 16MB with the "-global
-# mch.extended-tseg-mbytes=uint16" option. As a rule of
-# thumb, the default 16MB size suffices for 1TB of
-# guest-phys address space and a few tens of VCPUs; for
-# every further TB of guest-phys address space, add 8MB
-# of SMRAM. 48MB should suffice for 4TB of guest-phys
-# address space and 2-3 hundred VCPUs.
+# (System Management Mode), as defined in the AMD64 Architecture
+# Programmer's Manual, and in the Intel(R)64 and IA-32
+# Architectures Software Developer's Manual. On the "pc-q35-*"
+# machine types of the @i386 and @x86_64 emulation targets, SMM
+# emulation can be enabled with "-machine smm=on". (On the
+# "pc-q35-*" machine types of the @i386 emulation target,
+# @requires-smm presents further CPU requirements; one combination
+# known to work is "-cpu coreduo,nx=off".) If the firmware is
+# marked as both @secure-boot and @requires-smm, then write
+# accesses to the pflash chip (NVRAM) that holds the UEFI variable
+# store must be restricted to code that executes in SMM, using the
+# additional option "-global
+# driver=cfi.pflash01,property=secure,value=on". Furthermore, a
+# large guest-physical address space (comprising guest RAM, memory
+# hotplug range, and 64-bit PCI MMIO aperture), and/or a high VCPU
+# count, may present high SMRAM requirements from the firmware.
+# On the "pc-q35-*" machine types of the @i386 and @x86_64
+# emulation targets, the SMRAM size may be increased above the
+# default 16MB with the "-global mch.extended-tseg-mbytes=uint16"
+# option. As a rule of thumb, the default 16MB size suffices for
+# 1TB of guest-phys address space and a few tens of VCPUs; for
+# every further TB of guest-phys address space, add 8MB of SMRAM.
+# 48MB should suffice for 4TB of guest-phys address space and 2-3
+# hundred VCPUs.
#
-# @secure-boot: The firmware implements the software interfaces for UEFI
-# Secure Boot, as defined in the UEFI specification. Note
-# that without @requires-smm, guest code running with
-# kernel privileges can undermine the security of Secure
-# Boot.
+# @secure-boot: The firmware implements the software interfaces for
+# UEFI Secure Boot, as defined in the UEFI specification. Note
+# that without @requires-smm, guest code running with kernel
+# privileges can undermine the security of Secure Boot.
#
# @verbose-dynamic: When firmware log capture is enabled, the firmware
-# logs a large amount of debug messages, which may
-# impact boot performance. With log capture disabled,
-# there is no boot performance impact. On the
-# "pc-i440fx-*" and "pc-q35-*" machine types of the
-# @i386 and @x86_64 emulation targets, firmware log
-# capture can be enabled with the QEMU command line
-# options "-chardev file,id=fwdebug,path=LOGFILEPATH
-# -device isa-debugcon,iobase=0x402,chardev=fwdebug".
-# @verbose-dynamic is mutually exclusive with
-# @verbose-static.
+# logs a large amount of debug messages, which may impact boot
+# performance. With log capture disabled, there is no boot
+# performance impact. On the "pc-i440fx-*" and "pc-q35-*" machine
+# types of the @i386 and @x86_64 emulation targets, firmware log
+# capture can be enabled with the QEMU command line options
+# "-chardev file,id=fwdebug,path=LOGFILEPATH -device
+# isa-debugcon,iobase=0x402,chardev=fwdebug". @verbose-dynamic is
+# mutually exclusive with @verbose-static.
#
-# @verbose-static: The firmware unconditionally produces a large amount
-# of debug messages, which may impact boot performance.
-# This feature may typically be carried by certain UEFI
-# firmware for the "virt-*" machine types of the @arm
-# and @aarch64 emulation targets, where the debug
-# messages are written to the first (always present)
-# PL011 UART. @verbose-static is mutually exclusive
-# with @verbose-dynamic.
+# @verbose-static: The firmware unconditionally produces a large
+# amount of debug messages, which may impact boot performance.
+# This feature may typically be carried by certain UEFI firmware
+# for the "virt-*" machine types of the @arm and @aarch64
+# emulation targets, where the debug messages are written to the
+# first (always present) PL011 UART. @verbose-static is mutually
+# exclusive with @verbose-dynamic.
#
# @host-uefi-vars: The firmware expects the host to provide an uefi
-# variable store. qemu supports that via
-# "uefi-vars-sysbus" (aarch64, riscv64, loongarch64)
-# or "uefi-vars-x64" (x86_64) devices. The firmware
-# will not use flash for nvram. When loading the
-# firmware into flash the 'stateless' setup should be
-# used. It is recommened to load the firmware into
-# memory though.
+# variable store. qemu supports that via "uefi-vars-sysbus"
+# (aarch64, riscv64, loongarch64) or "uefi-vars-x64" (x86_64)
+# devices. The firmware will not use flash for nvram. When
+# loading the firmware into flash the 'stateless' setup should be
+# used. It is recommened to load the firmware into memory though.
#
# Since: 3.0
##
@@ -262,16 +250,16 @@
# @FirmwareFlashFile:
#
# Defines common properties that are necessary for loading a firmware
-# file into a pflash chip. The corresponding QEMU command line option is
-# "-drive file=@filename,format=@format". Note however that the
+# file into a pflash chip. The corresponding QEMU command line option
+# is "-drive file=@filename,format=@format". Note however that the
# option-argument shown here is incomplete; it is completed under
# @FirmwareMappingFlash.
#
# @filename: Specifies the filename on the host filesystem where the
-# firmware file can be found.
+# firmware file can be found.
#
# @format: Specifies the block format of the file pointed-to by
-# @filename, such as @raw or @qcow2.
+# @filename, such as @raw or @qcow2.
#
# Since: 3.0
##
@@ -286,22 +274,20 @@
# Describes how the firmware build handles code versus variable
# persistence.
#
-# @split: the executable file contains code while the NVRAM
-# template provides variable storage. The executable
-# must be configured read-only and can be shared between
-# multiple guests. The NVRAM template must be cloned
-# for each new guest and configured read-write.
+# @split: the executable file contains code while the NVRAM template
+# provides variable storage. The executable must be configured
+# read-only and can be shared between multiple guests. The NVRAM
+# template must be cloned for each new guest and configured
+# read-write.
#
-# @combined: the executable file contains both code and
-# variable storage. The executable must be cloned
-# for each new guest and configured read-write.
-# No NVRAM template will be specified.
+# @combined: the executable file contains both code and variable
+# storage. The executable must be cloned for each new guest and
+# configured read-write. No NVRAM template will be specified.
#
-# @stateless: the executable file contains code and variable
-# storage is not persisted. The executable must
-# be configured read-only and can be shared
-# between multiple guests. No NVRAM template
-# will be specified.
+# @stateless: the executable file contains code and variable storage
+# is not persisted. The executable must be configured read-only
+# and can be shared between multiple guests. No NVRAM template
+# will be specified.
#
# Since: 7.0.0
##
@@ -315,39 +301,36 @@
# and its accompanying NVRAM file, when @FirmwareDevice is @flash.
#
# @mode: Describes how the firmware build handles code versus variable
-# storage. If not present, it must be treated as if it was
-# configured with value @split. Since: 7.0.0
+# storage. If not present, it must be treated as if it was
+# configured with value @split. Since: 7.0.0
#
-# @executable: Identifies the firmware executable. The @mode
-# indicates whether there will be an associated
-# NVRAM template present. The preferred
-# corresponding QEMU command line options are
-# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
-# -machine pflash0=pflash0
-# or equivalent -blockdev instead of -drive. When
-# @mode is @combined the executable must be
-# cloned before use and configured with readonly=off.
-# With QEMU versions older than 4.0, you have to use
-# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
+# @executable: Identifies the firmware executable. The @mode
+# indicates whether there will be an associated NVRAM template
+# present. The preferred corresponding QEMU command line options
+# are
+# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
+# -machine pflash0=pflash0
+# or equivalent -blockdev instead of -drive. When @mode is
+# @combined the executable must be cloned before use and
+# configured with readonly=off. With QEMU versions older than
+# 4.0, you have to use
+# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
#
# @nvram-template: Identifies the NVRAM template compatible with
-# @executable, when @mode is set to @split,
-# otherwise it should not be present.
-# Management software instantiates an
-# individual copy -- a specific NVRAM file -- from
-# @nvram-template.@filename for each new virtual
-# machine definition created. @nvram-template.@filename
-# itself is never mapped into virtual machines, only
-# individual copies of it are. An NVRAM file is
-# typically used for persistently storing the
-# non-volatile UEFI variables of a virtual machine
-# definition. The preferred corresponding QEMU
-# command line options are
-# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
-# -machine pflash1=pflash1
-# or equivalent -blockdev instead of -drive.
-# With QEMU versions older than 4.0, you have to use
-# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
+# @executable, when @mode is set to @split, otherwise it should
+# not be present. Management software instantiates an individual
+# copy -- a specific NVRAM file -- from @nvram-template.@filename
+# for each new virtual machine definition created.
+# @nvram-template.@filename itself is never mapped into virtual
+# machines, only individual copies of it are. An NVRAM file is
+# typically used for persistently storing the non-volatile UEFI
+# variables of a virtual machine definition. The preferred
+# corresponding QEMU command line options are
+# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
+# -machine pflash1=pflash1
+# or equivalent -blockdev instead of -drive. With QEMU versions
+# older than 4.0, you have to use
+# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
#
# Since: 3.0
##
@@ -359,13 +342,13 @@
##
# @FirmwareMappingKernel:
#
-# Describes loading and mapping properties for the firmware executable,
-# when @FirmwareDevice is @kernel.
+# Describes loading and mapping properties for the firmware
+# executable, when @FirmwareDevice is @kernel.
#
-# @filename: Identifies the firmware executable. The firmware executable
-# may be shared by multiple virtual machine definitions. The
-# corresponding QEMU command line option is "-kernel
-# @filename".
+# @filename: Identifies the firmware executable. The firmware
+# executable may be shared by multiple virtual machine
+# definitions. The corresponding QEMU command line option is
+# "-kernel @filename".
#
# Since: 3.0
##
@@ -375,13 +358,13 @@
##
# @FirmwareMappingMemory:
#
-# Describes loading and mapping properties for the firmware executable,
-# when @FirmwareDevice is @memory.
+# Describes loading and mapping properties for the firmware
+# executable, when @FirmwareDevice is @memory.
#
-# @filename: Identifies the firmware executable. The firmware executable
-# may be shared by multiple virtual machine definitions. The
-# corresponding QEMU command line option is "-bios
-# @filename".
+# @filename: Identifies the firmware executable. The firmware
+# executable may be shared by multiple virtual machine
+# definitions. The corresponding QEMU command line option is
+# "-bios @filename".
#
# Since: 3.0
##
@@ -391,15 +374,15 @@
##
# @FirmwareMappingIgvm:
#
-# Describes loading and mapping properties for the firmware executable,
-# when @FirmwareDevice is @igvm.
+# Describes loading and mapping properties for the firmware
+# executable, when @FirmwareDevice is @igvm.
#
-# @filename: Identifies the IGVM file containing the firmware executable
-# along with other information used to configure the initial
-# state of the guest. The IGVM file may be shared by multiple
-# virtual machine definitions. This corresponds to creating
-# an object on the command line with "-object igvm-cfg,
-# file=@filename".
+# @filename: Identifies the IGVM file containing the firmware
+# executable along with other information used to configure the
+# initial state of the guest. The IGVM file may be shared by
+# multiple virtual machine definitions. This corresponds to
+# creating an object on the command line with "-object igvm-cfg,
+# file=@filename".
#
# Since: 10.1
##
@@ -413,7 +396,7 @@
# loading / mapping properties.
#
# @device: Selects the device type that the firmware must be mapped
-# into.
+# into.
#
# Since: 3.0
##
@@ -428,46 +411,49 @@
##
# @Firmware:
#
-# Describes a firmware (or a firmware use case) to management software.
+# Describes a firmware (or a firmware use case) to management
+# software.
#
# It is possible for multiple @Firmware elements to match the search
-# criteria of management software. Applications thus need rules to pick
-# one of the many matches, and users need the ability to override distro
-# defaults.
+# criteria of management software. Applications thus need rules to
+# pick one of the many matches, and users need the ability to override
+# distro defaults.
#
# It is recommended to create firmware JSON files (each containing a
-# single @Firmware root element) with a double-digit prefix, for example
-# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
-# predictable order. The firmware JSON files should be searched for in
-# three directories:
+# single @Firmware root element) with a double-digit prefix, for
+# example "50-ovmf.json", "50-seabios-256k.json", etc, so they can be
+# sorted in predictable order. The firmware JSON files should be
+# searched for in three directories:
#
-# - /usr/share/qemu/firmware -- populated by distro-provided firmware
-# packages (XDG_DATA_DIRS covers
-# /usr/share by default),
+# - /usr/share/qemu/firmware -- populated by distro-provided firmware
+# packages (XDG_DATA_DIRS covers
+# /usr/share by default),
#
-# - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
+# - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
#
-# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
-# additions (XDG_CONFIG_HOME
-# defaults to $HOME/.config).
+# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
+# additions (XDG_CONFIG_HOME
+# defaults to $HOME/.config).
#
# Top-down, the list of directories goes from general to specific.
#
# Management software should build a list of files from all three
# locations, then sort the list by filename (i.e., last pathname
-# component). Management software should choose the first JSON file on
-# the sorted list that matches the search criteria. If a more specific
-# directory has a file with same name as a less specific directory, then
-# the file in the more specific directory takes effect. If the more
-# specific file is zero length, it hides the less specific one.
+# component). Management software should choose the first JSON file
+# on the sorted list that matches the search criteria. If a more
+# specific directory has a file with same name as a less specific
+# directory, then the file in the more specific directory takes
+# effect. If the more specific file is zero length, it hides the less
+# specific one.
#
# For example, if a distro ships
#
-# - /usr/share/qemu/firmware/50-ovmf.json
+# - /usr/share/qemu/firmware/50-ovmf.json
#
-# - /usr/share/qemu/firmware/50-seabios-256k.json
+# - /usr/share/qemu/firmware/50-seabios-256k.json
#
-# then the sysadmin can prevent the default OVMF being used at all with
+# then the sysadmin can prevent the default OVMF being used at all
+# with
#
# $ touch /etc/qemu/firmware/50-ovmf.json
#
@@ -484,29 +470,29 @@
# $ vim /etc/qemu/firmware/99-ovmf.json
#
# @description: Provides a human-readable description of the firmware.
-# Management software may or may not display @description.
+# Management software may or may not display @description.
#
-# @interface-types: Lists the types of interfaces that the firmware can
-# expose to the guest OS. This is a non-empty, ordered
-# list; entries near the beginning of @interface-types
-# are considered more native to the firmware, and/or
-# to have a higher quality implementation in the
-# firmware, than entries near the end of
-# @interface-types.
+# @interface-types: Lists the types of interfaces that the firmware
+# can expose to the guest OS. This is a non-empty, ordered list;
+# entries near the beginning of @interface-types are considered
+# more native to the firmware, and/or to have a higher quality
+# implementation in the firmware, than entries near the end of
+# @interface-types.
#
-# @mapping: Describes the loading / mapping properties of the firmware.
+# @mapping: Describes the loading / mapping properties of the
+# firmware.
#
# @targets: Collects the target architectures (QEMU system emulators)
-# and their machine types that may execute the firmware.
+# and their machine types that may execute the firmware.
#
# @features: Lists the features that the firmware supports, and the
-# platform requirements it presents.
+# platform requirements it presents.
#
# @tags: A list of auxiliary strings associated with the firmware for
-# which @description is not appropriate, due to the latter's
-# possible exposure to the end-user. @tags serves development and
-# debugging purposes only, and management software shall
-# explicitly ignore it.
+# which @description is not appropriate, due to the latter's
+# possible exposure to the end-user. @tags serves development and
+# debugging purposes only, and management software shall
+# explicitly ignore it.
#
# Since: 3.0
#
diff --git a/docs/interop/vhost-user.json b/docs/interop/vhost-user.json
index 095eb99cf7..cd3a768615 100644
--- a/docs/interop/vhost-user.json
+++ b/docs/interop/vhost-user.json
@@ -21,19 +21,33 @@
# List the various vhost user backend types.
#
# @9p: 9p virtio console
+#
# @balloon: virtio balloon
+#
# @block: virtio block
+#
# @caif: virtio caif
+#
# @console: virtio console
+#
# @crypto: virtio crypto
+#
# @gpu: virtio gpu
+#
# @input: virtio input
+#
# @net: virtio net
+#
# @rng: virtio rng
+#
# @rpmsg: virtio remote processor messaging
+#
# @rproc-serial: virtio remoteproc serial link
+#
# @scsi: virtio scsi
+#
# @vsock: virtio vsock transport
+#
# @fs: virtio fs (since 4.2)
#
# Since: 4.0
@@ -65,6 +79,7 @@
# List of vhost user "block" features.
#
# @read-only: The --read-only command line option is supported.
+#
# @blk-file: The --blk-file command line option is supported.
#
# Since: 5.0
@@ -96,6 +111,7 @@
# List of vhost user "input" features.
#
# @evdev-path: The --evdev-path command line option is supported.
+#
# @no-grab: The --no-grab command line option is supported.
#
# Since: 4.0
@@ -127,6 +143,7 @@
# List of vhost user "gpu" features.
#
# @render-node: The --render-node command line option is supported.
+#
# @virgl: The --virgl command line option is supported.
#
# Since: 4.0
@@ -177,36 +194,39 @@
# Describes a vhost user backend to management software.
#
# It is possible for multiple @VhostUserBackend elements to match the
-# search criteria of management software. Applications thus need rules
-# to pick one of the many matches, and users need the ability to
+# search criteria of management software. Applications thus need
+# rules to pick one of the many matches, and users need the ability to
# override distro defaults.
#
# It is recommended to create vhost user backend JSON files (each
# containing a single @VhostUserBackend root element) with a
# double-digit prefix, for example "50-qemu-gpu.json",
# "50-crosvm-gpu.json", etc, so they can be sorted in predictable
-# order. The backend JSON files should be searched for in three
+# order. The backend JSON files should be searched for in three
# directories:
#
# - /usr/share/qemu/vhost-user -- populated by distro-provided
# packages (XDG_DATA_DIRS covers
# /usr/share by default),
#
-# - /etc/qemu/vhost-user -- exclusively for sysadmins' local additions,
+# - /etc/qemu/vhost-user -- exclusively for sysadmins' local
+# additions,
#
-# - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user local
-# additions (XDG_CONFIG_HOME
-# defaults to $HOME/.config).
+# - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user
+# local additions
+# (XDG_CONFIG_HOME defaults to
+# $HOME/.config).
#
# Top-down, the list of directories goes from general to specific.
#
# Management software should build a list of files from all three
# locations, then sort the list by filename (i.e., basename
-# component). Management software should choose the first JSON file on
-# the sorted list that matches the search criteria. If a more specific
-# directory has a file with same name as a less specific directory,
-# then the file in the more specific directory takes effect. If the
-# more specific file is zero length, it hides the less specific one.
+# component). Management software should choose the first JSON file
+# on the sorted list that matches the search criteria. If a more
+# specific directory has a file with same name as a less specific
+# directory, then the file in the more specific directory takes
+# effect. If the more specific file is zero length, it hides the less
+# specific one.
#
# For example, if a distro ships
#
@@ -214,7 +234,8 @@
#
# - /usr/share/qemu/vhost-user/50-crosvm-gpu.json
#
-# then the sysadmin can prevent the default QEMU GPU being used at all with
+# then the sysadmin can prevent the default QEMU GPU being used at all
+# with
#
# $ touch /etc/qemu/vhost-user/50-qemu-gpu.json
#
@@ -233,15 +254,15 @@
# @type: The vhost user backend type.
#
# @description: Provides a human-readable description of the backend.
-# Management software may or may not display @description.
+# Management software may or may not display @description.
#
# @binary: Absolute path to the backend binary.
#
# @tags: An optional list of auxiliary strings associated with the
-# backend for which @description is not appropriate, due to the
-# latter's possible exposure to the end-user. @tags serves
-# development and debugging purposes only, and management
-# software shall explicitly ignore it.
+# backend for which @description is not appropriate, due to the
+# latter's possible exposure to the end-user. @tags serves
+# development and debugging purposes only, and management software
+# shall explicitly ignore it.
#
# Since: 4.0
#
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 7/9] docs/interop/firmware: Belatedly convert "Example" section
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
` (5 preceding siblings ...)
2025-11-03 8:23 ` [PATCH v2 6/9] docs/interop: Refill QAPI doc comments to conform to conventions Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 9:47 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 8/9] docs/interop/firmware: Literal block markup Markus Armbruster
` (2 subsequent siblings)
9 siblings, 1 reply; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
These are gone since 3c5f6114d9f (qapi: remove "Example" doc section).
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
docs/interop/vhost-user.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/interop/vhost-user.json b/docs/interop/vhost-user.json
index cd3a768615..29c84e86e5 100644
--- a/docs/interop/vhost-user.json
+++ b/docs/interop/vhost-user.json
@@ -266,7 +266,7 @@
#
# Since: 4.0
#
-# Example:
+# .. qmp-example:
#
# {
# "description": "QEMU vhost-user-gpu",
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 8/9] docs/interop/firmware: Literal block markup
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
` (6 preceding siblings ...)
2025-11-03 8:23 ` [PATCH v2 7/9] docs/interop/firmware: Belatedly convert "Example" section Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-03 8:23 ` [PATCH v2 9/9] docs/interop: Add test to keep vhost-user.json sane Markus Armbruster
2025-11-04 12:58 ` [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
A few doc comments show command line snippets. The snippets are
indented, which is legible enough. Actually formatting these with
Sphinx would fail with "Unexpected indentation", though. We don't so
far. Add suitable markup anyway.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
docs/interop/firmware.json | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index 7ffa7697e4..da0362a2c0 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -308,12 +308,19 @@
# indicates whether there will be an associated NVRAM template
# present. The preferred corresponding QEMU command line options
# are
+#
+# ::
+#
# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
# -machine pflash0=pflash0
+#
# or equivalent -blockdev instead of -drive. When @mode is
# @combined the executable must be cloned before use and
# configured with readonly=off. With QEMU versions older than
# 4.0, you have to use
+#
+# ::
+#
# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
#
# @nvram-template: Identifies the NVRAM template compatible with
@@ -326,10 +333,17 @@
# typically used for persistently storing the non-volatile UEFI
# variables of a virtual machine definition. The preferred
# corresponding QEMU command line options are
+#
+# ::
+#
# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
# -machine pflash1=pflash1
+#
# or equivalent -blockdev instead of -drive. With QEMU versions
# older than 4.0, you have to use
+#
+# ::
+#
# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
#
# Since: 3.0
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v2 9/9] docs/interop: Add test to keep vhost-user.json sane
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
` (7 preceding siblings ...)
2025-11-03 8:23 ` [PATCH v2 8/9] docs/interop/firmware: Literal block markup Markus Armbruster
@ 2025-11-03 8:23 ` Markus Armbruster
2025-11-04 12:58 ` [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-03 8:23 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
We did this for firmware.json in commit d4181658dfb (docs: add test
for firmware.json QAPI).
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
docs/meson.build | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/docs/meson.build b/docs/meson.build
index 3676f81c4d..7e54b01e6a 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -99,7 +99,12 @@ if build_docs
alias_target('man', sphinxmans)
endif
-test('QAPI firmware.json regression tests', qapi_gen,
- args: ['-o', meson.current_build_dir() / 'qapi',
+test('QAPI firmware.json regression test', qapi_gen,
+ args: ['-o', meson.current_build_dir() / 'qapi-firmware',
meson.current_source_dir() / 'interop/firmware.json'],
suite: ['qapi-schema', 'qapi-interop'])
+
+test('QAPI vhost-user.json regression test', qapi_gen,
+ args: ['-o', meson.current_build_dir() / 'qapi-vhost-user',
+ meson.current_source_dir() / 'interop/vhost-user.json'],
+ suite: ['qapi-schema', 'qapi-interop'])
--
2.49.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup
2025-11-03 8:23 [PATCH v2 0/9] A QAPI schema doc markup fix, and style cleanup Markus Armbruster
` (8 preceding siblings ...)
2025-11-03 8:23 ` [PATCH v2 9/9] docs/interop: Add test to keep vhost-user.json sane Markus Armbruster
@ 2025-11-04 12:58 ` Markus Armbruster
9 siblings, 0 replies; 12+ messages in thread
From: Markus Armbruster @ 2025-11-04 12:58 UTC (permalink / raw)
To: qemu-devel
Cc: jsnow, eblake, vsementsov, thuth, berrange, philmd, kchamart, mst,
sgarzare
Queued.
^ permalink raw reply [flat|nested] 12+ messages in thread