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