Documentation/filesystems/netfs_library.rst

12  - Buffered read helpers.
13    - Read helper functions.
14    - Read helper structures.
15    - Read helper operations.
16    - Read helper procedure.
17    - Read helper cache API.
25 just includes turning various VM buffered read operations into requests to read
95 Buffered Read Helpers
98 The library provides a set of read helpers that handle the ->read_folio(),
114  * Allow the netfs to partially fulfil a read, which will then be resubmitted.
116  * Handle local caching, allowing cached data and server-read data to be
128 includes a mandatory method to issue a read operation along with a number of
132 Read Helper Functions
135 Three read helpers are provided::
152 at the corresponding read helper; whereas for ->write_begin(), it may be a
157 The helpers manage the read request, calling back into the network filesystem
164 sufficient data is read.
172 which should be called to complete a read subrequest.  This is given the number
178 Read Helper Structures
181 The read helpers make use of a couple of structures to maintain the state of
182 the read.  The first is a structure that manages a read request as a whole::
202    The inode and the address space of the file being read from.  The mapping
217    The file position of the start of the read request and the length.  These
235 The second structure is used to manage individual slices of the overall read
253    A pointer to the read request.
258    The file position of the start of this slice of the read request and the
265    slice.  If a short read occurs, the helpers will call again, having updated
266    this to reflect the amount read so far.
270    Flags pertaining to the read.  There are two of interest to the filesystem
289 Read Helper Operations
292 The network filesystem must provide the read helpers with a table of operations
322    readahead read request.  The filesystem gets to expand the request in both
344    data should be read from the server.
359    [Optional] This is called to find out if the data just read from the local
381 Read Helper Procedure
384 The read helpers work by the following general procedure:
389    propose expansions to the read request.  This is then proposed to the VM.
390    If the VM cannot fully perform the expansion, a partially expanded read will
401    * The helpers issue a read from the cache or a read from the server or just
406    * As slices finish being read, they terminate.
420      * If NETFS_SREQ_CLEAR_TAIL was set, a short read will be cleared to the
423  * Once the data is read, the folios that have been fully read/cleared:
441 Read Helper Cache API
444 When implementing a local cache to be used by the read helpers, two things are
446 read request and a table of operations for the helpers to call.
478 		int (*read)(struct netfs_cache_resources *cres,
510    [Required] Called to clean up the resources at the end of the read request.
528    downloaded from the server or read from the cache - or whether slicing
537  * ``read()``
539    [Required] Called to read from the cache.  The start file offset is given
540    along with an iterator to read to, which gives the length also.  It can be
559    if it tried to do a read from there already.
585 not the read request structure as they could be used in other situations where
586 there isn't a read request structure as well, such as writing dirty data to the