Merge tag 'pull-qapi-2024-10-02' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-10-02

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmb88k4SHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTr3sP/iT8x2pSy6MMOLnuzo/jsMp238U5kb88
# LjDPkUkYhg9m9Z05Odm8g2X3ZjAM0ZrxnSjCZ+yb3HcvaaVN29156ebueJetYSLY
# 4lN1IMBdQcVJuRWAaURd42ADPEaVn3+xk9eZtaakxP3a9PnoqDIvc+WbEVFgWkPs
# l2CgEqsoEaX8Ui1lDDJIEiZhjCVd4Gj3rT9BuchAtljmiO59c91O+H+OSg1I8YF4
# 46xa0rulmYQSv18fEt7OVfwVTJMiiXXXX4cE1zEneGzkvAnv1NRjAH3E4O9Wf97Q
# cNFOEXrhJvXTAh5sVF+1Mp4JktYsKBgUADwqPJJ26SXeuum+15HXt038cNqJlzyl
# yr+fg2vubI5iVQyMFP+Rlvx54d94C2NAqa/JudfL3iu7uJKKNxzjFdJqhwNFPvaL
# WVzBX66+ZV97D/ujqige99As58RZXFlR2ccLELsg7B6T307MFI/XhfFeG2WFViZi
# fFadS9OfNfhzpo/HfOPtJXnU7cBviwormIY7tKuo7jhyXV8YvKvvVpMMYxKJk68o
# wVUC6OBEQ+NqSCjUW+LNzIdpEDk6qL01rIgD48ywv0aV8FhUiVURVLBu6loEo/ib
# pBR/W6k2AudnJ+mLfkIGCXSSu3RWNx5yayS3LcEE1dKQJquyn8qJk8GMEwhRM8tF
# /NO4P74VmUUJ
# =f3Zh
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 02 Oct 2024 08:12:14 BST
# 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-10-02' of https://repo.or.cz/qemu/armbru:
  qapi/block-core: Drop drive-backup's "Any other error" documentation
  qapi: Drop "with an explanation" from error descriptions
  qapi: Document QCryptodevBackendServiceType
  qapi/cxl: Supply missing member documentation
  qapi/rocker: Supply missing member documentation
  qapi/pci: Supply missing member documentation
  qapi/introspect: Supply missing member documentation
  qapi/crypto: Supply missing member documentation
  qapi/common: Supply missing member documentation
  qapi/char: Supply missing member documentation

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

10 files changed, 86 insertions, 34 deletions

diff --git a/qapi/block-core.json b/qapi/block-core.json
index c3b0a23..5c2b3ac 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
 #
@@ -2304,7 +2303,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 +2326,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 +2350,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 +2371,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 +2392,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 +2466,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
 ##
diff --git a/qapi/char.json b/qapi/char.json
index ef58445..0d6de1e 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/common.json b/qapi/common.json
index 7558ce5..6ffc7a3 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/crypto.json b/qapi/crypto.json
index 867b09d..9431522 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/cryptodev.json b/qapi/cryptodev.json
index 5e41734..04d0e21 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/cxl.json b/qapi/cxl.json
index e9315d5..9f65589 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/introspect.json b/qapi/introspect.json
index 14df049..01bb242 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/pci.json b/qapi/pci.json
index 78bee57..dc85a41 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 fad3a31..023a2ef 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -46,28 +46,21 @@
         'BlockdevSnapshotSyncWrapper',
         'BlockdevSnapshotWrapper',
         'BlockdevVmdkAdapterType',
-        'ChardevBackendKind',
-        'CxlCorErrorType',
         'DisplayProtocol',
         'DriveBackupWrapper',
         'DummyBlockCoreForceArrays',
         'DummyForceArrays',
         'DummyVirtioForceArrays',
-        'GrabToggleKeys',
         'HotKeyMod',
         'ImageInfoSpecificKind',
         'InputAxis',
         'InputButton',
         'IscsiHeaderDigest',
         'IscsiTransport',
-        'JSONType',
         'KeyValueKind',
         'MemoryDeviceInfoKind',
         'NetClientDriver',
         'ObjectType',
-        'PciMemoryRegion',
-        'QCryptoAkCipherKeyType',
-        'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
         'RbdImageEncryptionFormat',
@@ -83,9 +76,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 73c7363..51aa5b4 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