1fb28afccSDavid Howells.. SPDX-License-Identifier: GPL-2.0 2fb28afccSDavid Howells 3fb28afccSDavid Howells================================= 4*ddca5b0eSDavid HowellsNetwork Filesystem Helper Library 5fb28afccSDavid Howells================================= 6fb28afccSDavid Howells 7fb28afccSDavid Howells.. Contents: 8fb28afccSDavid Howells 9fb28afccSDavid Howells - Overview. 10fb28afccSDavid Howells - Buffered read helpers. 11fb28afccSDavid Howells - Read helper functions. 12fb28afccSDavid Howells - Read helper structures. 13fb28afccSDavid Howells - Read helper operations. 14fb28afccSDavid Howells - Read helper procedure. 15fb28afccSDavid Howells - Read helper cache API. 16fb28afccSDavid Howells 17fb28afccSDavid Howells 18fb28afccSDavid HowellsOverview 19fb28afccSDavid Howells======== 20fb28afccSDavid Howells 21fb28afccSDavid HowellsThe network filesystem helper library is a set of functions designed to aid a 22fb28afccSDavid Howellsnetwork filesystem in implementing VM/VFS operations. For the moment, that 23fb28afccSDavid Howellsjust includes turning various VM buffered read operations into requests to read 24fb28afccSDavid Howellsfrom the server. The helper library, however, can also interpose other 25fb28afccSDavid Howellsservices, such as local caching or local data encryption. 26fb28afccSDavid Howells 27fb28afccSDavid HowellsNote that the library module doesn't link against local caching directly, so 28fb28afccSDavid Howellsaccess must be provided by the netfs. 29fb28afccSDavid Howells 30fb28afccSDavid Howells 31fb28afccSDavid HowellsBuffered Read Helpers 32fb28afccSDavid Howells===================== 33fb28afccSDavid Howells 34fb28afccSDavid HowellsThe library provides a set of read helpers that handle the ->readpage(), 35fb28afccSDavid Howells->readahead() and much of the ->write_begin() VM operations and translate them 36fb28afccSDavid Howellsinto a common call framework. 37fb28afccSDavid Howells 38fb28afccSDavid HowellsThe following services are provided: 39fb28afccSDavid Howells 40*ddca5b0eSDavid Howells * Handle folios that span multiple pages. 41fb28afccSDavid Howells 42*ddca5b0eSDavid Howells * Insulate the netfs from VM interface changes. 43fb28afccSDavid Howells 44*ddca5b0eSDavid Howells * Allow the netfs to arbitrarily split reads up into pieces, even ones that 45*ddca5b0eSDavid Howells don't match folio sizes or folio alignments and that may cross folios. 46fb28afccSDavid Howells 47*ddca5b0eSDavid Howells * Allow the netfs to expand a readahead request in both directions to meet its 48*ddca5b0eSDavid Howells needs. 49fb28afccSDavid Howells 50*ddca5b0eSDavid Howells * Allow the netfs to partially fulfil a read, which will then be resubmitted. 51fb28afccSDavid Howells 52*ddca5b0eSDavid Howells * Handle local caching, allowing cached data and server-read data to be 53fb28afccSDavid Howells interleaved for a single request. 54fb28afccSDavid Howells 55*ddca5b0eSDavid Howells * Handle clearing of bufferage that aren't on the server. 56fb28afccSDavid Howells 57fb28afccSDavid Howells * Handle retrying of reads that failed, switching reads from the cache to the 58fb28afccSDavid Howells server as necessary. 59fb28afccSDavid Howells 60fb28afccSDavid Howells * In the future, this is a place that other services can be performed, such as 61fb28afccSDavid Howells local encryption of data to be stored remotely or in the cache. 62fb28afccSDavid Howells 63fb28afccSDavid HowellsFrom the network filesystem, the helpers require a table of operations. This 64fb28afccSDavid Howellsincludes a mandatory method to issue a read operation along with a number of 65fb28afccSDavid Howellsoptional methods. 66fb28afccSDavid Howells 67fb28afccSDavid Howells 68fb28afccSDavid HowellsRead Helper Functions 69fb28afccSDavid Howells--------------------- 70fb28afccSDavid Howells 71fb28afccSDavid HowellsThree read helpers are provided:: 72fb28afccSDavid Howells 73*ddca5b0eSDavid Howells void netfs_readahead(struct readahead_control *ractl, 74fb28afccSDavid Howells const struct netfs_read_request_ops *ops, 75fb28afccSDavid Howells void *netfs_priv); 76*ddca5b0eSDavid Howells int netfs_readpage(struct file *file, 77*ddca5b0eSDavid Howells struct folio *folio, 78*ddca5b0eSDavid Howells const struct netfs_read_request_ops *ops, 79*ddca5b0eSDavid Howells void *netfs_priv); 80*ddca5b0eSDavid Howells int netfs_write_begin(struct file *file, 81fb28afccSDavid Howells struct address_space *mapping, 82fb28afccSDavid Howells loff_t pos, 83fb28afccSDavid Howells unsigned int len, 84fb28afccSDavid Howells unsigned int flags, 85*ddca5b0eSDavid Howells struct folio **_folio, 86fb28afccSDavid Howells void **_fsdata, 87fb28afccSDavid Howells const struct netfs_read_request_ops *ops, 88fb28afccSDavid Howells void *netfs_priv); 89fb28afccSDavid Howells 90fb28afccSDavid HowellsEach corresponds to a VM operation, with the addition of a couple of parameters 91fb28afccSDavid Howellsfor the use of the read helpers: 92fb28afccSDavid Howells 93fb28afccSDavid Howells * ``ops`` 94fb28afccSDavid Howells 95fb28afccSDavid Howells A table of operations through which the helpers can talk to the filesystem. 96fb28afccSDavid Howells 97fb28afccSDavid Howells * ``netfs_priv`` 98fb28afccSDavid Howells 99fb28afccSDavid Howells Filesystem private data (can be NULL). 100fb28afccSDavid Howells 101fb28afccSDavid HowellsBoth of these values will be stored into the read request structure. 102fb28afccSDavid Howells 103fb28afccSDavid HowellsFor ->readahead() and ->readpage(), the network filesystem should just jump 104fb28afccSDavid Howellsinto the corresponding read helper; whereas for ->write_begin(), it may be a 105fb28afccSDavid Howellslittle more complicated as the network filesystem might want to flush 106*ddca5b0eSDavid Howellsconflicting writes or track dirty data and needs to put the acquired folio if 107*ddca5b0eSDavid Howellsan error occurs after calling the helper. 108fb28afccSDavid Howells 109fb28afccSDavid HowellsThe helpers manage the read request, calling back into the network filesystem 110fb28afccSDavid Howellsthrough the suppplied table of operations. Waits will be performed as 111fb28afccSDavid Howellsnecessary before returning for helpers that are meant to be synchronous. 112fb28afccSDavid Howells 113fb28afccSDavid HowellsIf an error occurs and netfs_priv is non-NULL, ops->cleanup() will be called to 114fb28afccSDavid Howellsdeal with it. If some parts of the request are in progress when an error 115fb28afccSDavid Howellsoccurs, the request will get partially completed if sufficient data is read. 116fb28afccSDavid Howells 117fb28afccSDavid HowellsAdditionally, there is:: 118fb28afccSDavid Howells 119fb28afccSDavid Howells * void netfs_subreq_terminated(struct netfs_read_subrequest *subreq, 120fb28afccSDavid Howells ssize_t transferred_or_error, 121fb28afccSDavid Howells bool was_async); 122fb28afccSDavid Howells 123fb28afccSDavid Howellswhich should be called to complete a read subrequest. This is given the number 124fb28afccSDavid Howellsof bytes transferred or a negative error code, plus a flag indicating whether 125fb28afccSDavid Howellsthe operation was asynchronous (ie. whether the follow-on processing can be 126fb28afccSDavid Howellsdone in the current context, given this may involve sleeping). 127fb28afccSDavid Howells 128fb28afccSDavid Howells 129fb28afccSDavid HowellsRead Helper Structures 130fb28afccSDavid Howells---------------------- 131fb28afccSDavid Howells 132fb28afccSDavid HowellsThe read helpers make use of a couple of structures to maintain the state of 133fb28afccSDavid Howellsthe read. The first is a structure that manages a read request as a whole:: 134fb28afccSDavid Howells 135fb28afccSDavid Howells struct netfs_read_request { 136fb28afccSDavid Howells struct inode *inode; 137fb28afccSDavid Howells struct address_space *mapping; 138fb28afccSDavid Howells struct netfs_cache_resources cache_resources; 139fb28afccSDavid Howells void *netfs_priv; 140fb28afccSDavid Howells loff_t start; 141fb28afccSDavid Howells size_t len; 142fb28afccSDavid Howells loff_t i_size; 143fb28afccSDavid Howells const struct netfs_read_request_ops *netfs_ops; 144fb28afccSDavid Howells unsigned int debug_id; 145fb28afccSDavid Howells ... 146fb28afccSDavid Howells }; 147fb28afccSDavid Howells 148fb28afccSDavid HowellsThe above fields are the ones the netfs can use. They are: 149fb28afccSDavid Howells 150fb28afccSDavid Howells * ``inode`` 151fb28afccSDavid Howells * ``mapping`` 152fb28afccSDavid Howells 153fb28afccSDavid Howells The inode and the address space of the file being read from. The mapping 154fb28afccSDavid Howells may or may not point to inode->i_data. 155fb28afccSDavid Howells 156fb28afccSDavid Howells * ``cache_resources`` 157fb28afccSDavid Howells 158fb28afccSDavid Howells Resources for the local cache to use, if present. 159fb28afccSDavid Howells 160fb28afccSDavid Howells * ``netfs_priv`` 161fb28afccSDavid Howells 162fb28afccSDavid Howells The network filesystem's private data. The value for this can be passed in 163fb28afccSDavid Howells to the helper functions or set during the request. The ->cleanup() op will 164fb28afccSDavid Howells be called if this is non-NULL at the end. 165fb28afccSDavid Howells 166fb28afccSDavid Howells * ``start`` 167fb28afccSDavid Howells * ``len`` 168fb28afccSDavid Howells 169fb28afccSDavid Howells The file position of the start of the read request and the length. These 170fb28afccSDavid Howells may be altered by the ->expand_readahead() op. 171fb28afccSDavid Howells 172fb28afccSDavid Howells * ``i_size`` 173fb28afccSDavid Howells 174fb28afccSDavid Howells The size of the file at the start of the request. 175fb28afccSDavid Howells 176fb28afccSDavid Howells * ``netfs_ops`` 177fb28afccSDavid Howells 178fb28afccSDavid Howells A pointer to the operation table. The value for this is passed into the 179fb28afccSDavid Howells helper functions. 180fb28afccSDavid Howells 181fb28afccSDavid Howells * ``debug_id`` 182fb28afccSDavid Howells 183fb28afccSDavid Howells A number allocated to this operation that can be displayed in trace lines 184fb28afccSDavid Howells for reference. 185fb28afccSDavid Howells 186fb28afccSDavid Howells 187fb28afccSDavid HowellsThe second structure is used to manage individual slices of the overall read 188fb28afccSDavid Howellsrequest:: 189fb28afccSDavid Howells 190fb28afccSDavid Howells struct netfs_read_subrequest { 191fb28afccSDavid Howells struct netfs_read_request *rreq; 192fb28afccSDavid Howells loff_t start; 193fb28afccSDavid Howells size_t len; 194fb28afccSDavid Howells size_t transferred; 195fb28afccSDavid Howells unsigned long flags; 196fb28afccSDavid Howells unsigned short debug_index; 197fb28afccSDavid Howells ... 198fb28afccSDavid Howells }; 199fb28afccSDavid Howells 200fb28afccSDavid HowellsEach subrequest is expected to access a single source, though the helpers will 201fb28afccSDavid Howellshandle falling back from one source type to another. The members are: 202fb28afccSDavid Howells 203fb28afccSDavid Howells * ``rreq`` 204fb28afccSDavid Howells 205fb28afccSDavid Howells A pointer to the read request. 206fb28afccSDavid Howells 207fb28afccSDavid Howells * ``start`` 208fb28afccSDavid Howells * ``len`` 209fb28afccSDavid Howells 210fb28afccSDavid Howells The file position of the start of this slice of the read request and the 211fb28afccSDavid Howells length. 212fb28afccSDavid Howells 213fb28afccSDavid Howells * ``transferred`` 214fb28afccSDavid Howells 215fb28afccSDavid Howells The amount of data transferred so far of the length of this slice. The 216fb28afccSDavid Howells network filesystem or cache should start the operation this far into the 217fb28afccSDavid Howells slice. If a short read occurs, the helpers will call again, having updated 218fb28afccSDavid Howells this to reflect the amount read so far. 219fb28afccSDavid Howells 220fb28afccSDavid Howells * ``flags`` 221fb28afccSDavid Howells 222fb28afccSDavid Howells Flags pertaining to the read. There are two of interest to the filesystem 223fb28afccSDavid Howells or cache: 224fb28afccSDavid Howells 225fb28afccSDavid Howells * ``NETFS_SREQ_CLEAR_TAIL`` 226fb28afccSDavid Howells 227fb28afccSDavid Howells This can be set to indicate that the remainder of the slice, from 228fb28afccSDavid Howells transferred to len, should be cleared. 229fb28afccSDavid Howells 230fb28afccSDavid Howells * ``NETFS_SREQ_SEEK_DATA_READ`` 231fb28afccSDavid Howells 232fb28afccSDavid Howells This is a hint to the cache that it might want to try skipping ahead to 233fb28afccSDavid Howells the next data (ie. using SEEK_DATA). 234fb28afccSDavid Howells 235fb28afccSDavid Howells * ``debug_index`` 236fb28afccSDavid Howells 237fb28afccSDavid Howells A number allocated to this slice that can be displayed in trace lines for 238fb28afccSDavid Howells reference. 239fb28afccSDavid Howells 240fb28afccSDavid Howells 241fb28afccSDavid HowellsRead Helper Operations 242fb28afccSDavid Howells---------------------- 243fb28afccSDavid Howells 244fb28afccSDavid HowellsThe network filesystem must provide the read helpers with a table of operations 245fb28afccSDavid Howellsthrough which it can issue requests and negotiate:: 246fb28afccSDavid Howells 247fb28afccSDavid Howells struct netfs_read_request_ops { 248fb28afccSDavid Howells void (*init_rreq)(struct netfs_read_request *rreq, struct file *file); 249fb28afccSDavid Howells bool (*is_cache_enabled)(struct inode *inode); 250fb28afccSDavid Howells int (*begin_cache_operation)(struct netfs_read_request *rreq); 251fb28afccSDavid Howells void (*expand_readahead)(struct netfs_read_request *rreq); 252fb28afccSDavid Howells bool (*clamp_length)(struct netfs_read_subrequest *subreq); 253fb28afccSDavid Howells void (*issue_op)(struct netfs_read_subrequest *subreq); 254fb28afccSDavid Howells bool (*is_still_valid)(struct netfs_read_request *rreq); 255fb28afccSDavid Howells int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, 256*ddca5b0eSDavid Howells struct folio *folio, void **_fsdata); 257fb28afccSDavid Howells void (*done)(struct netfs_read_request *rreq); 258fb28afccSDavid Howells void (*cleanup)(struct address_space *mapping, void *netfs_priv); 259fb28afccSDavid Howells }; 260fb28afccSDavid Howells 261fb28afccSDavid HowellsThe operations are as follows: 262fb28afccSDavid Howells 263fb28afccSDavid Howells * ``init_rreq()`` 264fb28afccSDavid Howells 265fb28afccSDavid Howells [Optional] This is called to initialise the request structure. It is given 266fb28afccSDavid Howells the file for reference and can modify the ->netfs_priv value. 267fb28afccSDavid Howells 268fb28afccSDavid Howells * ``is_cache_enabled()`` 269fb28afccSDavid Howells 270fb28afccSDavid Howells [Required] This is called by netfs_write_begin() to ask if the file is being 271fb28afccSDavid Howells cached. It should return true if it is being cached and false otherwise. 272fb28afccSDavid Howells 273fb28afccSDavid Howells * ``begin_cache_operation()`` 274fb28afccSDavid Howells 275fb28afccSDavid Howells [Optional] This is called to ask the network filesystem to call into the 276fb28afccSDavid Howells cache (if present) to initialise the caching state for this read. The netfs 277fb28afccSDavid Howells library module cannot access the cache directly, so the cache should call 278fb28afccSDavid Howells something like fscache_begin_read_operation() to do this. 279fb28afccSDavid Howells 280fb28afccSDavid Howells The cache gets to store its state in ->cache_resources and must set a table 281fb28afccSDavid Howells of operations of its own there (though of a different type). 282fb28afccSDavid Howells 283fb28afccSDavid Howells This should return 0 on success and an error code otherwise. If an error is 284fb28afccSDavid Howells reported, the operation may proceed anyway, just without local caching (only 285fb28afccSDavid Howells out of memory and interruption errors cause failure here). 286fb28afccSDavid Howells 287fb28afccSDavid Howells * ``expand_readahead()`` 288fb28afccSDavid Howells 289fb28afccSDavid Howells [Optional] This is called to allow the filesystem to expand the size of a 290fb28afccSDavid Howells readahead read request. The filesystem gets to expand the request in both 291fb28afccSDavid Howells directions, though it's not permitted to reduce it as the numbers may 292fb28afccSDavid Howells represent an allocation already made. If local caching is enabled, it gets 293fb28afccSDavid Howells to expand the request first. 294fb28afccSDavid Howells 295fb28afccSDavid Howells Expansion is communicated by changing ->start and ->len in the request 296fb28afccSDavid Howells structure. Note that if any change is made, ->len must be increased by at 297fb28afccSDavid Howells least as much as ->start is reduced. 298fb28afccSDavid Howells 299fb28afccSDavid Howells * ``clamp_length()`` 300fb28afccSDavid Howells 301fb28afccSDavid Howells [Optional] This is called to allow the filesystem to reduce the size of a 302fb28afccSDavid Howells subrequest. The filesystem can use this, for example, to chop up a request 303fb28afccSDavid Howells that has to be split across multiple servers or to put multiple reads in 304fb28afccSDavid Howells flight. 305fb28afccSDavid Howells 306fb28afccSDavid Howells This should return 0 on success and an error code on error. 307fb28afccSDavid Howells 308fb28afccSDavid Howells * ``issue_op()`` 309fb28afccSDavid Howells 310fb28afccSDavid Howells [Required] The helpers use this to dispatch a subrequest to the server for 311fb28afccSDavid Howells reading. In the subrequest, ->start, ->len and ->transferred indicate what 312fb28afccSDavid Howells data should be read from the server. 313fb28afccSDavid Howells 314fb28afccSDavid Howells There is no return value; the netfs_subreq_terminated() function should be 315fb28afccSDavid Howells called to indicate whether or not the operation succeeded and how much data 316*ddca5b0eSDavid Howells it transferred. The filesystem also should not deal with setting folios 317fb28afccSDavid Howells uptodate, unlocking them or dropping their refs - the helpers need to deal 318fb28afccSDavid Howells with this as they have to coordinate with copying to the local cache. 319fb28afccSDavid Howells 320*ddca5b0eSDavid Howells Note that the helpers have the folios locked, but not pinned. It is 321*ddca5b0eSDavid Howells possible to use the ITER_XARRAY iov iterator to refer to the range of the 322*ddca5b0eSDavid Howells inode that is being operated upon without the need to allocate large bvec 323*ddca5b0eSDavid Howells tables. 324fb28afccSDavid Howells 325fb28afccSDavid Howells * ``is_still_valid()`` 326fb28afccSDavid Howells 327fb28afccSDavid Howells [Optional] This is called to find out if the data just read from the local 328fb28afccSDavid Howells cache is still valid. It should return true if it is still valid and false 329fb28afccSDavid Howells if not. If it's not still valid, it will be reread from the server. 330fb28afccSDavid Howells 331fb28afccSDavid Howells * ``check_write_begin()`` 332fb28afccSDavid Howells 333fb28afccSDavid Howells [Optional] This is called from the netfs_write_begin() helper once it has 334*ddca5b0eSDavid Howells allocated/grabbed the folio to be modified to allow the filesystem to flush 335fb28afccSDavid Howells conflicting state before allowing it to be modified. 336fb28afccSDavid Howells 337*ddca5b0eSDavid Howells It should return 0 if everything is now fine, -EAGAIN if the folio should be 338fb28afccSDavid Howells regrabbed and any other error code to abort the operation. 339fb28afccSDavid Howells 340fb28afccSDavid Howells * ``done`` 341fb28afccSDavid Howells 342*ddca5b0eSDavid Howells [Optional] This is called after the folios in the request have all been 343fb28afccSDavid Howells unlocked (and marked uptodate if applicable). 344fb28afccSDavid Howells 345fb28afccSDavid Howells * ``cleanup`` 346fb28afccSDavid Howells 347fb28afccSDavid Howells [Optional] This is called as the request is being deallocated so that the 348fb28afccSDavid Howells filesystem can clean up ->netfs_priv. 349fb28afccSDavid Howells 350fb28afccSDavid Howells 351fb28afccSDavid Howells 352fb28afccSDavid HowellsRead Helper Procedure 353fb28afccSDavid Howells--------------------- 354fb28afccSDavid Howells 355fb28afccSDavid HowellsThe read helpers work by the following general procedure: 356fb28afccSDavid Howells 357fb28afccSDavid Howells * Set up the request. 358fb28afccSDavid Howells 359fb28afccSDavid Howells * For readahead, allow the local cache and then the network filesystem to 360fb28afccSDavid Howells propose expansions to the read request. This is then proposed to the VM. 361fb28afccSDavid Howells If the VM cannot fully perform the expansion, a partially expanded read will 362fb28afccSDavid Howells be performed, though this may not get written to the cache in its entirety. 363fb28afccSDavid Howells 364fb28afccSDavid Howells * Loop around slicing chunks off of the request to form subrequests: 365fb28afccSDavid Howells 366fb28afccSDavid Howells * If a local cache is present, it gets to do the slicing, otherwise the 367fb28afccSDavid Howells helpers just try to generate maximal slices. 368fb28afccSDavid Howells 369fb28afccSDavid Howells * The network filesystem gets to clamp the size of each slice if it is to be 370fb28afccSDavid Howells the source. This allows rsize and chunking to be implemented. 371fb28afccSDavid Howells 372fb28afccSDavid Howells * The helpers issue a read from the cache or a read from the server or just 373fb28afccSDavid Howells clears the slice as appropriate. 374fb28afccSDavid Howells 375fb28afccSDavid Howells * The next slice begins at the end of the last one. 376fb28afccSDavid Howells 377fb28afccSDavid Howells * As slices finish being read, they terminate. 378fb28afccSDavid Howells 379fb28afccSDavid Howells * When all the subrequests have terminated, the subrequests are assessed and 380fb28afccSDavid Howells any that are short or have failed are reissued: 381fb28afccSDavid Howells 382fb28afccSDavid Howells * Failed cache requests are issued against the server instead. 383fb28afccSDavid Howells 384fb28afccSDavid Howells * Failed server requests just fail. 385fb28afccSDavid Howells 386fb28afccSDavid Howells * Short reads against either source will be reissued against that source 387fb28afccSDavid Howells provided they have transferred some more data: 388fb28afccSDavid Howells 389fb28afccSDavid Howells * The cache may need to skip holes that it can't do DIO from. 390fb28afccSDavid Howells 391fb28afccSDavid Howells * If NETFS_SREQ_CLEAR_TAIL was set, a short read will be cleared to the 392fb28afccSDavid Howells end of the slice instead of reissuing. 393fb28afccSDavid Howells 394*ddca5b0eSDavid Howells * Once the data is read, the folios that have been fully read/cleared: 395fb28afccSDavid Howells 396fb28afccSDavid Howells * Will be marked uptodate. 397fb28afccSDavid Howells 398fb28afccSDavid Howells * If a cache is present, will be marked with PG_fscache. 399fb28afccSDavid Howells 400fb28afccSDavid Howells * Unlocked 401fb28afccSDavid Howells 402*ddca5b0eSDavid Howells * Any folios that need writing to the cache will then have DIO writes issued. 403fb28afccSDavid Howells 404fb28afccSDavid Howells * Synchronous operations will wait for reading to be complete. 405fb28afccSDavid Howells 406*ddca5b0eSDavid Howells * Writes to the cache will proceed asynchronously and the folios will have the 407fb28afccSDavid Howells PG_fscache mark removed when that completes. 408fb28afccSDavid Howells 409fb28afccSDavid Howells * The request structures will be cleaned up when everything has completed. 410fb28afccSDavid Howells 411fb28afccSDavid Howells 412fb28afccSDavid HowellsRead Helper Cache API 413fb28afccSDavid Howells--------------------- 414fb28afccSDavid Howells 415fb28afccSDavid HowellsWhen implementing a local cache to be used by the read helpers, two things are 416fb28afccSDavid Howellsrequired: some way for the network filesystem to initialise the caching for a 417fb28afccSDavid Howellsread request and a table of operations for the helpers to call. 418fb28afccSDavid Howells 419fb28afccSDavid HowellsThe network filesystem's ->begin_cache_operation() method is called to set up a 420fb28afccSDavid Howellscache and this must call into the cache to do the work. If using fscache, for 421fb28afccSDavid Howellsexample, the cache would call:: 422fb28afccSDavid Howells 423fb28afccSDavid Howells int fscache_begin_read_operation(struct netfs_read_request *rreq, 424fb28afccSDavid Howells struct fscache_cookie *cookie); 425fb28afccSDavid Howells 426fb28afccSDavid Howellspassing in the request pointer and the cookie corresponding to the file. 427fb28afccSDavid Howells 428fb28afccSDavid HowellsThe netfs_read_request object contains a place for the cache to hang its 429fb28afccSDavid Howellsstate:: 430fb28afccSDavid Howells 431fb28afccSDavid Howells struct netfs_cache_resources { 432fb28afccSDavid Howells const struct netfs_cache_ops *ops; 433fb28afccSDavid Howells void *cache_priv; 434fb28afccSDavid Howells void *cache_priv2; 435fb28afccSDavid Howells }; 436fb28afccSDavid Howells 437fb28afccSDavid HowellsThis contains an operations table pointer and two private pointers. The 438fb28afccSDavid Howellsoperation table looks like the following:: 439fb28afccSDavid Howells 440fb28afccSDavid Howells struct netfs_cache_ops { 441fb28afccSDavid Howells void (*end_operation)(struct netfs_cache_resources *cres); 442fb28afccSDavid Howells 443fb28afccSDavid Howells void (*expand_readahead)(struct netfs_cache_resources *cres, 444fb28afccSDavid Howells loff_t *_start, size_t *_len, loff_t i_size); 445fb28afccSDavid Howells 446fb28afccSDavid Howells enum netfs_read_source (*prepare_read)(struct netfs_read_subrequest *subreq, 447fb28afccSDavid Howells loff_t i_size); 448fb28afccSDavid Howells 449fb28afccSDavid Howells int (*read)(struct netfs_cache_resources *cres, 450fb28afccSDavid Howells loff_t start_pos, 451fb28afccSDavid Howells struct iov_iter *iter, 452fb28afccSDavid Howells bool seek_data, 453fb28afccSDavid Howells netfs_io_terminated_t term_func, 454fb28afccSDavid Howells void *term_func_priv); 455fb28afccSDavid Howells 456*ddca5b0eSDavid Howells int (*prepare_write)(struct netfs_cache_resources *cres, 457*ddca5b0eSDavid Howells loff_t *_start, size_t *_len, loff_t i_size); 458*ddca5b0eSDavid Howells 459fb28afccSDavid Howells int (*write)(struct netfs_cache_resources *cres, 460fb28afccSDavid Howells loff_t start_pos, 461fb28afccSDavid Howells struct iov_iter *iter, 462fb28afccSDavid Howells netfs_io_terminated_t term_func, 463fb28afccSDavid Howells void *term_func_priv); 464fb28afccSDavid Howells }; 465fb28afccSDavid Howells 466fb28afccSDavid HowellsWith a termination handler function pointer:: 467fb28afccSDavid Howells 468fb28afccSDavid Howells typedef void (*netfs_io_terminated_t)(void *priv, 469fb28afccSDavid Howells ssize_t transferred_or_error, 470fb28afccSDavid Howells bool was_async); 471fb28afccSDavid Howells 472fb28afccSDavid HowellsThe methods defined in the table are: 473fb28afccSDavid Howells 474fb28afccSDavid Howells * ``end_operation()`` 475fb28afccSDavid Howells 476fb28afccSDavid Howells [Required] Called to clean up the resources at the end of the read request. 477fb28afccSDavid Howells 478fb28afccSDavid Howells * ``expand_readahead()`` 479fb28afccSDavid Howells 480fb28afccSDavid Howells [Optional] Called at the beginning of a netfs_readahead() operation to allow 481fb28afccSDavid Howells the cache to expand a request in either direction. This allows the cache to 482fb28afccSDavid Howells size the request appropriately for the cache granularity. 483fb28afccSDavid Howells 484fb28afccSDavid Howells The function is passed poiners to the start and length in its parameters, 485fb28afccSDavid Howells plus the size of the file for reference, and adjusts the start and length 486fb28afccSDavid Howells appropriately. It should return one of: 487fb28afccSDavid Howells 488fb28afccSDavid Howells * ``NETFS_FILL_WITH_ZEROES`` 489fb28afccSDavid Howells * ``NETFS_DOWNLOAD_FROM_SERVER`` 490fb28afccSDavid Howells * ``NETFS_READ_FROM_CACHE`` 491fb28afccSDavid Howells * ``NETFS_INVALID_READ`` 492fb28afccSDavid Howells 493fb28afccSDavid Howells to indicate whether the slice should just be cleared or whether it should be 494fb28afccSDavid Howells downloaded from the server or read from the cache - or whether slicing 495fb28afccSDavid Howells should be given up at the current point. 496fb28afccSDavid Howells 497fb28afccSDavid Howells * ``prepare_read()`` 498fb28afccSDavid Howells 499fb28afccSDavid Howells [Required] Called to configure the next slice of a request. ->start and 500fb28afccSDavid Howells ->len in the subrequest indicate where and how big the next slice can be; 501fb28afccSDavid Howells the cache gets to reduce the length to match its granularity requirements. 502fb28afccSDavid Howells 503fb28afccSDavid Howells * ``read()`` 504fb28afccSDavid Howells 505fb28afccSDavid Howells [Required] Called to read from the cache. The start file offset is given 506fb28afccSDavid Howells along with an iterator to read to, which gives the length also. It can be 507fb28afccSDavid Howells given a hint requesting that it seek forward from that start position for 508fb28afccSDavid Howells data. 509fb28afccSDavid Howells 510fb28afccSDavid Howells Also provided is a pointer to a termination handler function and private 511fb28afccSDavid Howells data to pass to that function. The termination function should be called 512fb28afccSDavid Howells with the number of bytes transferred or an error code, plus a flag 513fb28afccSDavid Howells indicating whether the termination is definitely happening in the caller's 514fb28afccSDavid Howells context. 515fb28afccSDavid Howells 516*ddca5b0eSDavid Howells * ``prepare_write()`` 517*ddca5b0eSDavid Howells 518*ddca5b0eSDavid Howells [Required] Called to adjust a write to the cache and check that there is 519*ddca5b0eSDavid Howells sufficient space in the cache. The start and length values indicate the 520*ddca5b0eSDavid Howells size of the write that netfslib is proposing, and this can be adjusted by 521*ddca5b0eSDavid Howells the cache to respect DIO boundaries. The file size is passed for 522*ddca5b0eSDavid Howells information. 523*ddca5b0eSDavid Howells 524fb28afccSDavid Howells * ``write()`` 525fb28afccSDavid Howells 526fb28afccSDavid Howells [Required] Called to write to the cache. The start file offset is given 527fb28afccSDavid Howells along with an iterator to write from, which gives the length also. 528fb28afccSDavid Howells 529fb28afccSDavid Howells Also provided is a pointer to a termination handler function and private 530fb28afccSDavid Howells data to pass to that function. The termination function should be called 531fb28afccSDavid Howells with the number of bytes transferred or an error code, plus a flag 532fb28afccSDavid Howells indicating whether the termination is definitely happening in the caller's 533fb28afccSDavid Howells context. 534fb28afccSDavid Howells 535fb28afccSDavid HowellsNote that these methods are passed a pointer to the cache resource structure, 536fb28afccSDavid Howellsnot the read request structure as they could be used in other situations where 537fb28afccSDavid Howellsthere isn't a read request structure as well, such as writing dirty data to the 538fb28afccSDavid Howellscache. 5396abbaa5bSMatthew Wilcox (Oracle) 540*ddca5b0eSDavid Howells 541*ddca5b0eSDavid HowellsAPI Function Reference 542*ddca5b0eSDavid Howells====================== 543*ddca5b0eSDavid Howells 5446abbaa5bSMatthew Wilcox (Oracle).. kernel-doc:: include/linux/netfs.h 545*ddca5b0eSDavid Howells.. kernel-doc:: fs/netfs/read_helper.c 546