filesystems/caching/backend-api.rst

11 	#include <linux/fscache-cache.h>.
17 Interaction with the API is handled on three levels: cache, volume and data
28 Cookies are used to provide some filesystem data to the cache, manage state and
29 pin the cache during access in addition to acting as reference points for the
34 The cache backend and the network filesystem can both ask for cache cookies -
42 Caches are represented in the API by cache cookies.  These are objects of
52 There are a few fields that the cache backend might be interested in.  The
53 ``debug_id`` can be used in tracing to match lines referring to the same cache
54 and ``name`` is the name the cache was registered with.  The ``cache_priv``
55 member is private data provided by the cache when it is brought online.  The
62 When a cache backend wants to bring a cache online, it should first register
63 the cache name and that will get it a cache cookie.  This is done with::
67 This will look up and potentially create a cache cookie.  The cache cookie may
69 that cache cookie will be used.  If the cache cookie is not in use by another
70 cache, it will be moved into the preparing state, otherwise it will return
73 If successful, the cache backend can then start setting up the cache.  In the
74 event that the initialisation fails, the cache backend should call::
76 	void fscache_relinquish_cache(struct fscache_cache *cache);
84 Once the cache is set up, it can be brought online by calling::
86 	int fscache_add_cache(struct fscache_cache *cache,
90 This stores the cache operations table pointer and cache private data into the
91 cache cookie and moves the cache to the active state, thereby allowing accesses
98 The cache backend can withdraw a cache from service by calling this function::
100 	void fscache_withdraw_cache(struct fscache_cache *cache);
102 This moves the cache to the withdrawn state to prevent new cache- and
103 volume-level accesses from starting and then waits for outstanding cache-level
106 The cache must then go through the data storage objects it has and tell fscache
112 for withdrawal.  This gets offloaded to a workqueue.  The cache backend can
115 	void fscache_wait_for_objects(struct fscache_cache *cache);
117 Once all the cookies are withdrawn, a cache backend can withdraw all the
125 When the cache is completely withdrawn, fscache should be notified by
128 	void fscache_relinquish_cache(struct fscache_cache *cache);
136 Within a cache, the data storage objects are organised into logical volumes.
140 		struct fscache_cache		*cache;
152    * ``cache`` - The parent cache cookie.
154    * ``cache_priv`` - A place for the cache to stash private data.
166      volume is bound to in the cache.
192 The fields in the cookie that are of interest to the cache backend are:
196    * ``cache_priv`` - A place for the cache to stash private data.
201 	cache to be read as the cookie has been created or invalidated.
207 	locally, so the cache object may be in an incoherent state with respect
211 	successfully stores data into the cache.
247 Data storage cookies are counted and this is used to block cache withdrawal
249 provided to the cache to deal with that::
251 	void fscache_count_object(struct fscache_cache *cache);
252 	void fscache_uncount_object(struct fscache_cache *cache);
253 	void fscache_wait_for_objects(struct fscache_cache *cache);
255 The count function records the allocation of an object in a cache and the
257 function returns, the cache may have been destroyed.
260 fscache to finish withdrawing all the objects in the cache.  When it completes,
261 there will be no remaining objects referring to the cache object or any volume
268 The cache backend implements the cache management API by providing a table of
269 operations that fscache can use to manage various aspects of the cache.  These
277 This contains a printable name for the cache backend driver plus a number of
278 pointers to methods to allow fscache to request management of the cache:
285      holds a cache-level access pin to prevent the cache from going away for
287      in the cache and should not return until it has done so.
300    * Look up a cookie in the cache [mandatory]::
306      volume-level access pin in the cache to prevent it from being withdrawn.
318      stuff whilst the cache backend gets on with the job of creating things.
329      by the cache backend or closed after a period of non-use by fscache.
336      associated data is to be removed from the cache.
344      This method is called to inform the cache backend of a change in size of
345      the netfs file due to local truncation.  The cache backend should make all
360      that the cache backend should throw away all the data in the cache for
364      On entry, new I O/operations are blocked.  Once the cache is in a position
372    * Prepare to make local modifications to the cache [mandatory]::
377      to need to modify the contents of the cache due to local writes or
378      truncations.  This gives the cache a chance to note that a cache object
398      The want_state parameter indicates the state the caller needs the cache
401 	* ``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache
407           cache object.
416 A cache backend provides a data I/O API by through the netfs library's ``struct
426 FS-Cache provides some utilities that a cache backend may make use of:
428    * Note occurrence of an I/O error in a cache::
430 	void fscache_io_error(struct fscache_cache *cache);
432      This tells FS-Cache that an I/O error occurred in the cache.  This
433      prevents any new I/O from being started on the cache.
435      This does not actually withdraw the cache.  That must be done separately.
444      on it until the cache is reset.
451      These record reads and writes from/to the cache.  The numbers are
459      These record ENOSPC errors in the cache, divided into failures of data
468    * Get the cookie from a set of cache resources::
472      Pull a pointer to the cookie from the cache resources.  This may return a
479 .. kernel-doc:: include/linux/fscache-cache.h