include/linux/fscache.h

   1 /* fscache.h: general filesystem caching interface
   2  *
   3  * Copyright (C) 2004-5 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/netfs-api.txt
  14  *
  15  * for a description of the network filesystem interface declared here.
  16  */
  17
  18 #ifndef _LINUX_FSCACHE_H
  19 #define _LINUX_FSCACHE_H
  20
  21 #include <linux/fs.h>
  22 #include <linux/list.h>
  23 #include <linux/pagemap.h>
  24 #include <linux/pagevec.h>
  25
  26 struct pagevec;
  27 struct fscache_cache_tag;
  28 struct fscache_cookie;
  29 struct fscache_netfs;
  30 struct fscache_netfs_operations;
  31
  32 typedef void (*fscache_rw_complete_t)(struct page *page,
  33                                       void *context,
  34                                       int error);
  35
  36 /* result of index entry consultation */
  37 typedef enum {
  38         FSCACHE_CHECKAUX_OKAY,          /* entry okay as is */
  39         FSCACHE_CHECKAUX_NEEDS_UPDATE,  /* entry requires update */
  40         FSCACHE_CHECKAUX_OBSOLETE,      /* entry requires deletion */
  41 } fscache_checkaux_t;
  42
  43 /*****************************************************************************/
  44 /*
  45  * fscache cookie definition
  46  */
  47 struct fscache_cookie_def
  48 {
  49         /* name of cookie type */
  50         char name[16];
  51
  52         /* cookie type */
  53         uint8_t type;
  54 #define FSCACHE_COOKIE_TYPE_INDEX       0
  55 #define FSCACHE_COOKIE_TYPE_DATAFILE    1
  56
  57         /* select the cache into which to insert an entry in this index
  58          * - optional
  59          * - should return a cache identifier or NULL to cause the cache to be
  60          *   inherited from the parent if possible or the first cache picked
  61          *   for a non-index file if not
  62          */
  63         struct fscache_cache_tag *(*select_cache)(const void *parent_netfs_data,
  64                                                   const void *cookie_netfs_data);
  65
  66         /* get an index key
  67          * - should store the key data in the buffer
  68          * - should return the amount of amount stored
  69          * - not permitted to return an error
  70          * - the netfs data from the cookie being used as the source is
  71          *   presented
  72          */
  73         uint16_t (*get_key)(const void *cookie_netfs_data,
  74                             void *buffer,
  75                             uint16_t bufmax);
  76
  77         /* get certain file attributes from the netfs data
  78          * - this function can be absent for an index
  79          * - not permitted to return an error
  80          * - the netfs data from the cookie being used as the source is
  81          *   presented
  82          */
  83         void (*get_attr)(const void *cookie_netfs_data, uint64_t *size);
  84
  85         /* get the auxilliary data from netfs data
  86          * - this function can be absent if the index carries no state data
  87          * - should store the auxilliary data in the buffer
  88          * - should return the amount of amount stored
  89          * - not permitted to return an error
  90          * - the netfs data from the cookie being used as the source is
  91          *   presented
  92          */
  93         uint16_t (*get_aux)(const void *cookie_netfs_data,
  94                             void *buffer,
  95                             uint16_t bufmax);
  96
  97         /* consult the netfs about the state of an object
  98          * - this function can be absent if the index carries no state data
  99          * - the netfs data from the cookie being used as the target is
 100          *   presented, as is the auxilliary data
 101          */
 102         fscache_checkaux_t (*check_aux)(void *cookie_netfs_data,
 103                                         const void *data,
 104                                         uint16_t datalen);
 105
 106         /* get an extra reference on a read context
 107          * - this function can be absent if the completion function doesn't
 108          *   require a context
 109          */
 110         void (*get_context)(void *cookie_netfs_data, void *context);
 111
 112         /* release an extra reference on a read context
 113          * - this function can be absent if the completion function doesn't
 114          *   require a context
 115          */
 116         void (*put_context)(void *cookie_netfs_data, void *context);
 117
 118         /* indicate pages that now have cache metadata retained
 119          * - this function should mark the specified pages as now being cached
 120          */
 121         void (*mark_pages_cached)(void *cookie_netfs_data,
 122                                   struct address_space *mapping,
 123                                   struct pagevec *cached_pvec);
 124
 125         /* indicate the cookie is no longer cached
 126          * - this function is called when the backing store currently caching
 127          *   a cookie is removed
 128          * - the netfs should use this to clean up any markers indicating
 129          *   cached pages
 130          * - this is mandatory for any object that may have data
 131          */
 132         void (*now_uncached)(void *cookie_netfs_data);
 133 };
 134
 135 /* pattern used to fill dead space in an index entry */
 136 #define FSCACHE_INDEX_DEADFILL_PATTERN 0x79
 137
 138 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 139 extern struct fscache_cookie *__fscache_acquire_cookie(struct fscache_cookie *parent,
 140                                                        struct fscache_cookie_def *def,
 141                                                        void *netfs_data);
 142
 143 extern void __fscache_relinquish_cookie(struct fscache_cookie *cookie,
 144                                         int retire);
 145
 146 extern void __fscache_update_cookie(struct fscache_cookie *cookie);
 147 #endif
 148
 149 static inline
 150 struct fscache_cookie *fscache_acquire_cookie(struct fscache_cookie *parent,
 151                                               struct fscache_cookie_def *def,
 152                                               void *netfs_data)
 153 {
 154 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 155         if (parent)
 156                 return __fscache_acquire_cookie(parent, def, netfs_data);
 157 #endif
 158         return NULL;
 159 }
 160
 161 static inline
 162 void fscache_relinquish_cookie(struct fscache_cookie *cookie,
 163                                int retire)
 164 {
 165 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 166         if (cookie)
 167                 __fscache_relinquish_cookie(cookie, retire);
 168 #endif
 169 }
 170
 171 static inline
 172 void fscache_update_cookie(struct fscache_cookie *cookie)
 173 {
 174 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 175         if (cookie)
 176                 __fscache_update_cookie(cookie);
 177 #endif
 178 }
 179
 180 /*****************************************************************************/
 181 /*
 182  * pin or unpin a cookie in a cache
 183  * - only available for data cookies
 184  */
 185 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 186 extern int __fscache_pin_cookie(struct fscache_cookie *cookie);
 187 extern void __fscache_unpin_cookie(struct fscache_cookie *cookie);
 188 #endif
 189
 190 static inline
 191 int fscache_pin_cookie(struct fscache_cookie *cookie)
 192 {
 193 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 194         if (cookie)
 195                 return __fscache_pin_cookie(cookie);
 196 #endif
 197         return -ENOBUFS;
 198 }
 199
 200 static inline
 201 void fscache_unpin_cookie(struct fscache_cookie *cookie)
 202 {
 203 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 204         if (cookie)
 205                 __fscache_unpin_cookie(cookie);
 206 #endif
 207 }
 208
 209 /*****************************************************************************/
 210 /*
 211  * fscache cached network filesystem type
 212  * - name, version and ops must be filled in before registration
 213  * - all other fields will be set during registration
 214  */
 215 struct fscache_netfs
 216 {
 217         uint32_t                        version;        /* indexing version */
 218         const char                      *name;          /* filesystem name */
 219         struct fscache_cookie           *primary_index;
 220         struct fscache_netfs_operations *ops;
 221         struct list_head                link;           /* internal link */
 222 };
 223
 224 struct fscache_netfs_operations
 225 {
 226 };
 227
 228 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 229 extern int __fscache_register_netfs(struct fscache_netfs *netfs);
 230 extern void __fscache_unregister_netfs(struct fscache_netfs *netfs);
 231 #endif
 232
 233 static inline
 234 int fscache_register_netfs(struct fscache_netfs *netfs)
 235 {
 236 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 237         return __fscache_register_netfs(netfs);
 238 #else
 239         return 0;
 240 #endif
 241 }
 242
 243 static inline
 244 void fscache_unregister_netfs(struct fscache_netfs *netfs)
 245 {
 246 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 247         __fscache_unregister_netfs(netfs);
 248 #endif
 249 }
 250
 251 /*****************************************************************************/
 252 /*
 253  * look up a cache tag
 254  * - cache tags are used to select specific caches in which to cache indexes
 255  */
 256 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 257 extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *name);
 258 extern void __fscache_release_cache_tag(struct fscache_cache_tag *tag);
 259 #endif
 260
 261 static inline
 262 struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
 263 {
 264 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 265         return __fscache_lookup_cache_tag(name);
 266 #else
 267         return NULL;
 268 #endif
 269 }
 270
 271 static inline
 272 void fscache_release_cache_tag(struct fscache_cache_tag *tag)
 273 {
 274 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 275         __fscache_release_cache_tag(tag);
 276 #endif
 277 }
 278
 279 /*****************************************************************************/
 280 /*
 281  * set the data size on a cached object
 282  * - no pages beyond the end of the object will be accessible
 283  * - returns -ENOBUFS if the file is not backed
 284  * - returns -ENOSPC if a pinned file of that size can't be stored
 285  * - returns 0 if okay
 286  */
 287 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 288 extern int __fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size);
 289 #endif
 290
 291 static inline
 292 int fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size)
 293 {
 294 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 295         if (cookie)
 296                 return __fscache_set_i_size(cookie, i_size);
 297 #endif
 298         return -ENOBUFS;
 299 }
 300
 301 /*****************************************************************************/
 302 /*
 303  * reserve data space for a cached object
 304  * - returns -ENOBUFS if the file is not backed
 305  * - returns -ENOSPC if there isn't enough space to honour the reservation
 306  * - returns 0 if okay
 307  */
 308 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 309 extern int __fscache_reserve_space(struct fscache_cookie *cookie, loff_t size);
 310 #endif
 311
 312 static inline
 313 int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
 314 {
 315 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 316         if (cookie)
 317                 return __fscache_reserve_space(cookie, size);
 318 #endif
 319         return -ENOBUFS;
 320 }
 321
 322 /*****************************************************************************/
 323 /*
 324  * read a page from the cache or allocate a block in which to store it
 325  * - if the page is not backed by a file:
 326  *   - -ENOBUFS will be returned and nothing more will be done
 327  * - else if the page is backed by a block in the cache:
 328  *   - a read will be started which will call end_io_func on completion
 329  * - else if the page is unbacked:
 330  *   - a block will be allocated
 331  *   - -ENODATA will be returned
 332  */
 333 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 334 extern int __fscache_read_or_alloc_page(struct fscache_cookie *cookie,
 335                                         struct page *page,
 336                                         fscache_rw_complete_t end_io_func,
 337                                         void *context,
 338                                         gfp_t gfp);
 339 #endif
 340
 341 static inline
 342 int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
 343                                struct page *page,
 344                                fscache_rw_complete_t end_io_func,
 345                                void *context,
 346                                gfp_t gfp)
 347 {
 348 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 349         if (cookie)
 350                 return __fscache_read_or_alloc_page(cookie, page, end_io_func,
 351                                                     context, gfp);
 352 #endif
 353         return -ENOBUFS;
 354 }
 355
 356 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 357 extern int __fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
 358                                          struct address_space *mapping,
 359                                          struct list_head *pages,
 360                                          unsigned *nr_pages,
 361                                          fscache_rw_complete_t end_io_func,
 362                                          void *context,
 363                                          gfp_t gfp);
 364 #endif
 365
 366 static inline
 367 int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
 368                                 struct address_space *mapping,
 369                                 struct list_head *pages,
 370                                 unsigned *nr_pages,
 371                                 fscache_rw_complete_t end_io_func,
 372                                 void *context,
 373                                 gfp_t gfp)
 374 {
 375 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 376         if (cookie)
 377                 return __fscache_read_or_alloc_pages(cookie, mapping, pages,
 378                                                      nr_pages, end_io_func,
 379                                                      context, gfp);
 380 #endif
 381         return -ENOBUFS;
 382 }
 383
 384 /*
 385  * allocate a block in which to store a page
 386  * - if the page is not backed by a file:
 387  *   - -ENOBUFS will be returned and nothing more will be done
 388  * - else
 389  *   - a block will be allocated if there isn't one
 390  *   - 0 will be returned
 391  */
 392 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 393 extern int __fscache_alloc_page(struct fscache_cookie *cookie,
 394                                 struct page *page,
 395                                 gfp_t gfp);
 396 #endif
 397
 398 static inline
 399 int fscache_alloc_page(struct fscache_cookie *cookie,
 400                        struct page *page,
 401                        gfp_t gfp)
 402 {
 403 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 404         if (cookie)
 405                 return __fscache_alloc_page(cookie, page, gfp);
 406 #endif
 407         return -ENOBUFS;
 408 }
 409
 410 /*
 411  * request a page be stored in the cache
 412  * - this request may be ignored if no cache block is currently allocated, in
 413  *   which case it:
 414  *   - returns -ENOBUFS
 415  * - if a cache block was already allocated:
 416  *   - a BIO will be dispatched to write the page (end_io_func will be called
 417  *     from the completion function)
 418  *   - returns 0
 419  */
 420 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 421 extern int __fscache_write_page(struct fscache_cookie *cookie,
 422                                 struct page *page,
 423                                 fscache_rw_complete_t end_io_func,
 424                                 void *context,
 425                                 gfp_t gfp);
 426
 427 extern int __fscache_write_pages(struct fscache_cookie *cookie,
 428                                  struct pagevec *pagevec,
 429                                  fscache_rw_complete_t end_io_func,
 430                                  void *context,
 431                                  gfp_t gfp);
 432 #endif
 433
 434 static inline
 435 int fscache_write_page(struct fscache_cookie *cookie,
 436                        struct page *page,
 437                        fscache_rw_complete_t end_io_func,
 438                        void *context,
 439                        gfp_t gfp)
 440 {
 441 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 442         if (cookie)
 443                 return __fscache_write_page(cookie, page, end_io_func,
 444                                             context, gfp);
 445 #endif
 446         return -ENOBUFS;
 447 }
 448
 449 static inline
 450 int fscache_write_pages(struct fscache_cookie *cookie,
 451                         struct pagevec *pagevec,
 452                         fscache_rw_complete_t end_io_func,
 453                         void *context,
 454                         gfp_t gfp)
 455 {
 456 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 457         if (cookie)
 458                 return __fscache_write_pages(cookie, pagevec, end_io_func,
 459                                              context, gfp);
 460 #endif
 461         return -ENOBUFS;
 462 }
 463
 464 /*
 465  * indicate that caching is no longer required on a page
 466  * - note: cannot cancel any outstanding BIOs between this page and the cache
 467  */
 468 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 469 extern void __fscache_uncache_page(struct fscache_cookie *cookie,
 470                                    struct page *page);
 471 extern void __fscache_uncache_pages(struct fscache_cookie *cookie,
 472                                     struct pagevec *pagevec);
 473 #endif
 474
 475 static inline
 476 void fscache_uncache_page(struct fscache_cookie *cookie,
 477                           struct page *page)
 478 {
 479 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 480         if (cookie)
 481                 __fscache_uncache_page(cookie, page);
 482 #endif
 483 }
 484
 485 static inline
 486 void fscache_uncache_pagevec(struct fscache_cookie *cookie,
 487                              struct pagevec *pagevec)
 488 {
 489 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
 490         if (cookie)
 491                 __fscache_uncache_pages(cookie, pagevec);
 492 #endif
 493 }
 494
 495 #endif /* _LINUX_FSCACHE_H */