qemu-commits
[Top][All Lists]
Advanced
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Qemu-commits] [qemu/qemu] e8c550: qapi: Improve migration TLS documenta

From: Peter Maydell
Subject: [Qemu-commits] [qemu/qemu] e8c550: qapi: Improve migration TLS documentation
Date: Tue, 26 Mar 2024 05:41:22 -0700 
  Branch: refs/heads/master
  Home:   https://github.com/qemu/qemu
  Commit: e8c5503a5c8b0479f1fde1b2abb7b488dee70996
      
https://github.com/qemu/qemu/commit/e8c5503a5c8b0479f1fde1b2abb7b488dee70996
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/migration.json

  Log Message:
  -----------
  qapi: Improve migration TLS documentation

MigrateSetParameters is about setting parameters, and
MigrationParameters is about querying them.  Their documentation of
@tls-creds and @tls-hostname has residual damage from a failed attempt
at de-duplicating them (see commit de63ab61241 "migrate: Share common
MigrationParameters struct" and commit 1bda8b3c695 "migration: Unshare
MigrationParameters struct for now").

MigrateSetParameters documentation issues:

* It claims plain text mode "was reported by omitting tls-creds"
  before 2.9.  MigrateSetParameters is not used for reporting, so this
  is misleading.  Delete.

* It similarly claims hostname defaulting to migration URI "was
  reported by omitting tls-hostname" before 2.9.  Delete as well.

Rephrase the remaining @tls-hostname contents for clarity.

Enum MigrationParameter mirrors the members of struct
MigrateSetParameters.  Differences to MigrateSetParameters's member
documentation are pointless.  Copy the new text to MigrationParameter.

MigrationParameters documentation issues:

* @tls-creds runs the two last sentences together without punctuation.
  Fix that.

* Much of the contents on @tls-hostname only applies to setting
  parameters, resulting in confusion.  Replace by a suitable abridged
  version of the new MigrateSetParameters text, and a note on
  @tls-hostname omission in 2.8.

Additional damage is due to flawed doc fix commit
66fcb9d651d (qapi/migration: Add missing tls-authz documentation):
since it copied the missing MigrateSetParameters text from
MigrationParameters instead of MigrationParameter, the part on
recreating @tls-authz on the fly is missing.  Copy that, too.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322135117.195489-2-armbru@redhat.com>
Reviewed-by: Peter Xu <peterx@redhat.com>
[Some typos corrected]


  Commit: 8eb0a257c55d1b27dc8c40ce3c275307b898f575
      
https://github.com/qemu/qemu/commit/8eb0a257c55d1b27dc8c40ce3c275307b898f575
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/migration.json

  Log Message:
  -----------
  qapi: Resync MigrationParameter and MigrateSetParameters

Enum MigrationParameter mirrors the members of struct
MigrateSetParameters.  Differences to MigrateSetParameters's member
documentation are pointless.  Clean them up:

* @compress-level, @compress-threads, @decompress-threads, and
  x-checkpoint-delay are more thoroughly documented for
  MigrationParameter, so use that version for both.

* @max-cpu-throttle is almost the same.  Use MigrationParameter's
  version for both.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322135117.195489-3-armbru@redhat.com>
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Reviewed-by: Peter Xu <peterx@redhat.com>


  Commit: e6c60bf02d1c32b5e3e7dc761d1737aa8886ab79
      
https://github.com/qemu/qemu/commit/e6c60bf02d1c32b5e3e7dc761d1737aa8886ab79
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/migration.json

  Log Message:
  -----------
  qapi: Fix bogus documentation of query-migrationthreads

The doc comment documents an argument that doesn't exist.  Would
fail compilation if it was marked up correctly.  Delete.

The Returns: section fails to refer to the data type, leaving the user
to guess.  Fix that.

The command name violates QAPI naming rules: it should be
query-migration-threads.  Too late to fix.

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


  Commit: c15fbc66e2189723155165af28ba2238bb2064b6
      
https://github.com/qemu/qemu/commit/c15fbc66e2189723155165af28ba2238bb2064b6
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/control.json

  Log Message:
  -----------
  qapi: Drop stray Arguments: line from qmp_capabilities docs

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


  Commit: f972ed5925cda823a99f89d6250cdae655140884
      
https://github.com/qemu/qemu/commit/f972ed5925cda823a99f89d6250cdae655140884
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/replay.json
    M qapi/virtio.json

  Log Message:
  -----------
  qapi: Expand a few awkward abbreviations in documentation

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-3-armbru@redhat.com>


  Commit: b5e29402f1feb96bce4733a7b6346a5b441f99ae
      
https://github.com/qemu/qemu/commit/b5e29402f1feb96bce4733a7b6346a5b441f99ae
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/block.json

  Log Message:
  -----------
  qapi: Tidy up block-latency-histogram-set documentation some more

Commit a937b6aa739 (qapi: Reformat doc comments to conform to current
conventions) reflowed some text that should have been left alone.
Revert that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-4-armbru@redhat.com>


  Commit: 7d50757c65f7609a24151fc2b5939cb78c2dc81c
      
https://github.com/qemu/qemu/commit/7d50757c65f7609a24151fc2b5939cb78c2dc81c
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/misc.json

  Log Message:
  -----------
  qapi: Tidy up indentation of add_client's example

Commit d23055b8db8 (qapi: Require descriptions and tagged sections to
be indented) indented add_client's example too much.  Revert that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-5-armbru@redhat.com>
[Move a stray hunk to the later patch it belongs to]


  Commit: aa03e163839fb13eafcf9c514bd832ea134cdccf
      
https://github.com/qemu/qemu/commit/aa03e163839fb13eafcf9c514bd832ea134cdccf
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/block-core.json

  Log Message:
  -----------
  qapi: Fix argument markup in drive-mirror documentation

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-6-armbru@redhat.com>


  Commit: 8698e1447fa48d7dcdeeeca4434afa86b97e3665
      
https://github.com/qemu/qemu/commit/8698e1447fa48d7dcdeeeca4434afa86b97e3665
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/ebpf.json

  Log Message:
  -----------
  qapi: Fix typo in request-ebpf documentation

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-7-armbru@redhat.com>


  Commit: 7d08424cf79c72d560f8d730963d2101a7393757
      
https://github.com/qemu/qemu/commit/7d08424cf79c72d560f8d730963d2101a7393757
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/migration.json

  Log Message:
  -----------
  qapi: Fix abbreviation punctuation in doc comments

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-8-armbru@redhat.com>


  Commit: 73c67f385118b5488edecda9b64a125e060242eb
      
https://github.com/qemu/qemu/commit/73c67f385118b5488edecda9b64a125e060242eb
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/migration.json
    M qapi/ui.json

  Log Message:
  -----------
  qapi: Start sentences with a capital letter, end them with a period

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-9-armbru@redhat.com>


  Commit: 1e6b0505c4e6830182b0c21fedec46b4f6d8f22a
      
https://github.com/qemu/qemu/commit/1e6b0505c4e6830182b0c21fedec46b4f6d8f22a
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/run-state.json

  Log Message:
  -----------
  qapi: Don't repeat member type in its documentation text

Documentation generated for the arguments of MEMORY_FAILURE looks like

    "recipient": "MemoryFailureRecipient"
       recipient is defined as "MemoryFailureRecipient".

    "action": "MemoryFailureAction"
       action that has been taken.  action is defined as
       "MemoryFailureAction".

    "flags": "MemoryFailureFlags"
       flags for MemoryFailureAction.  action is defined as
       "MemoryFailureFlags".

The "action is defined as ..." are redundant.  Drop.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-10-armbru@redhat.com>


  Commit: 209e64d9edff332da607bbf98430456a20025432
      
https://github.com/qemu/qemu/commit/209e64d9edff332da607bbf98430456a20025432
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/block-core.json
    M qapi/block.json
    M qapi/cxl.json
    M qapi/dump.json
    M qapi/ebpf.json
    M qapi/machine-target.json
    M qapi/machine.json
    M qapi/migration.json
    M qapi/net.json
    M qapi/qom.json
    M qapi/run-state.json
    M qapi/virtio.json

  Log Message:
  -----------
  qapi: Refill doc comments to conform to current conventions

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

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

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-11-armbru@redhat.com>


  Commit: 5305a4eeb80b9b69ae2c1a1440bd3ece0a8b35a2
      
https://github.com/qemu/qemu/commit/5305a4eeb80b9b69ae2c1a1440bd3ece0a8b35a2
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/block-core.json
    M qapi/crypto.json
    M qapi/dump.json
    M qapi/machine.json
    M qapi/migration.json
    M qapi/misc.json
    M qapi/qom.json
    M qapi/run-state.json
    M qapi/sockets.json
    M qapi/ui.json

  Log Message:
  -----------
  qapi: Correct documentation indentation and whitespace

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-12-armbru@redhat.com>
[Add a previous patch's stray hunk]


  Commit: 7270819384cabf6c501ef34217eb56a1b14696e3
      
https://github.com/qemu/qemu/commit/7270819384cabf6c501ef34217eb56a1b14696e3
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qga/qapi-schema.json

  Log Message:
  -----------
  qga/qapi-schema: Refill doc comments to conform to current conventions

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

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

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240322140910.328840-13-armbru@redhat.com>


  Commit: 6087783ea75030fe70f1b369cfd9d3c25bc2dadf
      
https://github.com/qemu/qemu/commit/6087783ea75030fe70f1b369cfd9d3c25bc2dadf
  Author: Marc-André Lureau <marcandre.lureau@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/pragma.json
    M qapi/ui.json

  Log Message:
  -----------
  qapi: document InputMultiTouchType

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


  Commit: b2913cc2a1825d70b9985613447b26d672df5418
      
https://github.com/qemu/qemu/commit/b2913cc2a1825d70b9985613447b26d672df5418
  Author: Paolo Bonzini <pbonzini@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/pragma.json
    M qapi/run-state.json

  Log Message:
  -----------
  qapi: document leftover members in qapi/run-state.json

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


  Commit: 1de759534de1a9a76bd72678d0290ce5ee00de25
      
https://github.com/qemu/qemu/commit/1de759534de1a9a76bd72678d0290ce5ee00de25
  Author: Paolo Bonzini <pbonzini@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/pragma.json
    M qapi/stats.json

  Log Message:
  -----------
  qapi: document leftover members in qapi/stats.json

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


  Commit: 125f973cc2f135a683e425ef30802102f13d47b3
      
https://github.com/qemu/qemu/commit/125f973cc2f135a683e425ef30802102f13d47b3
  Author: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/block-core.json
    M qapi/pragma.json

  Log Message:
  -----------
  qapi/block-core: improve Qcow2OverlapCheckFlags documentation

Most of fields have no description at all. Let's fix that. Still, no
reason to place here more detailed descriptions of what these
structures are, as we have public Qcow2 format specification.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Message-ID: <20240325120054.2693236-1-vsementsov@yandex-team.ru>
Acked-by: Markus Armbruster <armbru@redhat.com>
[Capitalize "QEMU", update qapi/pragma.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>


  Commit: 1a533ce986f52c35f324f5f4fff22cdc2619a47c
      
https://github.com/qemu/qemu/commit/1a533ce986f52c35f324f5f4fff22cdc2619a47c
  Author: David Hildenbrand <david@redhat.com>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/machine-target.json
    M qapi/pragma.json

  Log Message:
  -----------
  qapi: document parameters of query-cpu-model-* QAPI commands

Let's document the parameters of these commands, so we can remove them
from the "documentation-exceptions" list.

While at it, extend the "Returns:" documentation as well, fixing a wrong
use of CpuModelBaselineInfo vs. CpuModelCompareInfo for
query-cpu-model-comparison.

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


  Commit: 096ae430a7b5a704af4cd94dca7200d6cb069991
      
https://github.com/qemu/qemu/commit/096ae430a7b5a704af4cd94dca7200d6cb069991
  Author: Peter Maydell <peter.maydell@linaro.org>
  Date:   2024-03-26 (Tue, 26 Mar 2024)

  Changed paths:
    M qapi/block-core.json
    M qapi/block.json
    M qapi/control.json
    M qapi/crypto.json
    M qapi/cxl.json
    M qapi/dump.json
    M qapi/ebpf.json
    M qapi/machine-target.json
    M qapi/machine.json
    M qapi/migration.json
    M qapi/misc.json
    M qapi/net.json
    M qapi/pragma.json
    M qapi/qom.json
    M qapi/replay.json
    M qapi/run-state.json
    M qapi/sockets.json
    M qapi/stats.json
    M qapi/ui.json
    M qapi/virtio.json
    M qga/qapi-schema.json

  Log Message:
  -----------
  Merge tag 'pull-qapi-2024-03-26' of https://repo.or.cz/qemu/armbru into 
staging

QAPI patches patches for 2024-03-26

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmYCXs0SHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTRMkP/RR9ipyCh1P6KKuQCyouxM8nXZ945b33
# L0OBFY4cTZsMY98ZTU9i80f/Tjh58y5bYzSdr21jxBSdRlvb6w/Ys8xUsI2Hi/kZ
# czdKZbWT5IeSNrLw04CjhW2FKq8XXR7epHbPms2nBa1Xc5Jf8aIC2UhZKADeVCyE
# FCIUU8Ctkyvre3XGVOrIBhhVPs9hi33uG+HXiveQjjWwGZZ0v915sAZ4WvNEoiBS
# E0NwhJxtbQu8FwfBquE84o0TMzYb19MlU4zq3G5dv7PhLoXX9Lf097/tPEtoP4et
# H37eGD8MzL1hywf+E1vAw0HC/v7Ci5Kx1jpUUL03Hfvfa6Lktb6yYke8qAD1HopK
# o4btXKpfseuyTJuqTVaV4Z9tLqmpTddnUupBFkfKviMPdidAN9SM1qXx0VCM9mUo
# cwf5di6zOPTNYlsKuP6ofSGGaD5so9PGLGAZoGeZ1Cb7TLsgiqqD0GrPP0//1VLn
# GzOOsOA4Su9F2/qjkNu2HZ1jv6J105LbQnaPvqjVfkjzzmoOANYmViX3KmDwdBxX
# vSfy5/UpCP9TBv++N/ljRtrVzW9i4a2rIGeHWC0x/JJglIh45f2MzeyqJ5haV2n5
# MVY82yY7EY7U+YXUUUKSgGVWw7+/wj/R5wQ5a9Gjk9OlmTsTHxJIKIzhcw4lX9da
# ZmRLCSIlVu4Z
# =li36
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 26 Mar 2024 05:36:13 GMT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2024-03-26' of https://repo.or.cz/qemu/armbru:
  qapi: document parameters of query-cpu-model-* QAPI commands
  qapi/block-core: improve Qcow2OverlapCheckFlags documentation
  qapi: document leftover members in qapi/stats.json
  qapi: document leftover members in qapi/run-state.json
  qapi: document InputMultiTouchType
  qga/qapi-schema: Refill doc comments to conform to current conventions
  qapi: Correct documentation indentation and whitespace
  qapi: Refill doc comments to conform to current conventions
  qapi: Don't repeat member type in its documentation text
  qapi: Start sentences with a capital letter, end them with a period
  qapi: Fix abbreviation punctuation in doc comments
  qapi: Fix typo in request-ebpf documentation
  qapi: Fix argument markup in drive-mirror documentation
  qapi: Tidy up indentation of add_client's example
  qapi: Tidy up block-latency-histogram-set documentation some more
  qapi: Expand a few awkward abbreviations in documentation
  qapi: Drop stray Arguments: line from qmp_capabilities docs
  qapi: Fix bogus documentation of query-migrationthreads
  qapi: Resync MigrationParameter and MigrateSetParameters
  qapi: Improve migration TLS documentation

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>


Compare: https://github.com/qemu/qemu/compare/6a4180af9686...096ae430a7b5

To unsubscribe from these emails, change your notification settings at 
https://github.com/qemu/qemu/settings/notifications
reply via email to
[Prev in Thread] Current Thread [Next in Thread]