1 .. SPDX-License-Identifier: GPL-2.0
2
3 =================
4 Cache Backend API
5 =================
6
7 The FS-Cache system provides an API by which a
8 FS-Cache for it to then serve out to network f
9 parties. This API is used by::
10
11 #include <linux/fscache-cache.h>.
12
13
14 Overview
15 ========
16
17 Interaction with the API is handled on three l
18 storage, and each level has its own type of co
19
20 ======================= ==============
21 COOKIE C TYPE
22 ======================= ==============
23 Cache cookie struct fscache
24 Volume cookie struct fscache
25 Data storage cookie struct fscache
26 ======================= ==============
27
28 Cookies are used to provide some filesystem da
29 pin the cache during access in addition to act
30 API functions. Each cookie has a debugging ID
31 to make it easier to correlate traces. Note,
32 simply allocated from incrementing counters an
33
34 The cache backend and the network filesystem c
35 and if they ask for one of the same name, they
36 and data cookies, however, are created at the
37
38
39 Cache Cookies
40 =============
41
42 Caches are represented in the API by cache coo
43 type::
44
45 struct fscache_cache {
46 void *cache_priv;
47 unsigned int debug_id;
48 char *name;
49 ...
50 };
51
52 There are a few fields that the cache backend
53 ``debug_id`` can be used in tracing to match l
54 and ``name`` is the name the cache was registe
55 member is private data provided by the cache w
56 other fields are for internal use.
57
58
59 Registering a Cache
60 ===================
61
62 When a cache backend wants to bring a cache on
63 the cache name and that will get it a cache co
64
65 struct fscache_cache *fscache_acquire_
66
67 This will look up and potentially create a cac
68 have already been created by a network filesys
69 that cache cookie will be used. If the cache
70 cache, it will be moved into the preparing sta
71 busy.
72
73 If successful, the cache backend can then star
74 event that the initialisation fails, the cache
75
76 void fscache_relinquish_cache(struct f
77
78 to reset and discard the cookie.
79
80
81 Bringing a Cache Online
82 =======================
83
84 Once the cache is set up, it can be brought on
85
86 int fscache_add_cache(struct fscache_c
87 const struct fsc
88 void *cache_priv
89
90 This stores the cache operations table pointer
91 cache cookie and moves the cache to the active
92 to take place.
93
94
95 Withdrawing a Cache From Service
96 ================================
97
98 The cache backend can withdraw a cache from se
99
100 void fscache_withdraw_cache(struct fsc
101
102 This moves the cache to the withdrawn state to
103 volume-level accesses from starting and then w
104 accesses to complete.
105
106 The cache must then go through the data storag
107 to withdraw them, calling::
108
109 void fscache_withdraw_cookie(struct fs
110
111 on the cookie that each object belongs to. Th
112 for withdrawal. This gets offloaded to a work
113 wait for completion by calling::
114
115 void fscache_wait_for_objects(struct f
116
117 Once all the cookies are withdrawn, a cache ba
118 volumes, calling::
119
120 void fscache_withdraw_volume(struct fs
121
122 to tell fscache that a volume has been withdra
123 outstanding accesses on the volume to complete
124
125 When the cache is completely withdrawn, fscach
126 calling::
127
128 void fscache_relinquish_cache(struct f
129
130 to clear fields in the cookie and discard the
131
132
133 Volume Cookies
134 ==============
135
136 Within a cache, the data storage objects are o
137 These are represented in the API as objects of
138
139 struct fscache_volume {
140 struct fscache_cache
141 void
142 unsigned int
143 char
144 unsigned int
145 ...
146 u8
147 u8
148 };
149
150 There are a number of fields here that are of
151
152 * ``cache`` - The parent cache cookie.
153
154 * ``cache_priv`` - A place for the cache to
155
156 * ``debug_id`` - A debugging ID for logging
157
158 * ``key`` - A printable string with no '/'
159 the index key for the volume. The key is
160 a multiple of 4 bytes.
161
162 * ``key_hash`` - A hash of the index key.
163 matter the cpu arch and endianness.
164
165 * ``coherency`` - A piece of coherency data
166 volume is bound to in the cache.
167
168 * ``coherency_len`` - The amount of data in
169
170
171 Data Storage Cookies
172 ====================
173
174 A volume is a logical group of data storage ob
175 represented to the network filesystem by a coo
176 the API as objects of type::
177
178 struct fscache_cookie {
179 struct fscache_volume
180 void
181 unsigned long
182 unsigned int
183 unsigned int
184 loff_t
185 u8
186 u32
187 u8
188 u8
189 ...
190 };
191
192 The fields in the cookie that are of interest
193
194 * ``volume`` - The parent volume cookie.
195
196 * ``cache_priv`` - A place for the cache to
197
198 * ``flags`` - A collection of bit flags, in
199
200 * FSCACHE_COOKIE_NO_DATA_TO_READ - There
201 cache to be read as the cookie has bee
202
203 * FSCACHE_COOKIE_NEEDS_UPDATE - The cohe
204 been changed and needs committing.
205
206 * FSCACHE_COOKIE_LOCAL_WRITE - The netfs
207 locally, so the cache object may be in
208 to the server.
209
210 * FSCACHE_COOKIE_HAVE_DATA - The backend
211 successfully stores data into the cach
212
213 * FSCACHE_COOKIE_RETIRED - The cookie wa
214 relinquished and the cached data shoul
215
216 * ``debug_id`` - A debugging ID for logging
217
218 * ``inval_counter`` - The number of invalid
219
220 * ``advice`` - Information about how the co
221
222 * ``key_hash`` - A hash of the index key.
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
228
229 Each cookie has an index key, which may be sto
230 elsewhere. A pointer to this can be obtained
231
232 void *fscache_get_key(struct fscache_c
233
234 The index key is a binary blob, the storage fo
235 multiple of 4 bytes.
236
237 Each cookie also has a buffer for coherency da
238 detached from the cookie and a pointer is obta
239
240 void *fscache_get_aux(struct fscache_c
241
242
243
244 Cookie Accounting
245 =================
246
247 Data storage cookies are counted and this is u
248 completion until all objects have been destroy
249 provided to the cache to deal with that::
250
251 void fscache_count_object(struct fscac
252 void fscache_uncount_object(struct fsc
253 void fscache_wait_for_objects(struct f
254
255 The count function records the allocation of a
256 uncount function records its destruction. War
257 function returns, the cache may have been dest
258
259 The wait function can be used during the withd
260 fscache to finish withdrawing all the objects
261 there will be no remaining objects referring t
262 objects.
263
264
265 Cache Management API
266 ====================
267
268 The cache backend implements the cache managem
269 operations that fscache can use to manage vari
270 are held in a structure of type::
271
272 struct fscache_cache_ops {
273 const char *name;
274 ...
275 };
276
277 This contains a printable name for the cache b
278 pointers to methods to allow fscache to reques
279
280 * Set up a volume cookie [optional]::
281
282 void (*acquire_volume)(struct fscache_
283
284 This method is called when a volume cooki
285 holds a cache-level access pin to prevent
286 the duration. This method should set up
287 in the cache and should not return until
288
289 If successful, it can set ``cache_priv``
290
291
292 * Clean up volume cookie [optional]::
293
294 void (*free_volume)(struct fscache_volu
295
296 This method is called when a volume cooki
297 ``cache_priv`` is set.
298
299
300 * Look up a cookie in the cache [mandatory]
301
302 bool (*lookup_cookie)(struct fscache_c
303
304 This method is called to look up/create t
305 data storage for a cookie. It is called
306 volume-level access pin in the cache to p
307
308 True should be returned if successful and
309 returned, the withdraw_cookie op (see bel
310
311 If lookup fails, but the object could sti
312 been cached before), then::
313
314 void fscache_cookie_lookup_neg
315 struct fscache_cookie
316
317 can be called to let the network filesyst
318 stuff whilst the cache backend gets on wi
319
320 If successful, ``cookie->cache_priv`` can
321
322
323 * Withdraw an object without any cookie acc
324
325 void (*withdraw_cookie)(struct fscache
326
327 This method is called to withdraw a cooki
328 called when the cookie is relinquished by
329 by the cache backend or closed after a pe
330
331 The caller doesn't hold any access pins,
332 non-reentrant work item to manage races b
333 withdrawal can occur.
334
335 The cookie will have the ``FSCACHE_COOKIE
336 associated data is to be removed from the
337
338
339 * Change the size of a data storage object
340
341 void (*resize_cookie)(struct netfs_cac
342 loff_t new_size)
343
344 This method is called to inform the cache
345 the netfs file due to local truncation.
346 of the changes it needs to make before re
347 netfs inode mutex.
348
349 The caller holds a cookie-level access pi
350 withdrawal and the netfs must have the co
351 garbage collection or culling from removi
352
353
354 * Invalidate a data storage object [mandato
355
356 bool (*invalidate_cookie)(struct fscac
357
358 This is called when the network filesyste
359 modification or when an O_DIRECT write is
360 that the cache backend should throw away
361 this object and start afresh. It should
362 false otherwise.
363
364 On entry, new I O/operations are blocked.
365 to accept I/O again, the backend should r
366
367 void fscache_resume_after_invalidation
368
369 If the method returns false, caching will
370
371
372 * Prepare to make local modifications to th
373
374 void (*prepare_to_write)(struct fscach
375
376 This method is called when the network fi
377 to need to modify the contents of the cac
378 truncations. This gives the cache a chan
379 may be incoherent with respect to the ser
380 later. This may also cause the cached da
381 rebinding if not properly committed.
382
383
384 * Begin an operation for the netfs lib [man
385
386 bool (*begin_operation)(struct netfs_c
387 enum fscache_w
388
389 This method is called when an I/O operati
390 or resize). The caller holds an access p
391 marked the cookie as in-use.
392
393 If it can, the backend should attach any
394 to the netfs_cache_resources object and r
395
396 If it can't complete the setup, it should
397
398 The want_state parameter indicates the st
399 object to be in and what it wants to do d
400
401 * ``FSCACHE_WANT_PARAMS`` - The caller
402 object parameters; it doesn't need t
403
404 * ``FSCACHE_WANT_READ`` - The caller w
405
406 * ``FSCACHE_WANT_WRITE`` - The caller
407 cache object.
408
409 Note that there won't necessarily be anyt
410 cache_priv yet if the cookie is still bei
411
412
413 Data I/O API
414 ============
415
416 A cache backend provides a data I/O API by thr
417 netfs_cache_ops`` attached to a ``struct netfs
418 ``begin_operation`` method described above.
419
420 See the Documentation/filesystems/netfs_librar
421
422
423 Miscellaneous Functions
424 =======================
425
426 FS-Cache provides some utilities that a cache
427
428 * Note occurrence of an I/O error in a cach
429
430 void fscache_io_error(struct fscache_c
431
432 This tells FS-Cache that an I/O error occ
433 prevents any new I/O from being started o
434
435 This does not actually withdraw the cache
436
437 * Note cessation of caching on a cookie due
438
439 void fscache_caching_failed(struct fsc
440
441 This notes that a the caching that was be
442 some way, for instance the backing storag
443 invalidation failed and that no further I
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
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(voi
458
459 These record ENOSPC errors in the cache,
460 writes and failures of filesystem object
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 resour
469
470 struct fscache_cookie *fscache_cres_co
471
472 Pull a pointer to the cookie from the cac
473 NULL cookie if no cookie was set.
474
475
476 API Function Reference
477 ======================
478
479 .. kernel-doc:: include/linux/fscache-cache.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.