Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-5-armbru@redhat.com>
---
qapi/block-core.json | 44 ++++++++++++++++++++++++++++++++++++++++
qapi/block-export.json | 23 ++++++++++++---------
qapi/block.json | 8 ++++++--
qapi/machine-target.json | 35 ++++++++++++++++++++------------
qapi/machine.json | 6 ++++++
qapi/misc.json | 10 +++++++--
qapi/net.json | 14 ++++++++++---
qapi/qdev.json | 2 ++
qapi/qom.json | 4 ++++
qapi/transaction.json | 3 ++-
qapi/ui.json | 6 ++++++
qapi/yank.json | 2 ++
12 files changed, 126 insertions(+), 31 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 22b8634422..cea46b4668 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1458,6 +1458,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
# Since: 0.14
@@ -1676,6 +1678,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
# Since: 0.14
@@ -1756,6 +1760,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If "device" does not exist or cannot be determined,
# DeviceNotFound
#
@@ -1856,6 +1862,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @device does not exist, DeviceNotFound
# - Any other error returns a GenericError.
#
@@ -1896,6 +1904,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @device is not a valid block device, GenericError
#
# Since: 1.6
@@ -1923,6 +1933,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
# Since: 2.3
@@ -2129,6 +2141,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @device is not a valid block device, GenericError
#
# Since: 1.3
@@ -2306,6 +2320,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @node is not a valid block device or node, DeviceNotFound
# - If @name is already taken, GenericError with an explanation
#
@@ -2330,6 +2346,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @node is not a valid block device or node, DeviceNotFound
# - If @name is not found, GenericError with an explanation
# - if @name is frozen by an operation, GenericError
@@ -2355,6 +2373,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found, GenericError with an explanation
#
@@ -2377,6 +2397,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found, GenericError with an explanation
#
@@ -2399,6 +2421,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found, GenericError with an explanation
#
@@ -2429,6 +2453,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @node is not a valid block device, DeviceNotFound
# - If any bitmap in @bitmaps or @target is not found,
# GenericError
@@ -2471,6 +2497,8 @@
#
# Returns:
# - BlockDirtyBitmapSha256 on success
+#
+# Errors:
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found or if hashing has failed, GenericError
# with an explanation
@@ -2868,6 +2896,8 @@
#
# Returns:
# - Nothing on success.
+#
+# Errors:
# - If @device does not exist, DeviceNotFound.
#
# Since: 1.1
@@ -2907,6 +2937,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
#
@@ -2952,6 +2984,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
#
@@ -2979,6 +3013,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
#
@@ -3004,6 +3040,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
#
@@ -3036,6 +3074,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
#
@@ -6072,6 +6112,8 @@
#
# Returns:
# - nothing on success
+#
+# Errors:
# - If @device is not a valid block device, GenericError
# - If any snapshot matching @name exists, or @name is empty,
# GenericError
@@ -6109,6 +6151,8 @@
#
# Returns:
# - SnapshotInfo on success
+#
+# Errors:
# - If @device is not a valid block device, GenericError
# - If snapshot not found, GenericError
# - If the format of the image used does not support it,
diff --git a/qapi/block-export.json b/qapi/block-export.json
index d9bd376b48..3919a2d5b9 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -65,7 +65,8 @@
# server from advertising multiple client support (since 5.2;
# default: 0).
#
-# Returns: error if the server is already running.
+# Errors:
+# - if the server is already running
#
# Since: 1.3
##
@@ -247,8 +248,9 @@
# @deprecated: This command is deprecated. Use @block-export-add
# instead.
#
-# Returns: error if the server is not running, or export with the same
-# name already exists.
+# Errors:
+# - if the server is not running
+# - if an export with the same name already exists
#
# Since: 1.3
##
@@ -294,11 +296,10 @@
# @deprecated: This command is deprecated. Use @block-export-del
# instead.
#
-# Returns: error if
-#
-# - the server is not running
-# - export is not found
-# - mode is 'safe' and there are existing connections
+# Errors:
+# - if the server is not running
+# - if export is not found
+# - if mode is 'safe' and there are existing connections
#
# Since: 2.12
##
@@ -415,8 +416,10 @@
# @mode: Mode of command operation. See @BlockExportRemoveMode
# description. Default is 'safe'.
#
-# Returns: Error if the export is not found or @mode is 'safe' and the
-# export is still in use (e.g. by existing client connections)
+# Errors:
+# - if the export is not found
+# - if @mode is 'safe' and the export is still in use (e.g. by
+# existing client connections)
#
# Since: 5.2
##
diff --git a/qapi/block.json b/qapi/block.json
index 79a0bcc208..dab616799a 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -112,6 +112,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
# Notes: Ejecting a device with no media results in success
@@ -461,6 +463,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
# Since: 1.1
@@ -540,8 +544,8 @@
# @boundaries-flush: list of interval boundary values for flush
# latency histogram.
#
-# Returns: error if device is not found or any boundary arrays are
-# invalid.
+# Errors:
+# - if device is not found or any boundary arrays are invalid.
#
# Since: 4.0
#
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 2c5dda735e..db6c0fae98 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -154,10 +154,13 @@
# Some architectures may not support comparing CPU models. s390x
# supports comparing CPU models.
#
-# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU
-# models is not supported, if a model cannot be used, if a model
-# contains an unknown cpu definition name, unknown properties or
-# properties with wrong types.
+# Returns: a CpuModelBaselineInfo
+#
+# Errors:
+# - if comparing CPU models is not supported
+# - if a model cannot be used
+# - if a model contains an unknown cpu definition name, unknown
+# properties or properties with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
# on this architecture currently.
@@ -201,10 +204,13 @@
# Some architectures may not support baselining CPU models. s390x
# supports baselining CPU models.
#
-# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU
-# models is not supported, if a model cannot be used, if a model
-# contains an unknown cpu definition name, unknown properties or
-# properties with wrong types.
+# Returns: a CpuModelBaselineInfo
+#
+# Errors:
+# - if baselining CPU models is not supported
+# - if a model cannot be used
+# - if a model contains an unknown cpu definition name, unknown
+# properties or properties with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
# on this architecture currently.
@@ -263,11 +269,14 @@
# Some architectures may not support all expansion types. s390x
# supports "full" and "static". Arm only supports "full".
#
-# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU
-# models is not supported, if the model cannot be expanded, if the
-# model contains an unknown CPU definition name, unknown
-# properties or properties with a wrong type. Also returns an
-# error if an expansion type is not supported.
+# Returns: a CpuModelExpansionInfo
+#
+# Errors:
+# - if expanding CPU models is not supported
+# - if the model cannot be expanded
+# - if the model contains an unknown CPU definition name, unknown
+# properties or properties with a wrong type
+# - if an expansion type is not supported
#
# Since: 2.8
##
diff --git a/qapi/machine.json b/qapi/machine.json
index 93b4677286..0985c61740 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1062,6 +1062,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If the balloon driver is enabled but not functional because
# the KVM kernel module cannot support it, KVMMissingCap
# - If no balloon device is present, DeviceNotActive
@@ -1100,6 +1102,8 @@
#
# Returns:
# - @BalloonInfo on success
+#
+# Errors:
# - If the balloon driver is enabled but not functional because
# the KVM kernel module cannot support it, KVMMissingCap
# - If no balloon device is present, DeviceNotActive
@@ -1164,6 +1168,8 @@
#
# Returns:
# - @HvBalloonInfo on success
+#
+# Errors:
# - If no hv-balloon device is present, guest memory status
# reporting is not enabled or no guest memory status report
# received yet, GenericError
diff --git a/qapi/misc.json b/qapi/misc.json
index 11c55c2b6c..578f574a68 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -345,6 +345,8 @@
#
# Returns:
# - @AddfdInfo on success
+#
+# Errors:
# - If file descriptor was not received, GenericError
# - If @fdset-id is a negative value, GenericError
#
@@ -376,6 +378,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @fdset-id or @fd is not found, GenericError
#
# Since: 1.2
@@ -528,8 +532,10 @@
# @option: option name
#
# Returns: list of @CommandLineOptionInfo for all options (or for the
-# given @option). Returns an error if the given @option doesn't
-# exist.
+# given @option).
+#
+# Errors:
+# - if the given @option doesn't exist
#
# Since: 1.5
#
diff --git a/qapi/net.json b/qapi/net.json
index 1374caac64..09e644a742 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -19,6 +19,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @name is not a valid network device, DeviceNotFound
#
# Since: 0.14
@@ -46,6 +48,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @type is not a valid network backend, DeviceNotFound
#
# Example:
@@ -67,6 +71,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @id is not a valid network backend, DeviceNotFound
#
# Since: 0.14
@@ -828,9 +834,11 @@
# @name: net client name
#
# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
-# Returns an error if the given @name doesn't exist, or given NIC
-# doesn't support rx-filter querying, or given net client isn't a
-# NIC.
+#
+# Errors:
+# - if the given @name doesn't exist
+# - if the given NIC doesn't support rx-filter querying
+# - if the given net client isn't a NIC
#
# Since: 1.6
#
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 32ffaee644..cc72c55a99 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -91,6 +91,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @id is not a valid device, DeviceNotFound
#
# Notes: When this command completes, the device may not be removed
diff --git a/qapi/qom.json b/qapi/qom.json
index 2a6e49365a..33aa30bb41 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -1058,6 +1058,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - Error if @qom-type is not a valid class name
#
# Since: 2.0
@@ -1081,6 +1083,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - Error if @id is not a valid id for a QOM object
#
# Since: 2.0
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 45233ddd2a..78cc21800d 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -236,7 +236,8 @@
#
# Returns: nothing on success
#
-# Errors depend on the operations of the transaction
+# Errors:
+# Any errors from commands in the transaction
#
# Note: The transaction aborts on the first failure. Therefore, there
# will be information on only one failed operation returned in an
diff --git a/qapi/ui.json b/qapi/ui.json
index e3999b7c07..199a412c5a 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -80,6 +80,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If Spice is not enabled, DeviceNotFound
#
# Since: 0.14
@@ -142,6 +144,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If @protocol is 'spice' and Spice is not active,
# DeviceNotFound
#
@@ -1038,6 +1042,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - If key is unknown or redundant, GenericError
#
# Since: 1.3
diff --git a/qapi/yank.json b/qapi/yank.json
index b7aeb9ceef..a457284b45 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -80,6 +80,8 @@
#
# Returns:
# - Nothing on success
+#
+# Errors:
# - @DeviceNotFound error, if any of the YankInstances doesn't exist
#
# Example:
--
2.44.0