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

[PATCH v2] 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 exist. Update the documentation comment with correct use.

Also update documentation comments for remaining fields of `bvec_iter` to
improve readability.

The fields of `bvec_iter` is using a mix of tabs and spaces for
indentation. While at it, change them all to tabs, which is most prevalent
in this struct definition.

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
Changes in v2:
- Update documentation changes with input from Christoph.
- Change indentation of `bvec_iter`.
- Link to v1: https://msgid.link/20260212-bvec_iter-docs-v1-1-888607db0ddc@kernel.org
---
 include/linux/blk_types.h |  8 +++++++-
 include/linux/bvec.h      | 29 +++++++++++++++++++++--------
 2 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/include/linux/blk_types.h b/include/linux/blk_types.h
index 5dc061d318a45..261a692b10351 100644
--- a/include/linux/blk_types.h
+++ b/include/linux/blk_types.h
@@ -271,7 +271,13 @@ 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 */
+	/*
+	 * 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 to free the `bi_io_vec` allocation. Must not be used in drivers
+	 * and does not hold a useful value for cloned bios.
+	 */
+	unsigned short		bi_max_vecs;
 
 	atomic_t		__bi_cnt;	/* pin count */
 
diff --git a/include/linux/bvec.h b/include/linux/bvec.h
index 3fc0efa0825b1..06fb60471aaf1 100644
--- a/include/linux/bvec.h
+++ b/include/linux/bvec.h
@@ -75,14 +75,27 @@ static inline void bvec_set_virt(struct bio_vec *bv, void *vaddr,
 }
 
 struct bvec_iter {
-	sector_t		bi_sector;	/* device address in 512 byte
-						   sectors */
-	unsigned int		bi_size;	/* residual I/O count */
-
-	unsigned int		bi_idx;		/* current index into bvl_vec */
-
-	unsigned int            bi_bvec_done;	/* number of bytes completed in
-						   current bvec */
+	/*
+	 * 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. This indexes into `bi_io_vec` when
+	 * iterating a bvec array that is part of a `bio`.
+	 */
+	unsigned int		bi_idx;
+
+	/*
+	 * Current offset in the bvec entry pointed to by `bi_idx`.
+	 */
+	unsigned int		bi_bvec_done;
 } __packed __aligned(4);
 
 struct bvec_iter_all {

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

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

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

[Jens Axboe]

On Sat, 14 Feb 2026 10:12:54 +0100, Andreas Hindborg wrote:
> The documentation for bio and bvec_iter refers to a vector named bvl_vec.
> This does not exist. Update the documentation comment with correct use.
> 
> Also update documentation comments for remaining fields of `bvec_iter` to
> improve readability.
> 
> The fields of `bvec_iter` is using a mix of tabs and spaces for
> indentation. While at it, change them all to tabs, which is most prevalent
> in this struct definition.
> 
> [...]

Applied, thanks!

[1/1] block: update docs for bio and bvec_iter
      commit: 11506b3c233fcead6eba2842d17ec29c84f550d4

Best regards,
-- 
Jens Axboe