From: Kent Overstreet <kent.overstreet@linux.dev>
To: axboe@kernel.dk, linux-kernel@vger.kernel.org,
linux-block@vger.kernel.org
Cc: Kent Overstreet <kent.overstreet@linux.dev>,
Ming Lei <ming.lei@redhat.com>
Subject: [PATCH v2 3/5] block: Add documentation for bio iterator macros
Date: Mon, 5 Jun 2023 17:27:15 -0400 [thread overview]
Message-ID: <20230605212717.2570570-3-kent.overstreet@linux.dev> (raw)
In-Reply-To: <20230605212717.2570570-1-kent.overstreet@linux.dev>
We've now got 3x2 interfaces for iterating over bios: by page, by bvec,
or by folio, and variants that iterate over what bi_iter points to, or
the entire bio as created by the filesystem/originator.
This adds more detailed kerneldoc comments for each variant.
Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Ming Lei <ming.lei@redhat.com>
Cc: linux-block@vger.kernel.org
---
include/linux/bio.h | 54 ++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 48 insertions(+), 6 deletions(-)
diff --git a/include/linux/bio.h b/include/linux/bio.h
index 4b197ea83c..f599bcf15e 100644
--- a/include/linux/bio.h
+++ b/include/linux/bio.h
@@ -97,9 +97,14 @@ static inline void bio_iter_all_advance(const struct bio *bio,
((bvl = bio_iter_all_peek(bio, &iter)), true); \
bio_iter_all_advance((bio), &iter, bvl.bv_len))
-/*
- * drivers should _never_ use the all version - the bio may have been split
- * before it got to the driver and the driver won't own all of it
+/**
+ * bio_for_each_segment_all - iterate over single pages in a bio
+ *
+ * Like other _all versions, this is for the filesystem, or the owner/creator of
+ * a bio; it iterates over the original contents of a bio.
+ *
+ * Drivers that are working with bios that were submitted to them should not use
+ * the _all version.
*/
#define bio_for_each_segment_all(bvl, bio, iter) \
for (bvec_iter_all_init(&iter); \
@@ -160,6 +165,13 @@ static inline void bio_advance(struct bio *bio, unsigned int nbytes)
((bvl = bio_iter_iovec((bio), (iter))), 1); \
bio_advance_iter_single((bio), &(iter), (bvl).bv_len))
+/**
+ * bio_for_each_segment - iterate over single pages in a bio
+ *
+ * Like other non-_all versions, this iterates over what bio->bi_iter currently
+ * points to. This version is for drivers, where the bio may have previously
+ * been split or cloned.
+ */
#define bio_for_each_segment(bvl, bio, iter) \
__bio_for_each_segment(bvl, bio, iter, (bio)->bi_iter)
@@ -200,6 +212,13 @@ static inline struct folio_seg bio_iter_iovec_folio(struct bio *bio,
((fs = bio_iter_iovec_folio((bio), (iter))), 1); \
bio_advance_iter_single((bio), &(iter), (fs).fs_len))
+/**
+ * bio_for_each_folio - iterate over folios within a bio
+ *
+ * Like other non-_all versions, this iterates over what bio->bi_iter currently
+ * points to. This version is for drivers, where the bio may have previously
+ * been split or cloned.
+ */
#define bio_for_each_folio(fs, bio, iter) \
__bio_for_each_folio(fs, bio, iter, (bio)->bi_iter)
@@ -209,13 +228,30 @@ static inline struct folio_seg bio_iter_iovec_folio(struct bio *bio,
((bvl = mp_bvec_iter_bvec((bio)->bi_io_vec, (iter))), 1); \
bio_advance_iter_single((bio), &(iter), (bvl).bv_len))
-/* iterate over multi-page bvec */
+/**
+ * bio_for_each_bvec - iterate over bvecs within a bio
+ *
+ * This version iterates over entire bio_vecs, which will be a range of
+ * contiguous pages.
+ *
+ * Like other non-_all versions, this iterates over what bio->bi_iter currently
+ * points to. This version is for drivers, where the bio may have previously
+ * been split or cloned.
+ */
#define bio_for_each_bvec(bvl, bio, iter) \
__bio_for_each_bvec(bvl, bio, iter, (bio)->bi_iter)
/*
- * Iterate over all multi-page bvecs. Drivers shouldn't use this version for the
- * same reasons as bio_for_each_segment_all().
+ * bio_for_each_bvec_all - iterate over bvecs within a bio
+ *
+ * This version iterates over entire bio_vecs, which will be a range of
+ * contiguous pages.
+ *
+ * Like other _all versions, this is for the filesystem, or the owner/creator of
+ * a bio; it iterates over the original contents of a bio.
+ *
+ * Drivers that are working with bios that were submitted to them should not use
+ * the _all version.
*/
#define bio_for_each_bvec_all(bvl, bio, i) \
for (i = 0, bvl = bio_first_bvec_all(bio); \
@@ -321,6 +357,12 @@ static inline struct folio_seg bio_folio_iter_all_peek(const struct bio *bio,
* bio_for_each_folio_all - Iterate over each folio in a bio.
* @fi: struct bio_folio_iter_all which is updated for each folio.
* @bio: struct bio to iterate over.
+ *
+ * Like other _all versions, this is for the filesystem, or the owner/creator of
+ * a bio; it iterates over the original contents of a bio.
+ *
+ * Drivers that are working with bios that were submitted to them should not use
+ * the _all version.
*/
#define bio_for_each_folio_all(fs, bio, iter) \
for (bvec_iter_all_init(&iter); \
--
2.40.1
next prev parent reply other threads:[~2023-06-05 21:27 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-06-05 21:27 [PATCH v2 1/5] block: Rework bio_for_each_segment_all() Kent Overstreet
2023-06-05 21:27 ` [PATCH v2 2/5] block: Rework bio_for_each_folio_all() Kent Overstreet
2023-06-05 21:27 ` Kent Overstreet [this message]
2023-06-05 21:27 ` [PATCH v2 4/5] block: Change memcpy_(to|from)_bvec to pass bvec by value Kent Overstreet
2023-06-06 7:31 ` kernel test robot
2023-06-05 21:27 ` [PATCH v2 5/5] block: CONFIG_BLK_DEBUG Kent Overstreet
2023-06-05 22:41 ` Randy Dunlap
2023-06-06 2:03 ` [PATCH v2 1/5] block: Rework bio_for_each_segment_all() Ming Lei
2023-06-06 7:29 ` Kent Overstreet
2023-06-09 20:44 ` Kent Overstreet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230605212717.2570570-3-kent.overstreet@linux.dev \
--to=kent.overstreet@linux.dev \
--cc=axboe@kernel.dk \
--cc=linux-block@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=ming.lei@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).