From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:39080) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2GDj-0003q0-RR for qemu-devel@nongnu.org; Wed, 02 Jul 2014 04:48:57 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X2GDd-00011z-Md for qemu-devel@nongnu.org; Wed, 02 Jul 2014 04:48:51 -0400 Received: from mx1.redhat.com ([209.132.183.28]:29550) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2GDd-00011s-DF for qemu-devel@nongnu.org; Wed, 02 Jul 2014 04:48:45 -0400 Date: Wed, 2 Jul 2014 10:48:41 +0200 From: Kevin Wolf Message-ID: <20140702084841.GC5996@noname.str.redhat.com> References: <1403889855-5740-1-git-send-email-armbru@redhat.com> <1403889855-5740-4-git-send-email-armbru@redhat.com> <53B2EC11.70802@redhat.com> <87bnt8l0fl.fsf@blackfin.pond.sub.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87bnt8l0fl.fsf@blackfin.pond.sub.org> Subject: Re: [Qemu-devel] [PATCH v2 2.1 3/3] docs/qmp: Fix documentation of BLOCK_JOB_READY to match code List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Markus Armbruster Cc: wenchaoqemu@gmail.com, qemu-devel@nongnu.org, lcapitulino@redhat.com, stefanha@redhat.com, pbonzini@redhat.com Am 02.07.2014 um 08:49 hat Markus Armbruster geschrieben: > Eric Blake writes: > > > On 06/27/2014 11:24 AM, Markus Armbruster wrote: > >> Signed-off-by: Markus Armbruster > >> --- > >> docs/qmp/qmp-events.txt | 12 ++++++++++-- > >> 1 file changed, 10 insertions(+), 2 deletions(-) > >> > >> diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt > >> index 22fea58..44be891 100644 > >> --- a/docs/qmp/qmp-events.txt > >> +++ b/docs/qmp/qmp-events.txt > >> @@ -157,12 +157,20 @@ Emitted when a block job is ready to complete. > >> > >> Data: > >> > >> -- "device": device name (json-string) > >> +- "type": Job type (json-string; "stream" for image streaming > >> + "commit" for block commit) > >> +- "device": Device name (json-string) > >> +- "len": Maximum progress value (json-int) > >> +- "offset": Current progress value (json-int) > >> + On success this is equal to len. > >> + On failure this is less than len. > >> +- "speed": Rate limit, bytes per second (json-int) > >> > > > > Design question - if BLOCK_JOB_READY reports failure (that is, offset < > > len), are we still guaranteed to get a BLOCK_JOB_COMPLETED that also > > reports failure, or does 'query-blockjobs' completely forget about the > > job? > > Good one. It's underspecified, as far as I can tell. First step to fix > that is to find out what the code does. As far as I can see, BLOCK_JOB_READY implies success up to the point where the event was emitted. Should we document that len = offset in all cases? Perhaps add an assertion to block_job_event_ready(), too? Kevin