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 */