Lines Matching +full:i +full:- +full:cache +full:- +full:size
2 FS-CACHE NETWORK FILESYSTEM API
5 There's an API by which a network filesystem can make use of the FS-Cache
10 FS-Cache to make finding objects faster and to make retiring of groups of
17 (3) Barring the top-level index (one entry per cached netfs), the index
28 (5) Cache tag lookup
32 (9) Setting the data file size
41 (18) FS-Cache specific page flags.
48 FS-Cache needs a description of the network filesystem. This is specified
67 entire in-cache hierarchy for this netfs will be scrapped and begun
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
105 (1) Any index containing non-index objects should be restricted to a single
106 cache. Any such objects created within an index will be created in the
107 first cache only. The cache in which an index is created can be
108 controlled by cache tags (see below).
154 This defines an index, which is a special FS-Cache type.
167 (3) A function to select the cache in which to store an index [optional].
169 This function is invoked when an index needs to be instantiated in a cache
170 during the instantiation of a non-index object. Only the immediate index
171 parent for the non-index object will be queried. Any indices above that
173 need to be supplied for any non-index object or any index that will only
177 cache in the parent's list will be chosen, or failing that, the first
178 cache in the master list.
182 This function will be called to check that a match found in the cache for
185 whether the index entry in a cache is still valid.
188 cache are always valid.
190 The function is also passed the cache's idea of the object size and may
195 (*) FSCACHE_CHECKAUX_OKAY - the entry is okay as is
196 (*) FSCACHE_CHECKAUX_NEEDS_UPDATE - the entry requires update
197 (*) FSCACHE_CHECKAUX_OBSOLETE - the entry should be deleted
200 the cache and copy it into the netfs's structures.
205 The cache read/write functions are passed a context which is then passed
206 to the I/O completion callback function. To ensure this context remains
207 valid until after the I/O completion is called, two functions may be
216 (6) A function to mark a page as retaining cache metadata [optional].
218 This is called by the cache to indicate that it is retaining in-memory
228 (7) A function to unmark all the pages retaining cache metadata [mandatory].
230 This is called by FS-Cache to indicate that a backing store is being
232 cleared to prevent confusion. Note that the cache will have torn down all
243 The first step is to declare the network filesystem to the cache. This also
264 CACHE TAG LOOKUP
267 FS-Cache permits the use of more than one cache. To permit particular index
268 subtrees to be bound to particular caches, the second step is to look up cache
270 FS-Cache as to which cache should be used. The problem with doing that is that
271 FS-Cache will always pick the first cache that was registered.
285 The tag will be retrieved by FS-Cache when it calls the object definition
293 The third step is to inform FS-Cache about part of an index hierarchy that can
314 An optional blob of auxiliary data that is to be stored within the cache can be
322 The cache tracks the size of the data attached to an object and this set to be
324 ->check_aux() callback.
326 Note that this function never returns an error - all errors are handled
330 functions - see below).
332 Note also that no indices are actually created in a cache until a non-index
344 cell->cache =
347 cell->name, strlen(cell->name),
354 volume->cache =
355 fscache_acquire_cookie(volume->cell->cache,
357 &volume->vid, sizeof(volume->vid),
366 The fourth step is to request a data file be created in the cache. This is
370 vnode->cache =
371 fscache_acquire_cookie(volume->cache,
375 vnode, vnode->status.size, true);
383 the cache. This is almost identical to index cookie acquisition. The only
388 xattr->cache =
389 fscache_acquire_cookie(vnode->cache,
391 &xattr->name, strlen(xattr->name),
393 xattr, strlen(xattr->val), true);
400 SETTING THE DATA FILE SIZE
403 The fifth step is to set the physical attributes of the file, such as its size.
404 This doesn't automatically reserve any space in the cache, but permits the
405 cache to adjust its metadata for data tracking appropriately:
409 The cache will return -ENOBUFS if there is no backing cache or if there is no
410 space to allocate any extra metadata required in the cache.
412 Note that attempts to read or write data pages in the cache over this size may
413 be rebuffed with -ENOBUFS.
424 And the sixth step is to store and retrieve pages in the cache. There are
429 (1) A page should not be re-read or re-allocated without uncaching it first.
434 (3) A page should only be written to the cache if previous read or allocated.
436 This permits the cache to maintain its page tracking in proper order.
440 ---------
442 Firstly, the netfs should ask FS-Cache to examine the caches and read the
464 (1) The function will return -ENOBUFS.
466 Else if there's a copy of the page resident in the cache:
470 (2) The function will submit a request to read the data from the cache's
493 Otherwise, if there's not a copy available in cache, but the cache may be able
498 (2) A block may be reserved in the cache and attached to the object at the
501 (3) The function will return -ENODATA.
503 This function may also return -ENOMEM or -EINTR, in which case it won't have
504 read any data from the cache.
508 -------------
510 Alternatively, if there's not expected to be any data in the cache for a page
518 never reads from the cache. It will return 0 if a block has been allocated,
519 rather than -ENODATA as the other would. One or the other must be performed
520 before writing to the cache.
527 ----------
531 written back to the cache:
540 object_size is the revised size of the object and the gfp argument is used to
548 (1) The function will return -ENOBUFS.
550 Else if space can be allocated in the cache to hold this page:
554 (2) The function will submit a request to write the data to cache's backing
562 Else if there's no space available in the cache, -ENOBUFS will be returned. It
570 ------------------
594 Else if some pages couldn't be allocated or read, then -ENOBUFS will be
597 Else if some pages couldn't be read but were allocated, then -ENODATA will
607 Note that a return of -ENODATA, -ENOBUFS or any other error does not preclude
613 ----------------------------
616 read from the cache and also not read from the underlying filesystem then
637 This function permits the cache to release any in-memory representation it
640 make sure the cache's in-memory tracking information gets torn down.
652 to see if a page is being written to the cache, and:
660 When releasepage() is being implemented, a special FS-Cache function exists to
662 conflict with the cache trying to write pages to the cache (which may itself
675 storage request to complete, or it may attempt to cancel the storage request -
676 in which case the page will not be stored in the cache this time.
680 -----------------------
684 1:1 basis with the pages in the cache.
691 written to the cache and for the cache to finish with the page generally. No
700 cache, the following function can be called:
706 with a cookie is correct; if aux_data is non-NULL, it will update the auxiliary
707 data buffer first. It returns 0 if it is and -ESTALE if it isn't; it may also
708 return -ENOMEM and -ERESTARTSYS.
717 that is non-NULL and then schedule this to be stored on disk. The update
730 invalidate its state; allocate, read or write backing pages - though it is
767 The object's data size is updated from object_size and is passed to the
768 ->check_aux() function.
771 that is non-NULL inside the enablement lock before proceeding.
785 These operations permit data cookies to be pinned into the cache and to
788 The pinning function will return 0 if successful, -ENOBUFS in the cookie
789 isn't backed by a cache, -EOPNOTSUPP if the cache doesn't support pinning,
790 -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
791 -EIO if there's any other problem.
795 int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size);
797 This permits a netfs to request cache space be reserved to store up to the
799 size of the file to allow for future file expansion.
801 If size is given as zero then the reservation will be cancelled.
803 The function will return 0 if successful, -ENOBUFS in the cookie isn't
804 backed by a cache, -EOPNOTSUPP if the cache doesn't support reservations,
805 -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
806 -EIO if there's any other problem.
808 Note that this doesn't pin an object in a cache; it can still be culled to
822 If retire is non-zero, then the object will be marked for recycling, and all
830 The cookie's auxiliary data will be updated from aux_data if that is non-NULL
831 so that the cache can lazily update it on disk.
833 One very important note - relinquish must NOT be called for a cookie unless all
852 change - at which point the netfs has to throw away all the state it had for an
855 To indicate that a cache object should be invalidated, the following function
863 cache has had a chance to insert a barrier in the operations queue. After
877 FS-CACHE SPECIFIC PAGE FLAG
880 FS-Cache makes use of a page flag, PG_private_2, for its own purpose. This is
883 PG_fscache is used to indicate that the page is known by the cache, and that
884 the cache must be informed if the page is going to go away. It's an indication
885 to the netfs that the cache has an interest in this page, where an interest may
886 be a pointer to it, resources allocated or reserved for it, or I/O in progress
898 This bit does not overlap with such as PG_private. This means that FS-Cache