docs: Improve ->read_folio documentation

Add information on the use of 'file', whether ->read_folio should be
synchronous, and steer new callers towards calling read_mapping_folio()
instead of calling ->read_folio directly.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 08069ecd49a6ebf061e8096e9462db64576d8865..a08c652467d7c0bf2877eaa675801b9114adba9d 100644 (file)
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -774,13 +774,38 @@ cache in your filesystem.  The following members are defined:
        See the file "Locking" for more details.
 
 ``read_folio``
-       called by the VM to read a folio from backing store.  The folio
-       will be locked when read_folio is called, and should be unlocked
-       and marked uptodate once the read completes.  If ->read_folio
-       discovers that it cannot perform the I/O at this time, it can
-        unlock the folio and return AOP_TRUNCATED_PAGE.  In this case,
-       the folio will be looked up again, relocked and if that all succeeds,
-       ->read_folio will be called again.
+       Called by the page cache to read a folio from the backing store.
+       The 'file' argument supplies authentication information to network
+       filesystems, and is generally not used by block based filesystems.
+       It may be NULL if the caller does not have an open file (eg if
+       the kernel is performing a read for itself rather than on behalf
+       of a userspace process with an open file).
+
+       If the mapping does not support large folios, the folio will
+       contain a single page.  The folio will be locked when read_folio
+       is called.  If the read completes successfully, the folio should
+       be marked uptodate.  The filesystem should unlock the folio
+       once the read has completed, whether it was successful or not.
+       The filesystem does not need to modify the refcount on the folio;
+       the page cache holds a reference count and that will not be
+       released until the folio is unlocked.
+
+       Filesystems may implement ->read_folio() synchronously.
+       In normal operation, folios are read through the ->readahead()
+       method.  Only if this fails, or if the caller needs to wait for
+       the read to complete will the page cache call ->read_folio().
+       Filesystems should not attempt to perform their own readahead
+       in the ->read_folio() operation.
+
+       If the filesystem cannot perform the read at this time, it can
+       unlock the folio, do whatever action it needs to ensure that the
+       read will succeed in the future and return AOP_TRUNCATED_PAGE.
+       In this case, the caller should look up the folio, lock it,
+       and call ->read_folio again.
+
+       Callers may invoke the ->read_folio() method directly, but using
+       read_mapping_folio() will take care of locking, waiting for the
+       read to complete and handle cases such as AOP_TRUNCATED_PAGE.
 
 ``writepages``
        called by the VM to write out pages associated with the