doc: update documentation for swap_activate and swap_rw

This documentation for ->swap_activate() has been out-of-date for a long
time.  This patch updates it to match recent changes, and adds
documentation for the associated ->swap_rw()

Link: https://lkml.kernel.org/r/164859778126.29473.6778751233552859461.stgit@noble.brown
Signed-off-by: NeilBrown <neilb@suse.de>
Reviewed-by: Christoph Hellwig <hch@lst.de>
Tested-by: David Howells <dhowells@redhat.com>
Tested-by: Geert Uytterhoeven <geert+renesas@glider.be>
Cc: Hugh Dickins <hughd@google.com>
Cc: Mel Gorman <mgorman@techsingularity.net>
Cc: Trond Myklebust <trond.myklebust@hammerspace.com>
Cc: Miaohe Lin <linmiaohe@huawei.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>

diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst
index c26d854..ef2efa1 100644 (file)
--- a/Documentation/filesystems/locking.rst
+++ b/Documentation/filesystems/locking.rst
@@ -258,8 +258,9 @@ prototypes::
        int (*launder_folio)(struct folio *);
        bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count);
        int (*error_remove_page)(struct address_space *, struct page *);
        int (*launder_folio)(struct folio *);
        bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count);
        int (*error_remove_page)(struct address_space *, struct page *);

-       int (*swap_activate)(struct file *);
+       int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span)

        int (*swap_deactivate)(struct file *);
        int (*swap_deactivate)(struct file *);

+       int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter);

 
 locking rules:
        All except dirty_folio and freepage may block
 
 locking rules:
        All except dirty_folio and freepage may block


@@ -287,6 +288,7 @@ is_partially_uptodate:      yes
 error_remove_page:     yes
 swap_activate:         no
 swap_deactivate:       no
 error_remove_page:     yes
 swap_activate:         no
 swap_deactivate:       no

+swap_rw:               yes, unlocks

 ====================== ======================== =========      ===============
 
 ->write_begin(), ->write_end() and ->readpage() may be called from
 ====================== ======================== =========      ===============
 
 ->write_begin(), ->write_end() and ->readpage() may be called from


@@ -386,15 +388,19 @@ cleaned, or an error value if not. Note that in order to prevent the folio
 getting mapped back in and redirtied, it needs to be kept locked
 across the entire operation.
 
 getting mapped back in and redirtied, it needs to be kept locked
 across the entire operation.
 

-->swap_activate will be called with a non-zero argument on
-files backing (non block device backed) swapfiles. A return value
-of zero indicates success, in which case this file can be used for
-backing swapspace. The swapspace operations will be proxied to the
-address space operations.
+->swap_activate() will be called to prepare the given file for swap.  It
+should perform any validation and preparation necessary to ensure that
+writes can be performed with minimal memory allocation.  It should call
+add_swap_extent(), or the helper iomap_swapfile_activate(), and return
+the number of extents added.  If IO should be submitted through
+->swap_rw(), it should set SWP_FS_OPS, otherwise IO will be submitted
+directly to the block device ``sis->bdev``.

 
 ->swap_deactivate() will be called in the sys_swapoff()
 path after ->swap_activate() returned success.
 
 
 ->swap_deactivate() will be called in the sys_swapoff()
 path after ->swap_activate() returned success.
 

+->swap_rw will be called for swap IO if SWP_FS_OPS was set by ->swap_activate().
+

 file_lock_operations
 ====================
 
 file_lock_operations
 ====================
 

diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 794bd1a..d4bd213 100644 (file)
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -749,8 +749,9 @@ cache in your filesystem.  The following members are defined:
                                               size_t count);
                void (*is_dirty_writeback) (struct page *, bool *, bool *);
                int (*error_remove_page) (struct mapping *mapping, struct page *page);
                                               size_t count);
                void (*is_dirty_writeback) (struct page *, bool *, bool *);
                int (*error_remove_page) (struct mapping *mapping, struct page *page);

-               int (*swap_activate)(struct file *);
+               int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span)

                int (*swap_deactivate)(struct file *);
                int (*swap_deactivate)(struct file *);

+               int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter);

        };
 
 ``writepage``
        };
 
 ``writepage``


@@ -952,15 +953,21 @@ cache in your filesystem.  The following members are defined:
        unless you have them locked or reference counts increased.
 
 ``swap_activate``
        unless you have them locked or reference counts increased.
 
 ``swap_activate``

-       Called when swapon is used on a file to allocate space if
-       necessary and pin the block lookup information in memory.  A
-       return value of zero indicates success, in which case this file
-       can be used to back swapspace.
+
+       Called to prepare the given file for swap.  It should perform
+       any validation and preparation necessary to ensure that writes
+       can be performed with minimal memory allocation.  It should call
+       add_swap_extent(), or the helper iomap_swapfile_activate(), and
+       return the number of extents added.  If IO should be submitted
+       through ->swap_rw(), it should set SWP_FS_OPS, otherwise IO will
+       be submitted directly to the block device ``sis->bdev``.

 
 ``swap_deactivate``
        Called during swapoff on files where swap_activate was
        successful.
 
 
 ``swap_deactivate``
        Called during swapoff on files where swap_activate was
        successful.
 

+``swap_rw``
+       Called to read or write swap pages when SWP_FS_OPS is set.

 
 The File Object
 ===============
 
 The File Object
 ===============