korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-11-27 22:24:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Improve ->read_folio documentation

Browse Source 
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>
This commit is contained in:
Matthew Wilcox (Oracle) 2022-04-29 08:45:43 -04:00
parent 290e1a3204
commit 90c02eb9a7
1 changed files with 32 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Documentation/filesystems/vfs.rst
View File

@ -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