On Tue, Apr 01, 2025 at 18:57:30 +0300, Vladimir Sementsov-Ogievskiy wrote:
> 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.
>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsement...@yandex-team.ru>
> ---
>
> Hi all!
>
> That's a continuation of my "[RFC 00/15] block job API"[1], exactly, the
> simplest part of it - deprecating block-job-* commands which simply
> duplicate job-* ones.
>
> Note that the old series was started with trying to introduce job-change
> command as substitution to both block-job-change (which only can change
> mirror copy-mode parameter), and block-job-set-speed. It was rather
> complicated and controversial attempt, which latest implemenation was
> "[PATCH v3 0/7] introduce job-change qmp command"[2].
>
> In [2] Kevin noted, that we'd better follow existing blockdev-reopen
> approach of changing options (i.e. specify all options) than introduce a
> new one. But, on the other hand, now I'm afraid, that rewriting in
> third tools simple call to (old good) block-job-set-speed into
> job-change(_all_options_ + changed speed) is too much work just for
> "having nice interface". And too much for the only two options we want
> to change.
>
> So, let's just start from something more obvious. Finally,
> we can simple keep block-job-set-speed and block-job-change as is,
> as they (unlike other block-job-* commands) are not duplicated by
> similar job-* commands.
>
> [1]
> https://patchew.org/QEMU/20240313150907.623462-1-vsement...@yandex-team.ru/
> [2]
> https://patchew.org/QEMU/20241002140616.561652-1-vsement...@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 e2b4f077d4..eed3356359 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.
> +
Libvirt uses only the following two with 'block-job-' prefix:
src/qemu/qemu_monitor_json.c: if (!(cmd =
qemuMonitorJSONMakeCommand("block-job-cancel",
src/qemu/qemu_monitor_json.c: if (!(cmd =
qemuMonitorJSONMakeCommand("block-job-set-speed",
thus on behalf of libvirt:
ACKed-by: Peter Krempa <pkre...@redhat.com>
