@@ -1819,10 +1819,10 @@
# Care should be taken when specifying the string, to specify a
# valid filename or protocol. (Since 2.1)
#
-# @backing-mask-protocol: If true, replace any protocol mentioned in the
-# 'backing file format' with 'raw', rather than storing the protocol
-# name as the backing format. Can be used even when no image header
-# will be updated (default false; since 9.0).
+# @backing-mask-protocol: If true, replace any protocol mentioned in
+# the 'backing file format' with 'raw', rather than storing the
+# protocol name as the backing format. Can be used even when no
+# image header will be updated (default false; since 9.0).
#
# @speed: the maximum speed, in bytes per second
#
@@ -2825,10 +2825,10 @@
# Care should be taken when specifying the string, to specify a
# valid filename or protocol. (Since 2.1)
#
-# @backing-mask-protocol: If true, replace any protocol mentioned in the
-# 'backing file format' with 'raw', rather than storing the protocol
-# name as the backing format. Can be used even when no image header
-# will be updated (default false; since 9.0).
+# @backing-mask-protocol: If true, replace any protocol mentioned in
+# the 'backing file format' with 'raw', rather than storing the
+# protocol name as the backing format. Can be used even when no
+# image header will be updated (default false; since 9.0).
#
# @speed: the maximum speed, in bytes per second
#
@@ -3547,10 +3547,10 @@
# re-allocating them later. Besides potential performance
# degradation, such fragmentation can lead to increased allocation
# of clusters past the end of the image file, resulting in image
-# files whose file length can grow much larger than their guest disk
-# size would suggest. If image file length is of concern (e.g. when
-# storing qcow2 images directly on block devices), you should
-# consider enabling this option. (since 8.1)
+# files whose file length can grow much larger than their guest
+# disk size would suggest. If image file length is of concern
+# (e.g. when storing qcow2 images directly on block devices), you
+# should consider enabling this option. (since 8.1)
#
# @overlap-check: which overlap checks to perform for writes to the
# image, defaults to 'cached' (since 2.2)
@@ -555,8 +555,8 @@
#
# Example:
#
-# Set new histogram only for write, other histograms will remain not
-# changed (or not created):
+# Set new histogram only for write, other histograms will remain
+# not changed (or not created):
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0",
@@ -144,8 +144,8 @@
# @cxl-inject-memory-module-event:
#
# Inject an event record for a Memory Module Event (CXL r3.0
-# 8.2.9.2.1.3). This event includes a copy of the Device Health
-# info at the time of the event.
+# 8.2.9.2.1.3). This event includes a copy of the Device Health info
+# at the time of the event.
#
# @path: CXL type 3 device canonical QOM path
#
@@ -15,20 +15,20 @@
#
# @elf: elf format
#
-# @kdump-zlib: makedumpfile flattened, kdump-compressed format with zlib
-# compression
+# @kdump-zlib: makedumpfile flattened, kdump-compressed format with
+# zlib compression
#
# @kdump-lzo: makedumpfile flattened, kdump-compressed format with lzo
# compression
#
-# @kdump-snappy: makedumpfile flattened, kdump-compressed format with snappy
-# compression
+# @kdump-snappy: makedumpfile flattened, kdump-compressed format with
+# snappy compression
#
-# @kdump-raw-zlib: raw assembled kdump-compressed format with zlib compression
-# (since 8.2)
+# @kdump-raw-zlib: raw assembled kdump-compressed format with zlib
+# compression (since 8.2)
#
-# @kdump-raw-lzo: raw assembled kdump-compressed format with lzo compression
-# (since 8.2)
+# @kdump-raw-lzo: raw assembled kdump-compressed format with lzo
+# compression (since 8.2)
#
# @kdump-raw-snappy: raw assembled kdump-compressed format with snappy
# compression (since 8.2)
@@ -7,15 +7,13 @@
##
# = eBPF Objects
#
-# eBPF object is an ELF binary that contains the eBPF
-# program and eBPF map description(BTF). Overall, eBPF
-# object should contain the program and enough metadata
-# to create/load eBPF with libbpf. As the eBPF maps/program
-# should correspond to QEMU, the eBPF can't be used from
-# different QEMU build.
+# eBPF object is an ELF binary that contains the eBPF program and eBPF
+# map description(BTF). Overall, eBPF object should contain the
+# program and enough metadata to create/load eBPF with libbpf. As the
+# eBPF maps/program should correspond to QEMU, the eBPF can't be used
+# from different QEMU build.
#
# Currently, there is a possible eBPF for receive-side scaling (RSS).
-#
##
##
@@ -394,9 +394,9 @@
##
# @set-cpu-topology:
#
-# Modify the topology by moving the CPU inside the topology tree,
-# or by changing a modifier attribute of a CPU.
-# Absent values will not be modified.
+# Modify the topology by moving the CPU inside the topology tree, or
+# by changing a modifier attribute of a CPU. Absent values will not
+# be modified.
#
# @core-id: the vCPU ID to be moved
#
@@ -408,7 +408,8 @@
#
# @entitlement: entitlement to set
#
-# @dedicated: whether the provisioning of real to virtual CPU is dedicated
+# @dedicated: whether the provisioning of real to virtual CPU is
+# dedicated
#
# Features:
#
@@ -435,14 +436,15 @@
# Emitted when the guest asks to change the polarization.
#
# The guest can tell the host (via the PTF instruction) whether the
-# CPUs should be provisioned using horizontal or vertical polarization.
+# CPUs should be provisioned using horizontal or vertical
+# polarization.
#
-# On horizontal polarization the host is expected to provision all vCPUs
-# equally.
+# On horizontal polarization the host is expected to provision all
+# vCPUs equally.
#
-# On vertical polarization the host can provision each vCPU differently.
-# The guest will get information on the details of the provisioning
-# the next time it uses the STSI(15) instruction.
+# On vertical polarization the host can provision each vCPU
+# differently. The guest will get information on the details of the
+# provisioning the next time it uses the STSI(15) instruction.
#
# @polarization: polarization specified by the guest
#
@@ -925,8 +925,7 @@
# @cluster-id: cluster number within the parent container the CPU
# belongs to (since 7.1)
#
-# @core-id: core number within the parent container the CPU
-# belongs to
+# @core-id: core number within the parent container the CPU belongs to
#
# @thread-id: thread number within the core the CPU belongs to
#
@@ -982,8 +981,8 @@
#
# Examples:
#
-# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu
-# POWER8:
+# For pseries machine type started with -smp 2,cores=2,maxcpus=4
+# -cpu POWER8:
#
# -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [
@@ -1008,8 +1007,8 @@
# }
# ]}
#
-# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu
-# qemu (Since: 2.11):
+# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2
+# -cpu qemu (Since: 2.11):
#
# -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [
@@ -1152,8 +1151,8 @@
##
# @query-hv-balloon-status-report:
#
-# Returns the hv-balloon driver data contained in the last received "STATUS"
-# message from the guest.
+# Returns the hv-balloon driver data contained in the last received
+# "STATUS" message from the guest.
#
# Returns:
# @HvBalloonInfo
@@ -23,8 +23,8 @@
#
# @duplicate: number of duplicate (zero) pages (since 1.2)
#
-# @skipped: number of skipped zero pages. Always zero, only provided for
-# compatibility (since 1.5)
+# @skipped: number of skipped zero pages. Always zero, only provided
+# for compatibility (since 1.5)
#
# @normal: number of normal pages (since 1.2)
#
@@ -501,8 +501,8 @@
#
# @background-snapshot: If enabled, the migration stream will be a
# snapshot of the VM exactly at the point when the migration
-# procedure starts. The VM RAM is saved with running VM. (since
-# 6.0)
+# procedure starts. The VM RAM is saved with running VM.
+# (since 6.0)
#
# @zero-copy-send: Controls behavior on sending memory pages on
# migration. When true, enables a zero-copy mechanism for sending
@@ -640,9 +640,9 @@
#
# @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 -incoming.
+# @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
# reboot the OS, and restart QEMU. If the user reboots, the URI
@@ -652,8 +652,8 @@
# does not block the migration, but the user must not modify the
# contents of guest block devices between the quit and restart.
#
-# This mode supports VFIO devices provided the user first puts
-# the guest in the suspended runstate, such as by issuing
+# This mode supports VFIO devices provided the user first puts the
+# guest in the suspended runstate, such as by issuing
# guest-suspend-ram to the QEMU guest agent.
#
# Best performance is achieved when the memory backend is shared
@@ -678,11 +678,10 @@
# @legacy: Perform zero page checking in main migration thread.
#
# @multifd: Perform zero page checking in multifd sender thread if
-# multifd migration is enabled, else in the main migration
-# thread as for @legacy.
+# multifd migration is enabled, else in the main migration thread
+# as for @legacy.
#
# Since: 9.0
-#
##
{ 'enum': 'ZeroPageDetection',
'data': [ 'none', 'legacy', 'multifd' ] }
@@ -834,13 +833,14 @@
#
# @avail-switchover-bandwidth: to set the available bandwidth that
# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations when
-# making decisions to switchover. By default, this value is zero,
-# which means QEMU will estimate the bandwidth automatically. This can
-# be set when the estimated value is not accurate, while the user is
-# able to guarantee such bandwidth is available when switching over.
-# When specified correctly, this can make the switchover decision much
-# more accurate. (Since 8.2)
+# limit the bandwidth during switchover, but only for calculations
+# when making decisions to switchover. By default, this value is
+# zero, which means QEMU will estimate the bandwidth
+# automatically. This can be set when the estimated value is not
+# accurate, while the user is able to guarantee such bandwidth is
+# available when switching over. When specified correctly, this
+# can make the switchover decision much more accurate.
+# (Since 8.2)
#
# @downtime-limit: set maximum tolerated downtime for migration.
# maximum downtime in milliseconds (Since 2.8)
@@ -902,14 +902,14 @@
# to their node name otherwise. (Since 5.2)
#
# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty
-# limit during live migration. Should be in the range 1 to 1000ms.
-# Defaults to 1000ms. (Since 8.1)
+# limit during live migration. Should be in the range 1 to
+# 1000ms. Defaults to 1000ms. (Since 8.1)
#
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
-# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
-# (Since 8.2)
+# @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'.
@@ -922,8 +922,8 @@
# @compress-threads, @decompress-threads and @compress-wait-thread
# are deprecated because @compression is deprecated.
#
-# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
-# are experimental.
+# @unstable: Members @x-checkpoint-delay and
+# @x-vcpu-dirty-limit-period are experimental.
#
# Since: 2.4
##
@@ -1041,13 +1041,14 @@
#
# @avail-switchover-bandwidth: to set the available bandwidth that
# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations when
-# making decisions to switchover. By default, this value is zero,
-# which means QEMU will estimate the bandwidth automatically. This can
-# be set when the estimated value is not accurate, while the user is
-# able to guarantee such bandwidth is available when switching over.
-# When specified correctly, this can make the switchover decision much
-# more accurate. (Since 8.2)
+# limit the bandwidth during switchover, but only for calculations
+# when making decisions to switchover. By default, this value is
+# zero, which means QEMU will estimate the bandwidth
+# automatically. This can be set when the estimated value is not
+# accurate, while the user is able to guarantee such bandwidth is
+# available when switching over. When specified correctly, this
+# can make the switchover decision much more accurate.
+# (Since 8.2)
#
# @downtime-limit: set maximum tolerated downtime for migration.
# maximum downtime in milliseconds (Since 2.8)
@@ -1109,14 +1110,14 @@
# to their node name otherwise. (Since 5.2)
#
# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty
-# limit during live migration. Should be in the range 1 to 1000ms.
-# Defaults to 1000ms. (Since 8.1)
+# limit during live migration. Should be in the range 1 to
+# 1000ms. Defaults to 1000ms. (Since 8.1)
#
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
-# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
-# (Since 8.2)
+# @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'.
@@ -1129,8 +1130,8 @@
# @compress-threads, @decompress-threads and @compress-wait-thread
# are deprecated because @compression is deprecated.
#
-# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
-# are experimental.
+# @unstable: Members @x-checkpoint-delay and
+# @x-vcpu-dirty-limit-period are experimental.
#
# TODO: either fuse back into MigrationParameters, or make
# MigrationParameters members mandatory
@@ -1272,13 +1273,14 @@
#
# @avail-switchover-bandwidth: to set the available bandwidth that
# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations when
-# making decisions to switchover. By default, this value is zero,
-# which means QEMU will estimate the bandwidth automatically. This can
-# be set when the estimated value is not accurate, while the user is
-# able to guarantee such bandwidth is available when switching over.
-# When specified correctly, this can make the switchover decision much
-# more accurate. (Since 8.2)
+# limit the bandwidth during switchover, but only for calculations
+# when making decisions to switchover. By default, this value is
+# zero, which means QEMU will estimate the bandwidth
+# automatically. This can be set when the estimated value is not
+# accurate, while the user is able to guarantee such bandwidth is
+# available when switching over. When specified correctly, this
+# can make the switchover decision much more accurate.
+# (Since 8.2)
#
# @downtime-limit: set maximum tolerated downtime for migration.
# maximum downtime in milliseconds (Since 2.8)
@@ -1340,14 +1342,14 @@
# to their node name otherwise. (Since 5.2)
#
# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty
-# limit during live migration. Should be in the range 1 to 1000ms.
-# Defaults to 1000ms. (Since 8.1)
+# limit during live migration. Should be in the range 1 to
+# 1000ms. Defaults to 1000ms. (Since 8.1)
#
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
-# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
-# (Since 8.2)
+# @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'.
@@ -1360,8 +1362,8 @@
# @compress-threads, @decompress-threads and @compress-wait-thread
# are deprecated because @compression is deprecated.
#
-# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
-# are experimental.
+# @unstable: Members @x-checkpoint-delay and
+# @x-vcpu-dirty-limit-period are experimental.
#
# Since: 2.4
##
@@ -425,8 +425,8 @@
#
# @skb: generic mode, no driver support necessary
#
-# @native: DRV mode, program is attached to a driver, packets are passed to
-# the socket without allocation of skb.
+# @native: DRV mode, program is attached to a driver, packets are
+# passed to the socket without allocation of skb.
#
# Since: 8.2
##
@@ -441,23 +441,26 @@
#
# @ifname: The name of an existing network interface.
#
-# @mode: Attach mode for a default XDP program. If not specified, then
-# 'native' will be tried first, then 'skb'.
+# @mode: Attach mode for a default XDP program. If not specified,
+# then 'native' will be tried first, then 'skb'.
#
# @force-copy: Force XDP copy mode even if device supports zero-copy.
# (default: false)
#
-# @queues: number of queues to be used for multiqueue interfaces (default: 1).
+# @queues: number of queues to be used for multiqueue interfaces
+# (default: 1).
#
-# @start-queue: Use @queues starting from this queue number (default: 0).
+# @start-queue: Use @queues starting from this queue number
+# (default: 0).
#
-# @inhibit: Don't load a default XDP program, use one already loaded to
-# the interface (default: false). Requires @sock-fds.
+# @inhibit: Don't load a default XDP program, use one already loaded
+# to the interface (default: false). Requires @sock-fds.
#
-# @sock-fds: A colon (:) separated list of file descriptors for already open
-# but not bound AF_XDP sockets in the queue order. One fd per queue.
-# These descriptors should already be added into XDP socket map for
-# corresponding queues. Requires @inhibit.
+# @sock-fds: A colon (:) separated list of file descriptors for
+# already open but not bound AF_XDP sockets in the queue order.
+# One fd per queue. These descriptors should already be added
+# into XDP socket map for corresponding queues. Requires
+# @inhibit.
#
# Since: 8.2
##
@@ -668,19 +668,20 @@
# @readonly: if true, the backing file is opened read-only; if false,
# it is opened read-write. (default: false)
#
-# @rom: whether to create Read Only Memory (ROM) that cannot be modified
-# by the VM. Any write attempts to such ROM will be denied. Most
-# use cases want writable RAM instead of ROM. However, selected use
-# cases, like R/O NVDIMMs, can benefit from ROM. If set to 'on',
-# create ROM; if set to 'off', create writable RAM; if set to
-# 'auto', the value of the @readonly property is used. This
-# property is primarily helpful when we want to have proper RAM in
-# configurations that would traditionally create ROM before this
-# property was introduced: VM templating, where we want to open a
-# file readonly (@readonly set to true) and mark the memory to be
-# private for QEMU (@share set to false). For this use case, we need
-# writable RAM instead of ROM, and want to set this property to 'off'.
-# (default: auto, since 8.2)
+# @rom: whether to create Read Only Memory (ROM) that cannot be
+# modified by the VM. Any write attempts to such ROM will be
+# denied. Most use cases want writable RAM instead of ROM.
+# However, selected use cases, like R/O NVDIMMs, can benefit from
+# ROM. If set to 'on', create ROM; if set to 'off', create
+# writable RAM; if set to 'auto', the value of the @readonly
+# property is used. This property is primarily helpful when we
+# want to have proper RAM in configurations that would
+# traditionally create ROM before this property was introduced: VM
+# templating, where we want to open a file readonly (@readonly set
+# to true) and mark the memory to be private for QEMU (@share set
+# to false). For this use case, we need writable RAM instead of
+# ROM, and want to set this property to 'off'. (default: auto,
+# since 8.2)
#
# Since: 2.1
##
@@ -801,10 +802,9 @@
#
# @fd: file descriptor name previously passed via 'getfd' command,
# which represents a pre-opened /dev/iommu. This allows the
-# iommufd object to be shared accross several subsystems
-# (VFIO, VDPA, ...), and the file descriptor to be shared
-# with other process, e.g. DPDK. (default: QEMU opens
-# /dev/iommu by itself)
+# iommufd object to be shared accross several subsystems (VFIO,
+# VDPA, ...), and the file descriptor to be shared with other
+# process, e.g. DPDK. (default: QEMU opens /dev/iommu by itself)
#
# Since: 9.0
##
@@ -144,8 +144,8 @@
# hardware-specific action) rather than a host request (such as
# sending qemu a SIGINT). (since 2.10)
#
-# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since
-# 4.0)
+# @reason: The @ShutdownCause which resulted in the SHUTDOWN.
+# (since 4.0)
#
# Note: If the command-line option "-no-shutdown" has been specified,
# qemu will not exit, and a STOP event will eventually follow the
@@ -938,10 +938,11 @@
#
# @iothread: the id of IOThread object
#
-# @vqs: an optional array of virtqueue indices that will be handled by this
-# IOThread. When absent, virtqueues are assigned round-robin across all
-# IOThreadVirtQueueMappings provided. Either all IOThreadVirtQueueMappings
-# must have @vqs or none of them must have it.
+# @vqs: an optional array of virtqueue indices that will be handled by
+# this IOThread. When absent, virtqueues are assigned round-robin
+# across all IOThreadVirtQueueMappings provided. Either all
+# IOThreadVirtQueueMappings must have @vqs or none of them must
+# have it.
#
# Since: 9.0
##
@@ -952,7 +953,8 @@
##
# @DummyVirtioForceArrays:
#
-# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList internally
+# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
+# internally
#
# Since: 9.0
##
For legibility, wrap text paragraphs so every line is at most 70 characters long. 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 refilled paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240322140910.328840-11-armbru@redhat.com> --- qapi/block-core.json | 24 ++++----- qapi/block.json | 4 +- qapi/cxl.json | 4 +- qapi/dump.json | 16 +++--- qapi/ebpf.json | 12 ++--- qapi/machine-target.json | 22 +++++---- qapi/machine.json | 15 +++--- qapi/migration.json | 104 ++++++++++++++++++++------------------- qapi/net.json | 27 +++++----- qapi/qom.json | 34 ++++++------- qapi/run-state.json | 4 +- qapi/virtio.json | 12 +++-- 12 files changed, 142 insertions(+), 136 deletions(-)