From nobody Wed Dec 17 21:59:24 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1527081709474462.15608398632844; Wed, 23 May 2018 06:21:49 -0700 (PDT) Received: from localhost ([::1]:33345 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fLTi8-00009Y-Lq for importer@patchew.org; Wed, 23 May 2018 09:21:48 -0400 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 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:43384 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fLTYm-0006oP-Dg; Wed, 23 May 2018 09:12:08 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 013818182D27; Wed, 23 May 2018 13:12:08 +0000 (UTC) Received: from localhost.localdomain.com (unknown [10.36.118.16]) by smtp.corp.redhat.com (Postfix) with ESMTP id 535A48578B; Wed, 23 May 2018 13:12:07 +0000 (UTC) From: Kevin Wolf To: qemu-block@nongnu.org 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> X-Scanned-By: MIMEDefang 2.79 on 10.11.54.5 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Wed, 23 May 2018 13:12:08 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Wed, 23 May 2018 13:12:08 +0000 (UTC) for IP:'10.11.54.5' DOMAIN:'int-mx05.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'kwolf@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PULL 08/46] blockjob: Improve BlockJobInfo.offset/len documentation X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: kwolf@redhat.com, qemu-devel@nongnu.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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 c= an +# 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) --=20 2.13.6