[PULL 00/20] QAPI patches patches for 2024-03-26

[PULL 00/20] QAPI patches patches for 2024-03-26

[Markus Armbruster]

This pull request does not touch code, only QAPI schema documentation
comments and error-suppressing QAPI schema pragma
documentation-exceptions.

The following changes since commit 6a4180af9686830d88c387baab6d79563ce42a15:

  Merge tag 'pull-request-2024-03-25' of https://gitlab.com/thuth/qemu into staging (2024-03-25 14:19:42 +0000)

are available in the Git repository at:

  https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-03-26

for you to fetch changes up to 1a533ce986f52c35f324f5f4fff22cdc2619a47c:

  qapi: document parameters of query-cpu-model-* QAPI commands (2024-03-26 06:36:08 +0100)

----------------------------------------------------------------
QAPI patches patches for 2024-03-26

----------------------------------------------------------------
David Hildenbrand (1):
      qapi: document parameters of query-cpu-model-* QAPI commands

Marc-André Lureau (1):
      qapi: document InputMultiTouchType

Markus Armbruster (15):
      qapi: Improve migration TLS documentation
      qapi: Resync MigrationParameter and MigrateSetParameters
      qapi: Fix bogus documentation of query-migrationthreads
      qapi: Drop stray Arguments: line from qmp_capabilities docs
      qapi: Expand a few awkward abbreviations in documentation
      qapi: Tidy up block-latency-histogram-set documentation some more
      qapi: Tidy up indentation of add_client's example
      qapi: Fix argument markup in drive-mirror documentation
      qapi: Fix typo in request-ebpf documentation
      qapi: Fix abbreviation punctuation in doc comments
      qapi: Start sentences with a capital letter, end them with a period
      qapi: Don't repeat member type in its documentation text
      qapi: Refill doc comments to conform to current conventions
      qapi: Correct documentation indentation and whitespace
      qga/qapi-schema: Refill doc comments to conform to current conventions

Paolo Bonzini (2):
      qapi: document leftover members in qapi/run-state.json
      qapi: document leftover members in qapi/stats.json

Vladimir Sementsov-Ogievskiy (1):
      qapi/block-core: improve Qcow2OverlapCheckFlags documentation

 qapi/block-core.json     |  71 ++++++++-----
 qapi/block.json          |  14 +--
 qapi/control.json        |   2 -
 qapi/crypto.json         |  12 +--
 qapi/cxl.json            |   4 +-
 qapi/dump.json           |  18 ++--
 qapi/ebpf.json           |  14 ++-
 qapi/machine-target.json |  68 ++++++++-----
 qapi/machine.json        |  18 ++--
 qapi/migration.json      | 253 ++++++++++++++++++++++++-----------------------
 qapi/misc.json           |   8 +-
 qapi/net.json            |  27 ++---
 qapi/pragma.json         |  13 +--
 qapi/qom.json            |  38 +++----
 qapi/replay.json         |   4 +-
 qapi/run-state.json      |  45 ++++++---
 qapi/sockets.json        |   3 +-
 qapi/stats.json          |  14 ++-
 qapi/ui.json             |  28 ++++--
 qapi/virtio.json         |  20 ++--
 qga/qapi-schema.json     |  29 +++---
 21 files changed, 389 insertions(+), 314 deletions(-)

-- 
2.44.0

[PULL 01/20] qapi: Improve migration TLS documentation

[Markus Armbruster]

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 <armbru@redhat.com>
Message-ID: <20240322135117.195489-2-armbru@redhat.com>
Reviewed-by: Peter Xu <peterx@redhat.com>
[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.
-- 
2.44.0

[PULL 02/20] qapi: Resync MigrationParameter and MigrateSetParameters

[Markus Armbruster]

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 <armbru@redhat.com>
Message-ID: <20240322135117.195489-3-armbru@redhat.com>
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Reviewed-by: Peter Xu <peterx@redhat.com>
---
 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)
-- 
2.44.0

[PULL 03/20] qapi: Fix bogus documentation of query-migrationthreads

[Markus Armbruster]

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 <jsnow@redhat.com>
Fixes: 671326201dac (migration: Introduce interface query-migrationthreads)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322135117.195489-4-armbru@redhat.com>
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Reviewed-by: Peter Xu <peterx@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
---
 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
 ##
-- 
2.44.0

[PULL 04/20] qapi: Drop stray Arguments: line from qmp_capabilities docs

[Markus Armbruster]

Reported-by: John Snow <jsnow@redhat.com>
Fixes: 119ebac1feb2 (qapi-schema: use generated marshaller for 'qmp_capabilities')
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-2-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
---
 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
-- 
2.44.0

[PULL 05/20] qapi: Expand a few awkward abbreviations in documentation

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
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
 #
-- 
2.44.0

[PULL 06/20] qapi: Tidy up block-latency-histogram-set documentation some more

[Markus Armbruster]

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 <armbru@redhat.com>
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",
-- 
2.44.0

[PULL 07/20] qapi: Tidy up indentation of add_client's example

[Markus Armbruster]

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 <armbru@redhat.com>
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',
-- 
2.44.0

[PULL 08/20] qapi: Fix argument markup in drive-mirror documentation

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
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.
 #
-- 
2.44.0

[PULL 09/20] qapi: Fix typo in request-ebpf documentation

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
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.
-- 
2.44.0

[PULL 10/20] qapi: Fix abbreviation punctuation in doc comments

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
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.
-- 
2.44.0

[PULL 11/20] qapi: Start sentences with a capital letter, end them with a period

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
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.
-- 
2.44.0

[PULL 12/20] qapi: Don't repeat member type in its documentation text

[Markus Armbruster]

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 <armbru@redhat.com>
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
 #
-- 
2.44.0

[PULL 13/20] qapi: Refill doc comments to conform to current conventions

[Markus Armbruster]

For legibility, wrap text paragraphs so every line is at most 70
characters long.

To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3".  Finds no
differences.  Comparing with diff is not useful, as the refilled
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-11-armbru@redhat.com>
---
 qapi/block-core.json     |  24 ++++-----
 qapi/block.json          |   4 +-
 qapi/cxl.json            |   4 +-
 qapi/dump.json           |  16 +++---
 qapi/ebpf.json           |  12 ++---
 qapi/machine-target.json |  22 +++++----
 qapi/machine.json        |  15 +++---
 qapi/migration.json      | 104 ++++++++++++++++++++-------------------
 qapi/net.json            |  27 +++++-----
 qapi/qom.json            |  34 ++++++-------
 qapi/run-state.json      |   4 +-
 qapi/virtio.json         |  12 +++--
 12 files changed, 142 insertions(+), 136 deletions(-)

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

[PULL 14/20] qapi: Correct documentation indentation and whitespace

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
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
 ##
-- 
2.44.0

[PULL 15/20] qga/qapi-schema: Refill doc comments to conform to current conventions

[Markus Armbruster]

For legibility, wrap text paragraphs so every line is at most 70
characters long.

To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3".  Finds no
differences.  Comparing with diff is not useful, as the refilled
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-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
 #
-- 
2.44.0

[PULL 16/20] qapi: document InputMultiTouchType

[Markus Armbruster]

From: Marc-André Lureau <marcandre.lureau@redhat.com>

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-ID: <20240325095648.2835381-1-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Update qapi/pragma.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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
-- 
2.44.0

[PULL 17/20] qapi: document leftover members in qapi/run-state.json

[Markus Armbruster]

From: Paolo Bonzini <pbonzini@redhat.com>

Suggested-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-ID: <20240325104502.1358693-1-pbonzini@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Capitalize "ID", update qapi/pragma.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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',
-- 
2.44.0

[PULL 18/20] qapi: document leftover members in qapi/stats.json

[Markus Armbruster]

From: Paolo Bonzini <pbonzini@redhat.com>

Suggested-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-ID: <20240325104504.1358734-1-pbonzini@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Update qapi/pragma.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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
-- 
2.44.0

[PULL 19/20] qapi/block-core: improve Qcow2OverlapCheckFlags documentation

[Markus Armbruster]

From: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>

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 <vsementsov@yandex-team.ru>
Message-ID: <20240325120054.2693236-1-vsementsov@yandex-team.ru>
Acked-by: Markus Armbruster <armbru@redhat.com>
[Capitalize "QEMU", update qapi/pragma.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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',
-- 
2.44.0

[PULL 20/20] qapi: document parameters of query-cpu-model-* QAPI commands

[Markus Armbruster]

From: David Hildenbrand <david@redhat.com>

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 <armbru@redhat.com>
Cc: Eric Blake <eblake@redhat.com>
Cc: Eduardo Habkost <eduardo@habkost.net>
Cc: Marcel Apfelbaum <marcel.apfelbaum@gmail.com>
Cc: "Philippe Mathieu-Daudé" <philmd@linaro.org>
Cc: Yanan Wang <wangyanan55@huawei.com>
Signed-off-by: David Hildenbrand <david@redhat.com>
Message-ID: <20240325150141.342720-1-david@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Punctuation tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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
-- 
2.44.0

Re: [PULL 00/20] QAPI patches patches for 2024-03-26

[Peter Maydell]

On Tue, 26 Mar 2024 at 07:34, Markus Armbruster <armbru@redhat.com> wrote:
>
> This pull request does not touch code, only QAPI schema documentation
> comments and error-suppressing QAPI schema pragma
> documentation-exceptions.
>
> The following changes since commit 6a4180af9686830d88c387baab6d79563ce42a15:
>
>   Merge tag 'pull-request-2024-03-25' of https://gitlab.com/thuth/qemu into staging (2024-03-25 14:19:42 +0000)
>
> are available in the Git repository at:
>
>   https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-03-26
>
> for you to fetch changes up to 1a533ce986f52c35f324f5f4fff22cdc2619a47c:
>
>   qapi: document parameters of query-cpu-model-* QAPI commands (2024-03-26 06:36:08 +0100)
>
> ----------------------------------------------------------------
> QAPI patches patches for 2024-03-26
>
> ----------------------------------------------------------------


Applied, thanks.

Please update the changelog at https://wiki.qemu.org/ChangeLog/9.0
for any user-visible changes.

-- PMM