Skip to contentSkip to conversation

block: update docs for bio and bvec_iter

PATCH Superseded Andreas Hindborg 3 participants 4 messages Feb 12 – Feb 14 Block layer

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 block: update docs for bio and bvec_iter

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.

---
 include/linux/blk_types.h | 2 +-
 include/linux/bvec.h      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
include/linux/blk_types.h +1 -1
index 5dc061d318a45..10403145a4510 100644
@@ -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 */
 
include/linux/bvec.h +1 -1
index 3fc0efa0825b1..a05e792e6c216 100644
@@ -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,

Signature · 1 line
Andreas Hindborg <[email protected]>
#2 lore raw
In reply to Andreas Hindborg
Quoted 14 lines · 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.

---
 include/linux/blk_types.h | 2 +-
 include/linux/bvec.h      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
include/linux/blk_types.h +0 -0
index 5dc061d318a45..10403145a4510 100644

include/linux/blk_types.h struct bio { · line 274

Quoted 5 lines
include/linux/blk_types.h +1 -1
@@ -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.
*/

include/linux/bvec.h struct bvec_iter { · line 82

Quoted 13 lines
include/linux/blk_types.h +0 -0
 	atomic_t		__bi_cnt;	/* pin count */
 
include/linux/bvec.h +1 -1
index 3fc0efa0825b1..a05e792e6c216 100644
@@ -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;
}
#3 lore raw
Quoted 24 lines · Christoph Hellwig
Quoted 14 lines · 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.

---
 include/linux/blk_types.h | 2 +-
 include/linux/bvec.h      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
include/linux/blk_types.h +0 -0
index 5dc061d318a45..10403145a4510 100644

include/linux/blk_types.h struct bio { · line 274

Quoted 5 lines
include/linux/blk_types.h +1 -1
@@ -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:

Quoted 6 lines

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

Quoted 12 lines
Quoted 12 lines
include/linux/blk_types.h +0 -0
 	atomic_t		__bi_cnt;	/* pin count */
 
include/linux/bvec.h +0 -0
index 3fc0efa0825b1..a05e792e6c216 100644
@@ -79,7 +79,7 @@ struct bvec_iter {
 						   sectors */
 	unsigned int		bi_size;	/* residual I/O count */
 
Quoted 8 lines

include/linux/bvec.h struct bvec_iter { · line 82

Quoted 2 lines
include/linux/bvec.h +1 -1
-	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.

Quoted 24 lines

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.
Quoted 8 lines
	 */
	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