From 82c4f0c7c192af2c7db4b7d4ca6ab3454e4b25f5 Mon Sep 17 00:00:00 2001
From: Kevin Wolf <kwolf@redhat.com>
Date: Tue, 26 Jun 2018 09:47:58 +0200
Subject: [PATCH 090/268] blockjob: Improve BlockJobInfo.offset/len
documentation
RH-Author: Kevin Wolf <kwolf@redhat.com>
Message-id: <20180626094856.6924-16-kwolf@redhat.com>
Patchwork-id: 81087
O-Subject: [RHV-7.6 qemu-kvm-rhev PATCH v2 15/73] blockjob: Improve BlockJobInfo.offset/len documentation
Bugzilla: 1513543
RH-Acked-by: Jeffrey Cody <jcody@redhat.com>
RH-Acked-by: Max Reitz <mreitz@redhat.com>
RH-Acked-by: Fam Zheng <famz@redhat.com>
Clarify that len is just an estimation of the end value of offset, and
that offset increases monotonically while len can change arbitrarily.
While touching the documentation of offset, move it directly after len
to match the order of the declaration below.
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
(cherry picked from commit a81e0a825e3b89039a427bca037112f461b95fec)
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
---
qapi/block-core.json | 9 ++++++---
1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 31bf64a..2b4566f 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1148,7 +1148,12 @@
# @device: The job identifier. Originally the device name but other
# values are allowed since QEMU 2.7
#
-# @len: the maximum progress value
+# @len: Estimated @offset value at the completion of the job. This value can
+# arbitrarily change while the job is running, in both directions.
+#
+# @offset: Progress made until now. The unit is arbitrary and the value can
+# only meaningfully be used for the ratio of @offset to @len. The
+# value is monotonically increasing.
#
# @busy: false if the job is known to be in a quiescent state, with
# no pending I/O. Since 1.3.
@@ -1156,8 +1161,6 @@
# @paused: whether the job is paused or, if @busy is true, will
# pause itself as soon as possible. Since 1.3.
#
-# @offset: the current progress value
-#
# @speed: the rate limit, bytes per second
#
# @io-status: the status of the job (since 1.3)
--
1.8.3.1