FS-Cache: Add the FS-Cache cache backend API and documentation
[linux-2.6.git] / include / linux / fscache-cache.h
1 /* General filesystem caching backing cache interface
2  *
3  * Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.
4  * Written by David Howells (dhowells@redhat.com)
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version
9  * 2 of the License, or (at your option) any later version.
10  *
11  * NOTE!!! See:
12  *
13  *      Documentation/filesystems/caching/backend-api.txt
14  *
15  * for a description of the cache backend interface declared here.
16  */
17
18 #ifndef _LINUX_FSCACHE_CACHE_H
19 #define _LINUX_FSCACHE_CACHE_H
20
21 #include <linux/fscache.h>
22 #include <linux/sched.h>
23 #include <linux/slow-work.h>
24
25 #define NR_MAXCACHES BITS_PER_LONG
26
27 struct fscache_cache;
28 struct fscache_cache_ops;
29 struct fscache_object;
30 struct fscache_operation;
31
32 #ifdef CONFIG_FSCACHE_PROC
33 extern struct proc_dir_entry *proc_fscache;
34 #endif
35
36 /*
37  * cache tag definition
38  */
39 struct fscache_cache_tag {
40         struct list_head        link;
41         struct fscache_cache    *cache;         /* cache referred to by this tag */
42         unsigned long           flags;
43 #define FSCACHE_TAG_RESERVED    0               /* T if tag is reserved for a cache */
44         atomic_t                usage;
45         char                    name[0];        /* tag name */
46 };
47
48 /*
49  * cache definition
50  */
51 struct fscache_cache {
52         const struct fscache_cache_ops *ops;
53         struct fscache_cache_tag *tag;          /* tag representing this cache */
54         struct kobject          *kobj;          /* system representation of this cache */
55         struct list_head        link;           /* link in list of caches */
56         size_t                  max_index_size; /* maximum size of index data */
57         char                    identifier[36]; /* cache label */
58
59         /* node management */
60         struct work_struct      op_gc;          /* operation garbage collector */
61         struct list_head        object_list;    /* list of data/index objects */
62         struct list_head        op_gc_list;     /* list of ops to be deleted */
63         spinlock_t              object_list_lock;
64         spinlock_t              op_gc_list_lock;
65         atomic_t                object_count;   /* no. of live objects in this cache */
66         struct fscache_object   *fsdef;         /* object for the fsdef index */
67         unsigned long           flags;
68 #define FSCACHE_IOERROR         0       /* cache stopped on I/O error */
69 #define FSCACHE_CACHE_WITHDRAWN 1       /* cache has been withdrawn */
70 };
71
72 extern wait_queue_head_t fscache_cache_cleared_wq;
73
74 /*
75  * operation to be applied to a cache object
76  * - retrieval initiation operations are done in the context of the process
77  *   that issued them, and not in an async thread pool
78  */
79 typedef void (*fscache_operation_release_t)(struct fscache_operation *op);
80 typedef void (*fscache_operation_processor_t)(struct fscache_operation *op);
81
82 struct fscache_operation {
83         union {
84                 struct work_struct fast_work;   /* record for fast ops */
85                 struct slow_work slow_work;     /* record for (very) slow ops */
86         };
87         struct list_head        pend_link;      /* link in object->pending_ops */
88         struct fscache_object   *object;        /* object to be operated upon */
89
90         unsigned long           flags;
91 #define FSCACHE_OP_TYPE         0x000f  /* operation type */
92 #define FSCACHE_OP_FAST         0x0001  /* - fast op, processor may not sleep for disk */
93 #define FSCACHE_OP_SLOW         0x0002  /* - (very) slow op, processor may sleep for disk */
94 #define FSCACHE_OP_MYTHREAD     0x0003  /* - processing is done be issuing thread, not pool */
95 #define FSCACHE_OP_WAITING      4       /* cleared when op is woken */
96 #define FSCACHE_OP_EXCLUSIVE    5       /* exclusive op, other ops must wait */
97 #define FSCACHE_OP_DEAD         6       /* op is now dead */
98
99         atomic_t                usage;
100         unsigned                debug_id;       /* debugging ID */
101
102         /* operation processor callback
103          * - can be NULL if FSCACHE_OP_WAITING is going to be used to perform
104          *   the op in a non-pool thread */
105         fscache_operation_processor_t processor;
106
107         /* operation releaser */
108         fscache_operation_release_t release;
109 };
110
111 extern atomic_t fscache_op_debug_id;
112 extern const struct slow_work_ops fscache_op_slow_work_ops;
113
114 extern void fscache_enqueue_operation(struct fscache_operation *);
115 extern void fscache_put_operation(struct fscache_operation *);
116
117 /**
118  * fscache_operation_init - Do basic initialisation of an operation
119  * @op: The operation to initialise
120  * @release: The release function to assign
121  *
122  * Do basic initialisation of an operation.  The caller must still set flags,
123  * object, either fast_work or slow_work if necessary, and processor if needed.
124  */
125 static inline void fscache_operation_init(struct fscache_operation *op,
126                                           fscache_operation_release_t release)
127 {
128         atomic_set(&op->usage, 1);
129         op->debug_id = atomic_inc_return(&fscache_op_debug_id);
130         op->release = release;
131         INIT_LIST_HEAD(&op->pend_link);
132 }
133
134 /**
135  * fscache_operation_init_slow - Do additional initialisation of a slow op
136  * @op: The operation to initialise
137  * @processor: The processor function to assign
138  *
139  * Do additional initialisation of an operation as required for slow work.
140  */
141 static inline
142 void fscache_operation_init_slow(struct fscache_operation *op,
143                                  fscache_operation_processor_t processor)
144 {
145         op->processor = processor;
146         slow_work_init(&op->slow_work, &fscache_op_slow_work_ops);
147 }
148
149 /*
150  * data read operation
151  */
152 struct fscache_retrieval {
153         struct fscache_operation op;
154         struct address_space    *mapping;       /* netfs pages */
155         fscache_rw_complete_t   end_io_func;    /* function to call on I/O completion */
156         void                    *context;       /* netfs read context (pinned) */
157         struct list_head        to_do;          /* list of things to be done by the backend */
158         unsigned long           start_time;     /* time at which retrieval started */
159 };
160
161 typedef int (*fscache_page_retrieval_func_t)(struct fscache_retrieval *op,
162                                              struct page *page,
163                                              gfp_t gfp);
164
165 typedef int (*fscache_pages_retrieval_func_t)(struct fscache_retrieval *op,
166                                               struct list_head *pages,
167                                               unsigned *nr_pages,
168                                               gfp_t gfp);
169
170 /**
171  * fscache_get_retrieval - Get an extra reference on a retrieval operation
172  * @op: The retrieval operation to get a reference on
173  *
174  * Get an extra reference on a retrieval operation.
175  */
176 static inline
177 struct fscache_retrieval *fscache_get_retrieval(struct fscache_retrieval *op)
178 {
179         atomic_inc(&op->op.usage);
180         return op;
181 }
182
183 /**
184  * fscache_enqueue_retrieval - Enqueue a retrieval operation for processing
185  * @op: The retrieval operation affected
186  *
187  * Enqueue a retrieval operation for processing by the FS-Cache thread pool.
188  */
189 static inline void fscache_enqueue_retrieval(struct fscache_retrieval *op)
190 {
191         fscache_enqueue_operation(&op->op);
192 }
193
194 /**
195  * fscache_put_retrieval - Drop a reference to a retrieval operation
196  * @op: The retrieval operation affected
197  *
198  * Drop a reference to a retrieval operation.
199  */
200 static inline void fscache_put_retrieval(struct fscache_retrieval *op)
201 {
202         fscache_put_operation(&op->op);
203 }
204
205 /*
206  * cached page storage work item
207  * - used to do three things:
208  *   - batch writes to the cache
209  *   - do cache writes asynchronously
210  *   - defer writes until cache object lookup completion
211  */
212 struct fscache_storage {
213         struct fscache_operation op;
214         pgoff_t                 store_limit;    /* don't write more than this */
215 };
216
217 /*
218  * cache operations
219  */
220 struct fscache_cache_ops {
221         /* name of cache provider */
222         const char *name;
223
224         /* allocate an object record for a cookie */
225         struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
226                                                struct fscache_cookie *cookie);
227
228         /* look up the object for a cookie */
229         void (*lookup_object)(struct fscache_object *object);
230
231         /* finished looking up */
232         void (*lookup_complete)(struct fscache_object *object);
233
234         /* increment the usage count on this object (may fail if unmounting) */
235         struct fscache_object *(*grab_object)(struct fscache_object *object);
236
237         /* pin an object in the cache */
238         int (*pin_object)(struct fscache_object *object);
239
240         /* unpin an object in the cache */
241         void (*unpin_object)(struct fscache_object *object);
242
243         /* store the updated auxilliary data on an object */
244         void (*update_object)(struct fscache_object *object);
245
246         /* discard the resources pinned by an object and effect retirement if
247          * necessary */
248         void (*drop_object)(struct fscache_object *object);
249
250         /* dispose of a reference to an object */
251         void (*put_object)(struct fscache_object *object);
252
253         /* sync a cache */
254         void (*sync_cache)(struct fscache_cache *cache);
255
256         /* notification that the attributes of a non-index object (such as
257          * i_size) have changed */
258         int (*attr_changed)(struct fscache_object *object);
259
260         /* reserve space for an object's data and associated metadata */
261         int (*reserve_space)(struct fscache_object *object, loff_t i_size);
262
263         /* request a backing block for a page be read or allocated in the
264          * cache */
265         fscache_page_retrieval_func_t read_or_alloc_page;
266
267         /* request backing blocks for a list of pages be read or allocated in
268          * the cache */
269         fscache_pages_retrieval_func_t read_or_alloc_pages;
270
271         /* request a backing block for a page be allocated in the cache so that
272          * it can be written directly */
273         fscache_page_retrieval_func_t allocate_page;
274
275         /* request backing blocks for pages be allocated in the cache so that
276          * they can be written directly */
277         fscache_pages_retrieval_func_t allocate_pages;
278
279         /* write a page to its backing block in the cache */
280         int (*write_page)(struct fscache_storage *op, struct page *page);
281
282         /* detach backing block from a page (optional)
283          * - must release the cookie lock before returning
284          * - may sleep
285          */
286         void (*uncache_page)(struct fscache_object *object,
287                              struct page *page);
288
289         /* dissociate a cache from all the pages it was backing */
290         void (*dissociate_pages)(struct fscache_cache *cache);
291 };
292
293 /*
294  * data file or index object cookie
295  * - a file will only appear in one cache
296  * - a request to cache a file may or may not be honoured, subject to
297  *   constraints such as disk space
298  * - indices are created on disk just-in-time
299  */
300 struct fscache_cookie {
301         atomic_t                        usage;          /* number of users of this cookie */
302         atomic_t                        n_children;     /* number of children of this cookie */
303         spinlock_t                      lock;
304         struct hlist_head               backing_objects; /* object(s) backing this file/index */
305         const struct fscache_cookie_def *def;           /* definition */
306         struct fscache_cookie           *parent;        /* parent of this entry */
307         void                            *netfs_data;    /* back pointer to netfs */
308         struct radix_tree_root          stores;         /* pages to be stored on this cookie */
309 #define FSCACHE_COOKIE_PENDING_TAG      0               /* pages tag: pending write to cache */
310
311         unsigned long                   flags;
312 #define FSCACHE_COOKIE_LOOKING_UP       0       /* T if non-index cookie being looked up still */
313 #define FSCACHE_COOKIE_CREATING         1       /* T if non-index object being created still */
314 #define FSCACHE_COOKIE_NO_DATA_YET      2       /* T if new object with no cached data yet */
315 #define FSCACHE_COOKIE_PENDING_FILL     3       /* T if pending initial fill on object */
316 #define FSCACHE_COOKIE_FILLING          4       /* T if filling object incrementally */
317 #define FSCACHE_COOKIE_UNAVAILABLE      5       /* T if cookie is unavailable (error, etc) */
318 };
319
320 extern struct fscache_cookie fscache_fsdef_index;
321
322 /*
323  * on-disk cache file or index handle
324  */
325 struct fscache_object {
326         enum fscache_object_state {
327                 FSCACHE_OBJECT_INIT,            /* object in initial unbound state */
328                 FSCACHE_OBJECT_LOOKING_UP,      /* looking up object */
329                 FSCACHE_OBJECT_CREATING,        /* creating object */
330
331                 /* active states */
332                 FSCACHE_OBJECT_AVAILABLE,       /* cleaning up object after creation */
333                 FSCACHE_OBJECT_ACTIVE,          /* object is usable */
334                 FSCACHE_OBJECT_UPDATING,        /* object is updating */
335
336                 /* terminal states */
337                 FSCACHE_OBJECT_DYING,           /* object waiting for accessors to finish */
338                 FSCACHE_OBJECT_LC_DYING,        /* object cleaning up after lookup/create */
339                 FSCACHE_OBJECT_ABORT_INIT,      /* abort the init state */
340                 FSCACHE_OBJECT_RELEASING,       /* releasing object */
341                 FSCACHE_OBJECT_RECYCLING,       /* retiring object */
342                 FSCACHE_OBJECT_WITHDRAWING,     /* withdrawing object */
343                 FSCACHE_OBJECT_DEAD,            /* object is now dead */
344         } state;
345
346         int                     debug_id;       /* debugging ID */
347         int                     n_children;     /* number of child objects */
348         int                     n_ops;          /* number of ops outstanding on object */
349         int                     n_obj_ops;      /* number of object ops outstanding on object */
350         int                     n_in_progress;  /* number of ops in progress */
351         int                     n_exclusive;    /* number of exclusive ops queued */
352         spinlock_t              lock;           /* state and operations lock */
353
354         unsigned long           lookup_jif;     /* time at which lookup started */
355         unsigned long           event_mask;     /* events this object is interested in */
356         unsigned long           events;         /* events to be processed by this object
357                                                  * (order is important - using fls) */
358 #define FSCACHE_OBJECT_EV_REQUEUE       0       /* T if object should be requeued */
359 #define FSCACHE_OBJECT_EV_UPDATE        1       /* T if object should be updated */
360 #define FSCACHE_OBJECT_EV_CLEARED       2       /* T if accessors all gone */
361 #define FSCACHE_OBJECT_EV_ERROR         3       /* T if fatal error occurred during processing */
362 #define FSCACHE_OBJECT_EV_RELEASE       4       /* T if netfs requested object release */
363 #define FSCACHE_OBJECT_EV_RETIRE        5       /* T if netfs requested object retirement */
364 #define FSCACHE_OBJECT_EV_WITHDRAW      6       /* T if cache requested object withdrawal */
365
366         unsigned long           flags;
367 #define FSCACHE_OBJECT_LOCK             0       /* T if object is busy being processed */
368 #define FSCACHE_OBJECT_PENDING_WRITE    1       /* T if object has pending write */
369 #define FSCACHE_OBJECT_WAITING          2       /* T if object is waiting on its parent */
370
371         struct list_head        cache_link;     /* link in cache->object_list */
372         struct hlist_node       cookie_link;    /* link in cookie->backing_objects */
373         struct fscache_cache    *cache;         /* cache that supplied this object */
374         struct fscache_cookie   *cookie;        /* netfs's file/index object */
375         struct fscache_object   *parent;        /* parent object */
376         struct slow_work        work;           /* attention scheduling record */
377         struct list_head        dependents;     /* FIFO of dependent objects */
378         struct list_head        dep_link;       /* link in parent's dependents list */
379         struct list_head        pending_ops;    /* unstarted operations on this object */
380         pgoff_t                 store_limit;    /* current storage limit */
381 };
382
383 extern const char *fscache_object_states[];
384
385 #define fscache_object_is_active(obj)                         \
386         (!test_bit(FSCACHE_IOERROR, &(obj)->cache->flags) &&  \
387          (obj)->state >= FSCACHE_OBJECT_AVAILABLE &&          \
388          (obj)->state < FSCACHE_OBJECT_DYING)
389
390 extern const struct slow_work_ops fscache_object_slow_work_ops;
391
392 /**
393  * fscache_object_init - Initialise a cache object description
394  * @object: Object description
395  *
396  * Initialise a cache object description to its basic values.
397  *
398  * See Documentation/filesystems/caching/backend-api.txt for a complete
399  * description.
400  */
401 static inline
402 void fscache_object_init(struct fscache_object *object,
403                          struct fscache_cookie *cookie,
404                          struct fscache_cache *cache)
405 {
406         atomic_inc(&cache->object_count);
407
408         object->state = FSCACHE_OBJECT_INIT;
409         spin_lock_init(&object->lock);
410         INIT_LIST_HEAD(&object->cache_link);
411         INIT_HLIST_NODE(&object->cookie_link);
412         vslow_work_init(&object->work, &fscache_object_slow_work_ops);
413         INIT_LIST_HEAD(&object->dependents);
414         INIT_LIST_HEAD(&object->dep_link);
415         INIT_LIST_HEAD(&object->pending_ops);
416         object->n_children = 0;
417         object->n_ops = object->n_in_progress = object->n_exclusive = 0;
418         object->events = object->event_mask = 0;
419         object->flags = 0;
420         object->store_limit = 0;
421         object->cache = cache;
422         object->cookie = cookie;
423         object->parent = NULL;
424 }
425
426 extern void fscache_object_lookup_negative(struct fscache_object *object);
427 extern void fscache_obtained_object(struct fscache_object *object);
428
429 /**
430  * fscache_object_destroyed - Note destruction of an object in a cache
431  * @cache: The cache from which the object came
432  *
433  * Note the destruction and deallocation of an object record in a cache.
434  */
435 static inline void fscache_object_destroyed(struct fscache_cache *cache)
436 {
437         if (atomic_dec_and_test(&cache->object_count))
438                 wake_up_all(&fscache_cache_cleared_wq);
439 }
440
441 /**
442  * fscache_object_lookup_error - Note an object encountered an error
443  * @object: The object on which the error was encountered
444  *
445  * Note that an object encountered a fatal error (usually an I/O error) and
446  * that it should be withdrawn as soon as possible.
447  */
448 static inline void fscache_object_lookup_error(struct fscache_object *object)
449 {
450         set_bit(FSCACHE_OBJECT_EV_ERROR, &object->events);
451 }
452
453 /**
454  * fscache_set_store_limit - Set the maximum size to be stored in an object
455  * @object: The object to set the maximum on
456  * @i_size: The limit to set in bytes
457  *
458  * Set the maximum size an object is permitted to reach, implying the highest
459  * byte that may be written.  Intended to be called by the attr_changed() op.
460  *
461  * See Documentation/filesystems/caching/backend-api.txt for a complete
462  * description.
463  */
464 static inline
465 void fscache_set_store_limit(struct fscache_object *object, loff_t i_size)
466 {
467         object->store_limit = i_size >> PAGE_SHIFT;
468         if (i_size & ~PAGE_MASK)
469                 object->store_limit++;
470 }
471
472 /**
473  * fscache_end_io - End a retrieval operation on a page
474  * @op: The FS-Cache operation covering the retrieval
475  * @page: The page that was to be fetched
476  * @error: The error code (0 if successful)
477  *
478  * Note the end of an operation to retrieve a page, as covered by a particular
479  * operation record.
480  */
481 static inline void fscache_end_io(struct fscache_retrieval *op,
482                                   struct page *page, int error)
483 {
484         op->end_io_func(page, op->context, error);
485 }
486
487 /*
488  * out-of-line cache backend functions
489  */
490 extern void fscache_init_cache(struct fscache_cache *cache,
491                                const struct fscache_cache_ops *ops,
492                                const char *idfmt,
493                                ...) __attribute__ ((format (printf, 3, 4)));
494
495 extern int fscache_add_cache(struct fscache_cache *cache,
496                              struct fscache_object *fsdef,
497                              const char *tagname);
498 extern void fscache_withdraw_cache(struct fscache_cache *cache);
499
500 extern void fscache_io_error(struct fscache_cache *cache);
501
502 extern void fscache_mark_pages_cached(struct fscache_retrieval *op,
503                                       struct pagevec *pagevec);
504
505 extern enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
506                                                const void *data,
507                                                uint16_t datalen);
508
509 #endif /* _LINUX_FSCACHE_CACHE_H */