Lines Matching +full:cache +full:-
1 .. SPDX-License-Identifier: GPL-2.0
4 FS-Cache Cache backend API
7 The FS-Cache system provides an API by which actual caches can be supplied to
8 FS-Cache for it to then serve out to network filesystems and other interested
11 This API is declared in <linux/fscache-cache.h>.
14 Initialising and Registering a Cache
17 To start off, a cache definition must be initialised and registered for each
18 cache the backend wants to make available. For instance, CacheFS does this in
21 The cache definition (struct fscache_cache) should be initialised by calling::
23 void fscache_init_cache(struct fscache_cache *cache,
30 * "cache" is a pointer to the cache definition;
33 this cache; and
35 * "idfmt" is a format and printf-style arguments for constructing a label
36 for the cache.
39 The cache should then be registered with FS-Cache by passing a pointer to the
40 previously initialised cache definition to::
42 int fscache_add_cache(struct fscache_cache *cache,
48 * "fsdef" which should point to the object representation for the FS-Cache
49 master index in this cache. Netfs primary index entries will be created
50 here. FS-Cache keeps the caller's reference to the index object if
51 successful and will release it upon withdrawal of the cache.
53 * "tagname" which, if given, should be a text string naming this cache. If
58 This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag
62 Unregistering a Cache
65 A cache can be withdrawn from the system by calling this function with a
66 pointer to the cache definition::
68 void fscache_withdraw_cache(struct fscache_cache *cache);
76 The cache methods are executed one of two contexts:
79 the cache method to be invoked, or
81 (2) that of one of the processes in the FS-Cache thread pool.
84 cache.
87 be masqueraded for the duration of the cache driver's access to the cache.
88 This is left to the cache to handle; FS-Cache makes no effort in this regard.
94 The cache may present data to the outside world through FS-Cache's interfaces
95 in sysfs and procfs - the former for control and the latter for statistics.
99 and is for use by the cache as it sees fit.
105 * Index/Data file FS-Cache representation cookie::
118 cache operations.
121 * In-cache object representation::
130 struct fscache_cache *cache;
135 Structures of this type should be allocated by the cache backend and
136 passed to FS-Cache when requested by the appropriate cache operation. In
142 using "OBJ%x" to be consistent with FS-Cache.
150 * FS-Cache operation record::
162 FS-Cache has a pool of threads that it uses to give CPU time to the
164 the cache. These are represented by the above structure. The processor
173 * FS-Cache retrieval operation record::
182 A structure of this type is allocated by FS-Cache to record retrieval and
189 do this, the retrieval->op.processor method pointer should be set
194 The to_do field is an empty list available for the cache backend to use as
198 * FS-Cache storage operation record::
206 A structure of this type is allocated by FS-Cache to record outstanding
207 writes to be made. FS-Cache itself enqueues this operation and invokes
212 Cache Operations
215 The cache backend provides FS-Cache with a table of operations that can be
216 performed on the denizens of the cache. These are held in a structure of type:
222 * Name of cache provider [mandatory]::
232 struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
235 This method is used to allocate a cache object representation to back a
236 cookie in a particular cache. fscache_object_init() should be called on
240 multiple lookup calls to turn it into a more convenient form. FS-Cache
241 will call the lookup_complete() method to allow the cache to release the
251 in the cache if it can.
254 possible if it determines the object doesn't exist in the cache. If the
258 should also be called once a non-present object has been created.
268 This method is called to ask the cache to release any resources it was
277 may fail (for instance if the cache is being withdrawn) by returning NULL.
295 These methods are used to pin an object into the cache. Once pinned an
296 object cannot be reclaimed to make space. Return -ENOSPC if there's not
297 enough space in the cache to permit this.
304 This method is called to have the cache check the saved auxiliary data of
306 if they're consistent and -ESTALE otherwise. -ENOMEM and -ERESTARTSYS
314 new information should be in object->cookie->netfs_data. This can be
315 obtained by calling object->cookie->def->get_aux()/get_attr().
322 This is called to invalidate a data object (as pointed to by op->object).
335 cookie, and that the cache should release the object's resources and
350 * Synchronise a cache [mandatory]::
352 void (*sync)(struct fscache_cache *cache)
354 This is called to ask the backend to synchronise a cache with its backing
358 * Dissociate a cache [mandatory]::
360 void (*dissociate_pages)(struct fscache_cache *cache)
362 This is called to ask a cache to perform any page dissociations as part of
363 cache withdrawal.
370 This is called to indicate to the cache that certain attributes on a netfs
372 cache can read these from the netfs by calling the cookie's get_attr()
375 The cache may use the file size information to reserve space on the cache.
376 It should also call fscache_set_store_limit() to indicate to FS-Cache the
379 This method may return -ve if an error occurred or the cache object cannot
382 This operation is run asynchronously from FS-Cache's thread pool, and
387 * Reserve cache space for an object's data [optional]::
391 This is called to request that cache space be reserved to hold the data
395 This should return 0 if successful, -ENOSPC if there isn't enough space
396 available, or -ENOMEM or -EIO on other errors.
405 * Request page be read from cache [mandatory]::
411 This is called to attempt to read a netfs page from the cache, or to
412 reserve a backing block if not. FS-Cache will have done as much checking
415 If there's no page in the cache, then -ENODATA should be returned if the
416 backend managed to reserve a backing block; -ENOBUFS or -ENOMEM if it
419 If there is suitable data in the cache, then a read operation should be
423 The fscache_mark_pages_cached() should be called for the page if any cache
432 The retrieval record may be used to get CPU time via the FS-Cache thread
433 pool. If this is desired, the op->op.processor should be set to point to
439 If an I/O error occurs, fscache_io_error() should be called and -ENOBUFS
447 * Request pages be read from cache [mandatory]::
456 started must be added to the page cache for the specified mapping and also
460 If there was an error such as -ENOMEM, then that should be returned; else
461 if one or more pages couldn't be read or allocated, then -ENOBUFS should
462 be returned; else if one or more pages couldn't be read, then -ENODATA
467 * Request page be allocated in the cache [mandatory]::
474 read from the cache, even if there's data there that could be retrieved.
476 the write_page() method can write to the cache.
478 If there's no backing block available, then -ENOBUFS should be returned
479 (or -ENOMEM if there were other problems). If a block is successfully
483 * Request pages be allocated in the cache [mandatory]::
494 * Request page be written to cache [mandatory]::
500 successful read_or_alloc_page() call or similar. FS-Cache filters out
503 This method is called asynchronously from the FS-Cache thread pool. It is
504 not required to actually store anything, provided -ENODATA is then
508 otherwise zero should be returned. FS-Cache will take appropriate action
511 If this method returns success then FS-Cache will inform the netfs
515 * Discard retained per-page metadata [mandatory]::
520 cache backend should tear down any internal representation or tracking it
524 FS-Cache Utilities
527 FS-Cache provides some utilities that a cache backend may make use of:
529 * Note occurrence of an I/O error in a cache::
531 void fscache_io_error(struct fscache_cache *cache)
533 This tells FS-Cache that an I/O error occurred in the cache. After this
535 release) will be passed from the netfs to the cache backend for the
536 specified cache.
538 This does not actually withdraw the cache. That must be done separately.
576 This sets the limit FS-Cache imposes on the highest byte it's willing to
578 rejected by fscache_read_alloc_page() and co with -ENOBUFS.
599 retrieved from the cache can be found.
624 void fscache_object_destroyed(struct fscache_cache *cache);
626 This must be called to inform FS-Cache that an object that belonged to a
627 cache has been destroyed and deallocated. This will allow continuation
628 of the cache withdrawal process when it is stopped pending destruction of
636 This is called to indicate to FS-Cache that a lookup process for an object
641 known at this point that there can't be any data in the cache.
644 significant - all subsequent calls are ignored.
651 This is called to indicate to FS-Cache that a lookup process for an object
678 the cache that the netfs decided was stale. The object has been
679 discarded from the cache and the lookup will be performed again.
687 This is called to indicate that the cache backend preemptively killed an
691 - the object was stale and needs discarding.
694 - there was insufficient cache space
697 - the object was retired when relinquished.
700 - the object was culled to make space.
716 This enqueues a retrieval record for processing by the FS-Cache thread
718 op->op.processor callback function. This function may be called from