docs: document iomap writeback's iomap_finish_folio_write() requirement

Document that iomap_finish_folio_write() must be called after writeback
on the range completes.

Signed-off-by: Joanne Koong <joannelkoong@gmail.com>
Link: https://patch.msgid.link/20251111193658.3495942-4-joannelkoong@gmail.com
Reviewed-by: Christoph Hellwig <hch@lst.de>
Reviewed-by: Darrick J. Wong <djwong@kernel.org>
Signed-off-by: Christian Brauner <brauner@kernel.org>

diff --git a/Documentation/filesystems/iomap/operations.rst b/Documentation/filesystems/iomap/operations.rst
index c88205132039f87e1a6a5be5eb160dc6bfebeca5..4d30723be7fa50b562d16fc357a1d3bad87af37f 100644 (file)
--- a/Documentation/filesystems/iomap/operations.rst
+++ b/Documentation/filesystems/iomap/operations.rst
@@ -361,6 +361,9 @@ The fields are as follows:
     delalloc reservations to avoid having delalloc reservations for
     clean pagecache.
     This function must be supplied by the filesystem.
+    If this succeeds, iomap_finish_folio_write() must be called once writeback
+    completes for the range, regardless of whether the writeback succeeded or
+    failed.
 
   - ``writeback_submit``: Submit the previous built writeback context.
     Block based file systems should use the iomap_ioend_writeback_submit

diff --git a/include/linux/iomap.h b/include/linux/iomap.h
index 8b1ac08c74741bdf094ae0375f860c18f3705c5f..a5032e45607986ae51999794820eed96a8e8c837 100644 (file)
--- a/include/linux/iomap.h
+++ b/include/linux/iomap.h
@@ -435,6 +435,10 @@ struct iomap_writeback_ops {
         * An existing mapping from a previous call to this method can be reused
         * by the file system if it is still valid.
         *
+        * If this succeeds, iomap_finish_folio_write() must be called once
+        * writeback completes for the range, regardless of whether the
+        * writeback succeeded or failed.
+        *
         * Returns the number of bytes processed or a negative errno.
         */
        ssize_t (*writeback_range)(struct iomap_writepage_ctx *wpc,