[PATCH] block: update docs for bio and bvec_iter

[PATCH] block: update docs for bio and bvec_iter

[Andreas Hindborg]

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@kernel.org>
---
 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 */
 
 	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 */
 
 	unsigned int            bi_bvec_done;	/* number of bytes completed in
 						   current bvec */

---
base-commit: 05f7e89ab9731565d8a62e3b5d1ec206485eeb0b
change-id: 20260212-bvec_iter-docs-ceb3f7208d06

Best regards,
-- 
Andreas Hindborg <a.hindborg@kernel.org>

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

[Damien Le Moal]

On 2/13/26 02:17, 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.

s/exis/exist

> 
> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>

Other than the above nit,

Reviewed-by: Damien Le Moal <dlemoal@kernel.org>

-- 
Damien Le Moal
Western Digital Research

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

[Christoph Hellwig]

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@kernel.org>
> ---
>  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.
	 */

>  
>  	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;

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;
}

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

[Andreas Hindborg]

Christoph Hellwig <hch@infradead.org> 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@kernel.org>
>> ---
>>  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