Lines Matching refs:the
5 There's an API by which a network filesystem can make use of the FS-Cache
14 may or may not have anything associated with it, but the netfs doesn't
17 (3) Barring the top-level index (one entry per cached netfs), the index
18 hierarchy for each netfs is structured according the whim of the netfs.
22 This document contains the following sections:
32 (9) Setting the data file size
48 FS-Cache needs a description of the network filesystem. This is specified
49 using a record of the following structure:
58 This first two fields should be filled in before registration, and the third
59 will be filled in by the registration function; any other fields should just be
64 (1) The name of the netfs (used as the key in the toplevel index).
66 (2) The version of the netfs (if the name matches but the version doesn't, the
70 (3) The cookie representing the primary index will be allocated according to
71 another parameter passed into the registration function.
73 For example, kAFS (linux/fs/afs/) uses the following definitions to describe
88 (1) To aid the finding of a file based on a series of keys (such as AFS's
91 (2) To make it easier to discard a subset of all the files cached based around
92 a particular key - for instance to mirror the removal of an AFS volume.
95 their index hierarchies in quite the same way, FS-Cache tries to impose as few
97 the tree. The netfs can even mix indices and data files at the same level, but
106 cache. Any such objects created within an index will be created in the
113 (3) The depth of the index tree should be judged with care as the search
114 function is recursive. Too many layers will run the kernel out of stack.
121 To define an object, a structure of the following type should be filled out:
158 This has the following fields:
160 (1) The type of the object [mandatory].
162 This is one of the following values:
176 (2) The name of the object type (NUL terminated unless all 16 chars are used)
179 (3) A function to select the cache in which to store an index [optional].
182 during the instantiation of a non-index object. Only the immediate index
183 parent for the non-index object will be queried. Any indices above that
184 in the hierarchy may be stored in multiple caches. This function does not
188 If this function is not supplied or if it returns NULL then the first
189 cache in the parent's list will be chosen, or failing that, the first
190 cache in the master list.
192 (4) A function to retrieve an object's key from the netfs [mandatory].
194 This function will be called with the netfs data that was passed to the
195 cookie acquisition function and the maximum length of key data that it may
196 provide. It should write the required key data into the given buffer and
197 return the quantity it wrote.
199 (5) A function to retrieve attribute data from the netfs [optional].
201 This function will be called with the netfs data that was passed to the
202 cookie acquisition function. It should return the size of the file if
204 be reserved for this file in the cache.
206 If the function is absent, a file size of 0 is assumed.
208 (6) A function to retrieve auxiliary data from the netfs [optional].
210 This function will be called with the netfs data that was passed to the
211 cookie acquisition function and the maximum length of auxiliary data that
212 it may provide. It should write the auxiliary data into the given buffer
213 and return the quantity it wrote.
215 If this function is absent, the auxiliary data length will be set to 0.
217 The length of the auxiliary data buffer may be dependent on the key
221 (7) A function to check the auxiliary data [optional].
223 This function will be called to check that a match found in the cache for
224 this object is valid. For instance with AFS it could check the auxiliary
225 data against the data version number returned by the server to determine
226 whether the index entry in a cache is still valid.
231 If present, the function should return one of the following values:
233 (*) FSCACHE_CHECKAUX_OKAY - the entry is okay as is
234 (*) FSCACHE_CHECKAUX_NEEDS_UPDATE - the entry requires update
235 (*) FSCACHE_CHECKAUX_OBSOLETE - the entry should be deleted
237 This function can also be used to extract data from the auxiliary data in
238 the cache and copy it into the netfs's structures.
240 (8) A pair of functions to manage contexts for the completion callback
244 to the I/O completion callback function. To ensure this context remains
245 valid until after the I/O completion is called, two functions may be
246 provided: one to get an extra reference on the context, and one to drop a
249 If the context is not used or is a type of object that won't go out of
256 This is called by the cache to indicate that it is retaining in-memory
257 information for this page and that the netfs should uncache the page when
258 it has finished. This does not indicate whether there's data on the disk
261 The PG_fscache bit is set on the pages before this function would be
262 called, so the function need not be provided if this is sufficient.
266 (10) A function to unmark all the pages retaining cache metadata [mandatory].
269 unbound from a cookie and that all the marks on the pages should be
270 cleared to prevent confusion. Note that the cache will have torn down all
271 its tracking information so that the pages don't need to be explicitly
281 The first step is to declare the network filesystem to the cache. This also
282 involves specifying the layout of the primary index (for AFS, this would be the
289 It just takes a pointer to the netfs definition. It returns 0 or an error as
305 FS-Cache permits the use of more than one cache. To permit particular index
306 subtrees to be bound to particular caches, the second step is to look up cache
309 FS-Cache will always pick the first cache that was registered.
311 To get the representation for a named tag:
315 This takes a text string as the name and returns a representation of a tag. It
323 The tag will be retrieved by FS-Cache when it calls the object definition
333 the path to the file:
341 This function creates an index entry in the index represented by parent,
342 filling in the index entry by calling the operations pointed to by def.
346 acceptable to pass this token back to this function as the parent to another
347 acquisition (or even to the relinquish cookie, read page and write page
351 object needs to be created somewhere down the hierarchy. Furthermore, an index
353 This is all handled transparently, and the netfs doesn't see any of it.
355 A cookie will be created in the disabled state if enabled is false. A cookie
359 For example, with AFS, a cell would be added to the primary index. This index
360 entry would have a dependent inode containing a volume location index for the
368 Then when a volume location was accessed, it would be entered into the cell's
390 The fourth step is to request a data file be created in the cache. This is
391 identical to index cookie acquisition. The only difference is that the type in
392 the object definition should be something other than index type.
405 the cache. This is almost identical to index cookie acquisition. The only
406 difference is that the type in the object definition should be something other
407 than index type. Whilst the parent object could be an index, it's more likely
423 The fifth step is to set the physical attributes of the file, such as its size.
424 This doesn't automatically reserve any space in the cache, but permits the
430 space to allocate any extra metadata required in the cache. The attributes
431 will be accessed with the get_attr() cookie definition operation.
433 Note that attempts to read or write data pages in the cache over this size may
437 some point in the future, and as such, it may happen after the function returns
438 to the caller. The attribute adjustment excludes read and write operations.
445 And the sixth step is to store and retrieve pages in the cache. There are
452 (2) A read or allocated page must be uncached when the netfs page is released
453 from the pagecache.
455 (3) A page should only be written to the cache if previous read or allocated.
457 This permits the cache to maintain its page tracking in proper order.
463 Firstly, the netfs should ask FS-Cache to examine the caches and read the
465 allocate space to store the contents if not:
479 the page specified will have the data loaded into it (and is also used to
480 specify the page number), and the gfp argument is used to control how any
483 If the cookie indicates the inode is not cached:
487 Else if there's a copy of the page resident in the cache:
491 (2) The function will submit a request to read the data from the cache's
492 backing device directly into the page specified.
496 (4) When the read is complete, end_io_func() will be invoked with:
498 (*) The netfs data supplied when the cookie was created.
502 (*) The context argument passed to the above function. This will be
503 maintained with the get_context/put_context functions mentioned above.
507 If an error occurs, it should be assumed that the page contains no usable
510 end_io_func() will be called in process context if the read is results in
511 an error, but it might be called in interrupt context if the read is
514 Otherwise, if there's not a copy available in cache, but the cache may be able
515 to store the page:
519 (2) A block may be reserved in the cache and attached to the object at the
525 read any data from the cache.
531 Alternatively, if there's not expected to be any data in the cache for a page
532 because the file has been extended, a block can simply be allocated instead:
538 This is similar to the fscache_read_or_alloc_page() function, except that it
539 never reads from the cache. It will return 0 if a block has been allocated,
540 rather than -ENODATA as the other would. One or the other must be performed
541 before writing to the cache.
543 The mark_pages_cached() cookie operation will be called on the page if
550 Secondly, if the netfs changes the contents of the page (either due to an
551 initial download or if a user performs a write), then the page should be
552 written back to the cache:
558 The cookie argument must specify a data file cookie, the page specified should
559 contain the data to be written (and is also used to specify the page number),
560 and the gfp argument is used to control how any memory allocations made are
566 If the cookie indicates the inode is not cached then:
570 Else if space can be allocated in the cache to hold this page:
572 (1) PG_fscache_write will be set on the page.
574 (2) The function will submit a request to write the data to cache's backing
575 device directly from the page specified.
579 (4) When the write is complete PG_fscache_write is cleared on the page and
582 Else if there's no space available in the cache, -ENOBUFS will be returned. It
583 is also possible for the PG_fscache_write bit to be cleared when no write took
592 A facility is provided to read several pages at once, as requested by the
606 dispatched for reading to the disk. Reads of adjacent pages on disk may
620 Otherwise, if all pages had reads dispatched, then 0 will be returned, the
623 (4) end_io_func will be called once for each page being read as the reads
628 some of the pages being read and some being allocated. Those pages will have
636 read from the cache and also not read from the underlying filesystem then
643 prior to returning to the caller. The cookie argument should be as passed to
644 fscache_read_or_alloc_pages(). Every page in the pages list will be examined
657 This function permits the cache to release any in-memory representation it
659 each page on which the read or write page functions above have been called to
660 make sure the cache's in-memory tracking information gets torn down.
662 Note that pages can't be explicitly deleted from the a data file. The whole
663 data file must be retired (see the relinquish cookie function below).
665 Furthermore, note that this does not cancel the asynchronous read or write
666 operation started by the read/alloc and write functions, so the page
672 to see if a page is being written to the cache, and:
681 manage the heuristics of coping with vmscan trying to eject pages, which may
682 conflict with the cache trying to write pages to the cache (which may itself
689 This takes the netfs cookie, and the page and gfp arguments as supplied to
690 releasepage(). It will return false if the page cannot be released yet for
691 some reason and if it returns true, the page has been uncached and can now be
695 storage request to complete, or it may attempt to cancel the storage request -
696 in which case the page will not be stored in the cache this time.
702 A convenience routine is provided to perform an uncache on all the pages
703 attached to an inode. This assumes that the pages on the inode correspond on a
704 1:1 basis with the pages in the cache.
709 This takes the netfs cookie that the pages were cached with and the inode that
710 the pages are attached to. This function will wait for pages to finish being
711 written to the cache and for the cache to finish with the page generally. No
719 To find out whether auxiliary data for an object is up to data within the
720 cache, the following function can be called:
724 This will call back to the netfs to check whether the auxiliary data associated
728 To request an update of the index data for an index or other object, the
733 This function will refer back to the netfs_data pointer stored in the cookie by
734 the acquisition function to obtain the data to write into each revised index
735 entry. The update method in the parent index definition will be called to
736 transfer the data.
749 still possible to uncache pages and relinquish the cookie.
751 The initial enablement state is set by fscache_acquire_cookie(), but the cookie
757 If the cookie is not already disabled, this locks the cookie against other
758 enable and disable ops, marks the cookie as being disabled, discards or
760 associated object before unlocking the cookie.
772 If the cookie is not already enabled, this locks the cookie against other
773 enable and disable ops, invokes can_enable() and, if the cookie is not an index
774 cookie, will begin the procedure of acquiring backing objects.
776 The optional can_enable() function is passed the data argument and returns a
794 These operations permit data cookies to be pinned into the cache and to
795 have the pinning removed. They are not permitted on index cookies.
797 The pinning function will return 0 if successful, -ENOBUFS in the cookie
798 isn't backed by a cache, -EOPNOTSUPP if the cache doesn't support pinning,
799 -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
806 This permits a netfs to request cache space be reserved to store up to the
807 given amount of a file. It is permitted to ask for more than the current
808 size of the file to allow for future file expansion.
810 If size is given as zero then the reservation will be cancelled.
812 The function will return 0 if successful, -ENOBUFS in the cookie isn't
813 backed by a cache, -EOPNOTSUPP if the cache doesn't support reservations,
814 -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
830 If retire is non-zero, then the object will be marked for recycling, and all
834 If retire is zero, then the object may be available again when next the
835 acquisition function is called. Retirement here will overrule the pinning on a
839 the cookies for "child" indices, objects and pages have been relinquished
847 There is no direct way to invalidate an index subtree. To do this, the caller
848 should relinquish and retire the cookie they have, and then acquire a new one.
856 Typically this will be necessary when the server tells the netfs of a foreign
857 change - at which point the netfs has to throw away all the state it had for an
858 inode and reload from the server.
860 To indicate that a cache object should be invalidated, the following function
865 This can be called with spinlocks held as it defers the work to a thread pool.
867 cancelled and discarded. Some future operations will be rejected until the
868 cache has had a chance to insert a barrier in the operations queue. After
869 that, operations will be queued again behind the invalidation operation.
874 Using the following function, the netfs can wait for the invalidation operation
886 given the alternative name PG_fscache.
888 PG_fscache is used to indicate that the page is known by the cache, and that
889 the cache must be informed if the page is going to go away. It's an indication
890 to the netfs that the cache has an interest in this page, where an interest may
900 after fscache_read_or_alloc_pages() as the former will try and release pages it
904 can be used with a filesystem that uses the block buffering code.