[PATCH v2 0/2] derpecate some block-job- APIs

[PATCH v2 0/2] derpecate some block-job- APIs

[Vladimir Sementsov-Ogievskiy]

v2:
Update documentation: add patch 01

v1 was:
[PATCH] [for-10.1] qapi/block-core: derpecate some block-job- APIs
Supersedes: <20250401155730.103718-1-vsementsov@yandex-team.ru>

Vladimir Sementsov-Ogievskiy (2):
  qapi: synchronize jobs and block-jobs documentation
  qapi/block-core: derpecate some block-job- APIs

 docs/about/deprecated.rst | 31 ++++++++++++++
 qapi/block-core.json      | 89 ++++++++++++++++++++++++++++-----------
 qapi/job.json             | 29 ++++++++++++-
 3 files changed, 122 insertions(+), 27 deletions(-)

-- 
2.48.1

[PATCH v2 1/2] qapi: synchronize jobs and block-jobs documentation

[Vladimir Sementsov-Ogievskiy]

Actualize documentation and synchronize it for commands which actually
call the same functions internally.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 qapi/block-core.json | 59 +++++++++++++++++++++++++-------------------
 qapi/job.json        | 29 ++++++++++++++++++++--
 2 files changed, 61 insertions(+), 27 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index b1937780e1..d74a1f8b8b 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2956,13 +2956,14 @@
 #
 # Pause an active background block operation.
 #
-# This command returns immediately after marking the active background
-# block operation for pausing.  It is an error to call this command if
-# no operation is in progress or if the job is already paused.
+# This command returns immediately after marking the active job for
+# pausing.  Pausing an already paused job is an error.
+#
+# The job will pause as soon as possible, which means transitioning
+# into the PAUSED state if it was RUNNING, or into STANDBY if it was
+# READY.  The corresponding JOB_STATUS_CHANGE event will be emitted.
 #
-# The operation will pause as soon as possible.  No event is emitted
-# when the operation is actually paused.  Cancelling a paused job
-# automatically resumes it.
+# Cancelling a paused job automatically resumes it.
 #
 # @device: The job identifier.  This used to be a device name (hence
 #     the name of the parameter), but since QEMU 2.7 it can have other
@@ -2982,9 +2983,8 @@
 #
 # Resume an active background block operation.
 #
-# This command returns immediately after resuming a paused background
-# block operation.  It is an error to call this command if no
-# operation is in progress or if the job is not paused.
+# This command returns immediately after resuming a paused job.
+# Resuming an already running job is an error.
 #
 # This command also clears the error status of the job.
 #
@@ -3004,10 +3004,14 @@
 ##
 # @block-job-complete:
 #
-# Manually trigger completion of an active background block operation.
-# This is supported for drive mirroring, where it also switches the
-# device to write to the target path only.  The ability to complete is
-# signaled with a BLOCK_JOB_READY event.
+# Manually trigger completion of an active job in the READY or STANDBY
+# state.  Completing the job in any other state is an error.
+#
+# This is supported only for drive mirroring (which includes
+# drive-mirror, blockdev-mirror and block-commit job (only in case of
+# "active commit", when the node being commited is used by the guest)),
+# where it also switches the device to write to the target path only.
+# The ability to complete is signaled with a BLOCK_JOB_READY event.
 #
 # This command completes an active background block operation
 # synchronously.  The ordering of this command's return with the
@@ -3017,8 +3021,6 @@
 # rerror/werror arguments that were specified when starting the
 # operation.
 #
-# A cancelled or paused job cannot be completed.
-#
 # @device: The job identifier.  This used to be a device name (hence
 #     the name of the parameter), but since QEMU 2.7 it can have other
 #     values.
@@ -3035,10 +3037,12 @@
 ##
 # @block-job-dismiss:
 #
-# For jobs that have already concluded, remove them from the
-# block-job-query list.  This command only needs to be run for jobs
-# which were started with QEMU 2.12+ job lifetime management
-# semantics.
+# Deletes a job that is in the CONCLUDED state.  This command only
+# needs to be run explicitly for jobs that don't have automatic
+# dismiss enabled. In turn, automatic dismiss may be enabled only
+# for jobs that have @auto-dismiss option, which are drive-backup,
+# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and
+# block-stream.
 #
 # This command will refuse to operate on any job that has not yet
 # reached its terminal state, JOB_STATUS_CONCLUDED.  For jobs that
@@ -3055,12 +3059,17 @@
 ##
 # @block-job-finalize:
 #
-# Once a job that has manual=true reaches the pending state, it can be
-# instructed to finalize any graph changes and do any necessary
-# cleanup via this command.  For jobs in a transaction, instructing
-# one job to finalize will force ALL jobs in the transaction to
-# finalize, so it is only necessary to instruct a single member job to
-# finalize.
+# Instructs all jobs in a transaction (or a single job if it is not
+# part of any transaction) to finalize any graph changes and do any
+# necessary cleanup.  This command requires that all involved jobs are
+# in the PENDING state.
+#
+# For jobs in a transaction, instructing one job to finalize will
+# force ALL jobs in the transaction to finalize, so it is only
+# necessary to instruct a single member job to finalize.
+#
+# The command is applicable only to jobs which have @auto-finalize option
+# and only when this option is set to false.
 #
 # @id: The job identifier.
 #
diff --git a/qapi/job.json b/qapi/job.json
index cfc3beedd2..c8736f2a05 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -156,6 +156,9 @@
 # This command returns immediately after resuming a paused job.
 # Resuming an already running job is an error.
 #
+# This command also clears the error status for block-jobs (stream,
+# commit, mirror, backup).
+#
 # @id: The job identifier.
 #
 # Since: 3.0
@@ -184,7 +187,22 @@
 ##
 # @job-complete:
 #
-# Manually trigger completion of an active job in the READY state.
+# Manually trigger completion of an active job in the READY or STANDBY
+# state.  Completing the job in any other state is an error.
+#
+# This is supported only for drive mirroring (which includes
+# drive-mirror, blockdev-mirror and block-commit job (only in case of
+# "active commit", when the node being commited is used by the guest)),
+# where it also switches the device to write to the target path only.
+# The ability to complete is signaled with a BLOCK_JOB_READY event.
+#
+# This command completes an active background block operation
+# synchronously.  The ordering of this command's return with the
+# BLOCK_JOB_COMPLETED event is not defined.  Note that if an I/O error
+# occurs during the processing of this command: 1) the command itself
+# will fail; 2) the error will be processed according to the
+# rerror/werror arguments that were specified when starting the
+# operation.
 #
 # @id: The job identifier.
 #
@@ -197,7 +215,11 @@
 #
 # Deletes a job that is in the CONCLUDED state.  This command only
 # needs to be run explicitly for jobs that don't have automatic
-# dismiss enabled.
+# dismiss enabled. In turn, automatic dismiss may be enabled only
+# for jobs that have @auto-dismiss option, which are drive-backup,
+# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and
+# block-stream. And historically it's enabled by default for these
+# jobs.
 #
 # This command will refuse to operate on any job that has not yet
 # reached its terminal state, JOB_STATUS_CONCLUDED.  For jobs that
@@ -222,6 +244,9 @@
 # force ALL jobs in the transaction to finalize, so it is only
 # necessary to instruct a single member job to finalize.
 #
+# The command is applicable only to jobs which have @auto-finalize option
+# and only when this option is set to false.
+#
 # @id: The identifier of any job in the transaction, or of a job that
 #     is not part of any transaction.
 #
-- 
2.48.1

Re: [PATCH v2 1/2] qapi: synchronize jobs and block-jobs documentation

[Eric Blake]

On Fri, Apr 04, 2025 at 10:31:53PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> Actualize documentation and synchronize it for commands which actually
> call the same functions internally.
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
> ---
>  qapi/block-core.json | 59 +++++++++++++++++++++++++-------------------
>  qapi/job.json        | 29 ++++++++++++++++++++--
>  2 files changed, 61 insertions(+), 27 deletions(-)
>

Overall makes sense, but one thing jumped out at me:

>  # @block-job-complete:
>  #
> -# Manually trigger completion of an active background block operation.
> -# This is supported for drive mirroring, where it also switches the
> -# device to write to the target path only.  The ability to complete is
> -# signaled with a BLOCK_JOB_READY event.
> +# Manually trigger completion of an active job in the READY or STANDBY
> +# state.  Completing the job in any other state is an error.
> +#
> +# This is supported only for drive mirroring (which includes
> +# drive-mirror, blockdev-mirror and block-commit job (only in case of
> +# "active commit", when the node being commited is used by the guest)),
> +# where it also switches the device to write to the target path only.

The doubly-nested parenthetical feels long.  Is there a more concise
way of expressing the list of three commands, where one of the
commands only supports it in the special case of "active commit"?


-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH v2 1/2] qapi: synchronize jobs and block-jobs documentation

[Vladimir Sementsov-Ogievskiy]

On 07.04.25 18:28, Eric Blake wrote:
> On Fri, Apr 04, 2025 at 10:31:53PM +0300, Vladimir Sementsov-Ogievskiy wrote:
>> Actualize documentation and synchronize it for commands which actually
>> call the same functions internally.
>>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
>> ---
>>   qapi/block-core.json | 59 +++++++++++++++++++++++++-------------------
>>   qapi/job.json        | 29 ++++++++++++++++++++--
>>   2 files changed, 61 insertions(+), 27 deletions(-)
>>
> 
> Overall makes sense, but one thing jumped out at me:
> 
>>   # @block-job-complete:
>>   #
>> -# Manually trigger completion of an active background block operation.
>> -# This is supported for drive mirroring, where it also switches the
>> -# device to write to the target path only.  The ability to complete is
>> -# signaled with a BLOCK_JOB_READY event.
>> +# Manually trigger completion of an active job in the READY or STANDBY
>> +# state.  Completing the job in any other state is an error.
>> +#
>> +# This is supported only for drive mirroring (which includes
>> +# drive-mirror, blockdev-mirror and block-commit job (only in case of
>> +# "active commit", when the node being commited is used by the guest)),
>> +# where it also switches the device to write to the target path only.
> 
> The doubly-nested parenthetical feels long.  Is there a more concise
> way of expressing the list of three commands, where one of the
> commands only supports it in the special case of "active commit"?
> 

Probably, move the big "(...)" to the second sentence:

Note that drive mirroring includes [...] the guest).

-- 
Best regards,
Vladimir

Re: [PATCH v2 1/2] qapi: synchronize jobs and block-jobs documentation

[Markus Armbruster]

Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:

> Actualize documentation and synchronize it for commands which actually
> call the same functions internally.
>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
> ---
>  qapi/block-core.json | 59 +++++++++++++++++++++++++-------------------
>  qapi/job.json        | 29 ++++++++++++++++++++--
>  2 files changed, 61 insertions(+), 27 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index b1937780e1..d74a1f8b8b 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -2956,13 +2956,14 @@
>  #
>  # Pause an active background block operation.
>  #
> -# This command returns immediately after marking the active background
> -# block operation for pausing.  It is an error to call this command if
> -# no operation is in progress or if the job is already paused.
> +# This command returns immediately after marking the active job for
> +# pausing.  Pausing an already paused job is an error.
> +#
> +# The job will pause as soon as possible, which means transitioning
> +# into the PAUSED state if it was RUNNING, or into STANDBY if it was
> +# READY.  The corresponding JOB_STATUS_CHANGE event will be emitted.
>  #
> -# The operation will pause as soon as possible.  No event is emitted
> -# when the operation is actually paused.  Cancelling a paused job
> -# automatically resumes it.
> +# Cancelling a paused job automatically resumes it.
>  #
>  # @device: The job identifier.  This used to be a device name (hence
>  #     the name of the parameter), but since QEMU 2.7 it can have other
> @@ -2982,9 +2983,8 @@
>  #
>  # Resume an active background block operation.
>  #
> -# This command returns immediately after resuming a paused background
> -# block operation.  It is an error to call this command if no
> -# operation is in progress or if the job is not paused.
> +# This command returns immediately after resuming a paused job.
> +# Resuming an already running job is an error.
>  #
>  # This command also clears the error status of the job.
>  #
> @@ -3004,10 +3004,14 @@
>  ##
>  # @block-job-complete:
>  #
> -# Manually trigger completion of an active background block operation.
> -# This is supported for drive mirroring, where it also switches the
> -# device to write to the target path only.  The ability to complete is
> -# signaled with a BLOCK_JOB_READY event.
> +# Manually trigger completion of an active job in the READY or STANDBY
> +# state.  Completing the job in any other state is an error.
> +#
> +# This is supported only for drive mirroring (which includes
> +# drive-mirror, blockdev-mirror and block-commit job (only in case of
> +# "active commit", when the node being commited is used by the guest)),

I agree with Eric: needs a rephrasing to avoid the nested parenthesis.

> +# where it also switches the device to write to the target path only.
> +# The ability to complete is signaled with a BLOCK_JOB_READY event.
>  #
>  # This command completes an active background block operation
>  # synchronously.  The ordering of this command's return with the
> @@ -3017,8 +3021,6 @@
>  # rerror/werror arguments that were specified when starting the
>  # operation.
>  #
> -# A cancelled or paused job cannot be completed.
> -#
>  # @device: The job identifier.  This used to be a device name (hence
>  #     the name of the parameter), but since QEMU 2.7 it can have other
>  #     values.
> @@ -3035,10 +3037,12 @@
>  ##
>  # @block-job-dismiss:
>  #
> -# For jobs that have already concluded, remove them from the
> -# block-job-query list.  This command only needs to be run for jobs
> -# which were started with QEMU 2.12+ job lifetime management
> -# semantics.
> +# Deletes a job that is in the CONCLUDED state.  This command only
> +# needs to be run explicitly for jobs that don't have automatic
> +# dismiss enabled. In turn, automatic dismiss may be enabled only
> +# for jobs that have @auto-dismiss option, which are drive-backup,
> +# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and
> +# block-stream.
>  #
>  # This command will refuse to operate on any job that has not yet
>  # reached its terminal state, JOB_STATUS_CONCLUDED.  For jobs that
> @@ -3055,12 +3059,17 @@
>  ##
>  # @block-job-finalize:
>  #
> -# Once a job that has manual=true reaches the pending state, it can be
> -# instructed to finalize any graph changes and do any necessary
> -# cleanup via this command.  For jobs in a transaction, instructing
> -# one job to finalize will force ALL jobs in the transaction to
> -# finalize, so it is only necessary to instruct a single member job to
> -# finalize.
> +# Instructs all jobs in a transaction (or a single job if it is not
> +# part of any transaction) to finalize any graph changes and do any
> +# necessary cleanup.  This command requires that all involved jobs are
> +# in the PENDING state.
> +#
> +# For jobs in a transaction, instructing one job to finalize will
> +# force ALL jobs in the transaction to finalize, so it is only
> +# necessary to instruct a single member job to finalize.
> +#
> +# The command is applicable only to jobs which have @auto-finalize option
> +# and only when this option is set to false.
>  #
>  # @id: The job identifier.
>  #
> diff --git a/qapi/job.json b/qapi/job.json
> index cfc3beedd2..c8736f2a05 100644
> --- a/qapi/job.json
> +++ b/qapi/job.json
> @@ -156,6 +156,9 @@
>  # This command returns immediately after resuming a paused job.
>  # Resuming an already running job is an error.
>  #
> +# This command also clears the error status for block-jobs (stream,
> +# commit, mirror, backup).
> +#
>  # @id: The job identifier.
>  #
>  # Since: 3.0
> @@ -184,7 +187,22 @@
>  ##
>  # @job-complete:
>  #
> -# Manually trigger completion of an active job in the READY state.
> +# Manually trigger completion of an active job in the READY or STANDBY
> +# state.  Completing the job in any other state is an error.
> +#
> +# This is supported only for drive mirroring (which includes
> +# drive-mirror, blockdev-mirror and block-commit job (only in case of
> +# "active commit", when the node being commited is used by the guest)),
> +# where it also switches the device to write to the target path only.
> +# The ability to complete is signaled with a BLOCK_JOB_READY event.
> +#
> +# This command completes an active background block operation
> +# synchronously.  The ordering of this command's return with the
> +# BLOCK_JOB_COMPLETED event is not defined.  Note that if an I/O error
> +# occurs during the processing of this command: 1) the command itself
> +# will fail; 2) the error will be processed according to the
> +# rerror/werror arguments that were specified when starting the
> +# operation.
>  #
>  # @id: The job identifier.
>  #
> @@ -197,7 +215,11 @@
>  #
>  # Deletes a job that is in the CONCLUDED state.  This command only
>  # needs to be run explicitly for jobs that don't have automatic
> -# dismiss enabled.
> +# dismiss enabled. In turn, automatic dismiss may be enabled only
> +# for jobs that have @auto-dismiss option, which are drive-backup,
> +# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and
> +# block-stream. And historically it's enabled by default for these
> +# jobs.

Scratch "And historically"?

>  #
>  # This command will refuse to operate on any job that has not yet
>  # reached its terminal state, JOB_STATUS_CONCLUDED.  For jobs that
> @@ -222,6 +244,9 @@
>  # force ALL jobs in the transaction to finalize, so it is only
>  # necessary to instruct a single member job to finalize.
>  #
> +# The command is applicable only to jobs which have @auto-finalize option
> +# and only when this option is set to false.
> +#
>  # @id: The identifier of any job in the transaction, or of a job that
>  #     is not part of any transaction.
>  #

[PATCH v2 2/2] qapi/block-core: derpecate some block-job- APIs

[Vladimir Sementsov-Ogievskiy]

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.

ACKed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 docs/about/deprecated.rst | 31 +++++++++++++++++++++++++++++++
 qapi/block-core.json      | 30 ++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
index 76291fdfd6..afa7075051 100644
--- a/docs/about/deprecated.rst
+++ b/docs/about/deprecated.rst
@@ -148,6 +148,37 @@ 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 10.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 10.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 10.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 10.1)
+''''''''''''''''''''''''''''''''''
+
+Use ``job-dismiss`` instead.
+
+``block-job-finalize`` (since 10.1)
+'''''''''''''''''''''''''''''''''''
+
+Use ``job-finalize`` instead.
+
 ``query-migrationthreads`` (since 9.2)
 ''''''''''''''''''''''''''''''''''''''
 
diff --git a/qapi/block-core.json b/qapi/block-core.json
index d74a1f8b8b..aa2288d6fd 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2969,6 +2969,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
@@ -2976,6 +2981,7 @@
 # Since: 1.3
 ##
 { 'command': 'block-job-pause', 'data': { 'device': 'str' },
+  'features': ['deprecated'],
   'allow-preconfig': true }
 
 ##
@@ -2992,6 +2998,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
@@ -2999,6 +3010,7 @@
 # Since: 1.3
 ##
 { 'command': 'block-job-resume', 'data': { 'device': 'str' },
+  'features': ['deprecated'],
   'allow-preconfig': true }
 
 ##
@@ -3025,6 +3037,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
@@ -3032,6 +3049,7 @@
 # Since: 1.3
 ##
 { 'command': 'block-job-complete', 'data': { 'device': 'str' },
+  'features': ['deprecated'],
   'allow-preconfig': true }
 
 ##
@@ -3051,9 +3069,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 }
 
 ##
@@ -3073,9 +3097,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 }
 
 ##
-- 
2.48.1

Re: [PATCH v2 2/2] qapi/block-core: derpecate some block-job- APIs

[Eric Blake]

On Fri, Apr 04, 2025 at 10:31:54PM +0300, Vladimir Sementsov-Ogievskiy wrote:

In the subject line: s/derpecate/deprecate/

> 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

s/do check, is found job/checks whether the found job is/
s/This OK/This is 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

let's

>    difference in deprecated.txt. Still, for dismiss and finalize errors
>    are not documented at all, so be silent in deprecated.txt as well.
> 
> ACKed-by: Peter Krempa <pkrempa@redhat.com>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
> ---
>  docs/about/deprecated.rst | 31 +++++++++++++++++++++++++++++++
>  qapi/block-core.json      | 30 ++++++++++++++++++++++++++++++
>  2 files changed, 61 insertions(+)
> 
> diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
> index 76291fdfd6..afa7075051 100644
> --- a/docs/about/deprecated.rst
> +++ b/docs/about/deprecated.rst
> @@ -148,6 +148,37 @@ 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 10.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.

Typo fixes are minor, so:
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH v2 2/2] qapi/block-core: derpecate some block-job- APIs

[Markus Armbruster]

Typo in subject, make it "deprecate".

Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:

> 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.
>
> ACKed-by: Peter Krempa <pkrempa@redhat.com>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>

Reviewed-by: Markus Armbruster <armbru@redhat.com>