From e8c5503a5c8b0479f1fde1b2abb7b488dee70996 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 14:51:15 +0100 Subject: [PATCH 01/20] qapi: Improve migration TLS documentation MigrateSetParameters is about setting parameters, and MigrationParameters is about querying them. Their documentation of @tls-creds and @tls-hostname has residual damage from a failed attempt at de-duplicating them (see commit de63ab61241 "migrate: Share common MigrationParameters struct" and commit 1bda8b3c695 "migration: Unshare MigrationParameters struct for now"). MigrateSetParameters documentation issues: * It claims plain text mode "was reported by omitting tls-creds" before 2.9. MigrateSetParameters is not used for reporting, so this is misleading. Delete. * It similarly claims hostname defaulting to migration URI "was reported by omitting tls-hostname" before 2.9. Delete as well. Rephrase the remaining @tls-hostname contents for clarity. Enum MigrationParameter mirrors the members of struct MigrateSetParameters. Differences to MigrateSetParameters's member documentation are pointless. Copy the new text to MigrationParameter. MigrationParameters documentation issues: * @tls-creds runs the two last sentences together without punctuation. Fix that. * Much of the contents on @tls-hostname only applies to setting parameters, resulting in confusion. Replace by a suitable abridged version of the new MigrateSetParameters text, and a note on @tls-hostname omission in 2.8. Additional damage is due to flawed doc fix commit 66fcb9d651d (qapi/migration: Add missing tls-authz documentation): since it copied the missing MigrateSetParameters text from MigrationParameters instead of MigrationParameter, the part on recreating @tls-authz on the fly is missing. Copy that, too. Signed-off-by: Markus Armbruster Message-ID: <20240322135117.195489-2-armbru@redhat.com> Reviewed-by: Peter Xu [Some typos corrected] --- qapi/migration.json | 63 +++++++++++++++++++++++---------------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index aa1b39bce1..bebe9f71ba 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -809,16 +809,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. @@ -1006,22 +1009,22 @@ # 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) @@ -1240,17 +1243,15 @@ # 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. From 8eb0a257c55d1b27dc8c40ce3c275307b898f575 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 14:51:16 +0100 Subject: [PATCH 02/20] qapi: Resync MigrationParameter and MigrateSetParameters Enum MigrationParameter mirrors the members of struct MigrateSetParameters. Differences to MigrateSetParameters's member documentation are pointless. Clean them up: * @compress-level, @compress-threads, @decompress-threads, and x-checkpoint-delay are more thoroughly documented for MigrationParameter, so use that version for both. * @max-cpu-throttle is almost the same. Use MigrationParameter's version for both. Signed-off-by: Markus Armbruster Message-ID: <20240322135117.195489-3-armbru@redhat.com> Reviewed-by: Fabiano Rosas Reviewed-by: Peter Xu --- qapi/migration.json | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index bebe9f71ba..744d05f364 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -966,16 +966,26 @@ # @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 @@ -1042,8 +1052,8 @@ # @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 @@ -1064,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) From e6c60bf02d1c32b5e3e7dc761d1737aa8886ab79 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 14:51:17 +0100 Subject: [PATCH 03/20] qapi: Fix bogus documentation of query-migrationthreads The doc comment documents an argument that doesn't exist. Would fail compilation if it was marked up correctly. Delete. The Returns: section fails to refer to the data type, leaving the user to guess. Fix that. The command name violates QAPI naming rules: it should be query-migration-threads. Too late to fix. Reported-by: John Snow Fixes: 671326201dac (migration: Introduce interface query-migrationthreads) Signed-off-by: Markus Armbruster Message-ID: <20240322135117.195489-4-armbru@redhat.com> Reviewed-by: Fabiano Rosas Reviewed-by: Peter Xu Reviewed-by: John Snow --- qapi/migration.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 744d05f364..c865ab00c8 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -2419,9 +2419,7 @@ # # Returns information of migration threads # -# data: migration thread name -# -# Returns: information about migration threads +# Returns: @MigrationThreadInfo # # Since: 7.2 ## From c15fbc66e2189723155165af28ba2238bb2064b6 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:08:59 +0100 Subject: [PATCH 04/20] qapi: Drop stray Arguments: line from qmp_capabilities docs Reported-by: John Snow Fixes: 119ebac1feb2 (qapi-schema: use generated marshaller for 'qmp_capabilities') Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-2-armbru@redhat.com> Reviewed-by: John Snow --- qapi/control.json | 2 -- 1 file changed, 2 deletions(-) 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 From f972ed5925cda823a99f89d6250cdae655140884 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:00 +0100 Subject: [PATCH 05/20] qapi: Expand a few awkward abbreviations in documentation Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-3-armbru@redhat.com> --- qapi/replay.json | 4 ++-- qapi/virtio.json | 8 +++++--- 2 files changed, 7 insertions(+), 5 deletions(-) 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/virtio.json b/qapi/virtio.json index 95745fdfd7..b0cd41be72 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 # From b5e29402f1feb96bce4733a7b6346a5b441f99ae Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:01 +0100 Subject: [PATCH 06/20] qapi: Tidy up block-latency-histogram-set documentation some more Commit a937b6aa739 (qapi: Reformat doc comments to conform to current conventions) reflowed some text that should have been left alone. Revert that. Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-4-armbru@redhat.com> --- qapi/block.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/qapi/block.json b/qapi/block.json index 65d9804bdf..2410145cd3 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", @@ -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", From 7d50757c65f7609a24151fc2b5939cb78c2dc81c Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:02 +0100 Subject: [PATCH 07/20] qapi: Tidy up indentation of add_client's example Commit d23055b8db8 (qapi: Require descriptions and tagged sections to be indented) indented add_client's example too much. Revert that. Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-5-armbru@redhat.com> [Move a stray hunk to the later patch it belongs to] --- qapi/misc.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/misc.json b/qapi/misc.json index 1b0c5dad88..83def5edc4 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', From aa03e163839fb13eafcf9c514bd832ea134cdccf Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:03 +0100 Subject: [PATCH 08/20] qapi: Fix argument markup in drive-mirror documentation Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-6-armbru@redhat.com> --- qapi/block-core.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 1874f880a8..64668b080d 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -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. # From 8698e1447fa48d7dcdeeeca4434afa86b97e3665 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:04 +0100 Subject: [PATCH 09/20] qapi: Fix typo in request-ebpf documentation Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-7-armbru@redhat.com> --- qapi/ebpf.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/ebpf.json b/qapi/ebpf.json index f413d00154..61359e1c0f 100644 --- a/qapi/ebpf.json +++ b/qapi/ebpf.json @@ -51,7 +51,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. From 7d08424cf79c72d560f8d730963d2101a7393757 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:05 +0100 Subject: [PATCH 10/20] qapi: Fix abbreviation punctuation in doc comments Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-8-armbru@redhat.com> --- qapi/migration.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index c865ab00c8..a4319f87bf 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1773,7 +1773,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. @@ -1850,7 +1850,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. From 73c67f385118b5488edecda9b64a125e060242eb Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:06 +0100 Subject: [PATCH 11/20] qapi: Start sentences with a capital letter, end them with a period Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-9-armbru@redhat.com> --- qapi/migration.json | 16 ++++++++-------- qapi/ui.json | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index a4319f87bf..8fa1b7f8ed 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -829,8 +829,8 @@ # 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 @@ -1036,8 +1036,8 @@ # 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 @@ -1267,8 +1267,8 @@ # 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 @@ -1960,8 +1960,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: # diff --git a/qapi/ui.json b/qapi/ui.json index 5744c24e3c..e71cd2f50b 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -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. From 1e6b0505c4e6830182b0c21fedec46b4f6d8f22a Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:07 +0100 Subject: [PATCH 12/20] qapi: Don't repeat member type in its documentation text Documentation generated for the arguments of MEMORY_FAILURE looks like "recipient": "MemoryFailureRecipient" recipient is defined as "MemoryFailureRecipient". "action": "MemoryFailureAction" action that has been taken. action is defined as "MemoryFailureAction". "flags": "MemoryFailureFlags" flags for MemoryFailureAction. action is defined as "MemoryFailureFlags". The "action is defined as ..." are redundant. Drop. Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-10-armbru@redhat.com> --- qapi/run-state.json | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/qapi/run-state.json b/qapi/run-state.json index 789fc34559..ae084e13a0 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -568,11 +568,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 # From 209e64d9edff332da607bbf98430456a20025432 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:08 +0100 Subject: [PATCH 13/20] qapi: Refill doc comments to conform to current conventions For legibility, wrap text paragraphs so every line is at most 70 characters long. To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the refilled paragraphs are visible there. Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-11-armbru@redhat.com> --- qapi/block-core.json | 24 ++++----- qapi/block.json | 4 +- qapi/cxl.json | 4 +- qapi/dump.json | 16 +++--- qapi/ebpf.json | 12 ++--- qapi/machine-target.json | 22 +++++---- qapi/machine.json | 15 +++--- qapi/migration.json | 104 ++++++++++++++++++++------------------- qapi/net.json | 27 +++++----- qapi/qom.json | 34 ++++++------- qapi/run-state.json | 4 +- qapi/virtio.json | 12 +++-- 12 files changed, 142 insertions(+), 136 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 64668b080d..e6b392ffe7 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 # @@ -2825,10 +2825,10 @@ # Care should be taken when specifying the string, to specify a # valid filename or protocol. (Since 2.1) # -# @backing-mask-protocol: If true, replace any protocol mentioned in the -# 'backing file format' with 'raw', rather than storing the protocol -# name as the backing format. Can be used even when no image header -# will be updated (default false; since 9.0). +# @backing-mask-protocol: If true, replace any protocol mentioned in +# the 'backing file format' with 'raw', rather than storing the +# protocol name as the backing format. Can be used even when no +# image header will be updated (default false; since 9.0). # # @speed: the maximum speed, in bytes per second # @@ -3547,10 +3547,10 @@ # re-allocating them later. Besides potential performance # degradation, such fragmentation can lead to increased allocation # of clusters past the end of the image file, resulting in image -# files whose file length can grow much larger than their guest disk -# size would suggest. If image file length is of concern (e.g. when -# storing qcow2 images directly on block devices), you should -# consider enabling this option. (since 8.1) +# files whose file length can grow much larger than their guest +# disk size would suggest. If image file length is of concern +# (e.g. when storing qcow2 images directly on block devices), you +# should consider enabling this option. (since 8.1) # # @overlap-check: which overlap checks to perform for writes to the # image, defaults to 'cached' (since 2.2) diff --git a/qapi/block.json b/qapi/block.json index 2410145cd3..5de99fe09d 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -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", 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..ef1f3b62fc 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) diff --git a/qapi/ebpf.json b/qapi/ebpf.json index 61359e1c0f..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). -# ## ## diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 519adf3220..03d7a185b9 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -394,9 +394,9 @@ ## # @set-cpu-topology: # -# Modify the topology by moving the CPU inside the topology tree, -# or by changing a modifier attribute of a CPU. -# Absent values will not be modified. +# Modify the topology by moving the CPU inside the topology tree, or +# by changing a modifier attribute of a CPU. Absent values will not +# be modified. # # @core-id: the vCPU ID to be moved # @@ -408,7 +408,8 @@ # # @entitlement: entitlement to set # -# @dedicated: whether the provisioning of real to virtual CPU is dedicated +# @dedicated: whether the provisioning of real to virtual CPU is +# dedicated # # Features: # @@ -435,14 +436,15 @@ # Emitted when the guest asks to change the polarization. # # The guest can tell the host (via the PTF instruction) whether the -# CPUs should be provisioned using horizontal or vertical polarization. +# CPUs should be provisioned using horizontal or vertical +# polarization. # -# On horizontal polarization the host is expected to provision all vCPUs -# equally. +# On horizontal polarization the host is expected to provision all +# vCPUs equally. # -# On vertical polarization the host can provision each vCPU differently. -# The guest will get information on the details of the provisioning -# the next time it uses the STSI(15) instruction. +# On vertical polarization the host can provision each vCPU +# differently. The guest will get information on the details of the +# provisioning the next time it uses the STSI(15) instruction. # # @polarization: polarization specified by the guest # diff --git a/qapi/machine.json b/qapi/machine.json index 0840c91e70..01be411fa7 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -925,8 +925,7 @@ # @cluster-id: cluster number within the parent container the CPU # belongs to (since 7.1) # -# @core-id: core number within the parent container the CPU -# belongs to +# @core-id: core number within the parent container the CPU belongs to # # @thread-id: thread number within the core the CPU belongs to # @@ -982,8 +981,8 @@ # # Examples: # -# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu -# POWER8: +# For pseries machine type started with -smp 2,cores=2,maxcpus=4 +# -cpu POWER8: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1008,8 +1007,8 @@ # } # ]} # -# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu -# qemu (Since: 2.11): +# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 +# -cpu qemu (Since: 2.11): # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1152,8 +1151,8 @@ ## # @query-hv-balloon-status-report: # -# Returns the hv-balloon driver data contained in the last received "STATUS" -# message from the guest. +# Returns the hv-balloon driver data contained in the last received +# "STATUS" message from the guest. # # Returns: # @HvBalloonInfo diff --git a/qapi/migration.json b/qapi/migration.json index 8fa1b7f8ed..8845f8bb72 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) # @@ -501,8 +501,8 @@ # # @background-snapshot: If enabled, the migration stream will be a # snapshot of the VM exactly at the point when the migration -# procedure starts. The VM RAM is saved with running VM. (since -# 6.0) +# procedure starts. The VM RAM is saved with running VM. +# (since 6.0) # # @zero-copy-send: Controls behavior on sending memory pages on # migration. When true, enables a zero-copy mechanism for sending @@ -640,9 +640,9 @@ # # @normal: the original form of migration. (since 8.2) # -# @cpr-reboot: The migrate command stops the VM and saves state to -# the URI. After quitting QEMU, the user resumes by running -# QEMU -incoming. +# @cpr-reboot: The migrate command stops the VM and saves state to the +# URI. After quitting QEMU, the user resumes by running QEMU +# -incoming. # # This mode allows the user to quit QEMU, optionally update and # reboot the OS, and restart QEMU. If the user reboots, the URI @@ -652,8 +652,8 @@ # does not block the migration, but the user must not modify the # contents of guest block devices between the quit and restart. # -# This mode supports VFIO devices provided the user first puts -# the guest in the suspended runstate, such as by issuing +# This mode supports VFIO devices provided the user first puts the +# guest in the suspended runstate, such as by issuing # guest-suspend-ram to the QEMU guest agent. # # Best performance is achieved when the memory backend is shared @@ -678,11 +678,10 @@ # @legacy: Perform zero page checking in main migration thread. # # @multifd: Perform zero page checking in multifd sender thread if -# multifd migration is enabled, else in the main migration -# thread as for @legacy. +# multifd migration is enabled, else in the main migration thread +# as for @legacy. # # Since: 9.0 -# ## { 'enum': 'ZeroPageDetection', 'data': [ 'none', 'legacy', 'multifd' ] } @@ -834,13 +833,14 @@ # # @avail-switchover-bandwidth: to set the available bandwidth that # migration can use during switchover phase. NOTE! This does not -# limit the bandwidth during switchover, but only for calculations when -# making decisions to switchover. By default, this value is zero, -# which means QEMU will estimate the bandwidth automatically. This can -# be set when the estimated value is not accurate, while the user is -# able to guarantee such bandwidth is available when switching over. -# When specified correctly, this can make the switchover decision much -# more accurate. (Since 8.2) +# limit the bandwidth during switchover, but only for calculations +# when making decisions to switchover. By default, this value is +# zero, which means QEMU will estimate the bandwidth +# automatically. This can be set when the estimated value is not +# accurate, while the user is able to guarantee such bandwidth is +# available when switching over. When specified correctly, this +# can make the switchover decision much more accurate. +# (Since 8.2) # # @downtime-limit: set maximum tolerated downtime for migration. # maximum downtime in milliseconds (Since 2.8) @@ -902,14 +902,14 @@ # to their node name otherwise. (Since 5.2) # # @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty -# limit during live migration. Should be in the range 1 to 1000ms. -# Defaults to 1000ms. (Since 8.1) +# limit during live migration. Should be in the range 1 to +# 1000ms. Defaults to 1000ms. (Since 8.1) # # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is 'normal'. -# (Since 8.2) +# @mode: Migration mode. See description in @MigMode. Default is +# 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. # See description in @ZeroPageDetection. Default is 'multifd'. @@ -922,8 +922,8 @@ # @compress-threads, @decompress-threads and @compress-wait-thread # are deprecated because @compression is deprecated. # -# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period -# are experimental. +# @unstable: Members @x-checkpoint-delay and +# @x-vcpu-dirty-limit-period are experimental. # # Since: 2.4 ## @@ -1041,13 +1041,14 @@ # # @avail-switchover-bandwidth: to set the available bandwidth that # migration can use during switchover phase. NOTE! This does not -# limit the bandwidth during switchover, but only for calculations when -# making decisions to switchover. By default, this value is zero, -# which means QEMU will estimate the bandwidth automatically. This can -# be set when the estimated value is not accurate, while the user is -# able to guarantee such bandwidth is available when switching over. -# When specified correctly, this can make the switchover decision much -# more accurate. (Since 8.2) +# limit the bandwidth during switchover, but only for calculations +# when making decisions to switchover. By default, this value is +# zero, which means QEMU will estimate the bandwidth +# automatically. This can be set when the estimated value is not +# accurate, while the user is able to guarantee such bandwidth is +# available when switching over. When specified correctly, this +# can make the switchover decision much more accurate. +# (Since 8.2) # # @downtime-limit: set maximum tolerated downtime for migration. # maximum downtime in milliseconds (Since 2.8) @@ -1109,14 +1110,14 @@ # to their node name otherwise. (Since 5.2) # # @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty -# limit during live migration. Should be in the range 1 to 1000ms. -# Defaults to 1000ms. (Since 8.1) +# limit during live migration. Should be in the range 1 to +# 1000ms. Defaults to 1000ms. (Since 8.1) # # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is 'normal'. -# (Since 8.2) +# @mode: Migration mode. See description in @MigMode. Default is +# 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. # See description in @ZeroPageDetection. Default is 'multifd'. @@ -1129,8 +1130,8 @@ # @compress-threads, @decompress-threads and @compress-wait-thread # are deprecated because @compression is deprecated. # -# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period -# are experimental. +# @unstable: Members @x-checkpoint-delay and +# @x-vcpu-dirty-limit-period are experimental. # # TODO: either fuse back into MigrationParameters, or make # MigrationParameters members mandatory @@ -1272,13 +1273,14 @@ # # @avail-switchover-bandwidth: to set the available bandwidth that # migration can use during switchover phase. NOTE! This does not -# limit the bandwidth during switchover, but only for calculations when -# making decisions to switchover. By default, this value is zero, -# which means QEMU will estimate the bandwidth automatically. This can -# be set when the estimated value is not accurate, while the user is -# able to guarantee such bandwidth is available when switching over. -# When specified correctly, this can make the switchover decision much -# more accurate. (Since 8.2) +# limit the bandwidth during switchover, but only for calculations +# when making decisions to switchover. By default, this value is +# zero, which means QEMU will estimate the bandwidth +# automatically. This can be set when the estimated value is not +# accurate, while the user is able to guarantee such bandwidth is +# available when switching over. When specified correctly, this +# can make the switchover decision much more accurate. +# (Since 8.2) # # @downtime-limit: set maximum tolerated downtime for migration. # maximum downtime in milliseconds (Since 2.8) @@ -1340,14 +1342,14 @@ # to their node name otherwise. (Since 5.2) # # @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty -# limit during live migration. Should be in the range 1 to 1000ms. -# Defaults to 1000ms. (Since 8.1) +# limit during live migration. Should be in the range 1 to +# 1000ms. Defaults to 1000ms. (Since 8.1) # # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is 'normal'. -# (Since 8.2) +# @mode: Migration mode. See description in @MigMode. Default is +# 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. # See description in @ZeroPageDetection. Default is 'multifd'. @@ -1360,8 +1362,8 @@ # @compress-threads, @decompress-threads and @compress-wait-thread # are deprecated because @compression is deprecated. # -# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period -# are experimental. +# @unstable: Members @x-checkpoint-delay and +# @x-vcpu-dirty-limit-period are experimental. # # Since: 2.4 ## 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/qom.json b/qapi/qom.json index baae3a183f..e263e29a26 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -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/run-state.json b/qapi/run-state.json index ae084e13a0..bc1c3a9217 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -144,8 +144,8 @@ # hardware-specific action) rather than a host request (such as # sending qemu a SIGINT). (since 2.10) # -# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since -# 4.0) +# @reason: The @ShutdownCause which resulted in the SHUTDOWN. +# (since 4.0) # # Note: If the command-line option "-no-shutdown" has been specified, # qemu will not exit, and a STOP event will eventually follow the diff --git a/qapi/virtio.json b/qapi/virtio.json index b0cd41be72..74fc27c702 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -938,10 +938,11 @@ # # @iothread: the id of IOThread object # -# @vqs: an optional array of virtqueue indices that will be handled by this -# IOThread. When absent, virtqueues are assigned round-robin across all -# IOThreadVirtQueueMappings provided. Either all IOThreadVirtQueueMappings -# must have @vqs or none of them must have it. +# @vqs: an optional array of virtqueue indices that will be handled by +# this IOThread. When absent, virtqueues are assigned round-robin +# across all IOThreadVirtQueueMappings provided. Either all +# IOThreadVirtQueueMappings must have @vqs or none of them must +# have it. # # Since: 9.0 ## @@ -952,7 +953,8 @@ ## # @DummyVirtioForceArrays: # -# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList internally +# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList +# internally # # Since: 9.0 ## From 5305a4eeb80b9b69ae2c1a1440bd3ece0a8b35a2 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:09 +0100 Subject: [PATCH 14/20] qapi: Correct documentation indentation and whitespace Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-12-armbru@redhat.com> [Add a previous patch's stray hunk] --- qapi/block-core.json | 20 ++++++++++---------- qapi/crypto.json | 12 ++++++------ qapi/dump.json | 2 +- qapi/machine.json | 3 +-- qapi/migration.json | 38 ++++++++++++++++++-------------------- qapi/misc.json | 2 +- qapi/qom.json | 4 ++-- qapi/run-state.json | 9 ++++----- qapi/sockets.json | 3 +-- qapi/ui.json | 14 +++++++------- 10 files changed, 51 insertions(+), 56 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index e6b392ffe7..7d3fe59f6c 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -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) # @@ -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 ## @@ -4619,7 +4619,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 +4953,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/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/dump.json b/qapi/dump.json index ef1f3b62fc..2fa9504d86 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -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/machine.json b/qapi/machine.json index 01be411fa7..e8b60641f2 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -920,7 +920,7 @@ # @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) @@ -1190,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 8845f8bb72..8c65b90328 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -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 @@ -638,7 +637,7 @@ ## # @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 @@ -781,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 @@ -877,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 @@ -989,15 +988,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 @@ -1085,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 @@ -1225,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 @@ -1317,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 @@ -1750,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: # @@ -2176,7 +2175,6 @@ # @millisecond: value is in milliseconds # # Since: 8.2 -# ## { 'enum': 'TimeUnit', 'data': ['second', 'millisecond'] } @@ -2258,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 @@ -2295,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 # diff --git a/qapi/misc.json b/qapi/misc.json index 83def5edc4..ec30e5c570 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -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/qom.json b/qapi/qom.json index e263e29a26..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 diff --git a/qapi/run-state.json b/qapi/run-state.json index bc1c3a9217..5f07444b84 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,7 +141,7 @@ # @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) @@ -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 # 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/ui.json b/qapi/ui.json index e71cd2f50b..9721c1e5af 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) # @@ -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 # @@ -1314,7 +1314,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 +1417,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 ## From 7270819384cabf6c501ef34217eb56a1b14696e3 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Mar 2024 15:09:10 +0100 Subject: [PATCH 15/20] qga/qapi-schema: Refill doc comments to conform to current conventions For legibility, wrap text paragraphs so every line is at most 70 characters long. To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the refilled paragraphs are visible there. Signed-off-by: Markus Armbruster Message-ID: <20240322140910.328840-13-armbru@redhat.com> --- qga/qapi-schema.json | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) 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 # From 6087783ea75030fe70f1b369cfd9d3c25bc2dadf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= Date: Mon, 25 Mar 2024 13:56:48 +0400 Subject: [PATCH 16/20] qapi: document InputMultiTouchType MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Marc-André Lureau Message-ID: <20240325095648.2835381-1-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster [Update qapi/pragma.json] Signed-off-by: Markus Armbruster --- qapi/pragma.json | 2 -- qapi/ui.json | 12 ++++++++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/qapi/pragma.json b/qapi/pragma.json index 6929ab776e..92715d22b3 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -62,8 +62,6 @@ 'ImageInfoSpecificKind', 'InputAxis', 'InputButton', - 'InputMultiTouchEvent', - 'InputMultiTouchType', 'IscsiHeaderDigest', 'IscsiTransport', 'JSONType', diff --git a/qapi/ui.json b/qapi/ui.json index 9721c1e5af..f610bce118 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -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 From b2913cc2a1825d70b9985613447b26d672df5418 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 25 Mar 2024 11:45:02 +0100 Subject: [PATCH 17/20] qapi: document leftover members in qapi/run-state.json Suggested-by: Markus Armbruster Signed-off-by: Paolo Bonzini Message-ID: <20240325104502.1358693-1-pbonzini@redhat.com> Reviewed-by: Markus Armbruster [Capitalize "ID", update qapi/pragma.json] Signed-off-by: Markus Armbruster --- qapi/pragma.json | 4 +--- qapi/run-state.json | 26 +++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/qapi/pragma.json b/qapi/pragma.json index 92715d22b3..1a302981c1 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -57,7 +57,6 @@ 'DummyForceArrays', 'DummyVirtioForceArrays', 'GrabToggleKeys', - 'GuestPanicInformationHyperV', 'HotKeyMod', 'ImageInfoSpecificKind', 'InputAxis', @@ -93,8 +92,7 @@ 'query-cpu-model-expansion', 'query-rocker', 'query-rocker-ports', - 'query-stats-schemas', - 'watchdog-set-action' ], + 'query-stats-schemas' ], # Externally visible types whose member names may use uppercase 'member-name-exceptions': [ # visible in: 'ACPISlotType', # query-acpi-ospm-status diff --git a/qapi/run-state.json b/qapi/run-state.json index 5f07444b84..f8773f23b2 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -376,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'} } @@ -504,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', From 1de759534de1a9a76bd72678d0290ce5ee00de25 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 25 Mar 2024 11:45:04 +0100 Subject: [PATCH 18/20] qapi: document leftover members in qapi/stats.json Suggested-by: Markus Armbruster Signed-off-by: Paolo Bonzini Message-ID: <20240325104504.1358734-1-pbonzini@redhat.com> Reviewed-by: Markus Armbruster [Update qapi/pragma.json] Signed-off-by: Markus Armbruster --- qapi/pragma.json | 5 +---- qapi/stats.json | 14 +++++++++----- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/qapi/pragma.json b/qapi/pragma.json index 1a302981c1..99e4052ab3 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -75,8 +75,6 @@ 'Qcow2OverlapCheckFlags', 'RbdAuthMode', 'RbdImageEncryptionFormat', - 'StatsFilter', - 'StatsValue', 'String', 'StringWrapper', 'SysEmuTarget', @@ -91,8 +89,7 @@ 'query-cpu-model-comparison', 'query-cpu-model-expansion', 'query-rocker', - 'query-rocker-ports', - 'query-stats-schemas' ], + '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/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 From 125f973cc2f135a683e425ef30802102f13d47b3 Mon Sep 17 00:00:00 2001 From: Vladimir Sementsov-Ogievskiy Date: Mon, 25 Mar 2024 15:00:54 +0300 Subject: [PATCH 19/20] qapi/block-core: improve Qcow2OverlapCheckFlags documentation Most of fields have no description at all. Let's fix that. Still, no reason to place here more detailed descriptions of what these structures are, as we have public Qcow2 format specification. Signed-off-by: Vladimir Sementsov-Ogievskiy Message-ID: <20240325120054.2693236-1-vsementsov@yandex-team.ru> Acked-by: Markus Armbruster [Capitalize "QEMU", update qapi/pragma.json] Signed-off-by: Markus Armbruster --- qapi/block-core.json | 25 +++++++++++++++++++++---- qapi/pragma.json | 1 - 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 7d3fe59f6c..746d1694c2 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -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 ## diff --git a/qapi/pragma.json b/qapi/pragma.json index 99e4052ab3..9e28de1721 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -72,7 +72,6 @@ 'QCryptoAkCipherKeyType', 'QCryptodevBackendServiceType', 'QKeyCode', - 'Qcow2OverlapCheckFlags', 'RbdAuthMode', 'RbdImageEncryptionFormat', 'String', From 1a533ce986f52c35f324f5f4fff22cdc2619a47c Mon Sep 17 00:00:00 2001 From: David Hildenbrand Date: Mon, 25 Mar 2024 16:01:41 +0100 Subject: [PATCH 20/20] qapi: document parameters of query-cpu-model-* QAPI commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Let's document the parameters of these commands, so we can remove them from the "documentation-exceptions" list. While at it, extend the "Returns:" documentation as well, fixing a wrong use of CpuModelBaselineInfo vs. CpuModelCompareInfo for query-cpu-model-comparison. Cc: Markus Armbruster Cc: Eric Blake Cc: Eduardo Habkost Cc: Marcel Apfelbaum Cc: "Philippe Mathieu-Daudé" Cc: Yanan Wang Signed-off-by: David Hildenbrand Message-ID: <20240325150141.342720-1-david@redhat.com> Reviewed-by: Markus Armbruster [Punctuation tweaked] Signed-off-by: Markus Armbruster --- qapi/machine-target.json | 46 +++++++++++++++++++++++++++------------- qapi/pragma.json | 3 --- 2 files changed, 31 insertions(+), 18 deletions(-) diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 03d7a185b9..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 diff --git a/qapi/pragma.json b/qapi/pragma.json index 9e28de1721..59fbe74b8c 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -84,9 +84,6 @@ 'XDbgBlockGraph', 'YankInstanceType', 'blockdev-reopen', - 'query-cpu-model-baseline', - 'query-cpu-model-comparison', - 'query-cpu-model-expansion', 'query-rocker', 'query-rocker-ports' ], # Externally visible types whose member names may use uppercase