From 68eef67af17e97475b5ee8a202ac10c9fa45ac49 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 13:25:38 +0200 Subject: [PATCH 01/10] qapi/char: Supply missing member documentation 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 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', From ee43800d17f1942915018e4128ac0f261a12bab4 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 13:25:39 +0200 Subject: [PATCH 02/10] qapi/common: Supply missing member documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Philippe Mathieu-Daudé 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', From 6b4672663168e5c43d034e9a9bf29502eef3285a Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 13:25:40 +0200 Subject: [PATCH 03/10] qapi/crypto: Supply missing member documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Philippe Mathieu-Daudé 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', From 8fdec50a9d5cf415747c4fbe8184e4ebd77dcc72 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 13:25:41 +0200 Subject: [PATCH 04/10] qapi/introspect: Supply missing member documentation 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 Reviewed-by: Eric Blake 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', From 83b91c9d50009ba9c17c50f1d95bd901cb959359 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 13:25:42 +0200 Subject: [PATCH 05/10] qapi/pci: Supply missing member documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Philippe Mathieu-Daudé Message-ID: <20240911112545.2248881-6-armbru@redhat.com> Reviewed-by: Michael S. Tsirkin --- 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', From c91f44ff1692bdb0e3c91b3db253c43491cbe993 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 13:25:43 +0200 Subject: [PATCH 06/10] qapi/rocker: Supply missing member documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Philippe Mathieu-Daudé 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 From 923b9687289e9febe18dee0f3f2b062b4a1fe57f Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 13:25:44 +0200 Subject: [PATCH 07/10] qapi/cxl: Supply missing member documentation 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 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', From 4707331d1570e627b8fb72986227d1e2ac06e238 Mon Sep 17 00:00:00 2001 From: zhenwei pi Date: Wed, 11 Sep 2024 13:25:45 +0200 Subject: [PATCH 08/10] qapi: Document QCryptodevBackendServiceType QCryptodevBackendServiceType was introduced by bc304a6442e (cryptodev: Introduce server type in QAPI). However there is a lack of member description. Reported-by: Markus Armbruster Signed-off-by: zhenwei pi Reviewed-by: Markus Armbruster [Drop QCryptodevBackendServiceType from pragma documentation-exceptions] Signed-off-by: Markus Armbruster 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', From 0d5b2062289e22fbd54cfd04cd4a77c01c327568 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 15:24:58 +0200 Subject: [PATCH 09/10] qapi: Drop "with an explanation" from error descriptions 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 Message-ID: <20240911132459.2548063-2-armbru@redhat.com> Reviewed-by: Eric Blake --- 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 ## From b3bd7617dbae8e5f84c27a1ab8df89cba371a276 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 11 Sep 2024 15:24:59 +0200 Subject: [PATCH 10/10] qapi/block-core: Drop drive-backup's "Any other error" documentation 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 Message-ID: <20240911132459.2548063-3-armbru@redhat.com> Reviewed-by: Eric Blake --- 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 #