1.. SPDX-License-Identifier: GPL-2.0
2
3=================
4Cache Backend API
5=================
6
7The FS-Cache system provides an API by which actual caches can be supplied to
8FS-Cache for it to then serve out to network filesystems and other interested
9parties.  This API is used by::
10
11	#include <linux/fscache-cache.h>.
12
13
14Overview
15========
16
17Interaction with the API is handled on three levels: cache, volume and data
18storage, and each level has its own type of cookie object:
19
20	=======================	=======================
21	COOKIE			C TYPE
22	=======================	=======================
23	Cache cookie		struct fscache_cache
24	Volume cookie		struct fscache_volume
25	Data storage cookie	struct fscache_cookie
26	=======================	=======================
27
28Cookies are used to provide some filesystem data to the cache, manage state and
29pin the cache during access in addition to acting as reference points for the
30API functions.  Each cookie has a debugging ID that is included in trace points
31to make it easier to correlate traces.  Note, though, that debugging IDs are
32simply allocated from incrementing counters and will eventually wrap.
33
34The cache backend and the network filesystem can both ask for cache cookies -
35and if they ask for one of the same name, they'll get the same cookie.  Volume
36and data cookies, however, are created at the behest of the filesystem only.
37
38
39Cache Cookies
40=============
41
42Caches are represented in the API by cache cookies.  These are objects of
43type::
44
45	struct fscache_cache {
46		void		*cache_priv;
47		unsigned int	debug_id;
48		char		*name;
49		...
50	};
51
52There 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
54and ``name`` is the name the cache was registered with.  The ``cache_priv``
55member is private data provided by the cache when it is brought online.  The
56other fields are for internal use.
57
58
59Registering a Cache
60===================
61
62When a cache backend wants to bring a cache online, it should first register
63the cache name and that will get it a cache cookie.  This is done with::
64
65	struct fscache_cache *fscache_acquire_cache(const char *name);
66
67This will look up and potentially create a cache cookie.  The cache cookie may
68have already been created by a network filesystem looking for it, in which case
69that cache cookie will be used.  If the cache cookie is not in use by another
70cache, it will be moved into the preparing state, otherwise it will return
71busy.
72
73If successful, the cache backend can then start setting up the cache.  In the
74event that the initialisation fails, the cache backend should call::
75
76	void fscache_relinquish_cookie(struct fscache_cache *cache);
77
78to reset and discard the cookie.
79
80
81Bringing a Cache Online
82=======================
83
84Once the cache is set up, it can be brought online by calling::
85
86	int fscache_add_cache(struct fscache_cache *cache,
87			      const struct fscache_cache_ops *ops,
88			      void *cache_priv);
89
90This stores the cache operations table pointer and cache private data into the
91cache cookie and moves the cache to the active state, thereby allowing accesses
92to take place.
93
94
95Withdrawing a Cache From Service
96================================
97
98The cache backend can withdraw a cache from service by calling this function::
99
100	void fscache_withdraw_cache(struct fscache_cache *cache);
101
102This moves the cache to the withdrawn state to prevent new cache- and
103volume-level accesses from starting and then waits for outstanding cache-level
104accesses to complete.
105
106The cache must then go through the data storage objects it has and tell fscache
107to withdraw them, calling::
108
109	void fscache_withdraw_cookie(struct fscache_cookie *cookie);
110
111on the cookie that each object belongs to.  This schedules the specified cookie
112for withdrawal.  This gets offloaded to a workqueue.  The cache backend can
113test for completion by calling::
114
115	bool fscache_are_objects_withdrawn(struct fscache_cookie *cache);
116
117Once all the cookies are withdrawn, a cache backend can withdraw all the
118volumes, calling::
119
120	void fscache_withdraw_volume(struct fscache_volume *volume);
121
122to tell fscache that a volume has been withdrawn.  This waits for all
123outstanding accesses on the volume to complete before returning.
124
125When the the cache is completely withdrawn, fscache should be notified by
126calling::
127
128	void fscache_cache_relinquish(struct fscache_cache *cache);
129
130to clear fields in the cookie and discard the caller's ref on it.
131
132
133Volume Cookies
134==============
135
136Within a cache, the data storage objects are organised into logical volumes.
137These are represented in the API as objects of type::
138
139	struct fscache_volume {
140		struct fscache_cache		*cache;
141		void				*cache_priv;
142		unsigned int			debug_id;
143		char				*key;
144		unsigned int			key_hash;
145		...
146		u8				coherency_len;
147		u8				coherency[];
148	};
149
150There are a number of fields here that are of interest to the caching backend:
151
152   * ``cache`` - The parent cache cookie.
153
154   * ``cache_priv`` - A place for the cache to stash private data.
155
156   * ``debug_id`` - A debugging ID for logging in tracepoints.
157
158   * ``key`` - A printable string with no '/' characters in it that represents
159     the index key for the volume.  The key is NUL-terminated and padded out to
160     a multiple of 4 bytes.
161
162   * ``key_hash`` - A hash of the index key.  This should work out the same, no
163     matter the cpu arch and endianness.
164
165   * ``coherency`` - A piece of coherency data that should be checked when the
166     volume is bound to in the cache.
167
168   * ``coherency_len`` - The amount of data in the coherency buffer.
169
170
171Data Storage Cookies
172====================
173
174A volume is a logical group of data storage objects, each of which is
175represented to the network filesystem by a cookie.  Cookies are represented in
176the API as objects of type::
177
178	struct fscache_cookie {
179		struct fscache_volume		*volume;
180		void				*cache_priv;
181		unsigned long			flags;
182		unsigned int			debug_id;
183		unsigned int			inval_counter;
184		loff_t				object_size;
185		u8				advice;
186		u32				key_hash;
187		u8				key_len;
188		u8				aux_len;
189		...
190	};
191
192The fields in the cookie that are of interest to the cache backend are:
193
194   * ``volume`` - The parent volume cookie.
195
196   * ``cache_priv`` - A place for the cache to stash private data.
197
198   * ``flags`` - A collection of bit flags, including:
199
200      * FSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the
201	cache to be read as the cookie has been created or invalidated.
202
203      * FSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has
204	been changed and needs committing.
205
206      * FSCACHE_COOKIE_LOCAL_WRITE - The netfs's data has been modified
207	locally, so the cache object may be in an incoherent state with respect
208	to the server.
209
210      * FSCACHE_COOKIE_HAVE_DATA - The backend should set this if it
211	successfully stores data into the cache.
212
213      * FSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was
214	relinquished and the cached data should be discarded.
215
216   * ``debug_id`` - A debugging ID for logging in tracepoints.
217
218   * ``inval_counter`` - The number of invalidations done on the cookie.
219
220   * ``advice`` - Information about how the cookie is to be used.
221
222   * ``key_hash`` - A hash of the index key.  This should work out the same, no
223     matter the cpu arch and endianness.
224
225   * ``key_len`` - The length of the index key.
226
227   * ``aux_len`` - The length of the coherency data buffer.
228
229Each cookie has an index key, which may be stored inline to the cookie or
230elsewhere.  A pointer to this can be obtained by calling::
231
232	void *fscache_get_key(struct fscache_cookie *cookie);
233
234The index key is a binary blob, the storage for which is padded out to a
235multiple of 4 bytes.
236
237Each cookie also has a buffer for coherency data.  This may also be inline or
238detached from the cookie and a pointer is obtained by calling::
239
240	void *fscache_get_aux(struct fscache_cookie *cookie);
241
242
243
244Cookie Accounting
245=================
246
247Data storage cookies are counted and this is used to block cache withdrawal
248completion until all objects have been destroyed.  The following functions are
249provided to the cache to deal with that::
250
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);
254
255The count function records the allocation of an object in a cache and the
256uncount function records its destruction.  Warning: by the time the uncount
257function returns, the cache may have been destroyed.
258
259The wait function can be used during the withdrawal procedure to wait for
260fscache to finish withdrawing all the objects in the cache.  When it completes,
261there will be no remaining objects referring to the cache object or any volume
262objects.
263
264
265Cache Management API
266====================
267
268The cache backend implements the cache management API by providing a table of
269operations that fscache can use to manage various aspects of the cache.  These
270are held in a structure of type::
271
272	struct fscache_cache_ops {
273		const char *name;
274		...
275	};
276
277This contains a printable name for the cache backend driver plus a number of
278pointers to methods to allow fscache to request management of the cache:
279
280   * Set up a volume cookie [optional]::
281
282	void (*acquire_volume)(struct fscache_volume *volume);
283
284     This method is called when a volume cookie is being created.  The caller
285     holds a cache-level access pin to prevent the cache from going away for
286     the duration.  This method should set up the resources to access a volume
287     in the cache and should not return until it has done so.
288
289     If successful, it can set ``cache_priv`` to its own data.
290
291
292   * Clean up volume cookie [optional]::
293
294       void (*free_volume)(struct fscache_volume *volume);
295
296     This method is called when a volume cookie is being released if
297     ``cache_priv`` is set.
298
299
300   * Look up a cookie in the cache [mandatory]::
301
302	bool (*lookup_cookie)(struct fscache_cookie *cookie);
303
304     This method is called to look up/create the resources needed to access the
305     data storage for a cookie.  It is called from a worker thread with a
306     volume-level access pin in the cache to prevent it from being withdrawn.
307
308     True should be returned if successful and false otherwise.  If false is
309     returned, the withdraw_cookie op (see below) will be called.
310
311     If lookup fails, but the object could still be created (e.g. it hasn't
312     been cached before), then::
313
314		void fscache_cookie_lookup_negative(
315			struct fscache_cookie *cookie);
316
317     can be called to let the network filesystem proceed and start downloading
318     stuff whilst the cache backend gets on with the job of creating things.
319
320     If successful, ``cookie->cache_priv`` can be set.
321
322
323   * Withdraw an object without any cookie access counts held [mandatory]::
324
325	void (*withdraw_cookie)(struct fscache_cookie *cookie);
326
327     This method is called to withdraw a cookie from service.  It will be
328     called when the cookie is relinquished by the netfs, withdrawn or culled
329     by the cache backend or closed after a period of non-use by fscache.
330
331     The caller doesn't hold any access pins, but it is called from a
332     non-reentrant work item to manage races between the various ways
333     withdrawal can occur.
334
335     The cookie will have the ``FSCACHE_COOKIE_RETIRED`` flag set on it if the
336     associated data is to be removed from the cache.
337
338
339   * Change the size of a data storage object [mandatory]::
340
341	void (*resize_cookie)(struct netfs_cache_resources *cres,
342			      loff_t new_size);
343
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
346     of the changes it needs to make before returning as this is done under the
347     netfs inode mutex.
348
349     The caller holds a cookie-level access pin to prevent a race with
350     withdrawal and the netfs must have the cookie marked in-use to prevent
351     garbage collection or culling from removing any resources.
352
353
354   * Invalidate a data storage object [mandatory]::
355
356	bool (*invalidate_cookie)(struct fscache_cookie *cookie);
357
358     This is called when the network filesystem detects a third-party
359     modification or when an O_DIRECT write is made locally.  This requests
360     that the cache backend should throw away all the data in the cache for
361     this object and start afresh.  It should return true if successful and
362     false otherwise.
363
364     On entry, new I O/operations are blocked.  Once the cache is in a position
365     to accept I/O again, the backend should release the block by calling::
366
367	void fscache_resume_after_invalidation(struct fscache_cookie *cookie);
368
369     If the method returns false, caching will be withdrawn for this cookie.
370
371
372   * Prepare to make local modifications to the cache [mandatory]::
373
374	void (*prepare_to_write)(struct fscache_cookie *cookie);
375
376     This method is called when the network filesystem finds that it is going
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
379     may be incoherent with respect to the server and may need writing back
380     later.  This may also cause the cached data to be scrapped on later
381     rebinding if not properly committed.
382
383
384   * Begin an operation for the netfs lib [mandatory]::
385
386	bool (*begin_operation)(struct netfs_cache_resources *cres,
387				enum fscache_want_state want_state);
388
389     This method is called when an I/O operation is being set up (read, write
390     or resize).  The caller holds an access pin on the cookie and must have
391     marked the cookie as in-use.
392
393     If it can, the backend should attach any resources it needs to keep around
394     to the netfs_cache_resources object and return true.
395
396     If it can't complete the setup, it should return false.
397
398     The want_state parameter indicates the state the caller needs the cache
399     object to be in and what it wants to do during the operation:
400
401	* ``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache
402	  object parameters; it doesn't need to do data I/O yet.
403
404	* ``FSCACHE_WANT_READ`` - The caller wants to read data.
405
406	* ``FSCACHE_WANT_WRITE`` - The caller wants to write to or resize the
407          cache object.
408
409     Note that there won't necessarily be anything attached to the cookie's
410     cache_priv yet if the cookie is still being created.
411
412
413Data I/O API
414============
415
416A cache backend provides a data I/O API by through the netfs library's ``struct
417netfs_cache_ops`` attached to a ``struct netfs_cache_resources`` by the
418``begin_operation`` method described above.
419
420See the Documentation/filesystems/netfs_library.rst for a description.
421
422
423Miscellaneous Functions
424=======================
425
426FS-Cache provides some utilities that a cache backend may make use of:
427
428   * Note occurrence of an I/O error in a cache::
429
430	void fscache_io_error(struct fscache_cache *cache);
431
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.
434
435     This does not actually withdraw the cache.  That must be done separately.
436
437   * Note cessation of caching on a cookie due to failure::
438
439	void fscache_caching_failed(struct fscache_cookie *cookie);
440
441     This notes that a the caching that was being done on a cookie failed in
442     some way, for instance the backing storage failed to be created or
443     invalidation failed and that no further I/O operations should take place
444     on it until the cache is reset.
445
446   * Count I/O requests::
447
448	void fscache_count_read(void);
449	void fscache_count_write(void);
450
451     These record reads and writes from/to the cache.  The numbers are
452     displayed in /proc/fs/fscache/stats.
453
454   * Count out-of-space errors::
455
456	void fscache_count_no_write_space(void);
457	void fscache_count_no_create_space(void);
458
459     These record ENOSPC errors in the cache, divided into failures of data
460     writes and failures of filesystem object creations (e.g. mkdir).
461
462   * Count objects culled::
463
464	void fscache_count_culled(void);
465
466     This records the culling of an object.
467
468   * Get the cookie from a set of cache resources::
469
470	struct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres)
471
472     Pull a pointer to the cookie from the cache resources.  This may return a
473     NULL cookie if no cookie was set.
474
475
476API Function Reference
477======================
478
479.. kernel-doc:: include/linux/fscache-cache.h
480