summaryrefslogtreecommitdiff
path: root/Documentation/filesystems
diff options
context:
space:
mode:
authorMatthew Wilcox (Oracle) <willy@infradead.org>2022-04-29 15:45:43 +0300
committerMatthew Wilcox (Oracle) <willy@infradead.org>2022-06-29 15:51:06 +0300
commit90c02eb9a76c16427d644927a0de86600ad5ef85 (patch)
tree48868035aea279e803f14d3a004eac50809b92cc /Documentation/filesystems
parent290e1a320437011fc4f26456ab45eaebf9e44f5e (diff)
downloadlinux-90c02eb9a76c16427d644927a0de86600ad5ef85.tar.xz
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>
Diffstat (limited to 'Documentation/filesystems')
-rw-r--r--Documentation/filesystems/vfs.rst39
1 files changed, 32 insertions, 7 deletions
diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 08069ecd49a6..a08c652467d7 100644
--- 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