Re: [PATCH] block: update docs for bio and bvec_iter

[Andreas Hindborg]

Christoph Hellwig <hch@xxxxxxxxxxxxx> writes:

> On Thu, Feb 12, 2026 at 06:17:03PM +0100, Andreas Hindborg wrote:
>> The documentation for bio and bvec_iter refers to a vector named bvl_vec.
>> This does not exis. Update the documentation comment with the correct name.
>> 
>> Signed-off-by: Andreas Hindborg <a.hindborg@xxxxxxxxxx>
>> ---
>>  include/linux/blk_types.h | 2 +-
>>  include/linux/bvec.h      | 2 +-
>>  2 files changed, 2 insertions(+), 2 deletions(-)
>> 
>> diff --git a/include/linux/blk_types.h b/include/linux/blk_types.h
>> index 5dc061d318a45..10403145a4510 100644
>> --- a/include/linux/blk_types.h
>> +++ b/include/linux/blk_types.h
>> @@ -271,7 +271,7 @@ struct bio {
>>  	 * Everything starting with bi_max_vecs will be preserved by bio_reset()
>>  	 */
>>  
>> -	unsigned short		bi_max_vecs;	/* max bvl_vecs we can hold */
>> +	unsigned short		bi_max_vecs;	/* max count of bio_vec we can hold */
>
> If you want to touch it make it actually correct, as the story is
> rather complicated:
>
> 	/*
> 	 * Number of elements in bi_io_vec that were allocated for this bio.
> 	 * Only used by the bio submitter to make bio_add_page fail once full
> 	 * and freeing the bi_io_vec allocation.  Must not be used in drivers
> 	 * and does not hold a useful value for cloned bios.
> 	 */

Thanks, this is much more useful to the reader.

>
>>  
>>  	atomic_t		__bi_cnt;	/* pin count */
>>  
>> diff --git a/include/linux/bvec.h b/include/linux/bvec.h
>> index 3fc0efa0825b1..a05e792e6c216 100644
>> --- a/include/linux/bvec.h
>> +++ b/include/linux/bvec.h
>> @@ -79,7 +79,7 @@ struct bvec_iter {
>>  						   sectors */
>>  	unsigned int		bi_size;	/* residual I/O count */
>>  
>> -	unsigned int		bi_idx;		/* current index into bvl_vec */
>> +	unsigned int		bi_idx;		/* current index into bi_io_vec */
>
> Also not quite correct.  The bvec_iter can be used for bvec array that
> are not part of a bio. So more something like:
>
> 	/* current index into the bvec array */
> 	unsigned int		bi_idx;

Cool.

>
> Also to make this useful I think all the comments on the iter fields
> need a bit of polishing as the description is rather terse and often
> misleading.
>
> Maybe something like:
>
> struct bvec_iter {
> 	/*
> 	 * Current device address in 512 byte sectors.
> 	 * Only updated by the bio iter wrappers and not the bvec iterator
> 	 * helpers themselves.
> 	 */
> 	 sector_t		bi_sector;
>
> 	/*
> 	 * Remaining size in bytes.
> 	 */
> 	unsigned int		bi_size;
>
> 	/*
> 	 * Current index into the bvec array.  The actual current
> 	 * synthetic bvec is still offset from the caller provided entry
> 	 * by bio_bvec_done.
> 	 */
> 	unsigned int		bi_idx;
>
> 	/*
> 	 * Current offset in the bvec entry pointed to by by_idx.
> 	 */
> 	unsigned int            bi_bvec_done;
> }

I'll add these.


Best regards,
Andreas Hindborg