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