Merge tag 'pull-qapi-2024-03-26' of https://repo.or.cz/qemu/armbru into staging
QAPI patches patches for 2024-03-26
# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmYCXs0SHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTRMkP/RR9ipyCh1P6KKuQCyouxM8nXZ945b33
# L0OBFY4cTZsMY98ZTU9i80f/Tjh58y5bYzSdr21jxBSdRlvb6w/Ys8xUsI2Hi/kZ
# czdKZbWT5IeSNrLw04CjhW2FKq8XXR7epHbPms2nBa1Xc5Jf8aIC2UhZKADeVCyE
# FCIUU8Ctkyvre3XGVOrIBhhVPs9hi33uG+HXiveQjjWwGZZ0v915sAZ4WvNEoiBS
# E0NwhJxtbQu8FwfBquE84o0TMzYb19MlU4zq3G5dv7PhLoXX9Lf097/tPEtoP4et
# H37eGD8MzL1hywf+E1vAw0HC/v7Ci5Kx1jpUUL03Hfvfa6Lktb6yYke8qAD1HopK
# o4btXKpfseuyTJuqTVaV4Z9tLqmpTddnUupBFkfKviMPdidAN9SM1qXx0VCM9mUo
# cwf5di6zOPTNYlsKuP6ofSGGaD5so9PGLGAZoGeZ1Cb7TLsgiqqD0GrPP0//1VLn
# GzOOsOA4Su9F2/qjkNu2HZ1jv6J105LbQnaPvqjVfkjzzmoOANYmViX3KmDwdBxX
# vSfy5/UpCP9TBv++N/ljRtrVzW9i4a2rIGeHWC0x/JJglIh45f2MzeyqJ5haV2n5
# MVY82yY7EY7U+YXUUUKSgGVWw7+/wj/R5wQ5a9Gjk9OlmTsTHxJIKIzhcw4lX9da
# ZmRLCSIlVu4Z
# =li36
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 26 Mar 2024 05:36:13 GMT
# gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg: issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867 4E5F 3870 B400 EB91 8653
* tag 'pull-qapi-2024-03-26' of https://repo.or.cz/qemu/armbru:
qapi: document parameters of query-cpu-model-* QAPI commands
qapi/block-core: improve Qcow2OverlapCheckFlags documentation
qapi: document leftover members in qapi/stats.json
qapi: document leftover members in qapi/run-state.json
qapi: document InputMultiTouchType
qga/qapi-schema: Refill doc comments to conform to current conventions
qapi: Correct documentation indentation and whitespace
qapi: Refill doc comments to conform to current conventions
qapi: Don't repeat member type in its documentation text
qapi: Start sentences with a capital letter, end them with a period
qapi: Fix abbreviation punctuation in doc comments
qapi: Fix typo in request-ebpf documentation
qapi: Fix argument markup in drive-mirror documentation
qapi: Tidy up indentation of add_client's example
qapi: Tidy up block-latency-histogram-set documentation some more
qapi: Expand a few awkward abbreviations in documentation
qapi: Drop stray Arguments: line from qmp_capabilities docs
qapi: Fix bogus documentation of query-migrationthreads
qapi: Resync MigrationParameter and MigrateSetParameters
qapi: Improve migration TLS documentation
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 1874f88..746d169 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -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
#
@@ -2117,7 +2117,7 @@
# Start mirroring a block device's writes to a new destination.
# target specifies the target of the new image. If the file exists,
# or if it is a device, it will be used as the new destination for
-# writes. If it does not exist, a new file will be created. format
+# writes. If it does not exist, a new file will be created. @format
# specifies the format of the mirror image, default is to probe if
# mode='existing', else the format of the source.
#
@@ -2593,27 +2593,27 @@
#
# @bps_max_length: maximum length of the @bps_max burst period, in
# seconds. It must only be set if @bps_max is set as well.
-# Defaults to 1. (Since 2.6)
+# Defaults to 1. (Since 2.6)
#
# @bps_rd_max_length: maximum length of the @bps_rd_max burst period,
# in seconds. It must only be set if @bps_rd_max is set as well.
-# Defaults to 1. (Since 2.6)
+# Defaults to 1. (Since 2.6)
#
# @bps_wr_max_length: maximum length of the @bps_wr_max burst period,
# in seconds. It must only be set if @bps_wr_max is set as well.
-# Defaults to 1. (Since 2.6)
+# Defaults to 1. (Since 2.6)
#
# @iops_max_length: maximum length of the @iops burst period, in
# seconds. It must only be set if @iops_max is set as well.
-# Defaults to 1. (Since 2.6)
+# Defaults to 1. (Since 2.6)
#
# @iops_rd_max_length: maximum length of the @iops_rd_max burst
# period, in seconds. It must only be set if @iops_rd_max is set
-# as well. Defaults to 1. (Since 2.6)
+# as well. Defaults to 1. (Since 2.6)
#
# @iops_wr_max_length: maximum length of the @iops_wr_max burst
# period, in seconds. It must only be set if @iops_wr_max is set
-# as well. Defaults to 1. (Since 2.6)
+# as well. Defaults to 1. (Since 2.6)
#
# @iops_size: an I/O size in bytes (Since 1.7)
#
@@ -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
#
@@ -3354,7 +3354,7 @@
# decryption key (since 2.6). Mandatory except when doing a
# metadata-only probe of the image.
#
-# @header: block device holding a detached LUKS header. (since 9.0)
+# @header: block device holding a detached LUKS header. (since 9.0)
#
# Since: 2.9
##
@@ -3403,14 +3403,31 @@
# @Qcow2OverlapCheckFlags:
#
# Structure of flags for each metadata structure. Setting a field to
-# 'true' makes qemu guard that structure against unintended
-# overwriting. The default value is chosen according to the template
-# given.
+# 'true' makes QEMU guard that Qcow2 format structure against
+# unintended overwriting. See Qcow2 format specification for detailed
+# information on these structures. The default value is chosen
+# according to the template given.
#
# @template: Specifies a template mode which can be adjusted using the
# other flags, defaults to 'cached'
#
-# @bitmap-directory: since 3.0
+# @main-header: Qcow2 format header
+#
+# @active-l1: Qcow2 active L1 table
+#
+# @active-l2: Qcow2 active L2 table
+#
+# @refcount-table: Qcow2 refcount table
+#
+# @refcount-block: Qcow2 refcount blocks
+#
+# @snapshot-table: Qcow2 snapshot table
+#
+# @inactive-l1: Qcow2 inactive L1 tables
+#
+# @inactive-l2: Qcow2 inactive L2 tables
+#
+# @bitmap-directory: Qcow2 bitmap directory (since 3.0)
#
# Since: 2.9
##
@@ -3547,10 +3564,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)
@@ -4619,7 +4636,7 @@
# seconds for copy-before-write operation. When a timeout occurs,
# the respective copy-before-write operation will fail, and the
# @on-cbw-error parameter will decide how this failure is handled.
-# Default 0. (Since 7.1)
+# Default 0. (Since 7.1)
#
# Since: 6.2
##
@@ -4953,9 +4970,9 @@
# Driver specific image creation options for LUKS.
#
# @file: Node to create the image format on, mandatory except when
-# 'preallocation' is not requested
+# 'preallocation' is not requested
#
-# @header: Block device holding a detached LUKS header. (since 9.0)
+# @header: Block device holding a detached LUKS header. (since 9.0)
#
# @size: Size of the virtual disk in bytes
#
diff --git a/qapi/block.json b/qapi/block.json
index 65d9804..5de99fe0 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -545,8 +545,8 @@
#
# Example:
#
-# Set new histograms for all io types with intervals [0, 10), [10,
-# 50), [50, 100), [100, +inf):
+# Set new histograms for all io types with intervals
+# [0, 10), [10, 50), [50, 100), [100, +inf):
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0",
@@ -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",
@@ -565,9 +565,9 @@
#
# Example:
#
-# Set new histograms with the following intervals: read, flush: [0,
-# 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000,
-# 5000), [5000, +inf)
+# Set new histograms with the following intervals:
+# read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
+# write: [0, 1000), [1000, 5000), [5000, +inf)
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0",
diff --git a/qapi/control.json b/qapi/control.json
index f404dae..6bdbf07 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -11,8 +11,6 @@
#
# Enable QMP capabilities.
#
-# Arguments:
-#
# @enable: An optional list of QMPCapability values to enable. The
# client must not enable any capability that is not mentioned in
# the QMP greeting message. If the field is not provided, it
diff --git a/qapi/crypto.json b/qapi/crypto.json
index 931c88e..e102be3 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -48,15 +48,15 @@
#
# @sha1: SHA-1. Should not be used in any new code, legacy compat only
#
-# @sha224: SHA-224. (since 2.7)
+# @sha224: SHA-224. (since 2.7)
#
# @sha256: SHA-256. Current recommended strong hash.
#
-# @sha384: SHA-384. (since 2.7)
+# @sha384: SHA-384. (since 2.7)
#
-# @sha512: SHA-512. (since 2.7)
+# @sha512: SHA-512. (since 2.7)
#
-# @ripemd160: RIPEMD-160. (since 2.7)
+# @ripemd160: RIPEMD-160. (since 2.7)
#
# Since: 2.6
##
@@ -224,9 +224,9 @@
# 'sha256'
#
# @iter-time: number of milliseconds to spend in PBKDF passphrase
-# processing. Currently defaults to 2000. (since 2.8)
+# processing. Currently defaults to 2000. (since 2.8)
#
-# @detached-header: create a detached LUKS header. (since 9.0)
+# @detached-header: create a detached LUKS header. (since 9.0)
#
# Since: 2.6
##
diff --git a/qapi/cxl.json b/qapi/cxl.json
index 8cc4c72..4281726 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -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
#
diff --git a/qapi/dump.json b/qapi/dump.json
index 4c021dd..2fa9504 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -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)
@@ -77,7 +77,7 @@
#
# @detach: if true, QMP will return immediately rather than waiting
# for the dump to finish. The user can track progress using
-# "query-dump". (since 2.6).
+# "query-dump". (since 2.6).
#
# @begin: if specified, the starting physical address.
#
diff --git a/qapi/ebpf.json b/qapi/ebpf.json
index f413d00..e500b5a 100644
--- a/qapi/ebpf.json
+++ b/qapi/ebpf.json
@@ -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).
-#
##
##
@@ -51,7 +49,7 @@
# @request-ebpf:
#
# Retrieve an eBPF object that can be loaded with libbpf. Management
-# applications (g.e. libvirt) may load it and pass file descriptors to
+# applications (e.g. libvirt) may load it and pass file descriptors to
# QEMU, so they can run running QEMU without BPF capabilities.
#
# @id: The ID of the program to return.
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 519adf3..29e695a 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -124,11 +124,12 @@
##
# @query-cpu-model-comparison:
#
-# Compares two CPU models, 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.
+# 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.
#
# Usually, a CPU model is compared against the maximum possible CPU
# model of a certain configuration (e.g. the "host" model for KVM).
@@ -154,7 +155,14 @@
# Some architectures may not support comparing CPU models. s390x
# supports comparing CPU models.
#
-# Returns: a CpuModelBaselineInfo
+# @modela: description of the first CPU model to compare, referred to as
+# "model A" in CpuModelCompareResult
+#
+# @modelb: description of the second CPU model to compare, referred to as
+# "model B" in CpuModelCompareResult
+#
+# Returns: a CpuModelCompareInfo describing how both CPU models
+# compare
#
# Errors:
# - if comparing CPU models is not supported
@@ -175,9 +183,9 @@
##
# @query-cpu-model-baseline:
#
-# Baseline two CPU models, creating a compatible third model. The
-# created model will always be a static, migration-safe CPU model (see
-# "static" CPU model expansion for details).
+# Baseline two CPU models, @modela and @modelb, creating a compatible
+# third model. The created model will always be a static,
+# migration-safe CPU model (see "static" CPU model expansion for details).
#
# This interface can be used by tooling to create a compatible CPU
# model out two CPU models. The created CPU model will be identical
@@ -204,7 +212,11 @@
# Some architectures may not support baselining CPU models. s390x
# supports baselining CPU models.
#
-# Returns: a CpuModelBaselineInfo
+# @modela: description of the first CPU model to baseline
+#
+# @modelb: description of the second CPU model to baseline
+#
+# Returns: a CpuModelBaselineInfo describing the baselined CPU model
#
# Errors:
# - if baselining CPU models is not supported
@@ -243,10 +255,10 @@
##
# @query-cpu-model-expansion:
#
-# Expands a given CPU model (or a combination of CPU model +
-# additional options) to different granularities, allowing tooling to
-# get an understanding what a specific CPU model looks like in QEMU
-# under a certain configuration.
+# Expands a given CPU model, @model, (or a combination of CPU model +
+# additional options) to different granularities, specified by
+# @type, allowing tooling to get an understanding what a specific
+# CPU model looks like in QEMU under a certain configuration.
#
# This interface can be used to query the "host" CPU model.
#
@@ -269,7 +281,11 @@
# Some architectures may not support all expansion types. s390x
# supports "full" and "static". Arm only supports "full".
#
-# Returns: a CpuModelExpansionInfo
+# @model: description of the CPU model to expand
+#
+# @type: expansion type, specifying how to expand the CPU model
+#
+# Returns: a CpuModelExpansionInfo describing the expanded CPU model
#
# Errors:
# - if expanding CPU models is not supported
@@ -394,9 +410,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 +424,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 +452,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
#
diff --git a/qapi/machine.json b/qapi/machine.json
index 0840c91..e8b6064 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -920,13 +920,12 @@
# @socket-id: socket number within parent container the CPU belongs to
#
# @die-id: die number within the parent container the CPU belongs to
-# (since 4.1)
+# (since 4.1)
#
# @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
@@ -1191,7 +1190,6 @@
# <- { "event": "HV_BALLOON_STATUS_REPORT",
# "data": { "committed": 816640000, "available": 3333054464 },
# "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
-#
##
{ 'event': 'HV_BALLOON_STATUS_REPORT',
'data': 'HvBalloonInfo' }
diff --git a/qapi/migration.json b/qapi/migration.json
index aa1b39b..8c65b90 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -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)
#
@@ -68,7 +68,6 @@
# @deprecated: Member @skipped is always zero since 1.5.3
#
# Since: 0.14
-#
##
{ 'struct': 'MigrationStats',
'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
@@ -230,7 +229,7 @@
# throttled during auto-converge. This is only present when
# auto-converge has started throttling guest cpus. (Since 2.7)
#
-# @error-desc: the human readable error description string. Clients
+# @error-desc: the human readable error description string. Clients
# should not attempt to parse the error strings. (Since 2.7)
#
# @postcopy-blocktime: total time when all vCPU were blocked during
@@ -501,8 +500,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
@@ -638,11 +637,11 @@
##
# @MigMode:
#
-# @normal: the original form of migration. (since 8.2)
+# @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 +651,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 +677,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' ] }
@@ -782,15 +780,15 @@
#
# @throttle-trigger-threshold: The ratio of bytes_dirty_period and
# bytes_xfer_period to trigger throttling. It is expressed as
-# percentage. The default value is 50. (Since 5.0)
+# percentage. The default value is 50. (Since 5.0)
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are
# throttled when migration auto-converge is activated. The
-# default value is 20. (Since 2.7)
+# default value is 20. (Since 2.7)
#
# @cpu-throttle-increment: throttle percentage increase each time
# auto-converge detects that migration is not making progress.
-# The default value is 10. (Since 2.7)
+# The default value is 10. (Since 2.7)
#
# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
# the tail stage of throttling, the Guest is very sensitive to CPU
@@ -809,16 +807,19 @@
# for establishing a TLS connection over the migration data
# channel. On the outgoing side of the migration, the credentials
# must be for a 'client' endpoint, while for the incoming side the
-# credentials must be for a 'server' endpoint. Setting this will
-# enable TLS for all migrations. The default is unset, resulting
-# in unsecured migration at the QEMU level. (Since 2.7)
+# credentials must be for a 'server' endpoint. Setting this to a
+# non-empty string enables TLS for all migrations. An empty
+# string means that QEMU will use plain text mode for migration,
+# rather than TLS. (Since 2.7)
#
-# @tls-hostname: hostname of the target host for the migration. This
-# is required when using x509 based TLS credentials and the
-# migration URI does not already include a hostname. For example
-# if using fd: or exec: based migration, the hostname must be
-# provided so that the server's x509 certificate identity can be
-# validated. (Since 2.7)
+# @tls-hostname: migration target's hostname for validating the
+# server's x509 certificate identity. If empty, QEMU will use the
+# hostname from the migration URI, if any. A non-empty value is
+# required when using x509 based TLS credentials and the migration
+# URI does not include a hostname, such as fd: or exec: based
+# migration. (Since 2.7)
+#
+# Note: empty value works only since 2.9.
#
# @tls-authz: ID of the 'authz' object subclass that provides access
# control checking of the TLS x509 certificate distinguished name.
@@ -826,18 +827,19 @@
# and recreated on the fly while the migration server is active.
# If missing, it will default to denying access (Since 4.0)
#
-# @max-bandwidth: to set maximum speed for migration. maximum speed
-# in bytes per second. (Since 2.8)
+# @max-bandwidth: maximum speed for migration, in bytes per second.
+# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations when
-# making decisions to switchover. By default, this value is zero,
-# which means QEMU will estimate the bandwidth 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)
@@ -874,13 +876,13 @@
# migration, the compression level is an integer between 0 and 9,
# where 0 means no compression, 1 means the best compression
# speed, and 9 means best compression ratio which will consume
-# more CPU. Defaults to 1. (Since 5.0)
+# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
# where 0 means no compression, 1 means the best compression
# speed, and 20 means best compression ratio which will consume
-# more CPU. Defaults to 1. (Since 5.0)
+# more CPU. Defaults to 1. (Since 5.0)
#
# @block-bitmap-mapping: Maps block nodes and bitmaps on them to
# aliases for the purpose of dirty bitmap migration. Such aliases
@@ -899,14 +901,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'.
@@ -919,8 +921,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
##
@@ -963,28 +965,38 @@
# @announce-step: Increase in delay (in milliseconds) between
# subsequent packets in the announcement (Since 4.0)
#
-# @compress-level: compression level
+# @compress-level: Set the compression level to be used in live
+# migration, the compression level is an integer between 0 and 9,
+# where 0 means no compression, 1 means the best compression
+# speed, and 9 means best compression ratio which will consume
+# more CPU.
#
-# @compress-threads: compression thread count
+# @compress-threads: Set compression thread count to be used in live
+# migration, the compression thread count is an integer between 1
+# and 255.
#
# @compress-wait-thread: Controls behavior when all compression
# threads are currently busy. If true (default), wait for a free
# compression thread to become available; otherwise, send the page
# uncompressed. (Since 3.1)
#
-# @decompress-threads: decompression thread count
+# @decompress-threads: Set decompression thread count to be used in
+# live migration, the decompression thread count is an integer
+# between 1 and 255. Usually, decompression is at least 4 times as
+# fast as compression, so set the decompress-threads to the number
+# about 1/4 of compress-threads is adequate.
#
# @throttle-trigger-threshold: The ratio of bytes_dirty_period and
# bytes_xfer_period to trigger throttling. It is expressed as
-# percentage. The default value is 50. (Since 5.0)
+# percentage. The default value is 50. (Since 5.0)
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are
# throttled when migration auto-converge is activated. The
-# default value is 20. (Since 2.7)
+# default value is 20. (Since 2.7)
#
# @cpu-throttle-increment: throttle percentage increase each time
# auto-converge detects that migration is not making progress.
-# The default value is 10. (Since 2.7)
+# The default value is 10. (Since 2.7)
#
# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
# the tail stage of throttling, the Guest is very sensitive to CPU
@@ -1006,41 +1018,42 @@
# credentials must be for a 'server' endpoint. Setting this to a
# non-empty string enables TLS for all migrations. An empty
# string means that QEMU will use plain text mode for migration,
-# rather than TLS (Since 2.9) Previously (since 2.7), this was
-# reported by omitting tls-creds instead.
+# rather than TLS. This is the default. (Since 2.7)
#
-# @tls-hostname: hostname of the target host for the migration. This
-# is required when using x509 based TLS credentials and the
-# migration URI does not already include a hostname. For example
-# if using fd: or exec: based migration, the hostname must be
-# provided so that the server's x509 certificate identity can be
-# validated. (Since 2.7) An empty string means that QEMU will use
-# the hostname associated with the migration URI, if any. (Since
-# 2.9) Previously (since 2.7), this was reported by omitting
-# tls-hostname instead.
+# @tls-hostname: migration target's hostname for validating the
+# server's x509 certificate identity. If empty, QEMU will use the
+# hostname from the migration URI, if any. A non-empty value is
+# required when using x509 based TLS credentials and the migration
+# URI does not include a hostname, such as fd: or exec: based
+# migration. (Since 2.7)
+#
+# Note: empty value works only since 2.9.
#
# @tls-authz: ID of the 'authz' object subclass that provides access
# control checking of the TLS x509 certificate distinguished name.
-# (Since 4.0)
+# This object is only resolved at time of use, so can be deleted
+# and recreated on the fly while the migration server is active.
+# If missing, it will default to denying access (Since 4.0)
#
-# @max-bandwidth: to set maximum speed for migration. maximum speed
-# in bytes per second. (Since 2.8)
+# @max-bandwidth: maximum speed for migration, in bytes per second.
+# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations when
-# making decisions to switchover. By default, this value is zero,
-# which means QEMU will estimate the bandwidth 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)
#
-# @x-checkpoint-delay: the delay time between two COLO checkpoints.
-# (Since 2.8)
+# @x-checkpoint-delay: The delay time (in ms) between two COLO
+# checkpoints in periodic mode. (Since 2.8)
#
# @block-incremental: Affects how much storage is migrated when the
# block migration capability is enabled. When false, the entire
@@ -1061,8 +1074,8 @@
# postcopy. Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
#
-# @max-cpu-throttle: maximum cpu throttle percentage. The default
-# value is 99. (Since 3.1)
+# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99.
+# (Since 3.1)
#
# @multifd-compression: Which compression method to use. Defaults to
# none. (Since 5.0)
@@ -1071,13 +1084,13 @@
# migration, the compression level is an integer between 0 and 9,
# where 0 means no compression, 1 means the best compression
# speed, and 9 means best compression ratio which will consume
-# more CPU. Defaults to 1. (Since 5.0)
+# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
# where 0 means no compression, 1 means the best compression
# speed, and 20 means best compression ratio which will consume
-# more CPU. Defaults to 1. (Since 5.0)
+# more CPU. Defaults to 1. (Since 5.0)
#
# @block-bitmap-mapping: Maps block nodes and bitmaps on them to
# aliases for the purpose of dirty bitmap migration. Such aliases
@@ -1096,14 +1109,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'.
@@ -1116,8 +1129,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
@@ -1211,7 +1224,7 @@
#
# @throttle-trigger-threshold: The ratio of bytes_dirty_period and
# bytes_xfer_period to trigger throttling. It is expressed as
-# percentage. The default value is 50. (Since 5.0)
+# percentage. The default value is 50. (Since 5.0)
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are
# throttled when migration auto-converge is activated. (Since
@@ -1240,34 +1253,33 @@
# must be for a 'client' endpoint, while for the incoming side the
# credentials must be for a 'server' endpoint. An empty string
# means that QEMU will use plain text mode for migration, rather
-# than TLS (Since 2.7) Note: 2.8 reports this by omitting
-# tls-creds instead.
+# than TLS. (Since 2.7)
#
-# @tls-hostname: hostname of the target host for the migration. This
-# is required when using x509 based TLS credentials and the
-# migration URI does not already include a hostname. For example
-# if using fd: or exec: based migration, the hostname must be
-# provided so that the server's x509 certificate identity can be
-# validated. (Since 2.7) An empty string means that QEMU will use
-# the hostname associated with the migration URI, if any. (Since
-# 2.9) Note: 2.8 reports this by omitting tls-hostname instead.
+# Note: 2.8 omits empty @tls-creds instead.
+#
+# @tls-hostname: migration target's hostname for validating the
+# server's x509 certificate identity. If empty, QEMU will use the
+# hostname from the migration URI, if any. (Since 2.7)
+#
+# Note: 2.8 omits empty @tls-hostname instead.
#
# @tls-authz: ID of the 'authz' object subclass that provides access
# control checking of the TLS x509 certificate distinguished name.
# (Since 4.0)
#
-# @max-bandwidth: to set maximum speed for migration. maximum speed
-# in bytes per second. (Since 2.8)
+# @max-bandwidth: maximum speed for migration, in bytes per second.
+# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations when
-# making decisions to switchover. By default, this value is zero,
-# which means QEMU will estimate the bandwidth 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)
@@ -1304,13 +1316,13 @@
# migration, the compression level is an integer between 0 and 9,
# where 0 means no compression, 1 means the best compression
# speed, and 9 means best compression ratio which will consume
-# more CPU. Defaults to 1. (Since 5.0)
+# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
# where 0 means no compression, 1 means the best compression
# speed, and 20 means best compression ratio which will consume
-# more CPU. Defaults to 1. (Since 5.0)
+# more CPU. Defaults to 1. (Since 5.0)
#
# @block-bitmap-mapping: Maps block nodes and bitmaps on them to
# aliases for the purpose of dirty bitmap migration. Such aliases
@@ -1329,14 +1341,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'.
@@ -1349,8 +1361,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
##
@@ -1737,7 +1749,7 @@
# @detach: this argument exists only for compatibility reasons and is
# ignored by QEMU
#
-# @resume: resume one paused migration, default "off". (since 3.0)
+# @resume: resume one paused migration, default "off". (since 3.0)
#
# Features:
#
@@ -1762,7 +1774,7 @@
# default network.
#
# 5. For now, number of migration streams is restricted to one,
-# i.e number of items in 'channels' list is just 1.
+# i.e. number of items in 'channels' list is just 1.
#
# 6. The 'uri' and 'channels' arguments are mutually exclusive;
# exactly one of the two should be present.
@@ -1839,7 +1851,7 @@
# 3. The uri format is the same as for -incoming
#
# 4. For now, number of migration streams is restricted to one,
-# i.e number of items in 'channels' list is just 1.
+# i.e. number of items in 'channels' list is just 1.
#
# 5. The 'uri' and 'channels' arguments are mutually exclusive;
# exactly one of the two should be present.
@@ -1949,8 +1961,8 @@
#
# @primary: true for primary or false for secondary.
#
-# @failover: true to do failover, false to stop. but cannot be
-# specified if 'enable' is true. default value is false.
+# @failover: true to do failover, false to stop. Cannot be specified
+# if 'enable' is true. Default value is false.
#
# Example:
#
@@ -2163,7 +2175,6 @@
# @millisecond: value is in milliseconds
#
# Since: 8.2
-#
##
{ 'enum': 'TimeUnit',
'data': ['second', 'millisecond'] }
@@ -2245,7 +2256,7 @@
# will not increase dirty page rate anymore.
#
# @calc-time-unit: time unit in which @calc-time is specified.
-# By default it is seconds. (Since 8.2)
+# By default it is seconds. (Since 8.2)
#
# @sample-pages: number of sampled pages per each GiB of guest memory.
# Default value is 512. For 4KiB guest pages this corresponds to
@@ -2282,7 +2293,7 @@
# Query results of the most recent invocation of @calc-dirty-rate.
#
# @calc-time-unit: time unit in which to report calculation time.
-# By default it is reported in seconds. (Since 8.2)
+# By default it is reported in seconds. (Since 8.2)
#
# Since: 5.2
#
@@ -2408,9 +2419,7 @@
#
# Returns information of migration threads
#
-# data: migration thread name
-#
-# Returns: information about migration threads
+# Returns: @MigrationThreadInfo
#
# Since: 7.2
##
diff --git a/qapi/misc.json b/qapi/misc.json
index 1b0c5da..ec30e5c 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -32,9 +32,9 @@
#
# Example:
#
-# -> { "execute": "add_client", "arguments": { "protocol": "vnc",
-# "fdname": "myclient" } }
-# <- { "return": {} }
+# -> { "execute": "add_client", "arguments": { "protocol": "vnc",
+# "fdname": "myclient" } }
+# <- { "return": {} }
##
{ 'command': 'add_client',
'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
@@ -142,7 +142,7 @@
# option was passed on the command line.
#
# In the "suspended" state, it will completely stop the VM and
-# cause a transition to the "paused" state. (Since 9.0)
+# cause a transition to the "paused" state. (Since 9.0)
#
# Example:
#
diff --git a/qapi/net.json b/qapi/net.json
index 417b61a..0f5a259 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -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
##
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 6929ab7..59fbe74 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -57,13 +57,10 @@
'DummyForceArrays',
'DummyVirtioForceArrays',
'GrabToggleKeys',
- 'GuestPanicInformationHyperV',
'HotKeyMod',
'ImageInfoSpecificKind',
'InputAxis',
'InputButton',
- 'InputMultiTouchEvent',
- 'InputMultiTouchType',
'IscsiHeaderDigest',
'IscsiTransport',
'JSONType',
@@ -75,11 +72,8 @@
'QCryptoAkCipherKeyType',
'QCryptodevBackendServiceType',
'QKeyCode',
- 'Qcow2OverlapCheckFlags',
'RbdAuthMode',
'RbdImageEncryptionFormat',
- 'StatsFilter',
- 'StatsValue',
'String',
'StringWrapper',
'SysEmuTarget',
@@ -90,13 +84,8 @@
'XDbgBlockGraph',
'YankInstanceType',
'blockdev-reopen',
- 'query-cpu-model-baseline',
- 'query-cpu-model-comparison',
- 'query-cpu-model-expansion',
'query-rocker',
- 'query-rocker-ports',
- 'query-stats-schemas',
- 'watchdog-set-action' ],
+ 'query-rocker-ports' ],
# Externally visible types whose member names may use uppercase
'member-name-exceptions': [ # visible in:
'ACPISlotType', # query-acpi-ospm-status
diff --git a/qapi/qom.json b/qapi/qom.json
index baae3a1..8d4ca8e 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -649,14 +649,14 @@
#
# @offset: the offset into the target file that the region starts at.
# You can use this option to back multiple regions with a single
-# file. Must be a multiple of the page size.
+# file. Must be a multiple of the page size.
# (default: 0) (since 8.1)
#
# @discard-data: if true, the file contents can be destroyed when QEMU
# exits, to avoid unnecessarily flushing data to the backing file.
# Note that @discard-data is only an optimization, and QEMU might
# not discard file contents if it aborts unexpectedly or is
-# terminated using SIGKILL. (default: false)
+# terminated using SIGKILL. (default: false)
#
# @mem-path: the path to either a shared memory or huge page
# filesystem mount
@@ -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
##
diff --git a/qapi/replay.json b/qapi/replay.json
index 8626fb5..d3559f9 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -105,8 +105,8 @@
# replaying the execution. The command automatically loads nearest
# snapshot and replays the execution to find the desired instruction.
# When there is no preceding snapshot or the execution is not
-# replayed, then the command fails. icount for the reference may be
-# obtained with @query-replay command.
+# replayed, then the command fails. Instruction count can be obtained
+# with the @query-replay command.
#
# @icount: target instruction count
#
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 789fc34..f8773f2 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -91,7 +91,7 @@
#
# @snapshot-load: A snapshot is being loaded by the record & replay
# subsystem. This value is used only within QEMU. It doesn't
-# occur in QMP. (since 7.2)
+# occur in QMP. (since 7.2)
##
{ 'enum': 'ShutdownCause',
# Beware, shutdown_caused_by_guest() depends on enumeration order
@@ -109,7 +109,6 @@
# @status: the virtual machine @RunState
#
# Since: 0.14
-#
##
{ 'struct': 'StatusInfo',
'data': {'running': 'bool',
@@ -142,10 +141,10 @@
# @guest: If true, the shutdown was triggered by a guest request (such
# as a guest-initiated ACPI shutdown request or other
# hardware-specific action) rather than a host request (such as
-# sending qemu a SIGINT). (since 2.10)
+# sending qemu a SIGINT). (since 2.10)
#
-# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since
-# 4.0)
+# @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
@@ -184,9 +183,9 @@
# @guest: If true, the reset was triggered by a guest request (such as
# a guest-initiated ACPI reboot request or other hardware-specific
# action) rather than a host request (such as the QMP command
-# system_reset). (since 2.10)
+# system_reset). (since 2.10)
#
-# @reason: The @ShutdownCause of the RESET. (since 4.0)
+# @reason: The @ShutdownCause of the RESET. (since 4.0)
#
# Since: 0.12
#
@@ -377,9 +376,17 @@
##
# @watchdog-set-action:
#
-# Set watchdog action
+# Set watchdog action.
+#
+# @action: @WatchdogAction action taken when watchdog timer expires.
#
# Since: 2.11
+#
+# Example:
+#
+# -> { "execute": "watchdog-set-action",
+# "arguments": { "action": "inject-nmi" } }
+# <- { "return": {} }
##
{ 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }
@@ -505,6 +512,22 @@
#
# Hyper-V specific guest panic information (HV crash MSRs)
#
+# @arg1: for Windows, STOP code for the guest crash. For Linux,
+# an error code.
+#
+# @arg2: for Windows, first argument of the STOP. For Linux, the
+# guest OS ID, which has the kernel version in bits 16-47
+# and 0x8100 in bits 48-63.
+#
+# @arg3: for Windows, second argument of the STOP. For Linux, the
+# program counter of the guest.
+#
+# @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.
+#
# Since: 2.9
##
{'struct': 'GuestPanicInformationHyperV',
@@ -568,11 +591,9 @@
#
# @recipient: recipient is defined as @MemoryFailureRecipient.
#
-# @action: action that has been taken. action is defined as
-# @MemoryFailureAction.
+# @action: action that has been taken.
#
-# @flags: flags for MemoryFailureAction. action is defined as
-# @MemoryFailureFlags.
+# @flags: flags for MemoryFailureAction.
#
# Since: 5.2
#
diff --git a/qapi/sockets.json b/qapi/sockets.json
index ef77792..aa97c89 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -58,7 +58,7 @@
# @keep-alive: enable keep-alive when connecting to this socket. Not
# supported for passive sockets. (Since 4.2)
#
-# @mptcp: enable multi-path TCP. (Since 6.1)
+# @mptcp: enable multi-path TCP. (Since 6.1)
#
# Since: 1.3
##
@@ -125,7 +125,6 @@
# Decimal file descriptors are permitted at startup or other
# contexts where no monitor context is active.
#
-#
# Since: 1.2
##
{ 'struct': 'FdSocketAddress',
diff --git a/qapi/stats.json b/qapi/stats.json
index ce9d816..578b52c 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -114,13 +114,13 @@
#
# The arguments to the query-stats command; specifies a target for
# which to request statistics and optionally the required subset of
-# information for that target:
+# information for that target.
#
-# - which vCPUs to request statistics for
-# - which providers to request statistics from
-# - which named values to return within each provider
+# @target: the kind of objects to query. Note that each possible
+# target may enable additional filtering options
#
-# @target: the kind of objects to query
+# @providers: which providers to request statistics from, and optionally
+# which named values to return within each provider
#
# Since: 7.1
##
@@ -136,6 +136,8 @@
#
# @scalar: single unsigned 64-bit integers.
#
+# @boolean: single boolean value.
+#
# @list: list of unsigned 64-bit integers (used for histograms).
#
# Since: 7.1
@@ -254,6 +256,8 @@
#
# Return the schema for all available runtime-collected statistics.
#
+# @provider: a provider to restrict the query to.
+#
# Note: runtime-collected statistics and their names fall outside
# QEMU's usual deprecation policies. QEMU will try to keep the
# set of available data stable, together with their names, but
diff --git a/qapi/ui.json b/qapi/ui.json
index 5744c24..f610bce 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -181,7 +181,7 @@
# @head: head to use in case the device supports multiple heads. If
# this parameter is missing, head #0 will be used. Also note that
# the head can only be specified in conjunction with the device
-# ID. (Since 2.12)
+# ID. (Since 2.12)
#
# @format: image format for screendump. (default: ppm) (Since 7.1)
#
@@ -290,7 +290,7 @@
# @enabled: true if the SPICE server is enabled, false otherwise
#
# @migrated: true if the last guest migration completed and spice
-# migration had completed as well. false otherwise. (since 1.4)
+# migration had completed as well, false otherwise (since 1.4)
#
# @host: The hostname the SPICE server is bound to. This depends on
# the name resolution on the host and may be an IP address.
@@ -303,7 +303,7 @@
#
# @auth: the current authentication type used by the server
#
-# - 'none' if no authentication is being used
+# - 'none' if no authentication is being used
# - 'spice' uses SASL or direct TLS authentication, depending on
# command line options
#
@@ -1080,6 +1080,16 @@
#
# Type of a multi-touch event.
#
+# @begin: A new touch event sequence has just started.
+#
+# @update: A touch event sequence has been updated.
+#
+# @end: A touch event sequence has finished.
+#
+# @cancel: A touch event sequence has been canceled.
+#
+# @data: Absolute position data.
+#
# Since: 8.1
##
{ 'enum' : 'InputMultiTouchType',
@@ -1137,6 +1147,8 @@
#
# MultiTouch input event.
#
+# @type: The type of multi-touch event.
+#
# @slot: Which slot has generated the event.
#
# @tracking-id: ID to correlate this event with previously generated
@@ -1314,7 +1326,7 @@
# display device can notify the guest on window resizes
# (virtio-gpu) this will default to "on", assuming the guest will
# resize the display to match the window size then. Otherwise it
-# defaults to "off". (Since 3.1)
+# defaults to "off". (Since 3.1)
#
# @show-tabs: Display the tab bar for switching between the various
# graphical interfaces (e.g. VGA and virtual console character
@@ -1417,12 +1429,12 @@
# codes match their position on non-Mac keyboards and you can use
# Meta/Super and Alt where you expect them. (default: off)
#
-# @zoom-to-fit: Zoom guest display to fit into the host window. When
-# turned off the host window will be resized instead. Defaults to
-# "off". (Since 8.2)
+# @zoom-to-fit: Zoom guest display to fit into the host window. When
+# turned off the host window will be resized instead. Defaults to
+# "off". (Since 8.2)
#
# @zoom-interpolation: Apply interpolation to smooth output when
-# zoom-to-fit is enabled. Defaults to "off". (Since 9.0)
+# zoom-to-fit is enabled. Defaults to "off". (Since 9.0)
#
# Since: 7.0
##
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 95745fd..74fc27c 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -642,15 +642,17 @@
#
# @num: vhost_virtqueue num
#
-# @desc-phys: vhost_virtqueue desc_phys (descriptor area phys. addr.)
+# @desc-phys: vhost_virtqueue desc_phys (descriptor area physical
+# address)
#
# @desc-size: vhost_virtqueue desc_size
#
-# @avail-phys: vhost_virtqueue avail_phys (driver area phys. addr.)
+# @avail-phys: vhost_virtqueue avail_phys (driver area physical
+# address)
#
# @avail-size: vhost_virtqueue avail_size
#
-# @used-phys: vhost_virtqueue used_phys (device area phys. addr.)
+# @used-phys: vhost_virtqueue used_phys (device area physical address)
#
# @used-size: vhost_virtqueue used_size
#
@@ -936,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
##
@@ -950,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
##
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 9554b56..d5af155 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -1220,13 +1220,13 @@
# @signal: signal number (linux) or unhandled exception code (windows)
# if the process was abnormally terminated.
#
-# @out-data: base64-encoded stdout of the process. This field will only
-# be populated after the process exits.
+# @out-data: base64-encoded stdout of the process. This field will
+# only be populated after the process exits.
#
-# @err-data: base64-encoded stderr of the process. Note: @out-data and
-# @err-data are present only if 'capture-output' was specified for
-# 'guest-exec'. This field will only be populated after the process
-# exits.
+# @err-data: base64-encoded stderr of the process. Note: @out-data
+# and @err-data are present only if 'capture-output' was specified
+# for 'guest-exec'. This field will only be populated after the
+# process exits.
#
# @out-truncated: true if stdout was not fully captured due to size
# limitation.
@@ -1273,12 +1273,16 @@
# An enumeration of guest-exec capture modes.
#
# @none: do not capture any output
+#
# @stdout: only capture stdout
+#
# @stderr: only capture stderr
+#
# @separated: capture both stdout and stderr, but separated into
-# GuestExecStatus out-data and err-data, respectively
-# @merged: capture both stdout and stderr, but merge together
-# into out-data. not effective on windows guests.
+# GuestExecStatus out-data and err-data, respectively
+#
+# @merged: capture both stdout and stderr, but merge together into
+# out-data. Not effective on windows guests.
#
# Since: 8.0
##
@@ -1291,8 +1295,9 @@
#
# Controls what guest-exec output gets captures.
#
-# @flag: captures both stdout and stderr if true. Equivalent
-# to GuestExecCaptureOutputMode::all. (since 2.5)
+# @flag: captures both stdout and stderr if true. Equivalent to
+# GuestExecCaptureOutputMode::all. (since 2.5)
+#
# @mode: capture mode; preferred interface
#
# Since: 8.0
@@ -1315,7 +1320,7 @@
# @input-data: data to be passed to process stdin (base64 encoded)
#
# @capture-output: bool flag to enable capture of stdout/stderr of
-# running process. defaults to false.
+# running process. Defaults to false.
#
# Returns: PID
#
