Re: [PATCH v15 01/17] block: Add bio_add_folio()

On Tue, Jul 20, 2021 at 07:42:00AM +0100, Christoph Hellwig wrote:

On Mon, Jul 19, 2021 at 07:39:45PM +0100, Matthew Wilcox (Oracle) wrote:

quoted

+/**
+ * bio_add_folio - Attempt to add part of a folio to a bio.
+ * @bio: Bio to add to.
+ * @folio: Folio to add.
+ * @len: How many bytes from the folio to add.
+ * @off: First byte in this folio to add.
+ *
+ * Always uses the head page of the folio in the bio.  If a submitter only
+ * uses bio_add_folio(), it can count on never seeing tail pages in the
+ * completion routine.  BIOs do not support folios that are 4GiB or larger.
+ *
+ * Return: The number of bytes from this folio added to the bio.
+ */
+size_t bio_add_folio(struct bio *bio, struct folio *folio, size_t len,
+		size_t off)
+{
+	if (len > UINT_MAX || off > UINT_MAX)
+		return 0;
+	return bio_add_page(bio, &folio->page, len, off);
+}

I'd use the opportunity to switch to a true/false return instead of
the length.  This has been on my todo list for bio_add_page for a while,
so it might make sense to start out the new API the right way.

Looking at it with fresh eyes, I decided to rewrite the docs too.
ie this:

 /**
  * bio_add_folio - Attempt to add part of a folio to a bio.
- * @bio: Bio to add to.
+ * @bio: BIO to add to.
  * @folio: Folio to add.
  * @len: How many bytes from the folio to add.
  * @off: First byte in this folio to add.
  *
- * Always uses the head page of the folio in the bio.  If a submitter only
- * uses bio_add_folio(), it can count on never seeing tail pages in the
- * completion routine.  BIOs do not support folios that are 4GiB or larger.
+ * Filesystems that use folios can call this function instead of calling
+ * bio_add_page() for each page in the folio.  If @off is bigger than
+ * PAGE_SIZE, this function can create a bio_vec that starts in a page
+ * after the bv_page.  BIOs do not support folios that are 4GiB or larger.
  *
- * Return: The number of bytes from this folio added to the bio.
+ * Return: Whether the addition was successful.
  */
-size_t bio_add_folio(struct bio *bio, struct folio *folio, size_t len,
+bool bio_add_folio(struct bio *bio, struct folio *folio, size_t len,
                size_t off)
 {
        if (len > UINT_MAX || off > UINT_MAX)
                return 0;
-       return bio_add_page(bio, &folio->page, len, off);
+       return bio_add_page(bio, &folio->page, len, off) > 0;
 }

(i decided to go with > 0 so it's impervious to when you change
bio_add_page())