@@ -128,6 +128,75 @@ options are removed in favor of using explicit ``blockdev-create`` and
``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
details.
+``block-job-pause`` (since 9.1)
+'''''''''''''''''''''''''''''''
+
+Use ``job-pause`` instead. The only difference is that ``job-pause``
+always reports GenericError on failure when ``block-job-pause`` reports
+DeviceNotActive when block-job is not found.
+
+``block-job-resume`` (since 9.1)
+''''''''''''''''''''''''''''''''
+
+Use ``job-resume`` instead. The only difference is that ``job-resume``
+always reports GenericError on failure when ``block-job-resume`` reports
+DeviceNotActive when block-job is not found.
+
+``block-job-complete`` (since 9.1)
+''''''''''''''''''''''''''''''''''
+
+Use ``job-complete`` instead. The only difference is that ``job-complete``
+always reports GenericError on failure when ``block-job-complete`` reports
+DeviceNotActive when block-job is not found.
+
+``block-job-dismiss`` (since 9.1)
+'''''''''''''''''''''''''''''''''
+
+Use ``job-dismiss`` instead.
+
+``block-job-finalize`` (since 9.1)
+''''''''''''''''''''''''''''''''''
+
+Use ``job-finalize`` instead.
+
+``block-job-set-speed`` (since 9.1)
+'''''''''''''''''''''''''''''''''''
+
+Use ``job-change`` instead.
+
+``block-job-change`` (since 9.1)
+''''''''''''''''''''''''''''''''
+
+Use ``job-change`` instead.
+
+``block-job-cancel`` (since 9.1)
+''''''''''''''''''''''''''''''''
+
+Use ``job-cancel`` instead which correspond to
+``block-job-cancel`` (``force`` = true ). For special case of
+soft-cancelling mirror in ready state, use ``job-complete``
+(``no-block-replace`` = true ).
+
+``query-block-jobs`` (since 9.1)
+
+Use ``query-jobs`` instead. Per-field recommendations:
+
+``query-block-jobs`` ``device`` field: use ``query-jobs`` ``id`` field.
+
+``query-block-jobs`` ``len`` and ``offset`` fields: use ``query-jobs``
+``current-progress`` and ``total-progress`` fields.
+
+``query-block-jobs`` ``paused``, ``ready``:
+use ``qeury-jobs`` ``status``.
+
+``auto-finalize``, ``auto-dismiss``: these are parameters set by user
+on job creation and never changed. So, no reason to query them. No
+support in ``query-jobs``.
+
+``busy``: it actually means nothing for user, it's a mistake to rely on
+it. No support in ``query-jobs``.
+
+
Incorrectly typed ``device_add`` arguments (since 6.2)
''''''''''''''''''''''''''''''''''''''''''''''''''''''
@@ -143,8 +212,8 @@ all arguments passed to ``device_add`` are consistent with the documented
property types.
-``block-job-change`` and ``job-change`` argument ``type`` (since 9.1)
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+``job-change`` argument ``type`` (since 9.1)
+''''''''''''''''''''''''''''''''''''''''''''
QEMU can get job type from the job itself (by @id), @type field is redundant.
@@ -1422,9 +1422,15 @@
#
# Returns: a list of @BlockJobInfo for each active block job
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @query-jobs
+# instead.
+#
# Since: 1.1
##
{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'],
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -2875,6 +2881,11 @@
# @speed: the maximum speed, in bytes per second, or 0 for unlimited.
# Defaults to 0.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-change
+# instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
@@ -2883,6 +2894,7 @@
##
{ 'command': 'block-job-set-speed',
'data': { 'device': 'str', 'speed': 'int' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -2919,13 +2931,22 @@
# paused) instead of waiting for the destination to complete its
# final synchronization (since 1.3)
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-cancel
+# instead which correspond to block-job-cancel(force=true).
+# For special case of soft-cancelling mirror in ready state,
+# use job-complete(no-block-replace=true) instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
#
# Since: 1.1
##
-{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' },
+{ 'command': 'block-job-cancel',
+ 'features': ['deprecated'],
+ 'data': { 'device': 'str', '*force': 'bool' },
'allow-preconfig': true }
##
@@ -2945,6 +2966,11 @@
# the name of the parameter), but since QEMU 2.7 it can have other
# values.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-pause
+# instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
@@ -2952,6 +2978,7 @@
# Since: 1.3
##
{ 'command': 'block-job-pause', 'data': { 'device': 'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -2969,6 +2996,11 @@
# the name of the parameter), but since QEMU 2.7 it can have other
# values.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-resume
+# instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
@@ -2976,6 +3008,7 @@
# Since: 1.3
##
{ 'command': 'block-job-resume', 'data': { 'device': 'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -3000,6 +3033,11 @@
# the name of the parameter), but since QEMU 2.7 it can have other
# values.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-complete
+# instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
@@ -3007,6 +3045,7 @@
# Since: 1.3
##
{ 'command': 'block-job-complete', 'data': { 'device': 'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -3024,9 +3063,15 @@
#
# @id: The job identifier.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-dismiss
+# instead.
+#
# Since: 2.12
##
{ 'command': 'block-job-dismiss', 'data': { 'id': 'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -3041,9 +3086,15 @@
#
# @id: The job identifier.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-finalize
+# instead.
+#
# Since: 2.12
##
{ 'command': 'block-job-finalize', 'data': { 'id': 'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -3103,9 +3154,15 @@
#
# Change the block job's options.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-change
+# instead.
+#
# Since: 8.2
##
{ 'command': 'block-job-change',
+ 'features': ['deprecated'],
'data': 'JobChangeOptions', 'boxed': true }
##
For change, pause, resume, complete, dismiss and finalize actions corresponding job- and block-job commands are almost equal. The difference is in find_block_job_locked() vs find_job_locked() functions. What's different? 1. find_block_job_locked() do check, is found job a block-job. This OK when moving to more generic API, no needs to document this change. 2. find_block_job_locked() reports DeviceNotActive on failure, when find_job_locked() reports GenericError. So, lets document this difference in deprecated.txt. Still, for dismiss and finalize errors are not documented at all, so be silent in deprecated.txt as well. For cancel, we have a new solution about soft-cancelling mirror: job-complete(no-block-replace=true) For set-speed, the action is supported by job-change. For query, query-jobs is not equal to query-block-jobs, but now it has enough information (see documentation changes for details). Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> --- docs/about/deprecated.rst | 73 +++++++++++++++++++++++++++++++++++++-- qapi/block-core.json | 59 ++++++++++++++++++++++++++++++- 2 files changed, 129 insertions(+), 3 deletions(-)