motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-05 16:53:55 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

qapi: synchronize jobs and block-jobs documentation

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

Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Message-ID: <20250409084232.28201-2-vsementsov@yandex-team.ru>
This commit is contained in:
Vladimir Sementsov-Ogievskiy 2025-04-09 11:42:30 +03:00
parent 68aba2a935
commit da17dd5c5e
2 changed files with 64 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

61
qapi/block-core.json
View file

@ -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 operation will pause as soon as possible. No event is emitted
# when the operation is actually paused. Cancelling a paused job
# automatically resumes it.
# 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.
#
# 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,15 @@
##
# @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, where it also switches
# the device to write to the target path only. Note that drive
# mirroring 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). 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 +3022,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 +3038,13 @@
##
# @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. @auto-dismiss is 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
@ -3055,12 +3061,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.
#

30
qapi/job.json
View file

@ -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,23 @@
##
# @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, where it also switches
# the device to write to the target path only. Note that drive
# mirroring 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). 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 +216,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. @auto-dismiss is 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 +245,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.
#