[PULL 00/10] QAPI patches patches for 2024-10-02

[PULL 00/10] QAPI patches patches for 2024-10-02

[Markus Armbruster]

The following changes since commit 718780d20470c66a3a36d036b29148d5809dc855:

  Merge tag 'pull-nvme-20241001' of https://gitlab.com/birkelund/qemu into staging (2024-10-01 11:34:07 +0100)

are available in the Git repository at:

  https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-10-02

for you to fetch changes up to b3bd7617dbae8e5f84c27a1ab8df89cba371a276:

  qapi/block-core: Drop drive-backup's "Any other error" documentation (2024-10-02 09:10:01 +0200)

----------------------------------------------------------------
QAPI patches patches for 2024-10-02

----------------------------------------------------------------
Markus Armbruster (9):
      qapi/char: Supply missing member documentation
      qapi/common: Supply missing member documentation
      qapi/crypto: Supply missing member documentation
      qapi/introspect: Supply missing member documentation
      qapi/pci: Supply missing member documentation
      qapi/rocker: Supply missing member documentation
      qapi/cxl: Supply missing member documentation
      qapi: Drop "with an explanation" from error descriptions
      qapi/block-core: Drop drive-backup's "Any other error" documentation

Zhenwei Pi (1):
      qapi: Document QCryptodevBackendServiceType

 qapi/block-core.json | 12 +++++-------
 qapi/char.json       | 44 ++++++++++++++++++++++++++++----------------
 qapi/common.json     | 14 +++++++++++++-
 qapi/crypto.json     |  4 ++++
 qapi/cryptodev.json  | 10 ++++++++++
 qapi/cxl.json        |  3 +++
 qapi/introspect.json | 16 ++++++++++++++++
 qapi/pci.json        |  2 ++
 qapi/pragma.json     | 11 +----------
 qapi/rocker.json     |  4 ++++
 10 files changed, 86 insertions(+), 34 deletions(-)

-- 
2.46.0

[PULL 01/10] qapi/char: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document several members of ChardevBackendKind,
their description in the QEMU QMP Reference manual is "Not
documented".  Fix that, and improve the existing member documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240911112545.2248881-2-armbru@redhat.com>
---
 qapi/char.json   | 44 ++++++++++++++++++++++++++++----------------
 qapi/pragma.json |  1 -
 2 files changed, 28 insertions(+), 17 deletions(-)

diff --git a/qapi/char.json b/qapi/char.json
index ef58445cee..0d6de1ee35 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -434,37 +434,49 @@
 ##
 # @ChardevBackendKind:
 #
-# @pipe: Since 1.5
+# @file: regular files
 #
-# @udp: Since 1.5
+# @serial: serial host device
 #
-# @mux: Since 1.5
+# @parallel: parallel host device
 #
-# @msmouse: Since 1.5
+# @pipe: pipes (since 1.5)
 #
-# @wctablet: Since 2.9
+# @socket: stream socket
 #
-# @braille: Since 1.5
+# @udp: datagram socket (since 1.5)
 #
-# @testdev: Since 2.2
+# @pty: pseudo-terminal
 #
-# @stdio: Since 1.5
+# @null: provides no input, throws away output
 #
-# @console: Since 1.5
+# @mux: (since 1.5)
 #
-# @spicevmc: Since 1.5
+# @msmouse: emulated Microsoft serial mouse (since 1.5)
 #
-# @spiceport: Since 1.5
+# @wctablet: emulated Wacom Penpartner serial tablet (since 2.9)
 #
-# @qemu-vdagent: Since 6.1
+# @braille: Baum Braille device (since 1.5)
 #
-# @dbus: Since 7.0
+# @testdev: device for test-suite control (since 2.2)
 #
-# @vc: v1.5
+# @stdio: standard I/O (since 1.5)
 #
-# @ringbuf: Since 1.6
+# @console: Windows console (since 1.5)
 #
-# @memory: Since 1.5
+# @spicevmc: spice vm channel (since 1.5)
+#
+# @spiceport: Spice port channel (since 1.5)
+#
+# @qemu-vdagent: Spice vdagent (since 6.1)
+#
+# @dbus: D-Bus channel (since 7.0)
+#
+# @vc: virtual console (since 1.5)
+#
+# @ringbuf: memory ring buffer (since 1.6)
+#
+# @memory: synonym for @ringbuf (since 1.5)
 #
 # Features:
 #
diff --git a/qapi/pragma.json b/qapi/pragma.json
index fad3a31628..d5ae397293 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -46,7 +46,6 @@
         'BlockdevSnapshotSyncWrapper',
         'BlockdevSnapshotWrapper',
         'BlockdevVmdkAdapterType',
-        'ChardevBackendKind',
         'CxlCorErrorType',
         'DisplayProtocol',
         'DriveBackupWrapper',
-- 
2.46.0

[PULL 02/10] qapi/common: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the members of GrabToggleKeys, their
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-ID: <20240911112545.2248881-3-armbru@redhat.com>
---
 qapi/common.json | 14 +++++++++++++-
 qapi/pragma.json |  1 -
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/qapi/common.json b/qapi/common.json
index 7558ce5430..6ffc7a3789 100644
--- a/qapi/common.json
+++ b/qapi/common.json
@@ -183,7 +183,19 @@
 ##
 # @GrabToggleKeys:
 #
-# Keys to toggle input-linux between host and guest.
+# Key combinations to toggle input-linux between host and guest.
+#
+# @ctrl-ctrl: left and right control key
+#
+# @alt-alt: left and right alt key
+#
+# @shift-shift: left and right shift key
+#
+# @meta-meta: left and right meta key
+#
+# @scrolllock: scroll lock key
+#
+# @ctrl-scrolllock: either control key and scroll lock key
 #
 # Since: 4.0
 ##
diff --git a/qapi/pragma.json b/qapi/pragma.json
index d5ae397293..f03b9cc444 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -52,7 +52,6 @@
         'DummyBlockCoreForceArrays',
         'DummyForceArrays',
         'DummyVirtioForceArrays',
-        'GrabToggleKeys',
         'HotKeyMod',
         'ImageInfoSpecificKind',
         'InputAxis',
-- 
2.46.0

[PULL 03/10] qapi/crypto: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the members of QCryptoAkCipherKeyType,
their description in the QEMU QMP Reference manual is "Not
documented".  Fix that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-ID: <20240911112545.2248881-4-armbru@redhat.com>
---
 qapi/crypto.json | 4 ++++
 qapi/pragma.json | 1 -
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/qapi/crypto.json b/qapi/crypto.json
index 867b09d322..9431522768 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -602,6 +602,10 @@
 #
 # The type of asymmetric keys.
 #
+# @public: public key
+#
+# @private: private key
+#
 # Since: 7.1
 ##
 { 'enum': 'QCryptoAkCipherKeyType',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index f03b9cc444..625eac99df 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -64,7 +64,6 @@
         'NetClientDriver',
         'ObjectType',
         'PciMemoryRegion',
-        'QCryptoAkCipherKeyType',
         'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
-- 
2.46.0

[PULL 04/10] qapi/introspect: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the members of JSONType, their
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-ID: <20240911112545.2248881-5-armbru@redhat.com>
---
 qapi/introspect.json | 16 ++++++++++++++++
 qapi/pragma.json     |  1 -
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/qapi/introspect.json b/qapi/introspect.json
index 14df049580..01bb242947 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -127,6 +127,22 @@
 # section 1, plus 'int' (split off 'number'), plus the obvious top
 # type 'value'.
 #
+# @string: JSON string
+#
+# @number: JSON number
+#
+# @int: JSON number that is an integer
+#
+# @boolean: literal ``false`` or ``true``
+#
+# @null: literal ``null``
+#
+# @object: JSON object
+#
+# @array: JSON array
+#
+# @value: any JSON value
+#
 # Since: 2.5
 ##
 { 'enum': 'JSONType',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 625eac99df..7b0e12f42b 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -58,7 +58,6 @@
         'InputButton',
         'IscsiHeaderDigest',
         'IscsiTransport',
-        'JSONType',
         'KeyValueKind',
         'MemoryDeviceInfoKind',
         'NetClientDriver',
-- 
2.46.0

[PULL 05/10] qapi/pci: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document a member of PciMemoryRegion, its
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-ID: <20240911112545.2248881-6-armbru@redhat.com>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
---
 qapi/pci.json    | 2 ++
 qapi/pragma.json | 1 -
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/pci.json b/qapi/pci.json
index 78bee57b77..dc85a41d28 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -33,6 +33,8 @@
 #     - 'io' if the region is a PIO region
 #     - 'memory' if the region is a MMIO region
 #
+# @address: memory address
+#
 # @size: memory size
 #
 # @prefetch: if @type is 'memory', true if the memory is prefetchable
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 7b0e12f42b..baeae5bf52 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -62,7 +62,6 @@
         'MemoryDeviceInfoKind',
         'NetClientDriver',
         'ObjectType',
-        'PciMemoryRegion',
         'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
-- 
2.46.0

[PULL 06/10] qapi/rocker: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the argument of query-rocker and
query-rocker-ports, their description in the QEMU QMP Reference manual
is "Not documented".  Fix that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-ID: <20240911112545.2248881-7-armbru@redhat.com>
---
 qapi/pragma.json | 4 +---
 qapi/rocker.json | 4 ++++
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/qapi/pragma.json b/qapi/pragma.json
index baeae5bf52..feb7981700 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -78,9 +78,7 @@
         'X86CPURegister32',
         'XDbgBlockGraph',
         'YankInstanceType',
-        'blockdev-reopen',
-        'query-rocker',
-        'query-rocker-ports' ],
+        'blockdev-reopen' ],
     # Externally visible types whose member names may use uppercase
     'member-name-exceptions': [     # visible in:
         'ACPISlotType',             # query-acpi-ospm-status
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 73c7363b16..51aa5b4930 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -26,6 +26,8 @@
 #
 # Return rocker switch information.
 #
+# @name: switch name
+#
 # Returns: @Rocker information
 #
 # Since: 2.4
@@ -94,6 +96,8 @@
 #
 # Return rocker switch port information.
 #
+# @name: port name
+#
 # Returns: a list of @RockerPort information
 #
 # Since: 2.4
-- 
2.46.0

[PULL 07/10] qapi/cxl: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document a member of CxlCorErrorType, its
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240911112545.2248881-8-armbru@redhat.com>
---
 qapi/cxl.json    | 3 +++
 qapi/pragma.json | 1 -
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/qapi/cxl.json b/qapi/cxl.json
index e9315d5b4d..9f65589bce 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -326,6 +326,9 @@
 # @crc-threshold: Component specific and applicable to 68 byte Flit
 #     mode only.
 #
+# @retry-threshold: Retry threshold hit in the Local Retry State
+#     Machine, 68B Flits only.
+#
 # @cache-poison-received: Received poison from a peer on CXL.cache.
 #
 # @mem-poison-received: Received poison from a peer on CXL.mem
diff --git a/qapi/pragma.json b/qapi/pragma.json
index feb7981700..108e574678 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -46,7 +46,6 @@
         'BlockdevSnapshotSyncWrapper',
         'BlockdevSnapshotWrapper',
         'BlockdevVmdkAdapterType',
-        'CxlCorErrorType',
         'DisplayProtocol',
         'DriveBackupWrapper',
         'DummyBlockCoreForceArrays',
-- 
2.46.0

[PULL 08/10] qapi: Document QCryptodevBackendServiceType

[Markus Armbruster]

From: zhenwei pi <pizhenwei@bytedance.com>

QCryptodevBackendServiceType was introduced by
bc304a6442e (cryptodev: Introduce server type in QAPI). However there
is a lack of member description.

Reported-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: zhenwei pi <pizhenwei@bytedance.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Drop QCryptodevBackendServiceType from pragma documentation-exceptions]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240911112545.2248881-9-armbru@redhat.com>
---
 qapi/cryptodev.json | 10 ++++++++++
 qapi/pragma.json    |  1 -
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index 5e417340dc..04d0e21d20 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -27,6 +27,16 @@
 #
 # The supported service types of a crypto device.
 #
+# @cipher: Symmetric Key Cipher service
+#
+# @hash: Hash service
+#
+# @mac: Message Authentication Codes service
+#
+# @aead: Authenticated Encryption with Associated Data service
+#
+# @akcipher: Asymmetric Key Cipher service
+#
 # Since: 8.0
 ##
 { 'enum': 'QCryptodevBackendServiceType',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 108e574678..023a2ef7bc 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -61,7 +61,6 @@
         'MemoryDeviceInfoKind',
         'NetClientDriver',
         'ObjectType',
-        'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
         'RbdImageEncryptionFormat',
-- 
2.46.0

[PULL 09/10] qapi: Drop "with an explanation" from error descriptions

[Markus Armbruster]

All errors come with an explanation, namely the human-readable error
message in the error response's @desc member.  Drop the redundant
"with an explanation" phrase.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240911132459.2548063-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 qapi/block-core.json | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index c3b0a2376b..d3f076db9d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2304,7 +2304,7 @@
 #
 # Errors:
 #     - If @node is not a valid block device or node, DeviceNotFound
-#     - If @name is already taken, GenericError with an explanation
+#     - If @name is already taken, GenericError
 #
 # Since: 2.4
 #
@@ -2327,7 +2327,7 @@
 #
 # Errors:
 #     - If @node is not a valid block device or node, DeviceNotFound
-#     - If @name is not found, GenericError with an explanation
+#     - If @name is not found, GenericError
 #     - if @name is frozen by an operation, GenericError
 #
 # Since: 2.4
@@ -2351,7 +2351,7 @@
 #
 # Errors:
 #     - If @node is not a valid block device, DeviceNotFound
-#     - If @name is not found, GenericError with an explanation
+#     - If @name is not found, GenericError
 #
 # Since: 2.4
 #
@@ -2372,7 +2372,7 @@
 #
 # Errors:
 #     - If @node is not a valid block device, DeviceNotFound
-#     - If @name is not found, GenericError with an explanation
+#     - If @name is not found, GenericError
 #
 # Since: 4.0
 #
@@ -2393,7 +2393,7 @@
 #
 # Errors:
 #     - If @node is not a valid block device, DeviceNotFound
-#     - If @name is not found, GenericError with an explanation
+#     - If @name is not found, GenericError
 #
 # Since: 4.0
 #
@@ -2467,7 +2467,6 @@
 # Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found or if hashing has failed, GenericError
-#       with an explanation
 #
 # Since: 2.10
 ##
-- 
2.46.0

[PULL 10/10] qapi/block-core: Drop drive-backup's "Any other error" documentation

[Markus Armbruster]

We've always been rather lax about documenting errors.  Many "Errors"
sections are obviously not exhaustive.  Only drive-backup is explicit
about this: "Any other error returns a GenericError".

Not useful.  Drop.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240911132459.2548063-3-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 qapi/block-core.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index d3f076db9d..5c2b3ac0d4 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1858,7 +1858,6 @@
 #
 # Errors:
 #     - If @device does not exist, DeviceNotFound
-#     - Any other error returns a GenericError.
 #
 # Since: 1.3
 #
-- 
2.46.0

Re: [PULL 00/10] QAPI patches patches for 2024-10-02

[Peter Maydell]

On Wed, 2 Oct 2024 at 08:44, Markus Armbruster <armbru@redhat.com> wrote:
>
> The following changes since commit 718780d20470c66a3a36d036b29148d5809dc855:
>
>   Merge tag 'pull-nvme-20241001' of https://gitlab.com/birkelund/qemu into staging (2024-10-01 11:34:07 +0100)
>
> are available in the Git repository at:
>
>   https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-10-02
>
> for you to fetch changes up to b3bd7617dbae8e5f84c27a1ab8df89cba371a276:
>
>   qapi/block-core: Drop drive-backup's "Any other error" documentation (2024-10-02 09:10:01 +0200)
>
> ----------------------------------------------------------------
> QAPI patches patches for 2024-10-02
>


Applied, thanks.

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

-- PMM