include/linux/fscache-cache.h

   1 /* fscache-cache.h: general filesystem caching backing cache interface
   2  *
   3  * Copyright (C) 2004-6 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
  23 #define NR_MAXCACHES BITS_PER_LONG
  24
  25 struct fscache_cache;
  26 struct fscache_cache_ops;
  27 struct fscache_object;
  28
  29 /*
  30  * cache tag definition
  31  */
  32 struct fscache_cache_tag {
  33         struct list_head                link;
  34         struct fscache_cache            *cache;         /* cache referred to by this tag */
  35         atomic_t                        usage;
  36         char                            name[0];        /* tag name */
  37 };
  38
  39 /*
  40  * cache definition
  41  */
  42 struct fscache_cache {
  43         struct fscache_cache_ops        *ops;
  44         struct fscache_cache_tag        *tag;           /* tag representing this cache */
  45         struct list_head                link;           /* link in list of caches */
  46         struct rw_semaphore             withdrawal_sem; /* withdrawal control sem */
  47         size_t                          max_index_size; /* maximum size of index data */
  48         char                            identifier[32]; /* cache label */
  49
  50         /* node management */
  51         struct list_head                object_list;    /* list of data/index objects */
  52         spinlock_t                      object_list_lock;
  53         struct fscache_object           *fsdef;         /* object for the fsdef index */
  54         unsigned long                   flags;
  55 #define FSCACHE_IOERROR                 0       /* cache stopped on I/O error */
  56 };
  57
  58 extern void fscache_init_cache(struct fscache_cache *cache,
  59                                struct fscache_cache_ops *ops,
  60                                const char *idfmt,
  61                                ...) __attribute__ ((format (printf,3,4)));
  62
  63 extern int fscache_add_cache(struct fscache_cache *cache,
  64                              struct fscache_object *fsdef,
  65                              const char *tagname);
  66 extern void fscache_withdraw_cache(struct fscache_cache *cache);
  67
  68 extern void fscache_io_error(struct fscache_cache *cache);
  69
  70 /*****************************************************************************/
  71 /*
  72  * cache operations
  73  */
  74 struct fscache_cache_ops {
  75         /* name of cache provider */
  76         const char *name;
  77
  78         /* look up the object for a cookie, creating it on disc if necessary */
  79         struct fscache_object *(*lookup_object)(struct fscache_cache *cache,
  80                                                 struct fscache_object *parent,
  81                                                 struct fscache_cookie *cookie);
  82
  83         /* increment the usage count on this object (may fail if unmounting) */
  84         struct fscache_object *(*grab_object)(struct fscache_object *object);
  85
  86         /* lock a semaphore on an object */
  87         void (*lock_object)(struct fscache_object *object);
  88
  89         /* unlock a semaphore on an object */
  90         void (*unlock_object)(struct fscache_object *object);
  91
  92         /* pin an object in the cache */
  93         int (*pin_object)(struct fscache_object *object);
  94
  95         /* unpin an object in the cache */
  96         void (*unpin_object)(struct fscache_object *object);
  97
  98         /* store the updated auxilliary data on an object */
  99         void (*update_object)(struct fscache_object *object);
 100
 101         /* dispose of a reference to an object */
 102         void (*put_object)(struct fscache_object *object);
 103
 104         /* sync a cache */
 105         void (*sync_cache)(struct fscache_cache *cache);
 106
 107         /* set the data size of an object */
 108         int (*set_i_size)(struct fscache_object *object, loff_t i_size);
 109
 110         /* reserve space for an object's data and associated metadata */
 111         int (*reserve_space)(struct fscache_object *object, loff_t i_size);
 112
 113         /* request a backing block for a page be read or allocated in the
 114          * cache */
 115         int (*read_or_alloc_page)(struct fscache_object *object,
 116                                   struct page *page,
 117                                   fscache_rw_complete_t end_io_func,
 118                                   void *context,
 119                                   unsigned long gfp);
 120
 121         /* request backing blocks for a list of pages be read or allocated in
 122          * the cache */
 123         int (*read_or_alloc_pages)(struct fscache_object *object,
 124                                    struct address_space *mapping,
 125                                    struct list_head *pages,
 126                                    unsigned *nr_pages,
 127                                    fscache_rw_complete_t end_io_func,
 128                                    void *context,
 129                                    unsigned long gfp);
 130
 131         /* request a backing block for a page be allocated in the cache so that
 132          * it can be written directly */
 133         int (*allocate_page)(struct fscache_object *object,
 134                              struct page *page,
 135                              unsigned long gfp);
 136
 137         /* write a page to its backing block in the cache */
 138         int (*write_page)(struct fscache_object *object,
 139                           struct page *page,
 140                           fscache_rw_complete_t end_io_func,
 141                           void *context,
 142                           unsigned long gfp);
 143
 144         /* write several pages to their backing blocks in the cache */
 145         int (*write_pages)(struct fscache_object *object,
 146                            struct pagevec *pagevec,
 147                            fscache_rw_complete_t end_io_func,
 148                            void *context,
 149                            unsigned long gfp);
 150
 151         /* detach backing block from a bunch of pages */
 152         void (*uncache_pages)(struct fscache_object *object,
 153                              struct pagevec *pagevec);
 154
 155         /* dissociate a cache from all the pages it was backing */
 156         void (*dissociate_pages)(struct fscache_cache *cache);
 157 };
 158
 159 /*****************************************************************************/
 160 /*
 161  * data file or index object cookie
 162  * - a file will only appear in one cache
 163  * - a request to cache a file may or may not be honoured, subject to
 164  *   constraints such as disc space
 165  * - indexes files are created on disc just-in-time
 166  */
 167 struct fscache_cookie {
 168         atomic_t                        usage;          /* number of users of this cookie */
 169         atomic_t                        children;       /* number of children of this cookie */
 170         struct rw_semaphore             sem;            /* list creation vs scan lock */
 171         struct hlist_head               backing_objects; /* object(s) backing this file/index */
 172         struct fscache_cookie_def       *def;           /* definition */
 173         struct fscache_cookie           *parent;        /* parent of this entry */
 174         struct fscache_netfs            *netfs;         /* owner network fs definition */
 175         void                            *netfs_data;    /* back pointer to netfs */
 176 };
 177
 178 extern struct fscache_cookie fscache_fsdef_index;
 179
 180 /*****************************************************************************/
 181 /*
 182  * on-disc cache file or index handle
 183  */
 184 struct fscache_object {
 185         unsigned long                   flags;
 186 #define FSCACHE_OBJECT_RELEASING        0       /* T if object is being released */
 187 #define FSCACHE_OBJECT_RECYCLING        1       /* T if object is being retired */
 188 #define FSCACHE_OBJECT_WITHDRAWN        2       /* T if object has been withdrawn */
 189
 190         struct list_head                cache_link;     /* link in cache->object_list */
 191         struct hlist_node               cookie_link;    /* link in cookie->backing_objects */
 192         struct fscache_cache            *cache;         /* cache that supplied this object */
 193         struct fscache_cookie           *cookie;        /* netfs's file/index object */
 194 };
 195
 196 static inline
 197 void fscache_object_init(struct fscache_object *object)
 198 {
 199         object->flags = 0;
 200         INIT_LIST_HEAD(&object->cache_link);
 201         INIT_HLIST_NODE(&object->cookie_link);
 202         object->cache = NULL;
 203         object->cookie = NULL;
 204 }
 205
 206 /* find the parent index object for a object */
 207 static inline
 208 struct fscache_object *fscache_find_parent_object(struct fscache_object *object)
 209 {
 210         struct fscache_object *parent;
 211         struct fscache_cookie *cookie = object->cookie;
 212         struct fscache_cache *cache = object->cache;
 213         struct hlist_node *_p;
 214
 215         hlist_for_each_entry(parent, _p,
 216                              &cookie->parent->backing_objects,
 217                              cookie_link
 218                              ) {
 219                 if (parent->cache == cache)
 220                         return parent;
 221         }
 222
 223         return NULL;
 224 }
 225
 226 /* get an extra reference to a context */
 227 static inline
 228 void *fscache_get_context(struct fscache_cookie *cookie, void *context)
 229 {
 230         if (cookie->def->get_context)
 231                 cookie->def->get_context(cookie->netfs_data, context);
 232         return context;
 233 }
 234
 235 /* release an extra reference to a context */
 236 static inline
 237 void fscache_put_context(struct fscache_cookie *cookie, void *context)
 238 {
 239         if (cookie->def->put_context)
 240                 cookie->def->put_context(cookie->netfs_data, context);
 241 }
 242
 243 #endif /* _LINUX_FSCACHE_CACHE_H */