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