diff --git a/qapi/block-core.json b/qapi/block-core.json index 1874f880a8..746d1694c2 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 65d9804bdf..5de99fe09d 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 f404daef60..6bdbf077c2 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 931c88e688..e102be337b 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 8cc4c72fa9..4281726dec 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 4c021dd53c..2fa9504d86 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 f413d00154..e500b5a744 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 519adf3220..29e695aa06 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 0840c91e70..e8b60641f2 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 aa1b39bce1..8c65b90328 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 1b0c5dad88..ec30e5c570 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 417b61a321..0f5a259475 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 6929ab776e..59fbe74b8c 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 baae3a183f..8d4ca8ed92 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 8626fb58f4..d3559f9c8f 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 789fc34559..f8773f23b2 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 ef777928e7..aa97c89768 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 ce9d8161ec..578b52c7ef 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 5744c24e3c..f610bce118 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 95745fdfd7..74fc27c702 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 9554b566a7..d5af155007 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 #