diff mbox series

[3/5] block: Document the bio_vec properties

Message ID 20200516001914.17138-4-bvanassche@acm.org (mailing list archive)
State New, archived
Headers show
Series Block layer patches for kernel v5.8 | expand

Commit Message

Bart Van Assche May 16, 2020, 12:19 a.m. UTC 
Since it is nontrivial that nth_page() does not have to be used for a
bio_vec, document this.

CC: Christoph Hellwig <hch@infradead.org>
Cc: Ming Lei <ming.lei@redhat.com>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 include/linux/bvec.h | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

Comments

Christoph Hellwig May 16, 2020, 12:43 p.m. UTC | #1 
On Fri, May 15, 2020 at 05:19:12PM -0700, Bart Van Assche wrote:
> Since it is nontrivial that nth_page() does not have to be used for a
> bio_vec, document this.

No need to quote the commit in the source code, just add the expanation
and not the source in the commit log for this patch.
diff mbox series

Patch

diff --git a/include/linux/bvec.h b/include/linux/bvec.h
index a81c13ac1972..25295c11b164 100644
--- a/include/linux/bvec.h
+++ b/include/linux/bvec.h
@@ -12,8 +12,22 @@ 
 #include <linux/errno.h>
 #include <linux/mm.h>
 
-/*
- * was unsigned short, but we might as well be ready for > 64kB I/O pages
+/**
+ * struct bio_vec - a contiguous range of physical memory addresses
+ * @bv_page:   First page associated with the address range.
+ * @bv_len:    Number of bytes in the address range.
+ * @bv_offset: Start of the address range relative to the start of @bv_page.
+ *
+ * The following holds for a bvec if n * PAGE_SIZE < bv_offset + bv_len:
+ *
+ *   nth_page(@bv_page, n) == @bv_page + n
+ *
+ * From the description of commit 52d52d1c98a9 ("block: only allow contiguous
+ * page structs in a bio_vec"): "We currently have to call nth_page when
+ * iterating over pages inside a bio_vec.  Jens complained a while ago that
+ * this is fairly expensive. To mitigate this we can check that that the
+ * actual page structures are contiguous when adding them to the bio, and just
+ * do check pointer arithmetics later on." See also page_is_mergeable().
  */
 struct bio_vec {
 	struct page	*bv_page;