include/linux/fscache.h

   1 /* General filesystem caching 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/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 #include <linux/list_bl.h>
  26
  27 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
  28 #define fscache_available() (1)
  29 #define fscache_cookie_valid(cookie) (cookie)
  30 #else
  31 #define fscache_available() (0)
  32 #define fscache_cookie_valid(cookie) (0)
  33 #endif
  34
  35
  36 /*
  37  * overload PG_private_2 to give us PG_fscache - this is used to indicate that
  38  * a page is currently backed by a local disk cache
  39  */
  40 #define PageFsCache(page)               PagePrivate2((page))
  41 #define SetPageFsCache(page)            SetPagePrivate2((page))
  42 #define ClearPageFsCache(page)          ClearPagePrivate2((page))
  43 #define TestSetPageFsCache(page)        TestSetPagePrivate2((page))
  44 #define TestClearPageFsCache(page)      TestClearPagePrivate2((page))
  45
  46 /* pattern used to fill dead space in an index entry */
  47 #define FSCACHE_INDEX_DEADFILL_PATTERN 0x79
  48
  49 struct pagevec;
  50 struct fscache_cache_tag;
  51 struct fscache_cookie;
  52 struct fscache_netfs;
  53
  54 typedef void (*fscache_rw_complete_t)(struct page *page,
  55                                       void *context,
  56                                       int error);
  57
  58 /* result of index entry consultation */
  59 enum fscache_checkaux {
  60         FSCACHE_CHECKAUX_OKAY,          /* entry okay as is */
  61         FSCACHE_CHECKAUX_NEEDS_UPDATE,  /* entry requires update */
  62         FSCACHE_CHECKAUX_OBSOLETE,      /* entry requires deletion */
  63 };
  64
  65 /*
  66  * fscache cookie definition
  67  */
  68 struct fscache_cookie_def {
  69         /* name of cookie type */
  70         char name[16];
  71
  72         /* cookie type */
  73         uint8_t type;
  74 #define FSCACHE_COOKIE_TYPE_INDEX       0
  75 #define FSCACHE_COOKIE_TYPE_DATAFILE    1
  76
  77         /* select the cache into which to insert an entry in this index
  78          * - optional
  79          * - should return a cache identifier or NULL to cause the cache to be
  80          *   inherited from the parent if possible or the first cache picked
  81          *   for a non-index file if not
  82          */
  83         struct fscache_cache_tag *(*select_cache)(
  84                 const void *parent_netfs_data,
  85                 const void *cookie_netfs_data);
  86
  87         /* consult the netfs about the state of an object
  88          * - this function can be absent if the index carries no state data
  89          * - the netfs data from the cookie being used as the target is
  90          *   presented, as is the auxiliary data and the object size
  91          */
  92         enum fscache_checkaux (*check_aux)(void *cookie_netfs_data,
  93                                            const void *data,
  94                                            uint16_t datalen,
  95                                            loff_t object_size);
  96
  97         /* get an extra reference on a read context
  98          * - this function can be absent if the completion function doesn't
  99          *   require a context
 100          */
 101         void (*get_context)(void *cookie_netfs_data, void *context);
 102
 103         /* release an extra reference on a read context
 104          * - this function can be absent if the completion function doesn't
 105          *   require a context
 106          */
 107         void (*put_context)(void *cookie_netfs_data, void *context);
 108
 109         /* indicate page that now have cache metadata retained
 110          * - this function should mark the specified page as now being cached
 111          * - the page will have been marked with PG_fscache before this is
 112          *   called, so this is optional
 113          */
 114         void (*mark_page_cached)(void *cookie_netfs_data,
 115                                  struct address_space *mapping,
 116                                  struct page *page);
 117 };
 118
 119 /*
 120  * fscache cached network filesystem type
 121  * - name, version and ops must be filled in before registration
 122  * - all other fields will be set during registration
 123  */
 124 struct fscache_netfs {
 125         uint32_t                        version;        /* indexing version */
 126         const char                      *name;          /* filesystem name */
 127         struct fscache_cookie           *primary_index;
 128 };
 129
 130 /*
 131  * data file or index object cookie
 132  * - a file will only appear in one cache
 133  * - a request to cache a file may or may not be honoured, subject to
 134  *   constraints such as disk space
 135  * - indices are created on disk just-in-time
 136  */
 137 struct fscache_cookie {
 138         atomic_t                        usage;          /* number of users of this cookie */
 139         atomic_t                        n_children;     /* number of children of this cookie */
 140         atomic_t                        n_active;       /* number of active users of netfs ptrs */
 141         spinlock_t                      lock;
 142         spinlock_t                      stores_lock;    /* lock on page store tree */
 143         struct hlist_head               backing_objects; /* object(s) backing this file/index */
 144         const struct fscache_cookie_def *def;           /* definition */
 145         struct fscache_cookie           *parent;        /* parent of this entry */
 146         struct hlist_bl_node            hash_link;      /* Link in hash table */
 147         void                            *netfs_data;    /* back pointer to netfs */
 148         struct radix_tree_root          stores;         /* pages to be stored on this cookie */
 149 #define FSCACHE_COOKIE_PENDING_TAG      0               /* pages tag: pending write to cache */
 150 #define FSCACHE_COOKIE_STORING_TAG      1               /* pages tag: writing to cache */
 151
 152         unsigned long                   flags;
 153 #define FSCACHE_COOKIE_LOOKING_UP       0       /* T if non-index cookie being looked up still */
 154 #define FSCACHE_COOKIE_NO_DATA_YET      1       /* T if new object with no cached data yet */
 155 #define FSCACHE_COOKIE_UNAVAILABLE      2       /* T if cookie is unavailable (error, etc) */
 156 #define FSCACHE_COOKIE_INVALIDATING     3       /* T if cookie is being invalidated */
 157 #define FSCACHE_COOKIE_RELINQUISHED     4       /* T if cookie has been relinquished */
 158 #define FSCACHE_COOKIE_ENABLED          5       /* T if cookie is enabled */
 159 #define FSCACHE_COOKIE_ENABLEMENT_LOCK  6       /* T if cookie is being en/disabled */
 160 #define FSCACHE_COOKIE_AUX_UPDATED      8       /* T if the auxiliary data was updated */
 161 #define FSCACHE_COOKIE_ACQUIRED         9       /* T if cookie is in use */
 162 #define FSCACHE_COOKIE_RELINQUISHING    10      /* T if cookie is being relinquished */
 163
 164         u8                              type;           /* Type of object */
 165         u8                              key_len;        /* Length of index key */
 166         u8                              aux_len;        /* Length of auxiliary data */
 167         u32                             key_hash;       /* Hash of parent, type, key, len */
 168         union {
 169                 void                    *key;           /* Index key */
 170                 u8                      inline_key[16]; /* - If the key is short enough */
 171         };
 172         union {
 173                 void                    *aux;           /* Auxiliary data */
 174                 u8                      inline_aux[8];  /* - If the aux data is short enough */
 175         };
 176 };
 177
 178 static inline bool fscache_cookie_enabled(struct fscache_cookie *cookie)
 179 {
 180         return test_bit(FSCACHE_COOKIE_ENABLED, &cookie->flags);
 181 }
 182
 183 /*
 184  * slow-path functions for when there is actually caching available, and the
 185  * netfs does actually have a valid token
 186  * - these are not to be called directly
 187  * - these are undefined symbols when FS-Cache is not configured and the
 188  *   optimiser takes care of not using them
 189  */
 190 extern int __fscache_register_netfs(struct fscache_netfs *);
 191 extern void __fscache_unregister_netfs(struct fscache_netfs *);
 192 extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *);
 193 extern void __fscache_release_cache_tag(struct fscache_cache_tag *);
 194
 195 extern struct fscache_cookie *__fscache_acquire_cookie(
 196         struct fscache_cookie *,
 197         const struct fscache_cookie_def *,
 198         const void *, size_t,
 199         const void *, size_t,
 200         void *, loff_t, bool);
 201 extern void __fscache_relinquish_cookie(struct fscache_cookie *, const void *, bool);
 202 extern int __fscache_check_consistency(struct fscache_cookie *, const void *);
 203 extern void __fscache_update_cookie(struct fscache_cookie *, const void *);
 204 extern int __fscache_attr_changed(struct fscache_cookie *);
 205 extern void __fscache_invalidate(struct fscache_cookie *);
 206 extern void __fscache_wait_on_invalidate(struct fscache_cookie *);
 207 extern int __fscache_read_or_alloc_page(struct fscache_cookie *,
 208                                         struct page *,
 209                                         fscache_rw_complete_t,
 210                                         void *,
 211                                         gfp_t);
 212 extern int __fscache_read_or_alloc_pages(struct fscache_cookie *,
 213                                          struct address_space *,
 214                                          struct list_head *,
 215                                          unsigned *,
 216                                          fscache_rw_complete_t,
 217                                          void *,
 218                                          gfp_t);
 219 extern int __fscache_alloc_page(struct fscache_cookie *, struct page *, gfp_t);
 220 extern int __fscache_write_page(struct fscache_cookie *, struct page *, loff_t, gfp_t);
 221 extern void __fscache_uncache_page(struct fscache_cookie *, struct page *);
 222 extern bool __fscache_check_page_write(struct fscache_cookie *, struct page *);
 223 extern void __fscache_wait_on_page_write(struct fscache_cookie *, struct page *);
 224 extern bool __fscache_maybe_release_page(struct fscache_cookie *, struct page *,
 225                                          gfp_t);
 226 extern void __fscache_uncache_all_inode_pages(struct fscache_cookie *,
 227                                               struct inode *);
 228 extern void __fscache_readpages_cancel(struct fscache_cookie *cookie,
 229                                        struct list_head *pages);
 230 extern void __fscache_disable_cookie(struct fscache_cookie *, const void *, bool);
 231 extern void __fscache_enable_cookie(struct fscache_cookie *, const void *, loff_t,
 232                                     bool (*)(void *), void *);
 233
 234 /**
 235  * fscache_register_netfs - Register a filesystem as desiring caching services
 236  * @netfs: The description of the filesystem
 237  *
 238  * Register a filesystem as desiring caching services if they're available.
 239  *
 240  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 241  * description.
 242  */
 243 static inline
 244 int fscache_register_netfs(struct fscache_netfs *netfs)
 245 {
 246         if (fscache_available())
 247                 return __fscache_register_netfs(netfs);
 248         else
 249                 return 0;
 250 }
 251
 252 /**
 253  * fscache_unregister_netfs - Indicate that a filesystem no longer desires
 254  * caching services
 255  * @netfs: The description of the filesystem
 256  *
 257  * Indicate that a filesystem no longer desires caching services for the
 258  * moment.
 259  *
 260  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 261  * description.
 262  */
 263 static inline
 264 void fscache_unregister_netfs(struct fscache_netfs *netfs)
 265 {
 266         if (fscache_available())
 267                 __fscache_unregister_netfs(netfs);
 268 }
 269
 270 /**
 271  * fscache_lookup_cache_tag - Look up a cache tag
 272  * @name: The name of the tag to search for
 273  *
 274  * Acquire a specific cache referral tag that can be used to select a specific
 275  * cache in which to cache an index.
 276  *
 277  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 278  * description.
 279  */
 280 static inline
 281 struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
 282 {
 283         if (fscache_available())
 284                 return __fscache_lookup_cache_tag(name);
 285         else
 286                 return NULL;
 287 }
 288
 289 /**
 290  * fscache_release_cache_tag - Release a cache tag
 291  * @tag: The tag to release
 292  *
 293  * Release a reference to a cache referral tag previously looked up.
 294  *
 295  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 296  * description.
 297  */
 298 static inline
 299 void fscache_release_cache_tag(struct fscache_cache_tag *tag)
 300 {
 301         if (fscache_available())
 302                 __fscache_release_cache_tag(tag);
 303 }
 304
 305 /**
 306  * fscache_acquire_cookie - Acquire a cookie to represent a cache object
 307  * @parent: The cookie that's to be the parent of this one
 308  * @def: A description of the cache object, including callback operations
 309  * @index_key: The index key for this cookie
 310  * @index_key_len: Size of the index key
 311  * @aux_data: The auxiliary data for the cookie (may be NULL)
 312  * @aux_data_len: Size of the auxiliary data buffer
 313  * @netfs_data: An arbitrary piece of data to be kept in the cookie to
 314  * represent the cache object to the netfs
 315  * @object_size: The initial size of object
 316  * @enable: Whether or not to enable a data cookie immediately
 317  *
 318  * This function is used to inform FS-Cache about part of an index hierarchy
 319  * that can be used to locate files.  This is done by requesting a cookie for
 320  * each index in the path to the file.
 321  *
 322  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 323  * description.
 324  */
 325 static inline
 326 struct fscache_cookie *fscache_acquire_cookie(
 327         struct fscache_cookie *parent,
 328         const struct fscache_cookie_def *def,
 329         const void *index_key,
 330         size_t index_key_len,
 331         const void *aux_data,
 332         size_t aux_data_len,
 333         void *netfs_data,
 334         loff_t object_size,
 335         bool enable)
 336 {
 337         if (fscache_cookie_valid(parent) && fscache_cookie_enabled(parent))
 338                 return __fscache_acquire_cookie(parent, def,
 339                                                 index_key, index_key_len,
 340                                                 aux_data, aux_data_len,
 341                                                 netfs_data, object_size, enable);
 342         else
 343                 return NULL;
 344 }
 345
 346 /**
 347  * fscache_relinquish_cookie - Return the cookie to the cache, maybe discarding
 348  * it
 349  * @cookie: The cookie being returned
 350  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
 351  * @retire: True if the cache object the cookie represents is to be discarded
 352  *
 353  * This function returns a cookie to the cache, forcibly discarding the
 354  * associated cache object if retire is set to true.  The opportunity is
 355  * provided to update the auxiliary data in the cache before the object is
 356  * disconnected.
 357  *
 358  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 359  * description.
 360  */
 361 static inline
 362 void fscache_relinquish_cookie(struct fscache_cookie *cookie,
 363                                const void *aux_data,
 364                                bool retire)
 365 {
 366         if (fscache_cookie_valid(cookie))
 367                 __fscache_relinquish_cookie(cookie, aux_data, retire);
 368 }
 369
 370 /**
 371  * fscache_check_consistency - Request validation of a cache's auxiliary data
 372  * @cookie: The cookie representing the cache object
 373  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
 374  *
 375  * Request an consistency check from fscache, which passes the request to the
 376  * backing cache.  The auxiliary data on the cookie will be updated first if
 377  * @aux_data is set.
 378  *
 379  * Returns 0 if consistent and -ESTALE if inconsistent.  May also
 380  * return -ENOMEM and -ERESTARTSYS.
 381  */
 382 static inline
 383 int fscache_check_consistency(struct fscache_cookie *cookie,
 384                               const void *aux_data)
 385 {
 386         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 387                 return __fscache_check_consistency(cookie, aux_data);
 388         else
 389                 return 0;
 390 }
 391
 392 /**
 393  * fscache_update_cookie - Request that a cache object be updated
 394  * @cookie: The cookie representing the cache object
 395  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
 396  *
 397  * Request an update of the index data for the cache object associated with the
 398  * cookie.  The auxiliary data on the cookie will be updated first if @aux_data
 399  * is set.
 400  *
 401  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 402  * description.
 403  */
 404 static inline
 405 void fscache_update_cookie(struct fscache_cookie *cookie, const void *aux_data)
 406 {
 407         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 408                 __fscache_update_cookie(cookie, aux_data);
 409 }
 410
 411 /**
 412  * fscache_pin_cookie - Pin a data-storage cache object in its cache
 413  * @cookie: The cookie representing the cache object
 414  *
 415  * Permit data-storage cache objects to be pinned in the cache.
 416  *
 417  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 418  * description.
 419  */
 420 static inline
 421 int fscache_pin_cookie(struct fscache_cookie *cookie)
 422 {
 423         return -ENOBUFS;
 424 }
 425
 426 /**
 427  * fscache_pin_cookie - Unpin a data-storage cache object in its cache
 428  * @cookie: The cookie representing the cache object
 429  *
 430  * Permit data-storage cache objects to be unpinned from the cache.
 431  *
 432  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 433  * description.
 434  */
 435 static inline
 436 void fscache_unpin_cookie(struct fscache_cookie *cookie)
 437 {
 438 }
 439
 440 /**
 441  * fscache_attr_changed - Notify cache that an object's attributes changed
 442  * @cookie: The cookie representing the cache object
 443  *
 444  * Send a notification to the cache indicating that an object's attributes have
 445  * changed.  This includes the data size.  These attributes will be obtained
 446  * through the get_attr() cookie definition op.
 447  *
 448  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 449  * description.
 450  */
 451 static inline
 452 int fscache_attr_changed(struct fscache_cookie *cookie)
 453 {
 454         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 455                 return __fscache_attr_changed(cookie);
 456         else
 457                 return -ENOBUFS;
 458 }
 459
 460 /**
 461  * fscache_invalidate - Notify cache that an object needs invalidation
 462  * @cookie: The cookie representing the cache object
 463  *
 464  * Notify the cache that an object is needs to be invalidated and that it
 465  * should abort any retrievals or stores it is doing on the cache.  The object
 466  * is then marked non-caching until such time as the invalidation is complete.
 467  *
 468  * This can be called with spinlocks held.
 469  *
 470  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 471  * description.
 472  */
 473 static inline
 474 void fscache_invalidate(struct fscache_cookie *cookie)
 475 {
 476         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 477                 __fscache_invalidate(cookie);
 478 }
 479
 480 /**
 481  * fscache_wait_on_invalidate - Wait for invalidation to complete
 482  * @cookie: The cookie representing the cache object
 483  *
 484  * Wait for the invalidation of an object to complete.
 485  *
 486  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 487  * description.
 488  */
 489 static inline
 490 void fscache_wait_on_invalidate(struct fscache_cookie *cookie)
 491 {
 492         if (fscache_cookie_valid(cookie))
 493                 __fscache_wait_on_invalidate(cookie);
 494 }
 495
 496 /**
 497  * fscache_reserve_space - Reserve data space for a cached object
 498  * @cookie: The cookie representing the cache object
 499  * @i_size: The amount of space to be reserved
 500  *
 501  * Reserve an amount of space in the cache for the cache object attached to a
 502  * cookie so that a write to that object within the space can always be
 503  * honoured.
 504  *
 505  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 506  * description.
 507  */
 508 static inline
 509 int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
 510 {
 511         return -ENOBUFS;
 512 }
 513
 514 /**
 515  * fscache_read_or_alloc_page - Read a page from the cache or allocate a block
 516  * in which to store it
 517  * @cookie: The cookie representing the cache object
 518  * @page: The netfs page to fill if possible
 519  * @end_io_func: The callback to invoke when and if the page is filled
 520  * @context: An arbitrary piece of data to pass on to end_io_func()
 521  * @gfp: The conditions under which memory allocation should be made
 522  *
 523  * Read a page from the cache, or if that's not possible make a potential
 524  * one-block reservation in the cache into which the page may be stored once
 525  * fetched from the server.
 526  *
 527  * If the page is not backed by the cache object, or if it there's some reason
 528  * it can't be, -ENOBUFS will be returned and nothing more will be done for
 529  * that page.
 530  *
 531  * Else, if that page is backed by the cache, a read will be initiated directly
 532  * to the netfs's page and 0 will be returned by this function.  The
 533  * end_io_func() callback will be invoked when the operation terminates on a
 534  * completion or failure.  Note that the callback may be invoked before the
 535  * return.
 536  *
 537  * Else, if the page is unbacked, -ENODATA is returned and a block may have
 538  * been allocated in the cache.
 539  *
 540  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 541  * description.
 542  */
 543 static inline
 544 int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
 545                                struct page *page,
 546                                fscache_rw_complete_t end_io_func,
 547                                void *context,
 548                                gfp_t gfp)
 549 {
 550         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 551                 return __fscache_read_or_alloc_page(cookie, page, end_io_func,
 552                                                     context, gfp);
 553         else
 554                 return -ENOBUFS;
 555 }
 556
 557 /**
 558  * fscache_read_or_alloc_pages - Read pages from the cache and/or allocate
 559  * blocks in which to store them
 560  * @cookie: The cookie representing the cache object
 561  * @mapping: The netfs inode mapping to which the pages will be attached
 562  * @pages: A list of potential netfs pages to be filled
 563  * @nr_pages: Number of pages to be read and/or allocated
 564  * @end_io_func: The callback to invoke when and if each page is filled
 565  * @context: An arbitrary piece of data to pass on to end_io_func()
 566  * @gfp: The conditions under which memory allocation should be made
 567  *
 568  * Read a set of pages from the cache, or if that's not possible, attempt to
 569  * make a potential one-block reservation for each page in the cache into which
 570  * that page may be stored once fetched from the server.
 571  *
 572  * If some pages are not backed by the cache object, or if it there's some
 573  * reason they can't be, -ENOBUFS will be returned and nothing more will be
 574  * done for that pages.
 575  *
 576  * Else, if some of the pages are backed by the cache, a read will be initiated
 577  * directly to the netfs's page and 0 will be returned by this function.  The
 578  * end_io_func() callback will be invoked when the operation terminates on a
 579  * completion or failure.  Note that the callback may be invoked before the
 580  * return.
 581  *
 582  * Else, if a page is unbacked, -ENODATA is returned and a block may have
 583  * been allocated in the cache.
 584  *
 585  * Because the function may want to return all of -ENOBUFS, -ENODATA and 0 in
 586  * regard to different pages, the return values are prioritised in that order.
 587  * Any pages submitted for reading are removed from the pages list.
 588  *
 589  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 590  * description.
 591  */
 592 static inline
 593 int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
 594                                 struct address_space *mapping,
 595                                 struct list_head *pages,
 596                                 unsigned *nr_pages,
 597                                 fscache_rw_complete_t end_io_func,
 598                                 void *context,
 599                                 gfp_t gfp)
 600 {
 601         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 602                 return __fscache_read_or_alloc_pages(cookie, mapping, pages,
 603                                                      nr_pages, end_io_func,
 604                                                      context, gfp);
 605         else
 606                 return -ENOBUFS;
 607 }
 608
 609 /**
 610  * fscache_alloc_page - Allocate a block in which to store a page
 611  * @cookie: The cookie representing the cache object
 612  * @page: The netfs page to allocate a page for
 613  * @gfp: The conditions under which memory allocation should be made
 614  *
 615  * Request Allocation a block in the cache in which to store a netfs page
 616  * without retrieving any contents from the cache.
 617  *
 618  * If the page is not backed by a file then -ENOBUFS will be returned and
 619  * nothing more will be done, and no reservation will be made.
 620  *
 621  * Else, a block will be allocated if one wasn't already, and 0 will be
 622  * returned
 623  *
 624  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 625  * description.
 626  */
 627 static inline
 628 int fscache_alloc_page(struct fscache_cookie *cookie,
 629                        struct page *page,
 630                        gfp_t gfp)
 631 {
 632         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 633                 return __fscache_alloc_page(cookie, page, gfp);
 634         else
 635                 return -ENOBUFS;
 636 }
 637
 638 /**
 639  * fscache_readpages_cancel - Cancel read/alloc on pages
 640  * @cookie: The cookie representing the inode's cache object.
 641  * @pages: The netfs pages that we canceled write on in readpages()
 642  *
 643  * Uncache/unreserve the pages reserved earlier in readpages() via
 644  * fscache_readpages_or_alloc() and similar.  In most successful caches in
 645  * readpages() this doesn't do anything.  In cases when the underlying netfs's
 646  * readahead failed we need to clean up the pagelist (unmark and uncache).
 647  *
 648  * This function may sleep as it may have to clean up disk state.
 649  */
 650 static inline
 651 void fscache_readpages_cancel(struct fscache_cookie *cookie,
 652                               struct list_head *pages)
 653 {
 654         if (fscache_cookie_valid(cookie))
 655                 __fscache_readpages_cancel(cookie, pages);
 656 }
 657
 658 /**
 659  * fscache_write_page - Request storage of a page in the cache
 660  * @cookie: The cookie representing the cache object
 661  * @page: The netfs page to store
 662  * @object_size: Updated size of object
 663  * @gfp: The conditions under which memory allocation should be made
 664  *
 665  * Request the contents of the netfs page be written into the cache.  This
 666  * request may be ignored if no cache block is currently allocated, in which
 667  * case it will return -ENOBUFS.
 668  *
 669  * If a cache block was already allocated, a write will be initiated and 0 will
 670  * be returned.  The PG_fscache_write page bit is set immediately and will then
 671  * be cleared at the completion of the write to indicate the success or failure
 672  * of the operation.  Note that the completion may happen before the return.
 673  *
 674  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 675  * description.
 676  */
 677 static inline
 678 int fscache_write_page(struct fscache_cookie *cookie,
 679                        struct page *page,
 680                        loff_t object_size,
 681                        gfp_t gfp)
 682 {
 683         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 684                 return __fscache_write_page(cookie, page, object_size, gfp);
 685         else
 686                 return -ENOBUFS;
 687 }
 688
 689 /**
 690  * fscache_uncache_page - Indicate that caching is no longer required on a page
 691  * @cookie: The cookie representing the cache object
 692  * @page: The netfs page that was being cached.
 693  *
 694  * Tell the cache that we no longer want a page to be cached and that it should
 695  * remove any knowledge of the netfs page it may have.
 696  *
 697  * Note that this cannot cancel any outstanding I/O operations between this
 698  * page and the cache.
 699  *
 700  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 701  * description.
 702  */
 703 static inline
 704 void fscache_uncache_page(struct fscache_cookie *cookie,
 705                           struct page *page)
 706 {
 707         if (fscache_cookie_valid(cookie))
 708                 __fscache_uncache_page(cookie, page);
 709 }
 710
 711 /**
 712  * fscache_check_page_write - Ask if a page is being writing to the cache
 713  * @cookie: The cookie representing the cache object
 714  * @page: The netfs page that is being cached.
 715  *
 716  * Ask the cache if a page is being written to the cache.
 717  *
 718  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 719  * description.
 720  */
 721 static inline
 722 bool fscache_check_page_write(struct fscache_cookie *cookie,
 723                               struct page *page)
 724 {
 725         if (fscache_cookie_valid(cookie))
 726                 return __fscache_check_page_write(cookie, page);
 727         return false;
 728 }
 729
 730 /**
 731  * fscache_wait_on_page_write - Wait for a page to complete writing to the cache
 732  * @cookie: The cookie representing the cache object
 733  * @page: The netfs page that is being cached.
 734  *
 735  * Ask the cache to wake us up when a page is no longer being written to the
 736  * cache.
 737  *
 738  * See Documentation/filesystems/caching/netfs-api.txt for a complete
 739  * description.
 740  */
 741 static inline
 742 void fscache_wait_on_page_write(struct fscache_cookie *cookie,
 743                                 struct page *page)
 744 {
 745         if (fscache_cookie_valid(cookie))
 746                 __fscache_wait_on_page_write(cookie, page);
 747 }
 748
 749 /**
 750  * fscache_maybe_release_page - Consider releasing a page, cancelling a store
 751  * @cookie: The cookie representing the cache object
 752  * @page: The netfs page that is being cached.
 753  * @gfp: The gfp flags passed to releasepage()
 754  *
 755  * Consider releasing a page for the vmscan algorithm, on behalf of the netfs's
 756  * releasepage() call.  A storage request on the page may cancelled if it is
 757  * not currently being processed.
 758  *
 759  * The function returns true if the page no longer has a storage request on it,
 760  * and false if a storage request is left in place.  If true is returned, the
 761  * page will have been passed to fscache_uncache_page().  If false is returned
 762  * the page cannot be freed yet.
 763  */
 764 static inline
 765 bool fscache_maybe_release_page(struct fscache_cookie *cookie,
 766                                 struct page *page,
 767                                 gfp_t gfp)
 768 {
 769         if (fscache_cookie_valid(cookie) && PageFsCache(page))
 770                 return __fscache_maybe_release_page(cookie, page, gfp);
 771         return true;
 772 }
 773
 774 /**
 775  * fscache_uncache_all_inode_pages - Uncache all an inode's pages
 776  * @cookie: The cookie representing the inode's cache object.
 777  * @inode: The inode to uncache pages from.
 778  *
 779  * Uncache all the pages in an inode that are marked PG_fscache, assuming them
 780  * to be associated with the given cookie.
 781  *
 782  * This function may sleep.  It will wait for pages that are being written out
 783  * and will wait whilst the PG_fscache mark is removed by the cache.
 784  */
 785 static inline
 786 void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,
 787                                      struct inode *inode)
 788 {
 789         if (fscache_cookie_valid(cookie))
 790                 __fscache_uncache_all_inode_pages(cookie, inode);
 791 }
 792
 793 /**
 794  * fscache_disable_cookie - Disable a cookie
 795  * @cookie: The cookie representing the cache object
 796  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
 797  * @invalidate: Invalidate the backing object
 798  *
 799  * Disable a cookie from accepting further alloc, read, write, invalidate,
 800  * update or acquire operations.  Outstanding operations can still be waited
 801  * upon and pages can still be uncached and the cookie relinquished.
 802  *
 803  * This will not return until all outstanding operations have completed.
 804  *
 805  * If @invalidate is set, then the backing object will be invalidated and
 806  * detached, otherwise it will just be detached.
 807  *
 808  * If @aux_data is set, then auxiliary data will be updated from that.
 809  */
 810 static inline
 811 void fscache_disable_cookie(struct fscache_cookie *cookie,
 812                             const void *aux_data,
 813                             bool invalidate)
 814 {
 815         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
 816                 __fscache_disable_cookie(cookie, aux_data, invalidate);
 817 }
 818
 819 /**
 820  * fscache_enable_cookie - Reenable a cookie
 821  * @cookie: The cookie representing the cache object
 822  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
 823  * @object_size: Current size of object
 824  * @can_enable: A function to permit enablement once lock is held
 825  * @data: Data for can_enable()
 826  *
 827  * Reenable a previously disabled cookie, allowing it to accept further alloc,
 828  * read, write, invalidate, update or acquire operations.  An attempt will be
 829  * made to immediately reattach the cookie to a backing object.  If @aux_data
 830  * is set, the auxiliary data attached to the cookie will be updated.
 831  *
 832  * The can_enable() function is called (if not NULL) once the enablement lock
 833  * is held to rule on whether enablement is still permitted to go ahead.
 834  */
 835 static inline
 836 void fscache_enable_cookie(struct fscache_cookie *cookie,
 837                            const void *aux_data,
 838                            loff_t object_size,
 839                            bool (*can_enable)(void *data),
 840                            void *data)
 841 {
 842         if (fscache_cookie_valid(cookie) && !fscache_cookie_enabled(cookie))
 843                 __fscache_enable_cookie(cookie, aux_data, object_size,
 844                                         can_enable, data);
 845 }
 846
 847 #endif /* _LINUX_FSCACHE_H */