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 49struct pagevec; 50struct fscache_cache_tag; 51struct fscache_cookie; 52struct fscache_netfs; 53 54typedef void (*fscache_rw_complete_t)(struct page *page, 55 void *context, 56 int error); 57 58/* result of index entry consultation */ 59enum 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 */ 68struct 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 */ 124struct 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 */ 137struct 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 178static 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 */ 190extern int __fscache_register_netfs(struct fscache_netfs *); 191extern void __fscache_unregister_netfs(struct fscache_netfs *); 192extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *); 193extern void __fscache_release_cache_tag(struct fscache_cache_tag *); 194 195extern 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); 201extern void __fscache_relinquish_cookie(struct fscache_cookie *, const void *, bool); 202extern int __fscache_check_consistency(struct fscache_cookie *, const void *); 203extern void __fscache_update_cookie(struct fscache_cookie *, const void *); 204extern int __fscache_attr_changed(struct fscache_cookie *); 205extern void __fscache_invalidate(struct fscache_cookie *); 206extern void __fscache_wait_on_invalidate(struct fscache_cookie *); 207extern int __fscache_read_or_alloc_page(struct fscache_cookie *, 208 struct page *, 209 fscache_rw_complete_t, 210 void *, 211 gfp_t); 212extern 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); 219extern int __fscache_alloc_page(struct fscache_cookie *, struct page *, gfp_t); 220extern int __fscache_write_page(struct fscache_cookie *, struct page *, loff_t, gfp_t); 221extern void __fscache_uncache_page(struct fscache_cookie *, struct page *); 222extern bool __fscache_check_page_write(struct fscache_cookie *, struct page *); 223extern void __fscache_wait_on_page_write(struct fscache_cookie *, struct page *); 224extern bool __fscache_maybe_release_page(struct fscache_cookie *, struct page *, 225 gfp_t); 226extern void __fscache_uncache_all_inode_pages(struct fscache_cookie *, 227 struct inode *); 228extern void __fscache_readpages_cancel(struct fscache_cookie *cookie, 229 struct list_head *pages); 230extern void __fscache_disable_cookie(struct fscache_cookie *, const void *, bool); 231extern 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 */ 243static inline 244int 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 */ 263static inline 264void 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 */ 280static inline 281struct 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 */ 298static inline 299void 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 */ 325static inline 326struct 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 */ 361static inline 362void 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 */ 382static inline 383int 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 */ 404static inline 405void 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 */ 420static inline 421int 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 */ 435static inline 436void 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 */ 451static inline 452int 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 */ 473static inline 474void 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 */ 489static inline 490void 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 */ 508static inline 509int 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 */ 543static inline 544int 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 */ 592static inline 593int 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 */ 627static inline 628int 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 */ 650static inline 651void 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 */ 677static inline 678int 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 */ 703static inline 704void 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 */ 721static inline 722bool 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 */ 741static inline 742void 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 */ 764static inline 765bool 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 */ 785static inline 786void 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 */ 810static inline 811void 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 */ 835static inline 836void 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 */ 848