Loading...
1.. SPDX-License-Identifier: GPL-2.0
2
3==========================
4FS-Cache Cache 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.
10
11This API is declared in <linux/fscache-cache.h>.
12
13
14Initialising and Registering a Cache
15====================================
16
17To start off, a cache definition must be initialised and registered for each
18cache the backend wants to make available. For instance, CacheFS does this in
19the fill_super() operation on mounting.
20
21The cache definition (struct fscache_cache) should be initialised by calling::
22
23 void fscache_init_cache(struct fscache_cache *cache,
24 struct fscache_cache_ops *ops,
25 const char *idfmt,
26 ...);
27
28Where:
29
30 * "cache" is a pointer to the cache definition;
31
32 * "ops" is a pointer to the table of operations that the backend supports on
33 this cache; and
34
35 * "idfmt" is a format and printf-style arguments for constructing a label
36 for the cache.
37
38
39The cache should then be registered with FS-Cache by passing a pointer to the
40previously initialised cache definition to::
41
42 int fscache_add_cache(struct fscache_cache *cache,
43 struct fscache_object *fsdef,
44 const char *tagname);
45
46Two extra arguments should also be supplied:
47
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.
52
53 * "tagname" which, if given, should be a text string naming this cache. If
54 this is NULL, the identifier will be used instead. For CacheFS, the
55 identifier is set to name the underlying block device and the tag can be
56 supplied by mount.
57
58This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag
59is already in use. 0 will be returned on success.
60
61
62Unregistering a Cache
63=====================
64
65A cache can be withdrawn from the system by calling this function with a
66pointer to the cache definition::
67
68 void fscache_withdraw_cache(struct fscache_cache *cache);
69
70In CacheFS's case, this is called by put_super().
71
72
73Security
74========
75
76The cache methods are executed one of two contexts:
77
78 (1) that of the userspace process that issued the netfs operation that caused
79 the cache method to be invoked, or
80
81 (2) that of one of the processes in the FS-Cache thread pool.
82
83In either case, this may not be an appropriate context in which to access the
84cache.
85
86The calling process's fsuid, fsgid and SELinux security identities may need to
87be masqueraded for the duration of the cache driver's access to the cache.
88This is left to the cache to handle; FS-Cache makes no effort in this regard.
89
90
91Control and Statistics Presentation
92===================================
93
94The cache may present data to the outside world through FS-Cache's interfaces
95in sysfs and procfs - the former for control and the latter for statistics.
96
97A sysfs directory called /sys/fs/fscache/<cachetag>/ is created if CONFIG_SYSFS
98is enabled. This is accessible through the kobject struct fscache_cache::kobj
99and is for use by the cache as it sees fit.
100
101
102Relevant Data Structures
103========================
104
105 * Index/Data file FS-Cache representation cookie::
106
107 struct fscache_cookie {
108 struct fscache_object_def *def;
109 struct fscache_netfs *netfs;
110 void *netfs_data;
111 ...
112 };
113
114 The fields that might be of use to the backend describe the object
115 definition, the netfs definition and the netfs's data for this cookie.
116 The object definition contain functions supplied by the netfs for loading
117 and matching index entries; these are required to provide some of the
118 cache operations.
119
120
121 * In-cache object representation::
122
123 struct fscache_object {
124 int debug_id;
125 enum {
126 FSCACHE_OBJECT_RECYCLING,
127 ...
128 } state;
129 spinlock_t lock
130 struct fscache_cache *cache;
131 struct fscache_cookie *cookie;
132 ...
133 };
134
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
137 the case of CacheFS, they're embedded in CacheFS's internal object
138 structures.
139
140 The debug_id is a simple integer that can be used in debugging messages
141 that refer to a particular object. In such a case it should be printed
142 using "OBJ%x" to be consistent with FS-Cache.
143
144 Each object contains a pointer to the cookie that represents the object it
145 is backing. An object should retired when put_object() is called if it is
146 in state FSCACHE_OBJECT_RECYCLING. The fscache_object struct should be
147 initialised by calling fscache_object_init(object).
148
149
150 * FS-Cache operation record::
151
152 struct fscache_operation {
153 atomic_t usage;
154 struct fscache_object *object;
155 unsigned long flags;
156 #define FSCACHE_OP_EXCLUSIVE
157 void (*processor)(struct fscache_operation *op);
158 void (*release)(struct fscache_operation *op);
159 ...
160 };
161
162 FS-Cache has a pool of threads that it uses to give CPU time to the
163 various asynchronous operations that need to be done as part of driving
164 the cache. These are represented by the above structure. The processor
165 method is called to give the op CPU time, and the release method to get
166 rid of it when its usage count reaches 0.
167
168 An operation can be made exclusive upon an object by setting the
169 appropriate flag before enqueuing it with fscache_enqueue_operation(). If
170 an operation needs more processing time, it should be enqueued again.
171
172
173 * FS-Cache retrieval operation record::
174
175 struct fscache_retrieval {
176 struct fscache_operation op;
177 struct address_space *mapping;
178 struct list_head *to_do;
179 ...
180 };
181
182 A structure of this type is allocated by FS-Cache to record retrieval and
183 allocation requests made by the netfs. This struct is then passed to the
184 backend to do the operation. The backend may get extra refs to it by
185 calling fscache_get_retrieval() and refs may be discarded by calling
186 fscache_put_retrieval().
187
188 A retrieval operation can be used by the backend to do retrieval work. To
189 do this, the retrieval->op.processor method pointer should be set
190 appropriately by the backend and fscache_enqueue_retrieval() called to
191 submit it to the thread pool. CacheFiles, for example, uses this to queue
192 page examination when it detects PG_lock being cleared.
193
194 The to_do field is an empty list available for the cache backend to use as
195 it sees fit.
196
197
198 * FS-Cache storage operation record::
199
200 struct fscache_storage {
201 struct fscache_operation op;
202 pgoff_t store_limit;
203 ...
204 };
205
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
208 the write_page() method on the object at appropriate times to effect
209 storage.
210
211
212Cache Operations
213================
214
215The cache backend provides FS-Cache with a table of operations that can be
216performed on the denizens of the cache. These are held in a structure of type:
217
218 ::
219
220 struct fscache_cache_ops
221
222 * Name of cache provider [mandatory]::
223
224 const char *name
225
226 This isn't strictly an operation, but should be pointed at a string naming
227 the backend.
228
229
230 * Allocate a new object [mandatory]::
231
232 struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
233 struct fscache_cookie *cookie)
234
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
237 the object to initialise it prior to returning.
238
239 This function may also be used to parse the index key to be used for
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
242 form once lookup is complete or aborted.
243
244
245 * Look up and create object [mandatory]::
246
247 void (*lookup_object)(struct fscache_object *object)
248
249 This method is used to look up an object, given that the object is already
250 allocated and attached to the cookie. This should instantiate that object
251 in the cache if it can.
252
253 The method should call fscache_object_lookup_negative() as soon as
254 possible if it determines the object doesn't exist in the cache. If the
255 object is found to exist and the netfs indicates that it is valid then
256 fscache_obtained_object() should be called once the object is in a
257 position to have data stored in it. Similarly, fscache_obtained_object()
258 should also be called once a non-present object has been created.
259
260 If a lookup error occurs, fscache_object_lookup_error() should be called
261 to abort the lookup of that object.
262
263
264 * Release lookup data [mandatory]::
265
266 void (*lookup_complete)(struct fscache_object *object)
267
268 This method is called to ask the cache to release any resources it was
269 using to perform a lookup.
270
271
272 * Increment object refcount [mandatory]::
273
274 struct fscache_object *(*grab_object)(struct fscache_object *object)
275
276 This method is called to increment the reference count on an object. It
277 may fail (for instance if the cache is being withdrawn) by returning NULL.
278 It should return the object pointer if successful.
279
280
281 * Lock/Unlock object [mandatory]::
282
283 void (*lock_object)(struct fscache_object *object)
284 void (*unlock_object)(struct fscache_object *object)
285
286 These methods are used to exclusively lock an object. It must be possible
287 to schedule with the lock held, so a spinlock isn't sufficient.
288
289
290 * Pin/Unpin object [optional]::
291
292 int (*pin_object)(struct fscache_object *object)
293 void (*unpin_object)(struct fscache_object *object)
294
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.
298
299
300 * Check coherency state of an object [mandatory]::
301
302 int (*check_consistency)(struct fscache_object *object)
303
304 This method is called to have the cache check the saved auxiliary data of
305 the object against the netfs's idea of the state. 0 should be returned
306 if they're consistent and -ESTALE otherwise. -ENOMEM and -ERESTARTSYS
307 may also be returned.
308
309 * Update object [mandatory]::
310
311 int (*update_object)(struct fscache_object *object)
312
313 This is called to update the index entry for the specified object. The
314 new information should be in object->cookie->netfs_data. This can be
315 obtained by calling object->cookie->def->get_aux()/get_attr().
316
317
318 * Invalidate data object [mandatory]::
319
320 int (*invalidate_object)(struct fscache_operation *op)
321
322 This is called to invalidate a data object (as pointed to by op->object).
323 All the data stored for this object should be discarded and an
324 attr_changed operation should be performed. The caller will follow up
325 with an object update operation.
326
327 fscache_op_complete() must be called on op before returning.
328
329
330 * Discard object [mandatory]::
331
332 void (*drop_object)(struct fscache_object *object)
333
334 This method is called to indicate that an object has been unbound from its
335 cookie, and that the cache should release the object's resources and
336 retire it if it's in state FSCACHE_OBJECT_RECYCLING.
337
338 This method should not attempt to release any references held by the
339 caller. The caller will invoke the put_object() method as appropriate.
340
341
342 * Release object reference [mandatory]::
343
344 void (*put_object)(struct fscache_object *object)
345
346 This method is used to discard a reference to an object. The object may
347 be freed when all the references to it are released.
348
349
350 * Synchronise a cache [mandatory]::
351
352 void (*sync)(struct fscache_cache *cache)
353
354 This is called to ask the backend to synchronise a cache with its backing
355 device.
356
357
358 * Dissociate a cache [mandatory]::
359
360 void (*dissociate_pages)(struct fscache_cache *cache)
361
362 This is called to ask a cache to perform any page dissociations as part of
363 cache withdrawal.
364
365
366 * Notification that the attributes on a netfs file changed [mandatory]::
367
368 int (*attr_changed)(struct fscache_object *object);
369
370 This is called to indicate to the cache that certain attributes on a netfs
371 file have changed (for example the maximum size a file may reach). The
372 cache can read these from the netfs by calling the cookie's get_attr()
373 method.
374
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
377 highest byte it's willing to store for an object.
378
379 This method may return -ve if an error occurred or the cache object cannot
380 be expanded. In such a case, the object will be withdrawn from service.
381
382 This operation is run asynchronously from FS-Cache's thread pool, and
383 storage and retrieval operations from the netfs are excluded during the
384 execution of this operation.
385
386
387 * Reserve cache space for an object's data [optional]::
388
389 int (*reserve_space)(struct fscache_object *object, loff_t size);
390
391 This is called to request that cache space be reserved to hold the data
392 for an object and the metadata used to track it. Zero size should be
393 taken as request to cancel a reservation.
394
395 This should return 0 if successful, -ENOSPC if there isn't enough space
396 available, or -ENOMEM or -EIO on other errors.
397
398 The reservation may exceed the current size of the object, thus permitting
399 future expansion. If the amount of space consumed by an object would
400 exceed the reservation, it's permitted to refuse requests to allocate
401 pages, but not required. An object may be pruned down to its reservation
402 size if larger than that already.
403
404
405 * Request page be read from cache [mandatory]::
406
407 int (*read_or_alloc_page)(struct fscache_retrieval *op,
408 struct page *page,
409 gfp_t gfp)
410
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
413 as it can before calling, but most of the work belongs to the backend.
414
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
417 didn't.
418
419 If there is suitable data in the cache, then a read operation should be
420 queued and 0 returned. When the read finishes, fscache_end_io() should be
421 called.
422
423 The fscache_mark_pages_cached() should be called for the page if any cache
424 metadata is retained. This will indicate to the netfs that the page needs
425 explicit uncaching. This operation takes a pagevec, thus allowing several
426 pages to be marked at once.
427
428 The retrieval record pointed to by op should be retained for each page
429 queued and released when I/O on the page has been formally ended.
430 fscache_get/put_retrieval() are available for this purpose.
431
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
434 the appropriate processing routine, and fscache_enqueue_retrieval() should
435 be called at an appropriate point to request CPU time. For instance, the
436 retrieval routine could be enqueued upon the completion of a disk read.
437 The to_do field in the retrieval record is provided to aid in this.
438
439 If an I/O error occurs, fscache_io_error() should be called and -ENOBUFS
440 returned if possible or fscache_end_io() called with a suitable error
441 code.
442
443 fscache_put_retrieval() should be called after a page or pages are dealt
444 with. This will complete the operation when all pages are dealt with.
445
446
447 * Request pages be read from cache [mandatory]::
448
449 int (*read_or_alloc_pages)(struct fscache_retrieval *op,
450 struct list_head *pages,
451 unsigned *nr_pages,
452 gfp_t gfp)
453
454 This is like the read_or_alloc_page() method, except it is handed a list
455 of pages instead of one page. Any pages on which a read operation is
456 started must be added to the page cache for the specified mapping and also
457 to the LRU. Such pages must also be removed from the pages list and
458 ``*nr_pages`` decremented per page.
459
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
463 should be returned. If all the pages are dispatched then 0 should be
464 returned.
465
466
467 * Request page be allocated in the cache [mandatory]::
468
469 int (*allocate_page)(struct fscache_retrieval *op,
470 struct page *page,
471 gfp_t gfp)
472
473 This is like the read_or_alloc_page() method, except that it shouldn't
474 read from the cache, even if there's data there that could be retrieved.
475 It should, however, set up any internal metadata required such that
476 the write_page() method can write to the cache.
477
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
480 allocated, then the netfs page should be marked and 0 returned.
481
482
483 * Request pages be allocated in the cache [mandatory]::
484
485 int (*allocate_pages)(struct fscache_retrieval *op,
486 struct list_head *pages,
487 unsigned *nr_pages,
488 gfp_t gfp)
489
490 This is an multiple page version of the allocate_page() method. pages and
491 nr_pages should be treated as for the read_or_alloc_pages() method.
492
493
494 * Request page be written to cache [mandatory]::
495
496 int (*write_page)(struct fscache_storage *op,
497 struct page *page);
498
499 This is called to write from a page on which there was a previously
500 successful read_or_alloc_page() call or similar. FS-Cache filters out
501 pages that don't have mappings.
502
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
505 returned to the next read of this page.
506
507 If an error occurred, then a negative error code should be returned,
508 otherwise zero should be returned. FS-Cache will take appropriate action
509 in response to an error, such as withdrawing this object.
510
511 If this method returns success then FS-Cache will inform the netfs
512 appropriately.
513
514
515 * Discard retained per-page metadata [mandatory]::
516
517 void (*uncache_page)(struct fscache_object *object, struct page *page)
518
519 This is called when a netfs page is being evicted from the pagecache. The
520 cache backend should tear down any internal representation or tracking it
521 maintains for this page.
522
523
524FS-Cache Utilities
525==================
526
527FS-Cache provides some utilities that a cache backend may make use of:
528
529 * Note occurrence of an I/O error in a cache::
530
531 void fscache_io_error(struct fscache_cache *cache)
532
533 This tells FS-Cache that an I/O error occurred in the cache. After this
534 has been called, only resource dissociation operations (object and page
535 release) will be passed from the netfs to the cache backend for the
536 specified cache.
537
538 This does not actually withdraw the cache. That must be done separately.
539
540
541 * Invoke the retrieval I/O completion function::
542
543 void fscache_end_io(struct fscache_retrieval *op, struct page *page,
544 int error);
545
546 This is called to note the end of an attempt to retrieve a page. The
547 error value should be 0 if successful and an error otherwise.
548
549
550 * Record that one or more pages being retrieved or allocated have been dealt
551 with::
552
553 void fscache_retrieval_complete(struct fscache_retrieval *op,
554 int n_pages);
555
556 This is called to record the fact that one or more pages have been dealt
557 with and are no longer the concern of this operation. When the number of
558 pages remaining in the operation reaches 0, the operation will be
559 completed.
560
561
562 * Record operation completion::
563
564 void fscache_op_complete(struct fscache_operation *op);
565
566 This is called to record the completion of an operation. This deducts
567 this operation from the parent object's run state, potentially permitting
568 one or more pending operations to start running.
569
570
571 * Set highest store limit::
572
573 void fscache_set_store_limit(struct fscache_object *object,
574 loff_t i_size);
575
576 This sets the limit FS-Cache imposes on the highest byte it's willing to
577 try and store for a netfs. Any page over this limit is automatically
578 rejected by fscache_read_alloc_page() and co with -ENOBUFS.
579
580
581 * Mark pages as being cached::
582
583 void fscache_mark_pages_cached(struct fscache_retrieval *op,
584 struct pagevec *pagevec);
585
586 This marks a set of pages as being cached. After this has been called,
587 the netfs must call fscache_uncache_page() to unmark the pages.
588
589
590 * Perform coherency check on an object::
591
592 enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
593 const void *data,
594 uint16_t datalen);
595
596 This asks the netfs to perform a coherency check on an object that has
597 just been looked up. The cookie attached to the object will determine the
598 netfs to use. data and datalen should specify where the auxiliary data
599 retrieved from the cache can be found.
600
601 One of three values will be returned:
602
603 FSCACHE_CHECKAUX_OKAY
604 The coherency data indicates the object is valid as is.
605
606 FSCACHE_CHECKAUX_NEEDS_UPDATE
607 The coherency data needs updating, but otherwise the object is
608 valid.
609
610 FSCACHE_CHECKAUX_OBSOLETE
611 The coherency data indicates that the object is obsolete and should
612 be discarded.
613
614
615 * Initialise a freshly allocated object::
616
617 void fscache_object_init(struct fscache_object *object);
618
619 This initialises all the fields in an object representation.
620
621
622 * Indicate the destruction of an object::
623
624 void fscache_object_destroyed(struct fscache_cache *cache);
625
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
629 all the objects.
630
631
632 * Indicate negative lookup on an object::
633
634 void fscache_object_lookup_negative(struct fscache_object *object);
635
636 This is called to indicate to FS-Cache that a lookup process for an object
637 found a negative result.
638
639 This changes the state of an object to permit reads pending on lookup
640 completion to go off and start fetching data from the netfs server as it's
641 known at this point that there can't be any data in the cache.
642
643 This may be called multiple times on an object. Only the first call is
644 significant - all subsequent calls are ignored.
645
646
647 * Indicate an object has been obtained::
648
649 void fscache_obtained_object(struct fscache_object *object);
650
651 This is called to indicate to FS-Cache that a lookup process for an object
652 produced a positive result, or that an object was created. This should
653 only be called once for any particular object.
654
655 This changes the state of an object to indicate:
656
657 (1) if no call to fscache_object_lookup_negative() has been made on
658 this object, that there may be data available, and that reads can
659 now go and look for it; and
660
661 (2) that writes may now proceed against this object.
662
663
664 * Indicate that object lookup failed::
665
666 void fscache_object_lookup_error(struct fscache_object *object);
667
668 This marks an object as having encountered a fatal error (usually EIO)
669 and causes it to move into a state whereby it will be withdrawn as soon
670 as possible.
671
672
673 * Indicate that a stale object was found and discarded::
674
675 void fscache_object_retrying_stale(struct fscache_object *object);
676
677 This is called to indicate that the lookup procedure found an object in
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.
680
681
682 * Indicate that the caching backend killed an object::
683
684 void fscache_object_mark_killed(struct fscache_object *object,
685 enum fscache_why_object_killed why);
686
687 This is called to indicate that the cache backend preemptively killed an
688 object. The why parameter should be set to indicate the reason:
689
690 FSCACHE_OBJECT_IS_STALE
691 - the object was stale and needs discarding.
692
693 FSCACHE_OBJECT_NO_SPACE
694 - there was insufficient cache space
695
696 FSCACHE_OBJECT_WAS_RETIRED
697 - the object was retired when relinquished.
698
699 FSCACHE_OBJECT_WAS_CULLED
700 - the object was culled to make space.
701
702
703 * Get and release references on a retrieval record::
704
705 void fscache_get_retrieval(struct fscache_retrieval *op);
706 void fscache_put_retrieval(struct fscache_retrieval *op);
707
708 These two functions are used to retain a retrieval record while doing
709 asynchronous data retrieval and block allocation.
710
711
712 * Enqueue a retrieval record for processing::
713
714 void fscache_enqueue_retrieval(struct fscache_retrieval *op);
715
716 This enqueues a retrieval record for processing by the FS-Cache thread
717 pool. One of the threads in the pool will invoke the retrieval record's
718 op->op.processor callback function. This function may be called from
719 within the callback function.
720
721
722 * List of object state names::
723
724 const char *fscache_object_states[];
725
726 For debugging purposes, this may be used to turn the state that an object
727 is in into a text string for display purposes.
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_cache(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
113wait for completion by calling::
114
115 void fscache_wait_for_objects(struct fscache_cache *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 cache is completely withdrawn, fscache should be notified by
126calling::
127
128 void fscache_relinquish_cache(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