Re: [PATCH v2 3/6] block: Clarify that @bytes is no limit on *pnum

[Eric Blake <eblake@redhat.com>]

> > > +++ b/include/block/block_int.h
> > > @@ -347,6 +347,11 @@ struct BlockDriver {
> > >        * clamped to bdrv_getlength() and aligned to request_alignment,
> > >        * as well as non-NULL pnum, map, and file; in turn, the driver
> > >        * must return an error or set pnum to an aligned non-zero value.
> > > +     *
> > > +     * Note that @bytes is just a hint on how big of a region the
> > > +     * caller wants to inspect.  It is not a limit on *pnum.
> > > +     * Implementations are free to return larger values of *pnum if
> > > +     * doing so does not incur a performance penalty.
> > 
> > Worth mention that the cache will benefit of it?
> 
> Oh, right, absolutely.  Like so:
> 
> "block/io.c's bdrv_co_block_status() will clamp *pnum before returning it to
> its caller, but it itself can still make use of the unclamped *pnum value. 
> Specifically, the block-status cache for protocol nodes will benefit from
> storing as large a region as possible."

How about this tweak to the wording to make it flow a little better:

block/io.c's bdrv_co_block_status() will utilize an unclamped *pnum
value for the block-status cache on protocol nodes, prior to clamping
*pnum for return to its caller.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org