block: update docs for bio and bvec_iter
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
@@ -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
@@ -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]>
Quoted 2 lines · Andreas Hindborg
The documentation for bio and
bvec_iterrefers to a vector namedbvl_vec. This does not exis. Update the documentation comment with the correct name.
s/exis/exist
Quoted 2 lines
Signed-off-by Andreas Hindborg <[email protected]>
Other than the above nit,
Signature · 2 lines
Damien Le Moal Western Digital Research
Quoted 14 lines · Andreas Hindborg
The documentation for bio and
bvec_iterrefers to a vector namedbvl_vec. This does not exis. Update the documentation comment with the correct name.Signed-off-by Andreas Hindborg <[email protected]>--- 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
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
-0atomic_t __bi_cnt;/* pin count */ include/linux/bvec.h +1
-1@@ -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;
}Quoted 24 lines · Christoph Hellwig
Quoted 14 lines · Andreas Hindborg
The documentation for bio and
bvec_iterrefers to a vector namedbvl_vec. This does not exis. Update the documentation comment with the correct name.Signed-off-by Andreas Hindborg <[email protected]>--- include/linux/blk_types.h | 2 +- include/linux/bvec.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)include/linux/blk_types.h +0
-0include/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 inbi_io_vecthat were allocated for this bio.
* Only used by the bio submitter to makebio_add_pagefail once full
* and freeing thebi_io_vecallocation. 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
-0atomic_t __bi_cnt;/* pin count */ include/linux/bvec.h +0
-0@@ -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_itercan 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