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 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>
Signed-off-by: Jens Axboe <axboe@kernel.dk>

diff --git a/include/linux/blk_types.h b/include/linux/blk_types.h
index d59553324a84be260ba77fedaaba1007e9d952df..397602606f7437d6905cd2e21047b659119b255a 100644 (file)
--- a/include/linux/blk_types.h
+++ b/include/linux/blk_types.h
@@ -273,7 +273,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 3fc0efa0825b159982e1ada5321f469615af1693..06fb60471aaf1245283ebc8e13afa9828bbe7f34 100644 (file)
--- 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 {