From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:52689) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fLTYx-0001m0-Kv for qemu-devel@nongnu.org; Wed, 23 May 2018 09:12:21 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fLTYr-0006sF-TU for qemu-devel@nongnu.org; Wed, 23 May 2018 09:12:19 -0400 From: Kevin Wolf Date: Wed, 23 May 2018 15:11:17 +0200 Message-Id: <20180523131155.12359-9-kwolf@redhat.com> In-Reply-To: <20180523131155.12359-1-kwolf@redhat.com> References: <20180523131155.12359-1-kwolf@redhat.com> Subject: [Qemu-devel] [PULL 08/46] blockjob: Improve BlockJobInfo.offset/len documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-block@nongnu.org Cc: kwolf@redhat.com, qemu-devel@nongnu.org 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 Reviewed-by: Eric Blake Reviewed-by: John Snow --- 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 d32ec95666..0e29abf099 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) -- 2.13.6