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