mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qapi: Move error documentation to new "Errors" sections

Browse Source 
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-5-armbru@redhat.com>
This commit is contained in:
Markus Armbruster 2024-02-27 12:39:12 +01:00
parent 3a025d3d1f
commit 2746f060be
12 changed files with 126 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
qapi/block-core.json
View File

@ -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,

23
qapi/block-export.json
View File

@ -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
##

8
qapi/block.json
View File

@ -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
#

35
qapi/machine-target.json
View File

@ -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
##

6
qapi/machine.json
View File

@ -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

10
qapi/misc.json
View File

@ -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
#

14
qapi/net.json
View File

@ -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
#

2
qapi/qdev.json
View File

@ -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

4
qapi/qom.json
View File

@ -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

3
qapi/transaction.json
View File

@ -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

6
qapi/ui.json
View File

@ -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

2
qapi/yank.json
View File

@ -80,6 +80,8 @@
#
# Returns:
# - Nothing on success
#
# Errors:
# - @DeviceNotFound error, if any of the YankInstances doesn't exist
#
# Example: