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

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