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