OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

qapi: Refill doc comments to conform to current conventions

Browse Source 
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>
This commit is contained in:
Markus Armbruster 2024-03-22 15:09:08 +01:00
parent 1e6b0505c4
commit 209e64d9ed
12 changed files with 142 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
qapi/block-core.json
View File

@ -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)

4
qapi/block.json
View File

@ -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",

4
qapi/cxl.json
View File

@ -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
#

16
qapi/dump.json
View File

@ -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)

12
qapi/ebpf.json
View File

@ -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).
#
##
##

22
qapi/machine-target.json
View File

@ -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
#

15
qapi/machine.json
View File

@ -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

104
qapi/migration.json
View File

@ -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
##

27
qapi/net.json
View File

@ -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
##

34
qapi/qom.json
View File

@ -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
##

4
qapi/run-state.json
View File

@ -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

12
qapi/virtio.json
View File

@ -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
##