Re: [PATCH V10 16/19] block: document usage of bio iterator helpers

From
Omar Sandoval <osandov@osandov.com>
Date
2018-11-16 02:05:33
Also in
dm-devel, linux-bcache, linux-block, linux-btrfs, linux-ext4, linux-fsdevel, linux-mm, linux-xfs, lkml
Reply to
Ming Lei, 2018-11-15
On Thu, Nov 15, 2018 at 04:53:03PM +0800, Ming Lei wrote:
quoted hunk ↗ jump to hunk
Now multi-page bvec is supported, some helpers may return page by
page, meantime some may return segment by segment, this patch
documents the usage.

Cc: Dave Chinner <redacted>
Cc: Kent Overstreet <redacted>
Cc: Mike Snitzer <redacted>
Cc: <redacted>
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: <redacted>
Cc: Shaohua Li <shli@kernel.org>
Cc: <redacted>
Cc: <redacted>
Cc: David Sterba <dsterba@suse.com>
Cc: <redacted>
Cc: Darrick J. Wong <redacted>
Cc: <redacted>
Cc: Gao Xiang <redacted>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Theodore Ts'o <tytso@mit.edu>
Cc: <redacted>
Cc: Coly Li <redacted>
Cc: <redacted>
Cc: Boaz Harrosh <redacted>
Cc: Bob Peterson <redacted>
Cc: <redacted>
Signed-off-by: Ming Lei <redacted>
---
 Documentation/block/biovecs.txt | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.txt
index 25689584e6e0..bfafb70d0d9e 100644
--- a/Documentation/block/biovecs.txt
+++ b/Documentation/block/biovecs.txt
@@ -117,3 +117,29 @@ Other implications:
    size limitations and the limitations of the underlying devices. Thus
    there's no need to define ->merge_bvec_fn() callbacks for individual block
    drivers.
+
+Usage of helpers:
+=================
+
+* The following helpers whose names have the suffix of "_all" can only be used
+on non-BIO_CLONED bio, and usually they are used by filesystem code, and driver
+shouldn't use them because bio may have been split before they got to the driver:
Putting an english teacher hat on, this is quite the run-on sentence.
How about:

* The following helpers whose names have the suffix of "_all" can only be used
on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
shouldn't use them because the bio may have been split before it reached the
driver.

Maybe also an explanation of why the filesystem would want to use these?
quoted hunk ↗ jump to hunk
+	bio_for_each_segment_all()
+	bio_first_bvec_all()
+	bio_first_page_all()
+	bio_last_bvec_all()
+
+* The following helpers iterate over single-page bvec, and the local
+variable of 'struct bio_vec' or the reference records single-page IO
+vector during the itearation:

* The following helpers iterate over single-page bvecs. The passed 'struct
bio_vec' will contain a single-page IO vector during the iteration.
quoted hunk ↗ jump to hunk
+	bio_for_each_segment()
+	bio_for_each_segment_all()
+
+* The following helper iterates over multi-page bvec, and each bvec may
+include multiple physically contiguous pages, and the local variable of
+'struct bio_vec' or the reference records multi-page IO vector during the
+itearation:
* The following helper iterates over multi-page bvecs. Each bvec may
include multiple physically contiguous pages. The passed 'struct bio_vec' will
contain a multi-page IO vector during the iteration.
+	bio_for_each_bvec()
-- 
2.9.5
Thread (102 messages) 102 messages, 8 authors, last reply 2018-11-21
Keyboard shortcuts
hback out one level
jnext message in thread / next series-diff position
kprevious message in thread / previous series-diff position
ldrill in
Escclose help / fold thread tree
?toggle this help