11.. SPDX-License-Identifier: GPL-2.0
22
33=================================
4- NETWORK FILESYSTEM HELPER LIBRARY
4+ Network Filesystem Helper Library
55=================================
66
77.. Contents:
@@ -37,22 +37,22 @@ into a common call framework.
3737
3838The following services are provided:
3939
40- * Handles transparent huge pages (THPs) .
40+ * Handle folios that span multiple pages .
4141
42- * Insulates the netfs from VM interface changes.
42+ * Insulate the netfs from VM interface changes.
4343
44- * Allows the netfs to arbitrarily split reads up into pieces, even ones that
45- don't match page sizes or page alignments and that may cross pages .
44+ * Allow the netfs to arbitrarily split reads up into pieces, even ones that
45+ don't match folio sizes or folio alignments and that may cross folios .
4646
47- * Allows the netfs to expand a readahead request in both directions to meet
48- its needs.
47+ * Allow the netfs to expand a readahead request in both directions to meet its
48+ needs.
4949
50- * Allows the netfs to partially fulfil a read, which will then be resubmitted.
50+ * Allow the netfs to partially fulfil a read, which will then be resubmitted.
5151
52- * Handles local caching, allowing cached data and server-read data to be
52+ * Handle local caching, allowing cached data and server-read data to be
5353 interleaved for a single request.
5454
55- * Handles clearing of bufferage that aren't on the server.
55+ * Handle clearing of bufferage that aren't on the server.
5656
5757 * Handle retrying of reads that failed, switching reads from the cache to the
5858 server as necessary.
@@ -70,22 +70,22 @@ Read Helper Functions
7070
7171Three read helpers are provided::
7272
73- * void netfs_readahead(struct readahead_control *ractl,
74- const struct netfs_read_request_ops *ops,
75- void *netfs_priv);``
76- * int netfs_readpage(struct file *file,
77- struct page *page ,
78- const struct netfs_read_request_ops *ops,
79- void *netfs_priv);
80- * int netfs_write_begin(struct file *file,
81- struct address_space *mapping,
82- loff_t pos,
83- unsigned int len,
84- unsigned int flags,
85- struct page **_page ,
86- void **_fsdata,
87- const struct netfs_read_request_ops *ops,
88- void *netfs_priv);
73+ void netfs_readahead(struct readahead_control *ractl,
74+ const struct netfs_read_request_ops *ops,
75+ void *netfs_priv);
76+ int netfs_readpage(struct file *file,
77+ struct folio *folio ,
78+ const struct netfs_read_request_ops *ops,
79+ void *netfs_priv);
80+ int netfs_write_begin(struct file *file,
81+ struct address_space *mapping,
82+ loff_t pos,
83+ unsigned int len,
84+ unsigned int flags,
85+ struct folio **_folio ,
86+ void **_fsdata,
87+ const struct netfs_read_request_ops *ops,
88+ void *netfs_priv);
8989
9090Each corresponds to a VM operation, with the addition of a couple of parameters
9191for the use of the read helpers:
@@ -103,8 +103,8 @@ Both of these values will be stored into the read request structure.
103103For ->readahead() and ->readpage(), the network filesystem should just jump
104104into the corresponding read helper; whereas for ->write_begin(), it may be a
105105little more complicated as the network filesystem might want to flush
106- conflicting writes or track dirty data and needs to put the acquired page if an
107- error occurs after calling the helper.
106+ conflicting writes or track dirty data and needs to put the acquired folio if
107+ an error occurs after calling the helper.
108108
109109The helpers manage the read request, calling back into the network filesystem
110110through the suppplied table of operations. Waits will be performed as
@@ -253,7 +253,7 @@ through which it can issue requests and negotiate::
253253 void (*issue_op)(struct netfs_read_subrequest *subreq);
254254 bool (*is_still_valid)(struct netfs_read_request *rreq);
255255 int (*check_write_begin)(struct file *file, loff_t pos, unsigned len,
256- struct page *page , void **_fsdata);
256+ struct folio *folio , void **_fsdata);
257257 void (*done)(struct netfs_read_request *rreq);
258258 void (*cleanup)(struct address_space *mapping, void *netfs_priv);
259259 };
@@ -313,13 +313,14 @@ The operations are as follows:
313313
314314 There is no return value; the netfs_subreq_terminated() function should be
315315 called to indicate whether or not the operation succeeded and how much data
316- it transferred. The filesystem also should not deal with setting pages
316+ it transferred. The filesystem also should not deal with setting folios
317317 uptodate, unlocking them or dropping their refs - the helpers need to deal
318318 with this as they have to coordinate with copying to the local cache.
319319
320- Note that the helpers have the pages locked, but not pinned. It is possible
321- to use the ITER_XARRAY iov iterator to refer to the range of the inode that
322- is being operated upon without the need to allocate large bvec tables.
320+ Note that the helpers have the folios locked, but not pinned. It is
321+ possible to use the ITER_XARRAY iov iterator to refer to the range of the
322+ inode that is being operated upon without the need to allocate large bvec
323+ tables.
323324
324325 * ``is_still_valid() ``
325326
@@ -330,15 +331,15 @@ The operations are as follows:
330331 * ``check_write_begin() ``
331332
332333 [Optional] This is called from the netfs_write_begin() helper once it has
333- allocated/grabbed the page to be modified to allow the filesystem to flush
334+ allocated/grabbed the folio to be modified to allow the filesystem to flush
334335 conflicting state before allowing it to be modified.
335336
336- It should return 0 if everything is now fine, -EAGAIN if the page should be
337+ It should return 0 if everything is now fine, -EAGAIN if the folio should be
337338 regrabbed and any other error code to abort the operation.
338339
339340 * ``done ``
340341
341- [Optional] This is called after the pages in the request have all been
342+ [Optional] This is called after the folios in the request have all been
342343 unlocked (and marked uptodate if applicable).
343344
344345 * ``cleanup ``
@@ -390,19 +391,19 @@ The read helpers work by the following general procedure:
390391 * If NETFS_SREQ_CLEAR_TAIL was set, a short read will be cleared to the
391392 end of the slice instead of reissuing.
392393
393- * Once the data is read, the pages that have been fully read/cleared:
394+ * Once the data is read, the folios that have been fully read/cleared:
394395
395396 * Will be marked uptodate.
396397
397398 * If a cache is present, will be marked with PG_fscache.
398399
399400 * Unlocked
400401
401- * Any pages that need writing to the cache will then have DIO writes issued.
402+ * Any folios that need writing to the cache will then have DIO writes issued.
402403
403404 * Synchronous operations will wait for reading to be complete.
404405
405- * Writes to the cache will proceed asynchronously and the pages will have the
406+ * Writes to the cache will proceed asynchronously and the folios will have the
406407 PG_fscache mark removed when that completes.
407408
408409 * The request structures will be cleaned up when everything has completed.
@@ -452,6 +453,9 @@ operation table looks like the following::
452453 netfs_io_terminated_t term_func,
453454 void *term_func_priv);
454455
456+ int (*prepare_write)(struct netfs_cache_resources *cres,
457+ loff_t *_start, size_t *_len, loff_t i_size);
458+
455459 int (*write)(struct netfs_cache_resources *cres,
456460 loff_t start_pos,
457461 struct iov_iter *iter,
@@ -509,6 +513,14 @@ The methods defined in the table are:
509513 indicating whether the termination is definitely happening in the caller's
510514 context.
511515
516+ * ``prepare_write() ``
517+
518+ [Required] Called to adjust a write to the cache and check that there is
519+ sufficient space in the cache. The start and length values indicate the
520+ size of the write that netfslib is proposing, and this can be adjusted by
521+ the cache to respect DIO boundaries. The file size is passed for
522+ information.
523+
512524 * ``write() ``
513525
514526 [Required] Called to write to the cache. The start file offset is given
@@ -525,4 +537,9 @@ not the read request structure as they could be used in other situations where
525537there isn't a read request structure as well, such as writing dirty data to the
526538cache.
527539
540+
541+ API Function Reference
542+ ======================
543+
528544.. kernel-doc :: include/linux/netfs.h
545+ .. kernel-doc :: fs/netfs/read_helper.c
0 commit comments