[PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences

[PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Hi all!

Let's bring the documentation in line with the requirements. And
do check these requirements in QAPI parser.

v2: resend without duplicated patchs. Sorry for the noise.

Vladimir Sementsov-Ogievskiy (33):
  qapi: Add documentation format validation
  qapi/acpi.json: docs: width=70 and two spaces between sentences
  qapi/audio.json: docs: width=70 and two spaces between sentences
  qapi/block-core.json: docs: width=70 and two spaces between sentences
  qapi/block-export.json: docs: width=70 and two spaces between
    sentences
  qapi/block.json: docs: width=70 and two spaces between sentences
  qapi/char.json: docs: width=70 and two spaces between sentences
  qapi/crypto.json: docs: width=70 and two spaces between sentences
  qapi/dump.json: docs: width=70 and two spaces between sentences
  qapi/introspect.json: docs: width=70 and two spaces between sentences
  qapi/job.json: docs: width=70 and two spaces between sentences
  qapi/machine-s390x.json: docs: width=70 and two spaces between
    sentences
  qapi/machine.json: docs: width=70 and two spaces between sentences
  qapi/migration.json: docs: width=70 and two spaces between sentences
  qapi/misc-arm.json: docs: width=70 and two spaces between sentences
  qapi/misc-i386.json: docs: width=70 and two spaces between sentences
  qapi/misc.json: docs: width=70 and two spaces between sentences
  qapi/net.json: docs: width=70 and two spaces between sentences
  qapi/qdev.json: docs: width=70 and two spaces between sentences
  qapi/qom.json: docs: width=70 and two spaces between sentences
  qapi/replay.json: docs: width=70 and two spaces between sentences
  qapi/rocker.json: docs: width=70 and two spaces between sentences
  qapi/run-state.json: docs: width=70 and two spaces between sentences
  qapi/sockets.json: docs: width=70 and two spaces between sentences
  qapi/stats.json: docs: width=70 and two spaces between sentences
  qapi/tpm.json: docs: width=70 and two spaces between sentences
  qapi/trace.json: docs: width=70 and two spaces between sentences
  qapi/transaction.json: docs: width=70 and two spaces between sentences
  qapi/ui.json: docs: width=70 and two spaces between sentences
  qapi/vfio.json: docs: width=70 and two spaces between sentences
  qapi/virtio.json: docs: width=70 and two spaces between sentences
  qga/qapi-schema.json: docs: width=70 and two spaces between sentences
  qapi/acpi-hest.json: docs: width=70 and two spaces between sentences

 qapi/acpi-hest.json     |   2 +-
 qapi/acpi.json          |  20 ++-
 qapi/audio.json         |   4 +-
 qapi/block-core.json    | 191 +++++++++++++++-------------
 qapi/block-export.json  |  26 ++--
 qapi/block.json         |  18 +--
 qapi/char.json          |  34 +++--
 qapi/crypto.json        |   7 +-
 qapi/dump.json          |   9 +-
 qapi/introspect.json    |   8 +-
 qapi/job.json           |  26 ++--
 qapi/machine-s390x.json |   3 +-
 qapi/machine.json       |  59 +++++----
 qapi/migration.json     | 209 ++++++++++++++++++-------------
 qapi/misc-arm.json      |   6 +-
 qapi/misc-i386.json     |   9 +-
 qapi/misc.json          |  16 ++-
 qapi/net.json           |  61 +++++----
 qapi/qdev.json          |  13 +-
 qapi/qom.json           |  31 +++--
 qapi/replay.json        |   9 +-
 qapi/rocker.json        |  18 ++-
 qapi/run-state.json     |  60 +++++----
 qapi/sockets.json       |  34 ++---
 qapi/stats.json         |   3 +-
 qapi/tpm.json           |   3 +-
 qapi/trace.json         |   3 +-
 qapi/transaction.json   |  33 ++---
 qapi/ui.json            | 108 ++++++++++------
 qapi/vfio.json          |   3 +-
 qapi/virtio.json        | 269 +++-------------------------------------
 qga/qapi-schema.json    |  83 +++++++------
 scripts/qapi/parser.py  |  39 +++++-
 33 files changed, 713 insertions(+), 704 deletions(-)

-- 
2.48.1

[PATCH v2 01/33] qapi: Add documentation format validation

[Vladimir Sementsov-Ogievskiy]

Add explicit validation for QAPI documentation formatting rules:

1. Lines must not exceed 70 columns in width (including '# ' prefix)
2. Sentences must be separated by two spaces

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 scripts/qapi/parser.py | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 9fbf80a541..2c76686fc4 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -428,7 +428,44 @@ def get_doc_line(self) -> Optional[str]:
             return ''
         if self.val[1] != ' ':
             raise QAPIParseError(self, "missing space after #")
-        return self.val[2:].rstrip()
+
+        line = self.val[2:].rstrip()
+
+        self._validate_doc_line_format(line)
+
+        return line
+
+    def _validate_doc_line_format(self, line: str) -> None:
+        """
+        Validate documentation format rules for a single line:
+        1. Lines should not exceed 70 columns
+        2. Sentences should be separated by two spaces
+        """
+        # Check 70-column width rule
+        full_line_length = len(line) + 2  # "# " = 2 characters
+        if full_line_length > 70:
+            # Skip URL lines - they can't be broken
+            stripped_line = line.strip()
+            if (stripped_line.startswith(('http://', 'https://', 'ftp://')) and
+                ' ' not in stripped_line):
+                pass
+            else:
+                raise QAPIParseError(
+                    self, f"documentation line exceeds 70 columns "
+                    f"({full_line_length} columns): {line[:50]}..."
+                )
+
+        single_space_pattern = r'[.!?] [A-Z0-9]'
+        for m in list(re.finditer(single_space_pattern, line)):
+            left = line[0:m.start() + 1]
+            # Ignore abbreviations and numbered lists
+            if left.endswith('e.g.') or re.fullmatch(r' *\d\.', left):
+                continue
+            raise QAPIParseError(
+                 self, f"documentation has single space after sentence "
+                 f"ending. Use two spaces between sentences: "
+                 f"...{line[m.start()-5:m.end()+5]}..."
+            )
 
     @staticmethod
     def _match_at_name_colon(string: str) -> Optional[Match[str]]:
-- 
2.48.1

[PATCH v2 02/33] qapi/acpi.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/acpi.json | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/qapi/acpi.json b/qapi/acpi.json
index 906b3687a5..601271607b 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -116,10 +116,16 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-acpi-ospm-status" }
-#     <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
-#                      { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
-#                      { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
-#                      { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
+#     <- { "return": [
+#          { "device": "d1", "slot": "0",
+#            "slot-type": "DIMM", "source": 1,
+#            "status": 0 },
+#          { "slot": "1", "slot-type": "DIMM", "source": 0,
+#            "status": 0 },
+#          { "slot": "2", "slot-type": "DIMM", "source": 0,
+#            "status": 0 },
+#          { "slot": "3", "slot-type": "DIMM", "source": 0,
+#            "status": 0 }
 #        ]}
 ##
 { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
@@ -137,8 +143,10 @@
 #
 #     <- { "event": "ACPI_DEVICE_OST",
 #          "data": { "info": { "device": "d1", "slot": "0",
-#                              "slot-type": "DIMM", "source": 1, "status": 0 } },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#                              "slot-type": "DIMM", "source": 1,
+#                              "status": 0 } },
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'ACPI_DEVICE_OST',
      'data': { 'info': 'ACPIOSTInfo' } }
-- 
2.48.1

[PATCH v2 03/33] qapi/audio.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/audio.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qapi/audio.json b/qapi/audio.json
index 53142080f7..2df87b9710 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -76,8 +76,8 @@
 #
 # @out: options of the playback stream
 #
-# @nsamples: set the number of samples per read/write calls (default to 480,
-# 10ms at 48kHz).
+# @nsamples: set the number of samples per read/write calls
+#     (default to 480, 10ms at 48kHz).
 #
 # Since: 10.0
 ##
-- 
2.48.1

[PATCH v2 04/33] qapi/block-core.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/block-core.json | 191 ++++++++++++++++++++++++-------------------
 1 file changed, 106 insertions(+), 85 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index dc6eb4ae23..4828a78371 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -159,14 +159,15 @@
 ##
 # @ImageInfoSpecificRbd:
 #
-# @encryption-format: Image encryption format. If encryption is enabled for the
-#     image (see encrypted in BlockNodeInfo), this is the actual format in which the
-#     image is accessed. If encryption is not enabled, this is the result of
-#     probing when the image was opened, to give a suggestion which encryption
-#     format could be enabled. Note that probing results can be changed by the
-#     guest by writing a (possibly partial) encryption format header to the
-#     image, so don't treat this information as trusted if the guest is not
-#     trusted.
+# @encryption-format: Image encryption format.  If encryption is
+#     enabled for the image (see encrypted in BlockNodeInfo), this is
+#     the actual format in which the image is accessed.  If encryption
+#     is not enabled, this is the result of probing when the image was
+#     opened, to give a suggestion which encryption format could be
+#     enabled.  Note that probing results can be changed by the guest
+#     by writing a (possibly partial) encryption format header to the
+#     image, so don't treat this information as trusted if the guest
+#     is not trusted.
 #
 # Since: 6.1
 ##
@@ -340,8 +341,8 @@
 # node, annotated with information about that node in relation to its
 # parent.
 #
-# @name: Child name of the root node in the `BlockGraphInfo` struct, in
-#     its role as the child of some undescribed parent node
+# @name: Child name of the root node in the `BlockGraphInfo` struct,
+#     in its role as the child of some undescribed parent node
 #
 # @info: Block graph information starting at this node
 #
@@ -507,11 +508,12 @@
 # @backing_file_depth: number of files in the backing file chain
 #     (since: 1.2)
 #
-# @children: Information about child block nodes. (since: 10.1)
+# @children: Information about child block nodes.  (since: 10.1)
 #
-# @active: true if the backend is active; typical cases for inactive backends
-#     are on the migration source instance after migration completes and on the
-#     destination before it completes.  (since: 10.0)
+# @active: true if the backend is active; typical cases for inactive
+#     backends are on the migration source instance after migration
+#     completes and on the destination before it completes.
+#     (since: 10.0)
 #
 # @encrypted: true if the backing device is encrypted
 #
@@ -1627,11 +1629,12 @@
 #     different block device than @device).
 #
 # @on-cbw-error: policy defining behavior on I/O errors in
-#     copy-before-write jobs; defaults to break-guest-write.  (Since 10.1)
+#     copy-before-write jobs; defaults to break-guest-write.
+#     (Since 10.1)
 #
 # @auto-finalize: When false, this job will wait in a PENDING state
-#     after it has finished its work, waiting for `job-finalize` before
-#     making any block graph changes.  When true, this job will
+#     after it has finished its work, waiting for `job-finalize`
+#     before making any block graph changes.  When true, this job will
 #     automatically perform its abort or commit actions.  Defaults to
 #     true.  (Since 2.12)
 #
@@ -1743,7 +1746,8 @@
 #
 # @allow-write-only-overlay: If present, the check whether this
 #     operation is safe was relaxed so that it can be used to change
-#     backing file of a destination of a `blockdev-mirror`.  (since 5.0)
+#     backing file of a destination of a `blockdev-mirror`.
+#     (since 5.0)
 #
 # Since: 2.5
 #
@@ -1870,8 +1874,8 @@
 #     autogenerated.  (Since: 2.9)
 #
 # @auto-finalize: When false, this job will wait in a PENDING state
-#     after it has finished its work, waiting for `job-finalize` before
-#     making any block graph changes.  When true, this job will
+#     after it has finished its work, waiting for `job-finalize`
+#     before making any block graph changes.  When true, this job will
 #     automatically perform its abort or commit actions.  Defaults to
 #     true.  (Since 3.1)
 #
@@ -1944,10 +1948,10 @@
 # @blockdev-backup:
 #
 # Start a point-in-time copy of a block device to a new destination.
-# The status of ongoing `blockdev-backup` operations can be checked with
-# `query-block-jobs` where the `BlockJobInfo`.type field has the value
-# 'backup'.  The operation can be stopped before it has completed
-# using the `job-cancel` or `block-job-cancel` command.
+# The status of ongoing `blockdev-backup` operations can be checked
+# with `query-block-jobs` where the `BlockJobInfo`.type field has the
+# value 'backup'.  The operation can be stopped before it has
+# completed using the `job-cancel` or `block-job-cancel` command.
 #
 # Errors:
 #     - If @device is not a valid block device, DeviceNotFound
@@ -2005,7 +2009,8 @@
 #                           "format":"qcow2",
 #                           "virtual-size":2048000,
 #                           "backing_file":"base.qcow2",
-#                           "full-backing-filename":"disks/base.qcow2",
+#                           "full-backing-filename":
+#                               "disks/base.qcow2",
 #                           "backing-filename-format":"qcow2",
 #                           "snapshots":[
 #                              {
@@ -2231,8 +2236,8 @@
 #     'background' (Since: 3.0)
 #
 # @auto-finalize: When false, this job will wait in a PENDING state
-#     after it has finished its work, waiting for `job-finalize` before
-#     making any block graph changes.  When true, this job will
+#     after it has finished its work, waiting for `job-finalize`
+#     before making any block graph changes.  When true, this job will
 #     automatically perform its abort or commit actions.  Defaults to
 #     true.  (Since 3.1)
 #
@@ -2282,7 +2287,8 @@
 #
 # @disabled: the bitmap is created in the disabled state, which means
 #     that it will not track drive changes.  The bitmap may be enabled
-#     with `block-dirty-bitmap-enable`.  Default is false.  (Since: 4.0)
+#     with `block-dirty-bitmap-enable`.  Default is false.
+#     (Since: 4.0)
 #
 # Since: 2.4
 ##
@@ -2347,8 +2353,8 @@
 # @block-dirty-bitmap-remove:
 #
 # Stop write tracking and remove the dirty bitmap that was created
-# with `block-dirty-bitmap-add`.  If the bitmap is persistent, remove it
-# from its storage too.
+# with `block-dirty-bitmap-add`.  If the bitmap is persistent, remove
+# it from its storage too.
 #
 # Errors:
 #     - If @node is not a valid block device or node, DeviceNotFound
@@ -2546,8 +2552,8 @@
 #     'background' (Since: 3.0)
 #
 # @auto-finalize: When false, this job will wait in a PENDING state
-#     after it has finished its work, waiting for `job-finalize` before
-#     making any block graph changes.  When true, this job will
+#     after it has finished its work, waiting for `job-finalize`
+#     before making any block graph changes.  When true, this job will
 #     automatically perform its abort or commit actions.  Defaults to
 #     true.  (Since 3.1)
 #
@@ -2873,8 +2879,8 @@
 #     autogenerated.  (Since: 6.0)
 #
 # @auto-finalize: When false, this job will wait in a PENDING state
-#     after it has finished its work, waiting for `job-finalize` before
-#     making any block graph changes.  When true, this job will
+#     after it has finished its work, waiting for `job-finalize`
+#     before making any block graph changes.  When true, this job will
 #     automatically perform its abort or commit actions.  Defaults to
 #     true.  (Since 3.1)
 #
@@ -3044,16 +3050,16 @@
 #
 # This is supported only for drive mirroring, where it also switches
 # the device to write to the target path only.  Note that drive
-# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit`
-# job (only in case of "active commit", when the node being commited
-# is used by the guest).  The ability to complete is signaled with a
-# `BLOCK_JOB_READY` event.
+# mirroring includes `drive-mirror`, `blockdev-mirror` and
+# `block-commit` job (only in case of "active commit", when the node
+# being commited is used by the guest).  The ability to complete is
+# signaled with a `BLOCK_JOB_READY` event.
 #
 # This command completes an active background block operation
 # synchronously.  The ordering of this command's return with the
-# `BLOCK_JOB_COMPLETED` event is not defined.  Note that if an I/O error
-# occurs during the processing of this command: 1) the command itself
-# will fail; 2) the error will be processed according to the
+# `BLOCK_JOB_COMPLETED` event is not defined.  Note that if an I/O
+# error occurs during the processing of this command: 1) the command
+# itself will fail; 2) the error will be processed according to the
 # rerror/werror arguments that were specified when starting the
 # operation.
 #
@@ -3083,8 +3089,8 @@
 # needs to be run explicitly for jobs that don't have automatic
 # dismiss enabled.  In turn, automatic dismiss may be enabled only
 # for jobs that have @auto-dismiss option, which are `drive-backup`,
-# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
-# `block-stream`.  @auto-dismiss is enabled by default for these
+# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
+# and `block-stream`.  @auto-dismiss is enabled by default for these
 # jobs.
 #
 # This command will refuse to operate on any job that has not yet
@@ -3117,8 +3123,8 @@
 # force ALL jobs in the transaction to finalize, so it is only
 # necessary to instruct a single member job to finalize.
 #
-# The command is applicable only to jobs which have @auto-finalize option
-# and only when this option is set to false.
+# The command is applicable only to jobs which have @auto-finalize
+# option and only when this option is set to false.
 #
 # @id: The job identifier.
 #
@@ -4748,9 +4754,9 @@
 # @cache: cache-related options
 #
 # @active: whether the block node should be activated (default: true).
-#     Having inactive block nodes is useful primarily for migration because it
-#     allows opening an image on the destination while the source is still
-#     holding locks for it.  (Since 10.0)
+#     Having inactive block nodes is useful primarily for migration
+#     because it allows opening an image on the destination while the
+#     source is still holding locks for it.  (Since 10.0)
 #
 # @read-only: whether the block device should be read-only (default:
 #     false).  Note that some block drivers support only read-only
@@ -4942,11 +4948,12 @@
 # cancelled.
 #
 # The command receives a list of block devices to reopen.  For each
-# one of them, the top-level @node-name option (from `BlockdevOptions`)
-# must be specified and is used to select the block device to be
-# reopened.  Other @node-name options must be either omitted or set to
-# the current name of the appropriate node.  This command won't change
-# any node name and any attempt to do it will result in an error.
+# one of them, the top-level @node-name option (from
+# `BlockdevOptions`) must be specified and is used to select the block
+# device to be reopened.  Other @node-name options must be either
+# omitted or set to the current name of the appropriate node.  This
+# command won't change any node name and any attempt to do it will
+# result in an error.
 #
 # In the case of options that refer to child nodes, the behavior of
 # this command depends on the value:
@@ -4965,10 +4972,10 @@
 # Options (1) and (2) are supported in all cases.  Option (3) is
 # supported for @file and @backing, and option (4) for @backing only.
 #
-# Unlike with `blockdev-add`, the @backing option must always be present
-# unless the node being reopened does not have a backing file and its
-# image does not have a default backing file name as part of its
-# metadata.
+# Unlike with `blockdev-add`, the @backing option must always be
+# present unless the node being reopened does not have a backing file
+# and its image does not have a default backing file name as part of
+# its metadata.
 #
 # Since: 6.1
 ##
@@ -4979,8 +4986,8 @@
 ##
 # @blockdev-del:
 #
-# Deletes a block device that has been added using `blockdev-add`.  The
-# command will fail if the node is attached to a device or is
+# Deletes a block device that has been added using `blockdev-add`.
+# The command will fail if the node is attached to a device or is
 # otherwise being used.
 #
 # @node-name: Name of the graph node to delete.
@@ -5012,18 +5019,18 @@
 ##
 # @blockdev-set-active:
 #
-# Activate or inactivate a block device.  Use this to manage the handover of
-# block devices on migration with qemu-storage-daemon.
+# Activate or inactivate a block device.  Use this to manage the
+# handover of block devices on migration with qemu-storage-daemon.
 #
-# Activating a node automatically activates all of its child nodes first.
-# Inactivating a node automatically inactivates any of its child nodes that are
-# not in use by a still active node.
+# Activating a node automatically activates all of its child nodes
+# first.  Inactivating a node automatically inactivates any of its
+# child nodes that are not in use by a still active node.
 #
-# @node-name: Name of the graph node to activate or inactivate.  By default, all
-#     nodes are affected by the operation.
+# @node-name: Name of the graph node to activate or inactivate.  By
+#     default, all nodes are affected by the operation.
 #
-# @active: true if the nodes should be active when the command returns success,
-#     false if they should be inactive.
+# @active: true if the nodes should be active when the command returns
+#     success, false if they should be inactive.
 #
 # Since: 10.0
 #
@@ -5671,9 +5678,12 @@
 # .. qmp-example::
 #
 #     <- { "event": "BLOCK_IMAGE_CORRUPTED",
-#          "data": { "device": "", "node-name": "drive", "fatal": false,
-#                    "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
-#          "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
+#          "data": {
+#            "device": "", "node-name": "drive", "fatal": false,
+#            "msg":
+#              "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
+#          "timestamp": { "seconds": 1648243240,
+#                         "microseconds": 906060 } }
 #
 # Since: 1.7
 ##
@@ -5730,7 +5740,8 @@
 #                    "operation": "write",
 #                    "action": "stop",
 #                    "reason": "No space left on device" },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'BLOCK_IO_ERROR',
   'data': { 'qom-path': 'str', 'device': 'str', '*node-name': 'str',
@@ -5768,7 +5779,8 @@
 #          "data": { "type": "stream", "device": "virtio-disk0",
 #                    "len": 10737418240, "offset": 10737418240,
 #                    "speed": 0 },
-#          "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#          "timestamp": { "seconds": 1267061043,
+#                         "microseconds": 959568 } }
 ##
 { 'event': 'BLOCK_JOB_COMPLETED',
   'data': { 'type'  : 'JobType',
@@ -5803,7 +5815,8 @@
 #          "data": { "type": "stream", "device": "virtio-disk0",
 #                    "len": 10737418240, "offset": 134217728,
 #                    "speed": 0 },
-#          "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#          "timestamp": { "seconds": 1267061043,
+#                         "microseconds": 959568 } }
 ##
 { 'event': 'BLOCK_JOB_CANCELLED',
   'data': { 'type'  : 'JobType',
@@ -5832,7 +5845,8 @@
 #          "data": { "device": "ide0-hd1",
 #                    "operation": "write",
 #                    "action": "stop" },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'BLOCK_JOB_ERROR',
   'data': { 'device'   : 'str',
@@ -5866,7 +5880,8 @@
 #     <- { "event": "BLOCK_JOB_READY",
 #          "data": { "device": "drive0", "type": "mirror", "speed": 0,
 #                    "len": 2097152, "offset": 2097152 },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'BLOCK_JOB_READY',
   'data': { 'type'  : 'JobType',
@@ -5893,7 +5908,8 @@
 #
 #     <- { "event": "BLOCK_JOB_PENDING",
 #          "data": { "type": "mirror", "id": "backup_1" },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'BLOCK_JOB_PENDING',
   'data': { 'type'  : 'JobType',
@@ -6113,8 +6129,10 @@
 # .. qmp-example::
 #
 #     <- { "event": "QUORUM_FAILURE",
-#          "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
-#          "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+#          "data": { "reference": "usr1", "sector-num": 345435,
+#                    "sectors-count": 5 },
+#          "timestamp": { "seconds": 1344522075,
+#                         "microseconds": 745528 } }
 ##
 { 'event': 'QUORUM_FAILURE',
   'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } }
@@ -6145,17 +6163,20 @@
 #    :title: Read operation
 #
 #     <- { "event": "QUORUM_REPORT_BAD",
-#          "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
-#                    "type": "read" },
-#          "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+#          "data": { "node-name": "node0", "sector-num": 345435,
+#                    "sectors-count": 5, "type": "read" },
+#          "timestamp": { "seconds": 1344522075,
+#                         "microseconds": 745528 } }
 #
 # .. qmp-example::
 #    :title: Flush operation
 #
 #     <- { "event": "QUORUM_REPORT_BAD",
-#          "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
-#                    "type": "flush", "error": "Broken pipe" },
-#          "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
+#          "data": { "node-name": "node0", "sector-num": 0,
+#                    "sectors-count": 2097120, "type": "flush",
+#                    "error": "Broken pipe" },
+#          "timestamp": { "seconds": 1456406829,
+#                         "microseconds": 291763 } }
 ##
 { 'event': 'QUORUM_REPORT_BAD',
   'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str',
-- 
2.48.1

[PATCH v2 05/33] qapi/block-export.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/block-export.json | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 6878b89dcf..076954ef1a 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -38,8 +38,8 @@
 ##
 # @NbdServerOptions:
 #
-# Keep this type consistent with the `NbdServerOptionsLegacy` type.  The
-# only intended difference is using `SocketAddress` instead of
+# Keep this type consistent with the `NbdServerOptionsLegacy` type.
+# The only intended difference is using `SocketAddress` instead of
 # `SocketAddressLegacy`.
 #
 # @addr: Address on which to listen (since 4.2).
@@ -51,8 +51,8 @@
 ##
 # @NbdServerOptionsLegacy:
 #
-# Keep this type consistent with the `NbdServerOptions` type.  The only
-# intended difference is using `SocketAddressLegacy` instead of
+# Keep this type consistent with the `NbdServerOptions` type.  The
+# only intended difference is using `SocketAddressLegacy` instead of
 # `SocketAddress`.
 #
 # @addr: Address on which to listen (since 1.3).
@@ -125,8 +125,8 @@
 # A vhost-user-blk block export.
 #
 # @addr: The vhost-user socket on which to listen.  Both 'unix' and
-#     'fd' `SocketAddress` types are supported.  Passed fds must be UNIX
-#     domain sockets.
+#     'fd' `SocketAddress` types are supported.  Passed fds must be
+#     UNIX domain sockets.
 #
 # @logical-block-size: Logical block size in bytes.  Defaults to 512
 #     bytes.
@@ -373,11 +373,12 @@
 #     cannot be moved to the iothread.  The default is false.
 #     (since: 5.2)
 #
-# @allow-inactive: If true, the export allows the exported node to be inactive.
-#     If it is created for an inactive block node, the node remains inactive.  If
-#     the export type doesn't support running on an inactive node, an error is
-#     returned.  If false, inactive block nodes are automatically activated before
-#     creating the export and trying to inactivate them later fails.
+# @allow-inactive: If true, the export allows the exported node to be
+#     inactive.  If it is created for an inactive block node, the node
+#     remains inactive.  If the export type doesn't support running on
+#     an inactive node, an error is returned.  If false, inactive
+#     block nodes are automatically activated before creating the
+#     export and trying to inactivate them later fails.
 #     (since: 10.0; default: false)
 #
 # Since: 4.2
@@ -460,7 +461,8 @@
 # @node-name: The node name of the block node that is exported
 #
 # @shutting-down: True if the export is shutting down (e.g. after a
-#     `block-export-del` command, but before the shutdown has completed)
+#     `block-export-del` command, but before the shutdown has
+#     completed)
 #
 # Since: 5.2
 ##
-- 
2.48.1

[PATCH v2 06/33] qapi/block.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/block.json | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/qapi/block.json b/qapi/block.json
index 46955bbb3e..4398c801ee 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -240,7 +240,8 @@
 #          "arguments": { "id": "ide0-1-0" } }
 #
 #     <- { "error": { "class": "GenericError",
-#                     "desc": "Tray of device 'ide0-1-0' is not open" } }
+#                     "desc": "Tray of device 'ide0-1-0' is not open"
+#     } }
 #
 #     -> { "execute": "blockdev-open-tray",
 #          "arguments": { "id": "ide0-1-0" } }
@@ -350,7 +351,8 @@
 #
 #     -> { "execute": "blockdev-change-medium",
 #          "arguments": { "id": "ide0-1-0",
-#                         "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
+#                         "filename":
+#                           "/srv/images/Fedora-12-x86_64-DVD.iso",
 #                         "format": "raw" } }
 #     <- { "return": {} }
 #
@@ -359,17 +361,17 @@
 #
 #     -> { "execute": "blockdev-change-medium",
 #          "arguments": { "id": "floppyA",
-#                         "filename": "/srv/images/ro.img",
+#                         "filename": "ro.img",
 #                         "format": "raw",
 #                         "read-only-mode": "retain" } }
 #
 #     <- { "error":
 #          { "class": "GenericError",
-#            "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
+#            "desc": "Could not open 'ro.img': Permission denied" } }
 #
 #     -> { "execute": "blockdev-change-medium",
 #          "arguments": { "id": "floppyA",
-#                         "filename": "/srv/images/ro.img",
+#                         "filename": "ro.img",
 #                         "format": "raw",
 #                         "read-only-mode": "read-only" } }
 #
@@ -407,7 +409,8 @@
 #                    "id": "/machine/unattached/device[22]",
 #                    "tray-open": true
 #          },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'DEVICE_TRAY_MOVED',
   'data': { 'device': 'str', 'id': 'str', 'tray-open': 'bool' } }
@@ -430,7 +433,8 @@
 #          "data": { "id": "pr-helper0",
 #                    "connected": true
 #          },
-#          "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1519840375,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'PR_MANAGER_STATUS_CHANGED',
   'data': { 'id': 'str', 'connected': 'bool' } }
-- 
2.48.1

[PATCH v2 07/33] qapi/char.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/char.json | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/qapi/char.json b/qapi/char.json
index f0a53f742c..52cca8da67 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -47,12 +47,14 @@
 #           "return": [
 #              {
 #                 "label": "charchannel0",
-#                 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
+#                 "filename":
+#                   "unix:/.../seabios.rhel6.agent,server=on",
 #                 "frontend-open": false
 #              },
 #              {
 #                 "label": "charmonitor",
-#                 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
+#                 "filename":
+#                   "unix:/.../seabios.rhel6.monitor,server=on",
 #                 "frontend-open": true
 #              },
 #              {
@@ -272,7 +274,8 @@
 # @reconnect: For a client socket, if a socket is disconnected, then
 #     attempt a reconnect after the given number of seconds.  Setting
 #     this to zero disables this function.  The use of this member is
-#     deprecated, use @reconnect-ms instead.  (default: 0) (Since: 2.2)
+#     deprecated, use @reconnect-ms instead.
+#     (default: 0) (Since: 2.2)
 #
 # @reconnect-ms: For a client socket, if a socket is disconnected,
 #     then attempt a reconnect after the given number of milliseconds.
@@ -776,22 +779,25 @@
 #
 #     -> { "execute" : "chardev-add",
 #          "arguments" : { "id" : "foo",
-#                          "backend" : { "type" : "null", "data" : {} } } }
+#                          "backend" : { "type" : "null",
+#                                        "data" : {} } } }
 #     <- { "return": {} }
 #
 # .. qmp-example::
 #
 #     -> { "execute" : "chardev-add",
-#          "arguments" : { "id" : "bar",
-#                          "backend" : { "type" : "file",
-#                                        "data" : { "out" : "/tmp/bar.log" } } } }
+#          "arguments" : {
+#            "id" : "bar",
+#            "backend" : { "type" : "file",
+#                          "data" : { "out" : "/tmp/bar.log" } } } }
 #     <- { "return": {} }
 #
 # .. qmp-example::
 #
 #     -> { "execute" : "chardev-add",
 #          "arguments" : { "id" : "baz",
-#                          "backend" : { "type" : "pty", "data" : {} } } }
+#                          "backend" : { "type" : "pty",
+#                                        "data" : {} } } }
 #     <- { "return": { "pty" : "/dev/pty/42" } }
 ##
 { 'command': 'chardev-add',
@@ -814,7 +820,8 @@
 #
 #     -> { "execute" : "chardev-change",
 #          "arguments" : { "id" : "baz",
-#                          "backend" : { "type" : "pty", "data" : {} } } }
+#                          "backend" : { "type" : "pty",
+#                                        "data" : {} } } }
 #     <- { "return": { "pty" : "/dev/pty/42" } }
 #
 # .. qmp-example::
@@ -851,7 +858,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
+#     -> { "execute": "chardev-remove",
+#          "arguments": { "id" : "foo" } }
 #     <- { "return": {} }
 ##
 { 'command': 'chardev-remove',
@@ -868,7 +876,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
+#     -> { "execute": "chardev-send-break",
+#          "arguments": { "id" : "foo" } }
 #     <- { "return": {} }
 ##
 { 'command': 'chardev-send-break',
@@ -891,7 +900,8 @@
 #
 #     <- { "event": "VSERPORT_CHANGE",
 #          "data": { "id": "channel0", "open": true },
-#          "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
+#          "timestamp": { "seconds": 1401385907,
+#                         "microseconds": 422329 } }
 ##
 { 'event': 'VSERPORT_CHANGE',
   'data': { 'id': 'str',
-- 
2.48.1

[PATCH v2 08/33] qapi/crypto.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/crypto.json | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/qapi/crypto.json b/qapi/crypto.json
index ab6eda4c2f..72ac718147 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -46,7 +46,8 @@
 #
 # @md5: MD5.  Should not be used in any new code, legacy compat only
 #
-# @sha1: SHA-1.  Should not be used in any new code, legacy compat only
+# @sha1: SHA-1.  Should not be used in any new code, legacy compat
+#     only
 #
 # @sha224: SHA-224.  (since 2.7)
 #
@@ -377,8 +378,8 @@
 #     deactivate all keyslots that match password located in
 #     QCryptoSecret with this ID
 #
-# @iter-time: Optional (for activation only).  Number of milliseconds to
-#     spend in PBKDF passphrase processing for the newly activated
+# @iter-time: Optional (for activation only).  Number of milliseconds
+#     to spend in PBKDF passphrase processing for the newly activated
 #     keyslot.  Currently defaults to 2000.
 #
 # @keyslot: Optional.  ID of the keyslot to activate/deactivate.  For
-- 
2.48.1

[PATCH v2 09/33] qapi/dump.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/dump.json | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/qapi/dump.json b/qapi/dump.json
index 726b520870..96265cd925 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -176,9 +176,11 @@
 # .. qmp-example::
 #
 #     <- { "event": "DUMP_COMPLETED",
-#          "data": { "result": { "total": 1090650112, "status": "completed",
+#          "data": { "result": { "total": 1090650112,
+#                                "status": "completed",
 #                                "completed": 1090650112 } },
-#          "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
+#          "timestamp": { "seconds": 1648244171,
+#                         "microseconds": 950316 } }
 ##
 { 'event': 'DUMP_COMPLETED' ,
   'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
@@ -207,7 +209,8 @@
 #
 #     -> { "execute": "query-dump-guest-memory-capability" }
 #     <- { "return": { "formats":
-#                      ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }
+#                      [ "elf", "kdump-zlib", "kdump-lzo",
+#                        "kdump-snappy" ] } }
 ##
 { 'command': 'query-dump-guest-memory-capability',
   'returns': 'DumpGuestMemoryCapability' }
-- 
2.48.1

[PATCH v2 10/33] qapi/introspect.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/introspect.json | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/qapi/introspect.json b/qapi/introspect.json
index 53100714a8..c8432c8ed8 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -22,10 +22,10 @@
 # `SchemaInfo`.  This lets QMP clients figure out what commands and
 # events are available in this QEMU, and their parameters and results.
 #
-# However, the `SchemaInfo` can't reflect all the rules and restrictions
-# that apply to QMP.  It's interface introspection (figuring out
-# what's there), not interface specification.  The specification is in
-# the QAPI schema.
+# However, the `SchemaInfo` can't reflect all the rules and
+# restrictions that apply to QMP.  It's interface introspection
+# (figuring out what's there), not interface specification.  The
+# specification is in the QAPI schema.
 #
 # Furthermore, while we strive to keep the QMP wire format
 # backwards-compatible across QEMU versions, the introspection output
-- 
2.48.1

[PATCH v2 11/33] qapi/job.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/job.json | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/qapi/job.json b/qapi/job.json
index 8b08350af2..887777b973 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -194,16 +194,16 @@
 #
 # This is supported only for drive mirroring, where it also switches
 # the device to write to the target path only.  Note that drive
-# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit`
-# job (only in case of "active commit", when the node being commited
-# is used by the guest).  The ability to complete is signaled with a
-# `BLOCK_JOB_READY` event.
+# mirroring includes `drive-mirror`, `blockdev-mirror` and
+# `block-commit` job (only in case of "active commit", when the node
+# being commited is used by the guest).  The ability to complete is
+# signaled with a `BLOCK_JOB_READY` event.
 #
 # This command completes an active background block operation
 # synchronously.  The ordering of this command's return with the
-# `BLOCK_JOB_COMPLETED` event is not defined.  Note that if an I/O error
-# occurs during the processing of this command: 1) the command itself
-# will fail; 2) the error will be processed according to the
+# `BLOCK_JOB_COMPLETED` event is not defined.  Note that if an I/O
+# error occurs during the processing of this command: 1) the command
+# itself will fail; 2) the error will be processed according to the
 # rerror/werror arguments that were specified when starting the
 # operation.
 #
@@ -220,14 +220,14 @@
 # needs to be run explicitly for jobs that don't have automatic
 # dismiss enabled.  In turn, automatic dismiss may be enabled only
 # for jobs that have @auto-dismiss option, which are `drive-backup`,
-# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
-# `block-stream`.  @auto-dismiss is enabled by default for these
+# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
+# and `block-stream`.  @auto-dismiss is enabled by default for these
 # jobs.
 #
 # This command will refuse to operate on any job that has not yet
 # reached its terminal state, CONCLUDED.  For jobs that make use of
-# the JOB_READY event, `job-cancel` or `job-complete` will still need to
-# be used as appropriate.
+# the JOB_READY event, `job-cancel` or `job-complete` will still need
+# to be used as appropriate.
 #
 # @id: The job identifier.
 #
@@ -247,8 +247,8 @@
 # force ALL jobs in the transaction to finalize, so it is only
 # necessary to instruct a single member job to finalize.
 #
-# The command is applicable only to jobs which have @auto-finalize option
-# and only when this option is set to false.
+# The command is applicable only to jobs which have @auto-finalize
+# option and only when this option is set to false.
 #
 # @id: The identifier of any job in the transaction, or of a job that
 #     is not part of any transaction.
-- 
2.48.1

[PATCH v2 12/33] qapi/machine-s390x.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/machine-s390x.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json
index 966dbd61d2..f8ddc0ff8a 100644
--- a/qapi/machine-s390x.json
+++ b/qapi/machine-s390x.json
@@ -85,7 +85,8 @@
 #
 #     <- { "event": "CPU_POLARIZATION_CHANGE",
 #          "data": { "polarization": "horizontal" },
-#          "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
+#          "timestamp": { "seconds": 1401385907,
+#                         "microseconds": 422329 } }
 ##
 { 'event': 'CPU_POLARIZATION_CHANGE',
   'data': { 'polarization': 'S390CpuPolarization' },
-- 
2.48.1

[PATCH v2 13/33] qapi/machine.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/machine.json | 59 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 38 insertions(+), 21 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index 038eab281c..4d36cd35c3 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -225,7 +225,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "query-machines", "arguments": { "compat-props": true } }
+#     -> { "execute": "query-machines", "arguments": { "compat-props":
+#     true } }
 #     <- { "return": [
 #               {
 #                  "hotpluggable-cpus": true,
@@ -318,7 +319,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-uuid" }
-#     <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
+#     <- { "return": { "UUID": "550e8400-e29b-41d4-a716-
+#     446655440000" } }
 ##
 { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
 
@@ -620,7 +622,8 @@
 ##
 # @NumaCpuOptions:
 #
-# Option "-numa cpu" overrides default cpu to node mapping.  It accepts
+# Option "-numa cpu" overrides default cpu to node mapping.  It
+#     accepts
 # the same set of cpu properties as returned by
 # `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where
 # node-id could be used to override default node mapping.
@@ -686,7 +689,8 @@
 # Set the system locality latency and bandwidth information between
 # Initiator and Target proximity Domains.
 #
-# For more information about `NumaHmatLBOptions`, see chapter 5.2.27.4:
+# For more information about `NumaHmatLBOptions`, see chapter
+#     5.2.27.4:
 # Table 5-146 of ACPI 6.3 spec.
 #
 # @initiator: the Initiator Proximity Domain.
@@ -743,7 +747,8 @@
 # Cache write policy in the Memory Side Cache Information Structure of
 # HMAT
 #
-# For more information of `HmatCacheWritePolicy`, see chapter 5.2.27.5:
+# For more information of `HmatCacheWritePolicy`, see chapter
+#     5.2.27.5:
 # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
 #
 # @none: None (no memory side cache in this proximity domain, or cache
@@ -763,8 +768,8 @@
 #
 # Set the memory side cache information for a given memory domain.
 #
-# For more information of `NumaHmatCacheOptions`, see chapter 5.2.27.5:
-# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
+# For more information of `NumaHmatCacheOptions`, see chapter
+# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
 #
 # @node-id: the memory proximity domain to which the memory belongs.
 #
@@ -1023,10 +1028,13 @@
 #
 #     -> { "execute": "query-hotpluggable-cpus" }
 #     <- {"return": [
-#          { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
+#          { "props": { "core-id": 8 },
+#            "type": "POWER8-spapr-cpu-core",
 #            "vcpus-count": 1 },
-#          { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
-#            "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
+#          { "props": { "core-id": 0 },
+#            "type": "POWER8-spapr-cpu-core",
+#            "vcpus-count": 1,
+#            "qom-path": "/machine/unattached/device[0]"}
 #        ]}
 #
 # .. qmp-example::
@@ -1110,7 +1118,8 @@
 #
 #    ::
 #
-#      -> { "execute": "balloon", "arguments": { "value": 536870912 } }
+#      -> { "execute": "balloon",
+#           "arguments": { "value": 536870912 } }
 #      <- { "return": {} }
 #
 #    With a 2.5GiB guest this command inflated the ballon to 3GiB.
@@ -1169,7 +1178,8 @@
 #
 #     <- { "event": "BALLOON_CHANGE",
 #          "data": { "actual": 944766976 },
-#          "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+#          "timestamp": { "seconds": 1267020223,
+#                         "microseconds": 435656 } }
 ##
 { 'event': 'BALLOON_CHANGE',
   'data': { 'actual': 'int' } }
@@ -1228,8 +1238,10 @@
 # .. qmp-example::
 #
 #     <- { "event": "HV_BALLOON_STATUS_REPORT",
-#          "data": { "committed": 816640000, "available": 3333054464 },
-#          "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
+#          "data": { "committed": 816640000,
+#                    "available": 3333054464 },
+#          "timestamp": { "seconds": 1600295492,
+#                         "microseconds": 661044 } }
 ##
 { 'event': 'HV_BALLOON_STATUS_REPORT',
   'data': 'HvBalloonInfo' }
@@ -1262,7 +1274,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-memory-size-summary" }
-#     <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
+#     <- { "return": { "base-memory": 4294967296,
+#                      "plugged-memory": 0 } }
 #
 # Since: 2.11
 ##
@@ -1577,7 +1590,8 @@
 #     <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
 #          "data": { "id": "vm0", "size": 1073741824,
 #                    "qom-path": "/machine/unattached/device[2]" },
-#          "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
+#          "timestamp": { "seconds": 1588168529,
+#                         "microseconds": 201316 } }
 ##
 { 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
   'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} }
@@ -2000,7 +2014,8 @@
 #   `query-cpu-definitions`.)
 # * "-cpu" arguments and global properties: arguments to the -cpu
 #   option and global properties may affect expansion of CPU models.
-#   Using `query-cpu-model-expansion` while using these is not advised.
+#   Using `query-cpu-model-expansion` while using these is not
+#   advised.
 #
 # Some architectures may not support comparing CPU models.  s390x
 # supports comparing CPU models.
@@ -2054,7 +2069,8 @@
 #   `query-cpu-definitions`.)
 # * "-cpu" arguments and global properties: arguments to the -cpu
 #   option and global properties may affect expansion of CPU models.
-#   Using `query-cpu-model-expansion` while using these is not advised.
+#   Using `query-cpu-model-expansion` while using these is not
+#   advised.
 #
 # Some architectures may not support baselining CPU models.  s390x
 # supports baselining CPU models.
@@ -2085,8 +2101,8 @@
 #
 # @model: the expanded `CpuModelInfo`.
 #
-# @deprecated-props: an optional list of properties that are flagged as
-#     deprecated by the CPU vendor.  The list depends on the
+# @deprecated-props: an optional list of properties that are flagged
+#     as deprecated by the CPU vendor.  The list depends on the
 #     `CpuModelExpansionType`: "static" properties are a subset of the
 #     enabled-properties for the expanded model; "full" properties are
 #     a set of properties that are deprecated across all models for
@@ -2122,7 +2138,8 @@
 #   `query-cpu-definitions`.)
 # * "-cpu" arguments and global properties: arguments to the -cpu
 #   option and global properties may affect expansion of CPU models.
-#   Using `query-cpu-model-expansion` while using these is not advised.
+#   Using `query-cpu-model-expansion` while using these is not
+#   advised.
 #
 # Some architectures may not support all expansion types.  s390x
 # supports "full" and "static".  Arm only supports "full".
-- 
2.48.1

[PATCH v2 14/33] qapi/migration.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/migration.json | 209 ++++++++++++++++++++++++++------------------
 1 file changed, 124 insertions(+), 85 deletions(-)

diff --git a/qapi/migration.json b/qapi/migration.json
index be0f3fcc12..74b9db1a51 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -160,11 +160,11 @@
 #
 # @pre-switchover: Paused before device serialisation.  (since 2.11)
 #
-# @device: During device serialisation (also known as switchover phase).
-#     Before 9.2, this is only used when (1) in precopy, and (2) when
-#     pre-switchover capability is enabled.  After 10.0, this state will
-#     always be present for every migration procedure as the switchover
-#     phase.  (since 2.11)
+# @device: During device serialisation (also known as switchover
+#     phase).  Before 9.2, this is only used when (1) in precopy, and
+#     (2) when pre-switchover capability is enabled.  After 10.0, this
+#     state will always be present for every migration procedure as
+#     the switchover phase.  (since 2.11)
 #
 # @wait-unplug: wait for device unplug request by guest OS to be
 #     completed.  (since 4.2)
@@ -238,30 +238,33 @@
 #     This is only present when the postcopy-blocktime migration
 #     capability is enabled.  (Since 3.0)
 #
-# @postcopy-latency: average remote page fault latency (in ns).  Note that
-#     this doesn't include all faults, but only the ones that require a
-#     remote page request.  So it should be always bigger than the real
-#     average page fault latency. This is only present when the
-#     postcopy-blocktime migration capability is enabled.  (Since 10.1)
-#
-# @postcopy-latency-dist: remote page fault latency distributions.  Each
-#     element of the array is the number of faults that fall into the
-#     bucket period.  For the N-th bucket (N>=0), the latency window is
-#     [2^Nus, 2^(N+1)us).  For example, the 8th element stores how many
-#     remote faults got resolved within [256us, 512us) window. This is only
-#     present when the postcopy-blocktime migration capability is enabled.
+# @postcopy-latency: average remote page fault latency (in ns).
+#     Note that this doesn't include all faults, but only the ones
+#     that require a remote page request.  So it should be always
+#     bigger than the real average page fault latency.  This is only
+#     present when the postcopy-blocktime migration capability is
+#     enabled.  (Since 10.1)
+#
+# @postcopy-latency-dist: remote page fault latency distributions.
+#     Each element of the array is the number of faults that fall into
+#     the bucket period.  For the N-th bucket (N>=0), the latency
+#     window is [2^Nus, 2^(N+1)us).  For example, the 8th element
+#     stores how many remote faults got resolved within [256us, 512us)
+#     window.  This is only present when the postcopy-blocktime
+#     migration capability is enabled. (Since 10.1)
+#
+# @postcopy-vcpu-latency: average remote page fault latency per vCPU
+#     (in ns).  It has the same definition of @postcopy-latency, but
+#     instead this is the per-vCPU statistics.  This is only present
+#     when the postcopy-blocktime migration capability is enabled.
 #     (Since 10.1)
 #
-# @postcopy-vcpu-latency: average remote page fault latency per vCPU (in
-#     ns).  It has the same definition of @postcopy-latency, but instead
-#     this is the per-vCPU statistics.  This is only present when the
-#     postcopy-blocktime migration capability is enabled.  (Since 10.1)
-#
-# @postcopy-non-vcpu-latency: average remote page fault latency for all
-#     faults happend in non-vCPU threads (in ns).  It has the same
-#     definition of @postcopy-latency but this only provides statistics to
-#     non-vCPU faults.  This is only present when the postcopy-blocktime
-#     migration capability is enabled.  (Since 10.1)
+# @postcopy-non-vcpu-latency: average remote page fault latency for
+#     all faults happend in non-vCPU threads (in ns).  It has the same
+#     definition of @postcopy-latency but this only provides
+#     statistics to non-vCPU faults.  This is only present when the
+#     postcopy-blocktime migration capability is enabled.
+#     (Since 10.1)
 #
 # @socket-address: Only used for tcp, to know what the real port is
 #     (Since 4.0)
@@ -290,7 +293,8 @@
 # Features:
 #
 # @unstable: Members @postcopy-latency, @postcopy-vcpu-latency,
-#     @postcopy-latency-dist, @postcopy-non-vcpu-latency are experimental.
+#     @postcopy-latency-dist, @postcopy-non-vcpu-latency are
+#     experimental.
 #
 # Since: 0.14
 ##
@@ -564,7 +568,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "migrate-set-capabilities" , "arguments":
-#          { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
+#          { "capabilities": [ { "capability": "xbzrle",
+#                                "state": true } ] } }
 #     <- { "return": {} }
 ##
 { 'command': 'migrate-set-capabilities',
@@ -627,8 +632,8 @@
 #
 # @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
+# @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
@@ -903,9 +908,10 @@
 #     more CPU.  Defaults to 1.  (Since 5.0)
 #
 # @multifd-qatzip-level: Set the compression level to be used in live
-#     migration.  The level is an integer between 1 and 9, where 1 means
-#     the best compression speed, and 9 means the best compression
-#     ratio which will consume more CPU.  Defaults to 1.  (Since 9.2)
+#     migration.  The level is an integer between 1 and 9, where 1
+#     means the best compression speed, and 9 means the best
+#     compression ratio which will consume more CPU.  Defaults to 1.
+#     (Since 9.2)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
 #     migration, the compression level is an integer between 0 and 20,
@@ -1089,9 +1095,10 @@
 #     more CPU.  Defaults to 1.  (Since 5.0)
 #
 # @multifd-qatzip-level: Set the compression level to be used in live
-#     migration.  The level is an integer between 1 and 9, where 1 means
-#     the best compression speed, and 9 means the best compression
-#     ratio which will consume more CPU.  Defaults to 1.  (Since 9.2)
+#     migration.  The level is an integer between 1 and 9, where 1
+#     means the best compression speed, and 9 means the best
+#     compression ratio which will consume more CPU.  Defaults to 1.
+#     (Since 9.2)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
 #     migration, the compression level is an integer between 0 and 20,
@@ -1304,9 +1311,10 @@
 #     more CPU.  Defaults to 1.  (Since 5.0)
 #
 # @multifd-qatzip-level: Set the compression level to be used in live
-#     migration.  The level is an integer between 1 and 9, where 1 means
-#     the best compression speed, and 9 means the best compression
-#     ratio which will consume more CPU.  Defaults to 1.  (Since 9.2)
+#     migration.  The level is an integer between 1 and 9, where 1
+#     means the best compression speed, and 9 means the best
+#     compression ratio which will consume more CPU.  Defaults to 1.
+#     (Since 9.2)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
 #     migration, the compression level is an integer between 0 and 20,
@@ -1442,7 +1450,8 @@
 #
 # .. qmp-example::
 #
-#     <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
+#     <- {"timestamp": {"seconds": 1432121972,
+#                       "microseconds": 744001},
 #         "event": "MIGRATION",
 #         "data": {"status": "completed"} }
 ##
@@ -1461,7 +1470,8 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
+#     <- { "timestamp": {"seconds": 1449669631,
+#                        "microseconds": 239225},
 #           "event": "MIGRATION_PASS", "data": {"pass": 2} }
 ##
 { 'event': 'MIGRATION_PASS',
@@ -1545,8 +1555,10 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
-#          "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
+#     <- { "timestamp": {"seconds": 2032141960,
+#                        "microseconds": 417172},
+#          "event": "COLO_EXIT",
+#          "data": { "mode": "primary", "reason": "request" } }
 ##
 { 'event': 'COLO_EXIT',
   'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
@@ -1758,7 +1770,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
+#     -> { "execute": "migrate",
+#          "arguments": { "uri": "tcp:0:4446" } }
 #     <- { "return": {} }
 #
 #     -> { "execute": "migrate",
@@ -1774,8 +1787,9 @@
 #          "arguments": {
 #              "channels": [ { "channel-type": "main",
 #                              "addr": { "transport": "exec",
-#                                        "args": [ "/bin/nc", "-p", "6000",
-#                                                  "/some/sock" ] } } ] } }
+#                                        "args": [
+#                                          "/bin/nc", "-p", "6000",
+#                                          "/some/sock" ] } } ] } }
 #     <- { "return": {} }
 #
 #     -> { "execute": "migrate",
@@ -1813,9 +1827,9 @@
 #     list connected to a destination interface endpoint.
 #
 # @exit-on-error: Exit on incoming migration failure.  Default true.
-#     When set to false, the failure triggers a :qapi:event:`MIGRATION`
-#     event, and error details could be retrieved with `query-migrate`.
-#     (since 9.1)
+#     When set to false, the failure triggers a
+#     :qapi:event:`MIGRATION` event, and error details could be
+#     retrieved with `query-migrate`. (since 9.1)
 #
 # Since: 2.3
 #
@@ -1855,8 +1869,9 @@
 #          "arguments": {
 #              "channels": [ { "channel-type": "main",
 #                              "addr": { "transport": "exec",
-#                                        "args": [ "/bin/nc", "-p", "6000",
-#                                                  "/some/sock" ] } } ] } }
+#                                        "args": [
+#                                          "/bin/nc", "-p", "6000",
+#                                          "/some/sock" ] } } ] } }
 #     <- { "return": {} }
 #
 #     -> { "execute": "migrate-incoming",
@@ -2037,7 +2052,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-colo-status" }
-#     <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } }
+#     <- { "return": { "mode": "primary", "last-mode": "none",
+#                      "reason": "request" } }
 #
 # Since: 3.1
 ##
@@ -2094,7 +2110,8 @@
 #
 #     <- { "event": "UNPLUG_PRIMARY",
 #          "data": { "device-id": "hostdev0" },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'UNPLUG_PRIMARY',
   'data': { 'device-id': 'str' } }
@@ -2252,8 +2269,8 @@
 #
 # .. qmp-example::
 #
-#     -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
-#                                                     "sample-pages": 512} }
+#     -> { "execute": "calc-dirty-rate",
+#          "arguments": {"calc-time": 1, "sample-pages": 512} }
 #     <- { "return": {} }
 #
 # .. qmp-example::
@@ -2261,8 +2278,10 @@
 #
 #    Measure dirty rate using dirty bitmap for 500 milliseconds::
 #
-#     -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500,
-#         "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} }
+#     -> { "execute": "calc-dirty-rate",
+#          "arguments": { "calc-time": 500,
+#                         "calc-time-unit": "millisecond",
+#                         "mode": "dirty-bitmap"} }
 #
 #     <- { "return": {} }
 ##
@@ -2284,16 +2303,17 @@
 # .. qmp-example::
 #    :title: Measurement is in progress
 #
-#     <- {"status": "measuring", "sample-pages": 512,
-#         "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10,
-#         "calc-time-unit": "second"}
+#     <- { "status": "measuring", "sample-pages": 512,
+#          "mode": "page-sampling", "start-time": 1693900454,
+#          "calc-time": 10, "calc-time-unit": "second" }
 #
 # .. qmp-example::
 #    :title: Measurement has been completed
 #
-#     <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108,
-#         "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10,
-#         "calc-time-unit": "second"}
+#     <- { "status": "measured", "sample-pages": 512,
+#          "dirty-rate": 108, "mode": "page-sampling",
+#          "start-time": 1693900454,
+#          "calc-time": 10, "calc-time-unit": "second" }
 ##
 { 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' },
                                  'returns': 'DirtyRateInfo' }
@@ -2452,23 +2472,30 @@
 #        }
 #     <- { "return": { } }
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1432121972, "microseconds": 744001},
+#         "timestamp": {"seconds": 1432121972,
+#                       "microseconds": 744001},
 #         "data": {"status": "created", "id": "snapsave0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1432122172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1432122172,
+#                       "microseconds": 744001},
 #         "data": {"status": "running", "id": "snapsave0"}}
 #     <- {"event": "STOP",
-#         "timestamp": {"seconds": 1432122372, "microseconds": 744001} }
+#         "timestamp": {"seconds": 1432122372,
+#                       "microseconds": 744001} }
 #     <- {"event": "RESUME",
-#         "timestamp": {"seconds": 1432122572, "microseconds": 744001} }
+#         "timestamp": {"seconds": 1432122572,
+#                       "microseconds": 744001} }
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1432122772, "microseconds": 744001},
+#         "timestamp": {"seconds": 1432122772,
+#                       "microseconds": 744001},
 #         "data": {"status": "waiting", "id": "snapsave0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1432122972, "microseconds": 744001},
+#         "timestamp": {"seconds": 1432122972,
+#                       "microseconds": 744001},
 #         "data": {"status": "pending", "id": "snapsave0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1432123172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1432123172,
+#                       "microseconds": 744001},
 #         "data": {"status": "concluded", "id": "snapsave0"}}
 #     -> {"execute": "query-jobs"}
 #     <- {"return": [{"current-progress": 1,
@@ -2507,8 +2534,8 @@
 # time it takes to load the snapshot.
 #
 # It is strongly recommended that @devices contain all writable block
-# device nodes that can have changed since the original `snapshot-save`
-# command execution.
+# device nodes that can have changed since the original
+# `snapshot-save` command execution.
 #
 # .. qmp-example::
 #
@@ -2522,23 +2549,30 @@
 #        }
 #     <- { "return": { } }
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1472124172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1472124172,
+#                       "microseconds": 744001},
 #         "data": {"status": "created", "id": "snapload0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1472125172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1472125172,
+#                       "microseconds": 744001},
 #         "data": {"status": "running", "id": "snapload0"}}
 #     <- {"event": "STOP",
-#         "timestamp": {"seconds": 1472125472, "microseconds": 744001} }
+#         "timestamp": {"seconds": 1472125472,
+#                       "microseconds": 744001} }
 #     <- {"event": "RESUME",
-#         "timestamp": {"seconds": 1472125872, "microseconds": 744001} }
+#         "timestamp": {"seconds": 1472125872,
+#                       "microseconds": 744001} }
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1472126172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1472126172,
+#                       "microseconds": 744001},
 #         "data": {"status": "waiting", "id": "snapload0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1472127172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1472127172,
+#                       "microseconds": 744001},
 #         "data": {"status": "pending", "id": "snapload0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1472128172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1472128172,
+#                       "microseconds": 744001},
 #         "data": {"status": "concluded", "id": "snapload0"}}
 #     -> {"execute": "query-jobs"}
 #     <- {"return": [{"current-progress": 1,
@@ -2582,19 +2616,24 @@
 #        }
 #     <- { "return": { } }
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1442124172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1442124172,
+#                       "microseconds": 744001},
 #         "data": {"status": "created", "id": "snapdelete0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1442125172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1442125172,
+#                       "microseconds": 744001},
 #         "data": {"status": "running", "id": "snapdelete0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1442126172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1442126172,
+#                       "microseconds": 744001},
 #         "data": {"status": "waiting", "id": "snapdelete0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1442127172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1442127172,
+#                       "microseconds": 744001},
 #         "data": {"status": "pending", "id": "snapdelete0"}}
 #     <- {"event": "JOB_STATUS_CHANGE",
-#         "timestamp": {"seconds": 1442128172, "microseconds": 744001},
+#         "timestamp": {"seconds": 1442128172,
+#                       "microseconds": 744001},
 #         "data": {"status": "concluded", "id": "snapdelete0"}}
 #     -> {"execute": "query-jobs"}
 #     <- {"return": [{"current-progress": 1,
-- 
2.48.1

[PATCH v2 15/33] qapi/misc-arm.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/misc-arm.json | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index f921d740f1..a7e0649b25 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -41,7 +41,9 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-gic-capabilities" }
-#     <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
-#                     { "version": 3, "emulated": false, "kernel": true } ] }
+#     <- { "return": [{ "version": 2, "emulated": true,
+#                       "kernel": false },
+#                     { "version": 3, "emulated": false,
+#                       "kernel": true } ] }
 ##
 { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] }
-- 
2.48.1

[PATCH v2 16/33] qapi/misc-i386.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/misc-i386.json | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index d1ce8caf25..3783202674 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -137,9 +137,9 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-sev" }
-#     <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
-#                      "build-id" : 0, "policy" : 0, "state" : "running",
-#                      "handle" : 1 } }
+#     <- { "return": { "enabled": true, "api-major" : 0,
+#                      "api-minor" : 0, "build-id" : 0, "policy" : 0,
+#                      "state" : "running", "handle" : 1 } }
 ##
 { 'command': 'query-sev', 'returns': 'SevInfo' }
 
@@ -220,7 +220,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-sev-capabilities" }
-#     <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
+#     <- { "return": { "pdh": "8CCDD8DDD",
+#                      "cert-chain": "888CCCDDDEE",
 #                      "cpu0-id": "2lvmGwo+...61iEinw==",
 #                      "cbitpos": 47, "reduced-phys-bits": 1}}
 ##
-- 
2.48.1

[PATCH v2 17/33] qapi/misc.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/misc.json | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/qapi/misc.json b/qapi/misc.json
index 28c641fe2f..456241bcfd 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -34,8 +34,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "add_client", "arguments": { "protocol": "vnc",
-#                                                  "fdname": "myclient" } }
+#     -> { "execute": "add_client",
+#          "arguments": { "protocol": "vnc", "fdname": "myclient" } }
 #     <- { "return": {} }
 ##
 { 'command': 'add_client',
@@ -288,7 +288,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "get-win32-socket",
-#          "arguments": { "info": "abcd123..", "fdname": "skclient" } }
+#          "arguments": { "info": "abcd123..",
+#                         "fdname": "skclient" } }
 #     <- { "return": {} }
 ##
 { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
@@ -374,7 +375,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
+#     -> { "execute": "remove-fd",
+#          "arguments": { "fdset-id": 1, "fd": 3 } }
 #     <- { "return": {} }
 ##
 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
@@ -564,7 +566,8 @@
 #
 #     <- { "event": "RTC_CHANGE",
 #          "data": { "offset": 78 },
-#          "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+#          "timestamp": { "seconds": 1267020223,
+#                         "microseconds": 435656 } }
 ##
 { 'event': 'RTC_CHANGE',
   'data': { 'offset': 'int', 'qom-path': 'str' } }
@@ -594,7 +597,8 @@
 #                    "vfu-qom-path": "/objects/vfu1",
 #                    "dev-id": "sas1",
 #                    "dev-qom-path": "/machine/peripheral/sas1" },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'VFU_CLIENT_HANGUP',
   'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str',
-- 
2.48.1

[PATCH v2 18/33] qapi/net.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/net.json | 61 ++++++++++++++++++++++++++++++++-------------------
 1 file changed, 38 insertions(+), 23 deletions(-)

diff --git a/qapi/net.json b/qapi/net.json
index 60d196afe5..834a9abb9d 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -51,8 +51,9 @@
 # .. qmp-example::
 #
 #     -> { "execute": "netdev_add",
-#          "arguments": { "type": "user", "id": "netdev1",
-#                         "dnssearch": [ { "str": "example.org" } ] } }
+#          "arguments": {
+#            "type": "user", "id": "netdev1",
+#            "dnssearch": [ { "str": "example.org" } ] } }
 #     <- { "return": {} }
 ##
 { 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true,
@@ -119,9 +120,11 @@
 #
 # Unprivileged user-mode network connectivity using passt
 #
-# @path: Filename of the passt program to run (by default 'passt', and use PATH)
+# @path: Filename of the passt program to run (by default 'passt',
+#     and use PATH)
 #
-# @quiet: don't print informational messages (default, passed as '--quiet')
+# @quiet: don't print informational messages
+#    (default, passed as '--quiet')
 #
 # @vhost-user: enable vhost-user
 #
@@ -281,8 +284,8 @@
 #
 # @smbserver: IP address of the built-in SMB server
 #
-# @hostfwd: redirect incoming TCP, UDP or UNIX host connections to guest
-#     endpoints
+# @hostfwd: redirect incoming TCP, UDP or UNIX host connections to
+#     guest endpoints
 #
 # @guestfwd: forward guest TCP connections
 #
@@ -569,7 +572,8 @@
 #     (default: 0).
 #
 # @inhibit: Don't load a default XDP program, use one already loaded
-#     to the interface (default: false).  Requires @sock-fds or @map-path.
+#     to the interface (default: false).  Requires @sock-fds or
+#     @map-path.
 #
 # @sock-fds: A colon (:) separated list of file descriptors for
 #     already open but not bound AF_XDP sockets in the queue order.
@@ -582,7 +586,8 @@
 #     mutually exclusive.  Requires @inhibit.  (Since 10.1)
 #
 # @map-start-index: Use @map-path to insert xsk sockets starting from
-#     this index number (default: 0).  Requires @map-path.  (Since 10.1)
+#     this index number (default: 0).  Requires @map-path.
+#     (Since 10.1)
 #
 # Since: 8.2
 ##
@@ -774,10 +779,10 @@
 #     attempt a reconnect after the given number of seconds.  Setting
 #     this to zero disables this function.  (default: 0) (since 8.0)
 #
-# @reconnect-ms: For a client socket, if a socket is disconnected, then
-#     attempt a reconnect after the given number of milliseconds.  Setting
-#     this to zero disables this function.  This member is mutually
-#     exclusive with @reconnect.  (default: 0) (Since: 9.2)
+# @reconnect-ms: For a client socket, if a socket is disconnected,
+#     then attempt a reconnect after the given number of milliseconds.
+#     Setting this to zero disables this function.  This member is
+#     mutually exclusive with @reconnect.  (default: 0) (Since: 9.2)
 #
 # Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported.
 #
@@ -985,7 +990,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
+#     -> { "execute": "query-rx-filter",
+#          "arguments": { "name": "vnet0" } }
 #     <- { "return": [
 #             {
 #                 "promiscuous": true,
@@ -1031,9 +1037,11 @@
 # .. qmp-example::
 #
 #     <- { "event": "NIC_RX_FILTER_CHANGED",
-#          "data": { "name": "vnet0",
-#                    "path": "/machine/peripheral/vnet0/virtio-backend" },
-#          "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
+#          "data": {
+#            "name": "vnet0",
+#            "path": "/machine/peripheral/vnet0/virtio-backend" },
+#          "timestamp": { "seconds": 1368697518,
+#                         "microseconds": 326866 } }
 ##
 { 'event': 'NIC_RX_FILTER_CHANGED',
   'data': { '*name': 'str', 'path': 'str' } }
@@ -1108,7 +1116,8 @@
 #
 #     <- { "event": "FAILOVER_NEGOTIATED",
 #          "data": { "device-id": "net1" },
-#          "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
+#          "timestamp": { "seconds": 1368697518,
+#                         "microseconds": 326866 } }
 ##
 { 'event': 'FAILOVER_NEGOTIATED',
   'data': {'device-id': 'str'} }
@@ -1130,14 +1139,17 @@
 #          "data": { "netdev-id": "netdev0",
 #                    "addr": { "port": "47666", "ipv6": true,
 #                              "host": "::1", "type": "inet" } },
-#          "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
+#          "timestamp": { "seconds": 1666269863,
+#                         "microseconds": 311222 } }
 #
 # .. qmp-example::
 #
 #     <- { "event": "NETDEV_STREAM_CONNECTED",
 #          "data": { "netdev-id": "netdev0",
-#                    "addr": { "path": "/tmp/qemu0", "type": "unix" } },
-#          "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
+#                    "addr": { "path": "/tmp/qemu0",
+#                              "type": "unix" } },
+#          "timestamp": { "seconds": 1666269706,
+#                         "microseconds": 413651 } }
 ##
 { 'event': 'NETDEV_STREAM_CONNECTED',
   'data': { 'netdev-id': 'str',
@@ -1156,7 +1168,8 @@
 #
 #     <- { "event": "NETDEV_STREAM_DISCONNECTED",
 #          "data": {"netdev-id": "netdev0"},
-#          "timestamp": {"seconds": 1663330937, "microseconds": 526695} }
+#          "timestamp": {"seconds": 1663330937,
+#                        "microseconds": 526695} }
 ##
 { 'event': 'NETDEV_STREAM_DISCONNECTED',
   'data': { 'netdev-id': 'str' } }
@@ -1174,7 +1187,8 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": {"seconds": 1739538638, "microseconds": 354181 },
+#     <- { "timestamp": {"seconds": 1739538638,
+#                        "microseconds": 354181 },
 #          "event": "NETDEV_VHOST_USER_CONNECTED",
 #          "data": { "netdev-id": "netdev0", "chardev-id": "chr0" } }
 #
@@ -1193,7 +1207,8 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": { "seconds": 1739538634, "microseconds": 920450 },
+#     <- { "timestamp": { "seconds": 1739538634,
+#                         "microseconds": 920450 },
 #          "event": "NETDEV_VHOST_USER_DISCONNECTED",
 #          "data": { "netdev-id": "netdev0" } }
 #
-- 
2.48.1

[PATCH v2 19/33] qapi/qdev.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/qdev.json | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/qapi/qdev.json b/qapi/qdev.json
index e14a0c9259..9c4b498319 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -100,8 +100,8 @@
 #    process is signaled with a `DEVICE_DELETED` event.  Guest reset
 #    will automatically complete removal for all devices.  If a
 #    guest-side error in the hot removal process is detected, the
-#    device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` event
-#    is sent.  Some errors cannot be detected.
+#    device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR`
+#    event is sent.  Some errors cannot be detected.
 #
 # Since: 0.14
 #
@@ -114,7 +114,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "device_del",
-#          "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
+#          "arguments": {
+#            "id": "/machine/peripheral-anon/device[0]" } }
 #     <- { "return": {} }
 ##
 { 'command': 'device_del', 'data': {'id': 'str'} }
@@ -138,7 +139,8 @@
 #     <- { "event": "DEVICE_DELETED",
 #          "data": { "device": "virtio-net-pci-0",
 #                    "path": "/machine/peripheral/virtio-net-pci-0" },
-#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#          "timestamp": { "seconds": 1265044230,
+#                         "microseconds": 450486 } }
 ##
 { 'event': 'DEVICE_DELETED',
   'data': { '*device': 'str', 'path': 'str' } }
@@ -160,7 +162,8 @@
 #     <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
 #          "data": { "device": "core1",
 #                    "path": "/machine/peripheral/core1" },
-#          "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
+#          "timestamp": { "seconds": 1615570772,
+#                         "microseconds": 202844 } }
 ##
 { 'event': 'DEVICE_UNPLUG_GUEST_ERROR',
   'data': { '*device': 'str', 'path': 'str' } }
-- 
2.48.1

[PATCH v2 20/33] qapi/qom.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/qom.json | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/qapi/qom.json b/qapi/qom.json
index 830cb2ffe7..99cdd0f60c 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -52,7 +52,8 @@
 #
 # @name: the name of the property.
 #
-# @type: the type of the property, as described in `ObjectPropertyInfo`.
+# @type: the type of the property, as described in
+#     `ObjectPropertyInfo`.
 #
 # @value: the value of the property.  Absent when the property cannot
 #     be read.
@@ -92,9 +93,12 @@
 #     -> { "execute": "qom-list",
 #          "arguments": { "path": "/chardevs" } }
 #     <- { "return": [ { "name": "type", "type": "string" },
-#                      { "name": "parallel0", "type": "child<chardev-vc>" },
-#                      { "name": "serial0", "type": "child<chardev-vc>" },
-#                      { "name": "mon0", "type": "child<chardev-stdio>" } ] }
+#                      { "name": "parallel0", "type":
+#     "child<chardev-vc>" },
+#                      { "name": "serial0", "type": "child<chardev-
+#     vc>" },
+#                      { "name": "mon0", "type": "child<chardev-
+#     stdio>" } ] }
 ##
 { 'command': 'qom-list',
   'data': { 'path': 'str' },
@@ -1082,7 +1086,8 @@
 #     Authentication Information Structure' for the SNP_LAUNCH_FINISH
 #     command defined in the SEV-SNP firmware ABI (default: all-zero)
 #
-# @author-key-enabled: true if 'id-auth' blob contains the 'AUTHOR_KEY'
+# @author-key-enabled: true if 'id-auth' blob contains the
+#     'AUTHOR_KEY'
 #     field defined SEV-SNP firmware ABI (default: false)
 #
 # @host-data: 32-byte, base64-encoded, user-defined blob to provide to
@@ -1117,17 +1122,17 @@
 # @attributes: The 'attributes' of a TD guest that is passed to
 #     KVM_TDX_INIT_VM
 #
-# @sept-ve-disable: toggle bit 28 of TD attributes to control disabling
-#     of EPT violation conversion to #VE on guest TD access of PENDING
-#     pages.  Some guest OS (e.g., Linux TD guest) may require this to
-#     be set, otherwise they refuse to boot.
+# @sept-ve-disable: toggle bit 28 of TD attributes to control
+#     disabling of EPT violation conversion to #VE on guest TD access
+#     of PENDING pages.  Some guest OS (e.g., Linux TD guest) may
+#     require this to be set, otherwise they refuse to boot.
 #
 # @mrconfigid: ID for non-owner-defined configuration of the guest TD,
-#     e.g., run-time or OS configuration (base64 encoded SHA384 digest).
-#     Defaults to all zeros.
+#     e.g., run-time or OS configuration (base64 encoded SHA384
+#     digest).  Defaults to all zeros.
 #
-# @mrowner: ID for the guest TD’s owner (base64 encoded SHA384 digest).
-#     Defaults to all zeros.
+# @mrowner: ID for the guest TD’s owner (base64 encoded SHA384
+#     digest).  Defaults to all zeros.
 #
 # @mrownerconfig: ID for owner-defined configuration of the guest TD,
 #     e.g., specific to the workload rather than the run-time or OS
-- 
2.48.1

[PATCH v2 21/33] qapi/replay.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/replay.json | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/qapi/replay.json b/qapi/replay.json
index ccf84da68e..0f1398e9b6 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -59,7 +59,8 @@
 # .. qmp-example::
 #
 #     -> { "execute": "query-replay" }
-#     <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
+#     <- { "return": { "mode": "play", "filename": "log.rr",
+#                      "icount": 220414 } }
 ##
 { 'command': 'query-replay',
   'returns': 'ReplayInfo' }
@@ -80,7 +81,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
+#     -> { "execute": "replay-break",
+#          "arguments": { "icount": 220414 } }
 #     <- { "return": {} }
 ##
 { 'command': 'replay-break', 'data': { 'icount': 'int' } }
@@ -116,7 +118,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
+#     -> { "execute": "replay-seek",
+#          "arguments": { "icount": 220414 } }
 #     <- { "return": {} }
 ##
 { 'command': 'replay-seek', 'data': { 'icount': 'int' } }
-- 
2.48.1

[PATCH v2 22/33] qapi/rocker.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/rocker.json | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/qapi/rocker.json b/qapi/rocker.json
index 5d2dbd2603..0b211d787e 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -102,11 +102,16 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
-#     <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
-#                       "autoneg": "off", "link-up": true, "speed": 10000},
-#                      {"duplex": "full", "enabled": true, "name": "sw1.2",
-#                       "autoneg": "off", "link-up": true, "speed": 10000}
+#     -> { "execute": "query-rocker-ports", "arguments": { "name":
+#     "sw1" } }
+#     <- { "return": [ {"duplex": "full", "enabled": true, "name":
+#     "sw1.1",
+#                       "autoneg": "off", "link-up": true, "speed":
+#     10000},
+#                      {"duplex": "full", "enabled": true, "name":
+#     "sw1.2",
+#                       "autoneg": "off", "link-up": true, "speed":
+#     10000}
 #        ]}
 ##
 { 'command': 'query-rocker-ports',
@@ -246,7 +251,8 @@
 #
 #     -> { "execute": "query-rocker-of-dpa-flows",
 #          "arguments": { "name": "sw1" } }
-#     <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
+#     <- { "return": [ {"key": { "in-pport": 0, "priority": 1,
+#                                "tbl-id": 0},
 #                       "hits": 138,
 #                       "cookie": 0,
 #                       "action": {"goto-tbl": 10},
-- 
2.48.1

[PATCH v2 23/33] qapi/run-state.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/run-state.json | 60 ++++++++++++++++++++++++++++-----------------
 1 file changed, 37 insertions(+), 23 deletions(-)

diff --git a/qapi/run-state.json b/qapi/run-state.json
index 4757947ca6..b72fbf2579 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -156,7 +156,8 @@
 #
 #     <- { "event": "SHUTDOWN",
 #          "data": { "guest": true, "reason": "guest-shutdown" },
-#          "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
+#          "timestamp": { "seconds": 1267040730,
+#                         "microseconds": 682951 } }
 ##
 { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
 
@@ -171,7 +172,8 @@
 # .. qmp-example::
 #
 #     <- { "event": "POWERDOWN",
-#          "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
+#          "timestamp": { "seconds": 1267040730,
+#                         "microseconds": 682951 } }
 ##
 { 'event': 'POWERDOWN' }
 
@@ -193,7 +195,8 @@
 #
 #     <- { "event": "RESET",
 #          "data": { "guest": false, "reason": "guest-reset" },
-#          "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
+#          "timestamp": { "seconds": 1267041653,
+#                         "microseconds": 9518 } }
 ##
 { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
 
@@ -207,7 +210,8 @@
 # .. qmp-example::
 #
 #     <- { "event": "STOP",
-#          "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
+#          "timestamp": { "seconds": 1267041730,
+#                         "microseconds": 281295 } }
 ##
 { 'event': 'STOP' }
 
@@ -221,7 +225,8 @@
 # .. qmp-example::
 #
 #     <- { "event": "RESUME",
-#          "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
+#          "timestamp": { "seconds": 1271770767,
+#                         "microseconds": 582542 } }
 ##
 { 'event': 'RESUME' }
 
@@ -236,7 +241,8 @@
 # .. qmp-example::
 #
 #     <- { "event": "SUSPEND",
-#          "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
+#          "timestamp": { "seconds": 1344456160,
+#                         "microseconds": 309119 } }
 ##
 { 'event': 'SUSPEND' }
 
@@ -247,15 +253,16 @@
 # saved on disk, for example, S4 state, which is sometimes called
 # hibernate state
 #
-# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when entering
-#    this state.
+# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when
+#    entering this state.
 #
 # Since: 1.2
 #
 # .. qmp-example::
 #
 #     <- { "event": "SUSPEND_DISK",
-#          "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
+#          "timestamp": { "seconds": 1344456160,
+#                         "microseconds": 309119 } }
 ##
 { 'event': 'SUSPEND_DISK' }
 
@@ -270,7 +277,8 @@
 # .. qmp-example::
 #
 #     <- { "event": "WAKEUP",
-#          "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+#          "timestamp": { "seconds": 1344522075,
+#                         "microseconds": 745528 } }
 ##
 { 'event': 'WAKEUP' }
 
@@ -281,9 +289,9 @@
 #
 # @action: action that has been taken
 #
-# .. note:: If action is "reset", "shutdown", or "pause" the `WATCHDOG`
-#    event is followed respectively by the `RESET`, `SHUTDOWN`, or `STOP`
-#    events.
+# .. note:: If action is "reset", "shutdown", or "pause" the
+#   `WATCHDOG` event is followed respectively by the `RESET`,
+#   `SHUTDOWN`, or `STOP` events.
 #
 # .. note:: This event is rate-limited.
 #
@@ -293,7 +301,8 @@
 #
 #     <- { "event": "WATCHDOG",
 #          "data": { "action": "reset" },
-#          "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#          "timestamp": { "seconds": 1267061043,
+#                         "microseconds": 959568 } }
 ##
 { 'event': 'WATCHDOG',
   'data': { 'action': 'WatchdogAction' } }
@@ -402,7 +411,8 @@
 #
 # @panic: `PanicAction` action taken on guest panic.
 #
-# @watchdog: `WatchdogAction` action taken when watchdog timer expires.
+# @watchdog: `WatchdogAction` action taken when watchdog timer
+#     expires.
 #
 # Since: 6.0
 #
@@ -437,7 +447,8 @@
 #
 #     <- { "event": "GUEST_PANICKED",
 #          "data": { "action": "pause" },
-#          "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
+#          "timestamp": { "seconds": 1648245231,
+#                         "microseconds": 900001 } }
 ##
 { 'event': 'GUEST_PANICKED',
   'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@@ -457,7 +468,8 @@
 #
 #     <- { "event": "GUEST_CRASHLOADED",
 #          "data": { "action": "run" },
-#          "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
+#          "timestamp": { "seconds": 1648245259,
+#                         "microseconds": 893771 } }
 ##
 { 'event': 'GUEST_CRASHLOADED',
   'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@@ -472,7 +484,8 @@
 # .. qmp-example::
 #
 #     <- { "event": "GUEST_PVSHUTDOWN",
-#          "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
+#          "timestamp": { "seconds": 1648245259,
+#                         "microseconds": 893771 } }
 ##
 { 'event': 'GUEST_PVSHUTDOWN' }
 
@@ -542,8 +555,8 @@
 # @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.
+# @arg5: for Windows, fourth argument of the `STOP`.  For x86 Linux,
+#     the stack pointer of the guest.
 #
 # Since: 2.9
 ##
@@ -610,7 +623,7 @@
 #
 # @error-code: TD-specific error code
 #
-# @message: Human-readable error message provided by the guest. Not
+# @message: Human-readable error message provided by the guest.  Not
 #     to be trusted.
 #
 # @gpa: guest-physical address of a page that contains more verbose
@@ -644,8 +657,9 @@
 #          "data": { "recipient": "hypervisor",
 #                    "action": "fatal",
 #                    "flags": { "action-required": false,
-#                               "recursive": false } },
-#          "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#                               "recursive": false } }
+#          "timestamp": { "seconds": 1267061043,
+#                         "microseconds": 959568 } }
 ##
 { 'event': 'MEMORY_FAILURE',
   'data': { 'recipient': 'MemoryFailureRecipient',
-- 
2.48.1

[PATCH v2 24/33] qapi/sockets.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/sockets.json | 34 ++++++++++++++++++----------------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/qapi/sockets.json b/qapi/sockets.json
index 32fac51728..473be2ac58 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -58,24 +58,26 @@
 # @ipv6: whether to accept IPv6 addresses, default try both IPv4 and
 #     IPv6
 #
-# @keep-alive: enable keep-alive when connecting to/listening on this socket.
+# @keep-alive: enable keep-alive when connecting to/listening on this
+#     socket.
 #     (Since 4.2, not supported for listening sockets until 10.1)
 #
-# @keep-alive-count: number of keep-alive packets sent before the connection is
-#     closed.  Only supported for TCP sockets on systems where TCP_KEEPCNT
-#     socket option is defined (this includes Linux, Windows, macOS, FreeBSD,
-#     but not OpenBSD).  When set to 0, system setting is used.  (Since 10.1)
-#
-# @keep-alive-idle: time in seconds the connection needs to be idle before
-#     sending a keepalive packet.  Only supported for TCP sockets on systems
-#     where TCP_KEEPIDLE socket option is defined (this includes Linux,
-#     Windows, macOS, FreeBSD, but not OpenBSD).  When set to 0, system setting
-#     is used.  (Since 10.1)
-#
-# @keep-alive-interval: time in seconds between keep-alive packets.  Only
-#     supported for TCP sockets on systems where TCP_KEEPINTVL is defined (this
-#     includes Linux, Windows, macOS, FreeBSD, but not OpenBSD).  When set to
-#     0, system setting is used.  (Since 10.1)
+# @keep-alive-count: number of keep-alive packets sent before the
+#     connection is closed.  Only supported for TCP sockets on systems
+#     where TCP_KEEPCNT socket option is defined (this includes Linux,
+#     Windows, macOS, FreeBSD, but not OpenBSD).  When set to 0,
+#     system setting is used.  (Since 10.1)
+#
+# @keep-alive-idle: time in seconds the connection needs to be idle
+#     before sending a keepalive packet.  Only supported for TCP
+#     sockets on systems where TCP_KEEPIDLE socket option is defined
+#     (this includes Linux, Windows, macOS, FreeBSD, but not OpenBSD).
+#     When set to 0, system setting is used.  (Since 10.1)
+#
+# @keep-alive-interval: time in seconds between keep-alive packets.
+#     Only supported for TCP sockets on systems where TCP_KEEPINTVL is
+#     defined (this includes Linux, Windows, macOS, FreeBSD, but not
+#     OpenBSD).  When set to 0, system setting is used.  (Since 10.1)
 #
 # @mptcp: enable multi-path TCP.  (Since 6.1)
 #
-- 
2.48.1

[PATCH v2 25/33] qapi/stats.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/stats.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/stats.json b/qapi/stats.json
index 151ac43c48..b7c61af0ca 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -185,7 +185,8 @@
 # Return runtime-collected statistics for objects such as the VM or
 # its vCPUs.
 #
-# The arguments are a `StatsFilter` and specify the provider and objects
+# The arguments are a `StatsFilter` and specify the provider and
+#     objects
 # to return statistics about.
 #
 # Returns: a list of statistics, one for each provider and object
-- 
2.48.1

[PATCH v2 26/33] qapi/tpm.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/tpm.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/tpm.json b/qapi/tpm.json
index 3f2850a573..efa7addd78 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -175,7 +175,8 @@
 #              "options":
 #                { "type": "passthrough",
 #                  "data":
-#                    { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
+#                    { "cancel-path":
+#                        "/sys/class/misc/tpm0/device/cancel",
 #                      "path": "/dev/tpm0"
 #                    }
 #                },
-- 
2.48.1

[PATCH v2 27/33] qapi/trace.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/trace.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/trace.json b/qapi/trace.json
index de369dae6b..6162a9aa71 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -57,7 +57,8 @@
 #
 #     -> { "execute": "trace-event-get-state",
 #          "arguments": { "name": "qemu_memalign" } }
-#     <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
+#     <- { "return": [ { "name": "qemu_memalign", "state": "disabled",
+#                        "vcpu": false } ] }
 ##
 { 'command': 'trace-event-get-state',
   'data': {'name': 'str' },
-- 
2.48.1

[PATCH v2 28/33] qapi/transaction.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/transaction.json | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/qapi/transaction.json b/qapi/transaction.json
index 4b4eb09bf3..f43da7f30d 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -250,21 +250,24 @@
 #
 #     -> { "execute": "transaction",
 #          "arguments": { "actions": [
-#              { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
-#                                          "snapshot-file": "/some/place/my-image",
-#                                          "format": "qcow2" } },
-#              { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
-#                                          "snapshot-file": "/some/place/my-image2",
-#                                          "snapshot-node-name": "node3432",
-#                                          "mode": "existing",
-#                                          "format": "qcow2" } },
-#              { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
-#                                          "snapshot-file": "/some/place/my-image2",
-#                                          "mode": "existing",
-#                                          "format": "qcow2" } },
-#              { "type": "blockdev-snapshot-internal-sync", "data" : {
-#                                          "device": "ide-hd2",
-#                                          "name": "snapshot0" } } ] } }
+#              { "type": "blockdev-snapshot-sync",
+#                "data" : { "device": "ide-hd0",
+#                            "snapshot-file": "/some/place/my-image",
+#                            "format": "qcow2" } },
+#              { "type": "blockdev-snapshot-sync",
+#                "data" : { "node-name": "myfile",
+#                           "snapshot-file": "/some/place/my-image2",
+#                           "snapshot-node-name": "node3432",
+#                           "mode": "existing",
+#                           "format": "qcow2" } },
+#              { "type": "blockdev-snapshot-sync",
+#                "data" : { "device": "ide-hd1",
+#                           "snapshot-file": "/some/place/my-image2",
+#                           "mode": "existing",
+#                           "format": "qcow2" } },
+#              { "type": "blockdev-snapshot-internal-sync",
+#                "data" : { "device": "ide-hd2",
+#                           "name": "snapshot0" } } ] } }
 #     <- { "return": {} }
 ##
 { 'command': 'transaction',
-- 
2.48.1

[PATCH v2 29/33] qapi/ui.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/ui.json | 108 ++++++++++++++++++++++++++++++++-------------------
 1 file changed, 67 insertions(+), 41 deletions(-)

diff --git a/qapi/ui.json b/qapi/ui.json
index 1b2f4a4769..ab64c6372a 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -87,8 +87,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "set_password", "arguments": { "protocol": "vnc",
-#                                                    "password": "secret" } }
+#     -> { "execute": "set_password",
+#          "arguments": { "protocol": "vnc", "password": "secret" } }
 #     <- { "return": {} }
 ##
 { 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' }
@@ -149,8 +149,8 @@
 #
 # .. qmp-example::
 #
-#     -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
-#                                                       "time": "+60" } }
+#     -> { "execute": "expire_password",
+#          "arguments": { "protocol": "vnc", "time": "+60" } }
 #     <- { "return": {} }
 ##
 { 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' }
@@ -381,11 +381,14 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
+#     <- { "timestamp": { "seconds": 1290688046,
+#                         "microseconds": 388707},
 #          "event": "SPICE_CONNECTED",
 #          "data": {
-#            "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
-#            "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
+#            "server": { "port": "5920", "family": "ipv4",
+#                        "host": "127.0.0.1" },
+#            "client": { "port": "52873", "family": "ipv4",
+#                        "host": "127.0.0.1" }
 #        }}
 ##
 { 'event': 'SPICE_CONNECTED',
@@ -407,13 +410,16 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
+#     <- { "timestamp": {"seconds": 1290688046,
+#                        "microseconds": 417172},
 #          "event": "SPICE_INITIALIZED",
 #          "data": {"server": {"auth": "spice", "port": "5921",
 #                              "family": "ipv4", "host": "127.0.0.1"},
-#                   "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
-#                              "connection-id": 1804289383, "host": "127.0.0.1",
-#                              "channel-id": 0, "tls": true}
+#                   "client": { "port": "49004", "family": "ipv4",
+#                               "channel-type": 3,
+#                               "connection-id": 1804289383,
+#                               "host": "127.0.0.1",
+#                               "channel-id": 0, "tls": true}
 #        }}
 ##
 { 'event': 'SPICE_INITIALIZED',
@@ -434,11 +440,14 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
+#     <- { "timestamp": {"seconds": 1290688046,
+#                        "microseconds": 388707},
 #          "event": "SPICE_DISCONNECTED",
 #          "data": {
-#            "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
-#            "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
+#            "server": { "port": "5920", "family": "ipv4",
+#                        "host": "127.0.0.1"},
+#            "client": { "port": "52873", "family": "ipv4",
+#                        "host": "127.0.0.1"}
 #        }}
 ##
 { 'event': 'SPICE_DISCONNECTED',
@@ -455,7 +464,8 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
+#     <- { "timestamp": {"seconds": 1290688046,
+#                        "microseconds": 417172},
 #          "event": "SPICE_MIGRATE_COMPLETED" }
 ##
 { 'event': 'SPICE_MIGRATE_COMPLETED',
@@ -727,11 +737,14 @@
 #
 #     <- { "event": "VNC_CONNECTED",
 #          "data": {
-#                "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
+#                "server": { "auth": "sasl", "family": "ipv4",
+#                            "websocket": false,
 #                            "service": "5901", "host": "0.0.0.0" },
 #                "client": { "family": "ipv4", "service": "58425",
-#                            "host": "127.0.0.1", "websocket": false } },
-#          "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
+#                            "host": "127.0.0.1",
+#                            "websocket": false } },
+#          "timestamp": { "seconds": 1262976601,
+#                         "microseconds": 975795 } }
 ##
 { 'event': 'VNC_CONNECTED',
   'data': { 'server': 'VncServerInfo',
@@ -754,11 +767,15 @@
 #
 #     <-  { "event": "VNC_INITIALIZED",
 #           "data": {
-#                "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
+#                "server": { "auth": "sasl", "family": "ipv4",
+#                            "websocket": false,
 #                            "service": "5901", "host": "0.0.0.0"},
-#                "client": { "family": "ipv4", "service": "46089", "websocket": false,
-#                            "host": "127.0.0.1", "sasl_username": "luiz" } },
-#           "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
+#                "client": { "family": "ipv4", "service": "46089",
+#                            "websocket": false,
+#                            "host": "127.0.0.1",
+#                            "sasl_username": "luiz" } },
+#           "timestamp": { "seconds": 1263475302,
+#                          "microseconds": 150772 } }
 ##
 { 'event': 'VNC_INITIALIZED',
   'data': { 'server': 'VncServerInfo',
@@ -780,11 +797,14 @@
 #
 #     <- { "event": "VNC_DISCONNECTED",
 #          "data": {
-#                "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
-#                            "service": "5901", "host": "0.0.0.0" },
-#                "client": { "family": "ipv4", "service": "58425", "websocket": false,
-#                            "host": "127.0.0.1", "sasl_username": "luiz" } },
-#          "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
+#                "server": { "auth": "sasl", "family": "ipv4",
+#                            "websocket": false, "service": "5901",
+#                            "host": "0.0.0.0" },
+#                "client": { "family": "ipv4", "service": "58425",
+#                            "websocket": false, "host": "127.0.0.1",
+#                            "sasl_username": "luiz" } },
+#          "timestamp": { "seconds": 1262976601,
+#                         "microseconds": 975795 } }
 ##
 { 'event': 'VNC_DISCONNECTED',
   'data': { 'server': 'VncServerInfo',
@@ -1023,10 +1043,10 @@
 #
 # Send keys to guest.
 #
-# @keys: An array of `KeyValue` elements.  All @KeyValues in this array
-#     are simultaneously sent to the guest.  A `KeyValue`.number value
-#     is sent directly to the guest, while `KeyValue`.qcode must be a
-#     valid `QKeyCode` value
+# @keys: An array of `KeyValue` elements.  All @KeyValues in this
+#     array are simultaneously sent to the guest.  A `KeyValue`.number
+#     value is sent directly to the guest, while `KeyValue`.qcode must
+#     be a valid `QKeyCode` value
 #
 # @hold-time: time to delay key up events, milliseconds.  Defaults to
 #     100
@@ -1039,9 +1059,10 @@
 # .. qmp-example::
 #
 #     -> { "execute": "send-key",
-#          "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
-#                                   { "type": "qcode", "data": "alt" },
-#                                   { "type": "qcode", "data": "delete" } ] } }
+#          "arguments": { "keys": [
+#            { "type": "qcode", "data": "ctrl" },
+#            { "type": "qcode", "data": "alt" },
+#            { "type": "qcode", "data": "delete" } ] } }
 #     <- { "return": {} }
 ##
 { 'command': 'send-key',
@@ -1278,13 +1299,15 @@
 #     -> { "execute": "input-send-event",
 #         "arguments": { "device": "video0",
 #                        "events": [ { "type": "btn",
-#                        "data" : { "down": true, "button": "left" } } ] } }
+#                        "data" : { "down": true,
+#                                   "button": "left" } } ] } }
 #     <- { "return": {} }
 #
 #     -> { "execute": "input-send-event",
 #         "arguments": { "device": "video0",
 #                        "events": [ { "type": "btn",
-#                        "data" : { "down": false, "button": "left" } } ] } }
+#                        "data" : { "down": false,
+#                                   "button": "left" } } ] } }
 #     <- { "return": {} }
 #
 # .. qmp-example::
@@ -1305,8 +1328,10 @@
 #
 #     -> { "execute": "input-send-event" ,
 #       "arguments": { "events": [
-#                    { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
-#                    { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
+#                    { "type": "abs",
+#                      "data" : { "axis": "x", "value" : 20000 } },
+#                    { "type": "abs",
+#                      "data" : { "axis": "y", "value" : 400 } } ] } }
 #     <- { "return": {} }
 ##
 { 'command': 'input-send-event',
@@ -1335,10 +1360,11 @@
 # @show-menubar: Display the main window menubar.  Defaults to "on".
 #     (Since 8.0)
 #
-# @keep-aspect-ratio: Keep width/height aspect ratio of guest content when
-#     resizing host window.  Defaults to "on". (Since 10.1)
+# @keep-aspect-ratio: Keep width/height aspect ratio of guest content
+#     when resizing host window.  Defaults to "on". (Since 10.1)
 #
-# @scale: Set preferred scale of the display.  Defaults to 1.0.  (Since 10.1)
+# @scale: Set preferred scale of the display.  Defaults to 1.0.
+#     (Since 10.1)
 #
 # Since: 2.12
 ##
-- 
2.48.1

[PATCH v2 30/33] qapi/vfio.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/vfio.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/vfio.json b/qapi/vfio.json
index a1a9c5b673..a4c4f9f91c 100644
--- a/qapi/vfio.json
+++ b/qapi/vfio.json
@@ -53,7 +53,8 @@
 #
 # .. qmp-example::
 #
-#     <- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 },
+#     <- { "timestamp": { "seconds": 1713771323,
+#                         "microseconds": 212268 },
 #          "event": "VFIO_MIGRATION",
 #          "data": {
 #              "device-id": "vfio_dev1",
-- 
2.48.1

[PATCH v2 31/33] qapi/virtio.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

For x-query-virtio-status just drop the examples. No idea how
to bring them into 70 columns width. And the command is unstable
anyway.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/virtio.json | 269 ++++-------------------------------------------
 1 file changed, 20 insertions(+), 249 deletions(-)

diff --git a/qapi/virtio.json b/qapi/virtio.json
index 05295ab665..5e5250944c 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -42,23 +42,23 @@
 #     <- { "return": [
 #              {
 #                  "name": "virtio-input",
-#                  "path": "/machine/peripheral-anon/device[4]/virtio-backend"
+#                  "path": "/machine/peripheral-anon/device[4]/vir..."
 #              },
 #              {
 #                  "name": "virtio-crypto",
-#                  "path": "/machine/peripheral/crypto0/virtio-backend"
+#                  "path": "/machine/peripheral/crypto0/virtio-bac..."
 #              },
 #              {
 #                  "name": "virtio-scsi",
-#                  "path": "/machine/peripheral-anon/device[2]/virtio-backend"
+#                  "path": "/machine/peripheral-anon/device[2]/vir..."
 #              },
 #              {
 #                  "name": "virtio-net",
-#                  "path": "/machine/peripheral-anon/device[1]/virtio-backend"
+#                  "path": "/machine/peripheral-anon/device[1]/vir..."
 #              },
 #              {
 #                  "name": "virtio-serial",
-#                  "path": "/machine/peripheral-anon/device[0]/virtio-backend"
+#                  "path": "/machine/peripheral-anon/device[0]/vir..."
 #              }
 #          ]
 #        }
@@ -204,239 +204,6 @@
 # Returns: Status of the virtio device
 #
 # Since: 7.2
-#
-# .. qmp-example::
-#    :annotated:
-#
-#    Poll for the status of virtio-crypto (no vhost-crypto active)
-#    ::
-#
-#     -> { "execute": "x-query-virtio-status",
-#          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
-#        }
-#     <- { "return": {
-#              "device-endian": "little",
-#              "bus-name": "",
-#              "disable-legacy-check": false,
-#              "name": "virtio-crypto",
-#              "started": true,
-#              "device-id": 20,
-#              "backend-features": {
-#                  "transports": [],
-#                  "dev-features": []
-#              },
-#              "start-on-kick": false,
-#              "isr": 1,
-#              "broken": false,
-#              "status": {
-#                  "statuses": [
-#                      "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
-#                      "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
-#                      "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
-#                      "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
-#                  ]
-#              },
-#              "num-vqs": 2,
-#              "guest-features": {
-#                  "dev-features": [],
-#                  "transports": [
-#                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
-#                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
-#                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
-#                  ]
-#              },
-#              "host-features": {
-#                  "unknown-dev-features": 1073741824,
-#                  "unknown-dev-features2": 0,
-#                  "dev-features": [],
-#                  "transports": [
-#                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
-#                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
-#                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
-#                      "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
-#                      "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
-#                  ]
-#              },
-#              "use-guest-notifier-mask": true,
-#              "vm-running": true,
-#              "queue-sel": 1,
-#              "disabled": false,
-#              "vhost-started": false,
-#              "use-started": true
-#          }
-#        }
-#
-# .. qmp-example::
-#    :annotated:
-#
-#    Poll for the status of virtio-net (vhost-net is active)
-#    ::
-#
-#     -> { "execute": "x-query-virtio-status",
-#          "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
-#        }
-#     <- { "return": {
-#              "device-endian": "little",
-#              "bus-name": "",
-#              "disabled-legacy-check": false,
-#              "name": "virtio-net",
-#              "started": true,
-#              "device-id": 1,
-#              "vhost-dev": {
-#                  "n-tmp-sections": 4,
-#                  "n-mem-sections": 4,
-#                  "max-queues": 1,
-#                  "backend-cap": 2,
-#                  "log-size": 0,
-#                  "backend-features": {
-#                      "dev-features": [],
-#                      "transports": []
-#                  },
-#                  "nvqs": 2,
-#                  "protocol-features": {
-#                      "protocols": []
-#                  },
-#                  "vq-index": 0,
-#                  "log-enabled": false,
-#                  "acked-features": {
-#                      "dev-features": [
-#                          "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
-#                      ],
-#                      "transports": [
-#                          "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
-#                          "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
-#                          "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
-#                      ]
-#                  },
-#                  "features": {
-#                      "dev-features": [
-#                          "VHOST_F_LOG_ALL: Logging write descriptors supported",
-#                          "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
-#                      ],
-#                      "transports": [
-#                          "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
-#                          "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
-#                          "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
-#                          "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
-#                          "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
-#                          "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
-#                      ]
-#                  }
-#              },
-#              "backend-features": {
-#                  "dev-features": [
-#                      "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
-#                      "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
-#                      "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
-#                      "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
-#                      "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
-#                      "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
-#                      "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
-#                      "VIRTIO_NET_F_CTRL_VQ: Control channel available",
-#                      "VIRTIO_NET_F_STATUS: Configuration status field available",
-#                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
-#                      "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
-#                      "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
-#                      "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
-#                      "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
-#                      "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
-#                      "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
-#                      "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
-#                      "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
-#                      "VIRTIO_NET_F_MAC: Device has given MAC address",
-#                      "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
-#                      "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
-#                      "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
-#                  ],
-#                  "transports": [
-#                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
-#                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
-#                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
-#                      "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
-#                      "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
-#                  ]
-#              },
-#              "start-on-kick": false,
-#              "isr": 1,
-#              "broken": false,
-#              "status": {
-#                  "statuses": [
-#                      "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
-#                      "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
-#                      "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
-#                      "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
-#                  ]
-#              },
-#              "num-vqs": 3,
-#              "guest-features": {
-#                  "dev-features": [
-#                      "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
-#                      "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
-#                      "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
-#                      "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
-#                      "VIRTIO_NET_F_CTRL_VQ: Control channel available",
-#                      "VIRTIO_NET_F_STATUS: Configuration status field available",
-#                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
-#                      "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
-#                      "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
-#                      "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
-#                      "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
-#                      "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
-#                      "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
-#                      "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
-#                      "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
-#                      "VIRTIO_NET_F_MAC: Device has given MAC address",
-#                      "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
-#                      "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
-#                      "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
-#                  ],
-#                  "transports": [
-#                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
-#                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
-#                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
-#                 ]
-#              },
-#              "host-features": {
-#                  "dev-features": [
-#                      "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
-#                      "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
-#                      "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
-#                      "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
-#                      "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
-#                      "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
-#                      "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
-#                      "VIRTIO_NET_F_CTRL_VQ: Control channel available",
-#                      "VIRTIO_NET_F_STATUS: Configuration status field available",
-#                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
-#                      "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
-#                      "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
-#                      "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
-#                      "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
-#                      "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
-#                      "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
-#                      "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
-#                      "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
-#                      "VIRTIO_NET_F_MAC: Device has given MAC address",
-#                      "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
-#                      "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
-#                      "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
-#                  ],
-#                  "transports": [
-#                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
-#                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
-#                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
-#                      "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
-#                      "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
-#                 ]
-#              },
-#              "use-guest-notifier-mask": true,
-#              "vm-running": true,
-#              "queue-sel": 2,
-#              "disabled": false,
-#              "vhost-started": true,
-#              "use-started": true
-#          }
-#        }
 ##
 { 'command': 'x-query-virtio-status',
   'data': { 'path': 'str' },
@@ -588,8 +355,9 @@
 #    ::
 #
 #     -> { "execute": "x-query-virtio-queue-status",
-#          "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
-#                         "queue": 1 }
+#          "arguments": {
+#            "path": "/machine/peripheral/vsock0/virtio-backend",
+#            "queue": 1 }
 #        }
 #     <- { "return": {
 #              "signalled-used": 0,
@@ -615,8 +383,9 @@
 #    ::
 #
 #     -> { "execute": "x-query-virtio-queue-status",
-#          "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
-#                         "queue": 20 }
+#          "arguments": {
+#            "path": "/machine/peripheral-anon/device[0]/virtio-b...",
+#            "queue": 20 }
 #        }
 #     <- { "return": {
 #              "signalled-used": 0,
@@ -713,8 +482,9 @@
 #    :title: Get vhost_virtqueue status for vhost-crypto
 #
 #     -> { "execute": "x-query-virtio-vhost-queue-status",
-#          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
-#                         "queue": 0 }
+#          "arguments": {
+#            "path": "/machine/peripheral/crypto0/virtio-backend",
+#            "queue": 0 }
 #        }
 #     <- { "return": {
 #              "avail-phys": 5216124928,
@@ -737,8 +507,9 @@
 #    :title: Get vhost_virtqueue status for vhost-vsock
 #
 #     -> { "execute": "x-query-virtio-vhost-queue-status",
-#          "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
-#                         "queue": 0 }
+#          "arguments": {
+#            "path": "/machine/peripheral/vsock0/virtio-backend",
+#            "queue": 0 }
 #        }
 #     <- { "return": {
 #              "avail-phys": 5182261248,
@@ -860,7 +631,7 @@
 #    :title: Introspect on virtio-net's VirtQueue 0 at index 5
 #
 #     -> { "execute": "x-query-virtio-queue-element",
-#          "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
+#          "arguments": { "path": "/machine/peripheral-anon/...",
 #                         "queue": 0,
 #                         "index": 5 }
 #        }
@@ -890,7 +661,7 @@
 #    :title: Introspect on virtio-crypto's VirtQueue 1 at head
 #
 #     -> { "execute": "x-query-virtio-queue-element",
-#          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
+#          "arguments": { "path": "/machine/peripheral/crypto0/...",
 #                         "queue": 1 }
 #        }
 #     <- { "return": {
@@ -919,7 +690,7 @@
 #    :title: Introspect on virtio-scsi's VirtQueue 2 at head
 #
 #     -> { "execute": "x-query-virtio-queue-element",
-#          "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
+#          "arguments": { "path": "/machine/peripheral-anon/...",
 #                         "queue": 2 }
 #        }
 #     <- { "return": {
-- 
2.48.1

[PATCH v2 32/33] qga/qapi-schema.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qga/qapi-schema.json | 83 ++++++++++++++++++++++++--------------------
 1 file changed, 45 insertions(+), 38 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 8162d888bb..9e3fd1eee5 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -96,8 +96,8 @@
 # In cases where a partial stale response was previously received by
 # the client, this cannot always be done reliably.  One particular
 # scenario being if qemu-ga responses are fed character-by-character
-# into a JSON parser.  In these situations, using `guest-sync-delimited`
-# may be optimal.
+# into a JSON parser.  In these situations, using
+# `guest-sync-delimited` may be optimal.
 #
 # For clients that fetch responses line by line and convert them to
 # JSON objects, `guest-sync` should be sufficient, but note that in
@@ -153,9 +153,9 @@
 # This command tries to set guest's System Time to the given value,
 # then sets the Hardware Clock (RTC) to the current System Time.  This
 # will make it easier for a guest to resynchronize without waiting for
-# NTP. If no @time is specified, then the time to set is read from
-# RTC. However, this may not be supported on all platforms (i.e.
-# Windows). If that's the case users are advised to always pass a
+# NTP.  If no @time is specified, then the time to set is read from
+# RTC.  However, this may not be supported on all platforms (i.e.
+# Windows).  If that's the case users are advised to always pass a
 # value.
 #
 # @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in
@@ -444,8 +444,8 @@
 # Returns: Number of file systems currently frozen.
 #
 # .. note:: On Windows, the command is implemented with the help of a
-#    Volume Shadow-copy Service DLL helper.  The frozen state is limited
-#    for up to 10 seconds by VSS.
+#    Volume Shadow-copy Service DLL helper.  The frozen state is
+#    limited for up to 10 seconds by VSS.
 #
 # Since: 0.15.0
 ##
@@ -482,9 +482,9 @@
 # Returns: Number of file systems thawed by this call
 #
 # .. note:: If the return value does not match the previous call to
-#    `guest-fsfreeze-freeze`, this likely means some freezable filesystems
-#    were unfrozen before this call, and that the filesystem state may
-#    have changed before issuing this command.
+#    `guest-fsfreeze-freeze`, this likely means some freezable
+#    filesystems were unfrozen before this call, and that the
+#    filesystem state may have changed before issuing this command.
 #
 # Since: 0.15.0
 ##
@@ -513,7 +513,8 @@
 ##
 # @GuestFilesystemTrimResponse:
 #
-# @paths: list of `GuestFilesystemTrimResult` per path that was trimmed
+# @paths: list of `GuestFilesystemTrimResult` per path that was
+#     trimmed
 #
 # Since: 2.4
 ##
@@ -557,16 +558,16 @@
 #
 # This command does NOT return a response on success.  There is a high
 # chance the command succeeded if the VM exits with a zero exit status
-# or, when running with --no-shutdown, by issuing the `query-status` QMP
-# command to to confirm the VM status is "shutdown". However, the VM
-# could also exit (or set its status to "shutdown") due to other
+# or, when running with --no-shutdown, by issuing the `query-status`
+# QMP command to to confirm the VM status is "shutdown".  However, the
+# VM could also exit (or set its status to "shutdown") due to other
 # reasons.
 #
 # Errors:
 #     - If suspend to disk is not supported, Unsupported
 #
-# .. note:: It's strongly recommended to issue the `guest-sync` command
-#    before sending commands when the guest resumes.
+# .. note:: It's strongly recommended to issue the `guest-sync`
+#     command before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -586,7 +587,7 @@
 # - manual write into sysfs
 #
 # IMPORTANT: `guest-suspend-ram` requires working wakeup support in
-# QEMU. You should check QMP command `query-current-machine` returns
+# QEMU.  You should check QMP command `query-current-machine` returns
 # wakeup-suspend-support: true before issuing this command.  Failure
 # in doing so can result in a suspended guest that QEMU will not be
 # able to awaken, forcing the user to power cycle the guest to bring
@@ -602,8 +603,8 @@
 # Errors:
 #     - If suspend to ram is not supported, Unsupported
 #
-# .. note:: It's strongly recommended to issue the `guest-sync` command
-#    before sending commands when the guest resumes.
+# .. note:: It's strongly recommended to issue the `guest-sync`
+#     command before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -622,7 +623,7 @@
 # - pm-utils (via pm-suspend-hybrid)
 #
 # IMPORTANT: `guest-suspend-hybrid` requires working wakeup support in
-# QEMU. You should check QMP command `query-current-machine` returns
+# QEMU.  You should check QMP command `query-current-machine` returns
 # wakeup-suspend-support: true before issuing this command.  Failure
 # in doing so can result in a suspended guest that QEMU will not be
 # able to awaken, forcing the user to power cycle the guest to bring
@@ -638,8 +639,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# .. note:: It's strongly recommended to issue the `guest-sync` command
-#    before sending commands when the guest resumes.
+# .. note:: It's strongly recommended to issue the `guest-sync`
+#     command before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1048,10 +1049,11 @@
 #
 # @used-bytes: file system used bytes (since 3.0)
 #
-# @total-bytes: filesystem capacity in bytes for unprivileged users (since 3.0)
+# @total-bytes: filesystem capacity in bytes for unprivileged users
+#     (since 3.0)
 #
-# @total-bytes-privileged: filesystem capacity in bytes for privileged users
-#     (since 9.1)
+# @total-bytes-privileged: filesystem capacity in bytes for privileged
+#     users (since 9.1)
 #
 # @disk: an array of disk hardware information that the volume lies
 #     on, which may be empty if the disk type is not supported
@@ -1171,7 +1173,8 @@
 ##
 # @GuestMemoryBlockResponse:
 #
-# @phys-index: same with the 'phys-index' member of `GuestMemoryBlock`.
+# @phys-index: same with the 'phys-index' member of
+#     `GuestMemoryBlock`.
 #
 # @response: the result of memory block operation.
 #
@@ -1491,10 +1494,11 @@
 #
 # .. note:: On POSIX systems the fields @id, @name, @pretty-name,
 #    @version, @version-id, @variant and @variant-id follow the
-#    definition specified in os-release(5). Refer to the manual page for
-#    exact description of the fields.  Their values are taken from the
-#    os-release file.  If the file is not present in the system, or the
-#    values are not present in the file, the fields are not included.
+#    definition specified in os-release(5).  Refer to the manual page
+#    for exact description of the fields.  Their values are taken from
+#    the os-release file.  If the file is not present in the system,
+#    or the values are not present in the file, the fields are not
+#    included.
 #
 #    On Windows the values are filled from information gathered from
 #    the system.
@@ -1639,7 +1643,7 @@
 # @guest-ssh-remove-authorized-keys:
 #
 # Remove public keys from the user .ssh/authorized_keys on Unix
-# systems (not implemented for other systems). It's not an error if
+# systems (not implemented for other systems).  It's not an error if
 # the key is already missing.
 #
 # @username: the user account to remove the authorized keys
@@ -1862,10 +1866,10 @@
 #
 # Retrieve CPU process load information
 #
-# .. note:: Windows does not have load average API, so QGA emulates it by
-#           calculating the average CPU usage in the last 1, 5, 15 minutes
-#           similar as Linux does this.
-#           Calculation starts from the first time this command is called.
+# .. note:: Windows does not have load average API, so QGA emulates it
+#     by calculating the average CPU usage in the last 1, 5, 15
+#     minutes similar as Linux does this.  Calculation starts from the
+#     first time this command is called.
 #
 # Returns: load information
 #
@@ -1881,9 +1885,11 @@
 #
 # Route information, currently, only linux supported.
 #
-# @iface: The destination network or host's egress network interface in the routing table
+# @iface: The destination network or host's egress network interface
+#     in the routing table
 #
-# @destination: The IP address of the target network or host, The final destination of the packet
+# @destination: The IP address of the target network or host, The
+#     final destination of the packet
 #
 # @metric: Route metric
 #
@@ -1899,7 +1905,8 @@
 #
 # @use: Route usage count (not for windows)
 #
-# @window: TCP window size, used for flow control (not for windows, IPv4 only)
+# @window: TCP window size, used for flow control (not for windows,
+#     IPv4 only)
 #
 # @mtu: Data link layer maximum packet size (not for windows)
 #
-- 
2.48.1

[PATCH v2 33/33] qapi/acpi-hest.json: docs: width=70 and two spaces between sentences

[Vladimir Sementsov-Ogievskiy]

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/acpi-hest.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json
index 28af1266a7..22a28b2199 100644
--- a/qapi/acpi-hest.json
+++ b/qapi/acpi-hest.json
@@ -6,7 +6,7 @@
 # == GHESv2 CPER Error Injection
 #
 # Defined since ACPI Specification 6.1,
-# section 18.3.2.8 Generic Hardware Error Source version 2. See:
+# section 18.3.2.8 Generic Hardware Error Source version 2.  See:
 #
 # https://uefi.org/sites/default/files/resources/ACPI_6_1.pdf
 ##
-- 
2.48.1

Re: [PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences

[Daniel P. Berrangé]

On Sat, Oct 11, 2025 at 05:04:06PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> Hi all!
> 
> Let's bring the documentation in line with the requirements. And
> do check these requirements in QAPI parser.

This implicitly assumes that the requirements are desirable.

This is a large number of patches, showing the requirements are widely
ignored today. When I look at the changes in the patches my overwhealming
reaction is that they are not beneficial, which in turn makes me believe
the requirements should be changed to match the reality of the code,
rather than the reverse.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|