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 refcount_t ref; /* 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 unsigned int debug_id; 130 spinlock_t lock; 131 spinlock_t stores_lock; /* lock on page store tree */ 132 struct hlist_head backing_objects; /* object(s) backing this file/index */ 133 const struct fscache_cookie_def *def; /* definition */ 134 struct fscache_cookie *parent; /* parent of this entry */ 135 struct hlist_bl_node hash_link; /* Link in hash table */ 136 struct list_head proc_link; /* Link in proc list */ 137 void *netfs_data; /* back pointer to netfs */ 138 struct radix_tree_root stores; /* pages to be stored on this cookie */ 139#define FSCACHE_COOKIE_PENDING_TAG 0 /* pages tag: pending write to cache */ 140#define FSCACHE_COOKIE_STORING_TAG 1 /* pages tag: writing to cache */ 141 142 unsigned long flags; 143#define FSCACHE_COOKIE_LOOKING_UP 0 /* T if non-index cookie being looked up still */ 144#define FSCACHE_COOKIE_NO_DATA_YET 1 /* T if new object with no cached data yet */ 145#define FSCACHE_COOKIE_UNAVAILABLE 2 /* T if cookie is unavailable (error, etc) */ 146#define FSCACHE_COOKIE_INVALIDATING 3 /* T if cookie is being invalidated */ 147#define FSCACHE_COOKIE_RELINQUISHED 4 /* T if cookie has been relinquished */ 148#define FSCACHE_COOKIE_ENABLED 5 /* T if cookie is enabled */ 149#define FSCACHE_COOKIE_ENABLEMENT_LOCK 6 /* T if cookie is being en/disabled */ 150#define FSCACHE_COOKIE_AUX_UPDATED 8 /* T if the auxiliary data was updated */ 151#define FSCACHE_COOKIE_ACQUIRED 9 /* T if cookie is in use */ 152#define FSCACHE_COOKIE_RELINQUISHING 10 /* T if cookie is being relinquished */ 153 154 u8 type; /* Type of object */ 155 u8 key_len; /* Length of index key */ 156 u8 aux_len; /* Length of auxiliary data */ 157 u32 key_hash; /* Hash of parent, type, key, len */ 158 union { 159 void *key; /* Index key */ 160 u8 inline_key[16]; /* - If the key is short enough */ 161 }; 162 union { 163 void *aux; /* Auxiliary data */ 164 u8 inline_aux[8]; /* - If the aux data is short enough */ 165 }; 166}; 167 168static inline bool fscache_cookie_enabled(struct fscache_cookie *cookie) 169{ 170 return test_bit(FSCACHE_COOKIE_ENABLED, &cookie->flags); 171} 172 173/* 174 * slow-path functions for when there is actually caching available, and the 175 * netfs does actually have a valid token 176 * - these are not to be called directly 177 * - these are undefined symbols when FS-Cache is not configured and the 178 * optimiser takes care of not using them 179 */ 180extern int __fscache_register_netfs(struct fscache_netfs *); 181extern void __fscache_unregister_netfs(struct fscache_netfs *); 182extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *); 183extern void __fscache_release_cache_tag(struct fscache_cache_tag *); 184 185extern struct fscache_cookie *__fscache_acquire_cookie( 186 struct fscache_cookie *, 187 const struct fscache_cookie_def *, 188 const void *, size_t, 189 const void *, size_t, 190 void *, loff_t, bool); 191extern void __fscache_relinquish_cookie(struct fscache_cookie *, const void *, bool); 192extern int __fscache_check_consistency(struct fscache_cookie *, const void *); 193extern void __fscache_update_cookie(struct fscache_cookie *, const void *); 194extern int __fscache_attr_changed(struct fscache_cookie *); 195extern void __fscache_invalidate(struct fscache_cookie *); 196extern void __fscache_wait_on_invalidate(struct fscache_cookie *); 197 198#ifdef FSCACHE_USE_NEW_IO_API 199extern int __fscache_begin_read_operation(struct netfs_read_request *, struct fscache_cookie *); 200#else 201extern int __fscache_read_or_alloc_page(struct fscache_cookie *, 202 struct page *, 203 fscache_rw_complete_t, 204 void *, 205 gfp_t); 206extern int __fscache_read_or_alloc_pages(struct fscache_cookie *, 207 struct address_space *, 208 struct list_head *, 209 unsigned *, 210 fscache_rw_complete_t, 211 void *, 212 gfp_t); 213extern int __fscache_alloc_page(struct fscache_cookie *, struct page *, gfp_t); 214extern int __fscache_write_page(struct fscache_cookie *, struct page *, loff_t, gfp_t); 215extern void __fscache_uncache_page(struct fscache_cookie *, struct page *); 216extern bool __fscache_check_page_write(struct fscache_cookie *, struct page *); 217extern void __fscache_wait_on_page_write(struct fscache_cookie *, struct page *); 218extern bool __fscache_maybe_release_page(struct fscache_cookie *, struct page *, 219 gfp_t); 220extern void __fscache_uncache_all_inode_pages(struct fscache_cookie *, 221 struct inode *); 222extern void __fscache_readpages_cancel(struct fscache_cookie *cookie, 223 struct list_head *pages); 224#endif /* FSCACHE_USE_NEW_IO_API */ 225 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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.rst 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#ifdef FSCACHE_USE_NEW_IO_API 511 512/** 513 * fscache_begin_read_operation - Begin a read operation for the netfs lib 514 * @rreq: The read request being undertaken 515 * @cookie: The cookie representing the cache object 516 * 517 * Begin a read operation on behalf of the netfs helper library. @rreq 518 * indicates the read request to which the operation state should be attached; 519 * @cookie indicates the cache object that will be accessed. 520 * 521 * This is intended to be called from the ->begin_cache_operation() netfs lib 522 * operation as implemented by the network filesystem. 523 * 524 * Returns: 525 * * 0 - Success 526 * * -ENOBUFS - No caching available 527 * * Other error code from the cache, such as -ENOMEM. 528 */ 529static inline 530int fscache_begin_read_operation(struct netfs_read_request *rreq, 531 struct fscache_cookie *cookie) 532{ 533 if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie)) 534 return __fscache_begin_read_operation(rreq, cookie); 535 return -ENOBUFS; 536} 537 538#else /* FSCACHE_USE_NEW_IO_API */ 539 540/** 541 * fscache_read_or_alloc_page - Read a page from the cache or allocate a block 542 * in which to store it 543 * @cookie: The cookie representing the cache object 544 * @page: The netfs page to fill if possible 545 * @end_io_func: The callback to invoke when and if the page is filled 546 * @context: An arbitrary piece of data to pass on to end_io_func() 547 * @gfp: The conditions under which memory allocation should be made 548 * 549 * Read a page from the cache, or if that's not possible make a potential 550 * one-block reservation in the cache into which the page may be stored once 551 * fetched from the server. 552 * 553 * If the page is not backed by the cache object, or if it there's some reason 554 * it can't be, -ENOBUFS will be returned and nothing more will be done for 555 * that page. 556 * 557 * Else, if that page is backed by the cache, a read will be initiated directly 558 * to the netfs's page and 0 will be returned by this function. The 559 * end_io_func() callback will be invoked when the operation terminates on a 560 * completion or failure. Note that the callback may be invoked before the 561 * return. 562 * 563 * Else, if the page is unbacked, -ENODATA is returned and a block may have 564 * been allocated in the cache. 565 * 566 * See Documentation/filesystems/caching/netfs-api.rst for a complete 567 * description. 568 */ 569static inline 570int fscache_read_or_alloc_page(struct fscache_cookie *cookie, 571 struct page *page, 572 fscache_rw_complete_t end_io_func, 573 void *context, 574 gfp_t gfp) 575{ 576 if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie)) 577 return __fscache_read_or_alloc_page(cookie, page, end_io_func, 578 context, gfp); 579 else 580 return -ENOBUFS; 581} 582 583/** 584 * fscache_read_or_alloc_pages - Read pages from the cache and/or allocate 585 * blocks in which to store them 586 * @cookie: The cookie representing the cache object 587 * @mapping: The netfs inode mapping to which the pages will be attached 588 * @pages: A list of potential netfs pages to be filled 589 * @nr_pages: Number of pages to be read and/or allocated 590 * @end_io_func: The callback to invoke when and if each page is filled 591 * @context: An arbitrary piece of data to pass on to end_io_func() 592 * @gfp: The conditions under which memory allocation should be made 593 * 594 * Read a set of pages from the cache, or if that's not possible, attempt to 595 * make a potential one-block reservation for each page in the cache into which 596 * that page may be stored once fetched from the server. 597 * 598 * If some pages are not backed by the cache object, or if it there's some 599 * reason they can't be, -ENOBUFS will be returned and nothing more will be 600 * done for that pages. 601 * 602 * Else, if some of the pages are backed by the cache, a read will be initiated 603 * directly to the netfs's page and 0 will be returned by this function. The 604 * end_io_func() callback will be invoked when the operation terminates on a 605 * completion or failure. Note that the callback may be invoked before the 606 * return. 607 * 608 * Else, if a page is unbacked, -ENODATA is returned and a block may have 609 * been allocated in the cache. 610 * 611 * Because the function may want to return all of -ENOBUFS, -ENODATA and 0 in 612 * regard to different pages, the return values are prioritised in that order. 613 * Any pages submitted for reading are removed from the pages list. 614 * 615 * See Documentation/filesystems/caching/netfs-api.rst for a complete 616 * description. 617 */ 618static inline 619int fscache_read_or_alloc_pages(struct fscache_cookie *cookie, 620 struct address_space *mapping, 621 struct list_head *pages, 622 unsigned *nr_pages, 623 fscache_rw_complete_t end_io_func, 624 void *context, 625 gfp_t gfp) 626{ 627 if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie)) 628 return __fscache_read_or_alloc_pages(cookie, mapping, pages, 629 nr_pages, end_io_func, 630 context, gfp); 631 else 632 return -ENOBUFS; 633} 634 635/** 636 * fscache_alloc_page - Allocate a block in which to store a page 637 * @cookie: The cookie representing the cache object 638 * @page: The netfs page to allocate a page for 639 * @gfp: The conditions under which memory allocation should be made 640 * 641 * Request Allocation a block in the cache in which to store a netfs page 642 * without retrieving any contents from the cache. 643 * 644 * If the page is not backed by a file then -ENOBUFS will be returned and 645 * nothing more will be done, and no reservation will be made. 646 * 647 * Else, a block will be allocated if one wasn't already, and 0 will be 648 * returned 649 * 650 * See Documentation/filesystems/caching/netfs-api.rst for a complete 651 * description. 652 */ 653static inline 654int fscache_alloc_page(struct fscache_cookie *cookie, 655 struct page *page, 656 gfp_t gfp) 657{ 658 if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie)) 659 return __fscache_alloc_page(cookie, page, gfp); 660 else 661 return -ENOBUFS; 662} 663 664/** 665 * fscache_readpages_cancel - Cancel read/alloc on pages 666 * @cookie: The cookie representing the inode's cache object. 667 * @pages: The netfs pages that we canceled write on in readpages() 668 * 669 * Uncache/unreserve the pages reserved earlier in readpages() via 670 * fscache_readpages_or_alloc() and similar. In most successful caches in 671 * readpages() this doesn't do anything. In cases when the underlying netfs's 672 * readahead failed we need to clean up the pagelist (unmark and uncache). 673 * 674 * This function may sleep as it may have to clean up disk state. 675 */ 676static inline 677void fscache_readpages_cancel(struct fscache_cookie *cookie, 678 struct list_head *pages) 679{ 680 if (fscache_cookie_valid(cookie)) 681 __fscache_readpages_cancel(cookie, pages); 682} 683 684/** 685 * fscache_write_page - Request storage of a page in the cache 686 * @cookie: The cookie representing the cache object 687 * @page: The netfs page to store 688 * @object_size: Updated size of object 689 * @gfp: The conditions under which memory allocation should be made 690 * 691 * Request the contents of the netfs page be written into the cache. This 692 * request may be ignored if no cache block is currently allocated, in which 693 * case it will return -ENOBUFS. 694 * 695 * If a cache block was already allocated, a write will be initiated and 0 will 696 * be returned. The PG_fscache_write page bit is set immediately and will then 697 * be cleared at the completion of the write to indicate the success or failure 698 * of the operation. Note that the completion may happen before the return. 699 * 700 * See Documentation/filesystems/caching/netfs-api.rst for a complete 701 * description. 702 */ 703static inline 704int fscache_write_page(struct fscache_cookie *cookie, 705 struct page *page, 706 loff_t object_size, 707 gfp_t gfp) 708{ 709 if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie)) 710 return __fscache_write_page(cookie, page, object_size, gfp); 711 else 712 return -ENOBUFS; 713} 714 715/** 716 * fscache_uncache_page - Indicate that caching is no longer required on a page 717 * @cookie: The cookie representing the cache object 718 * @page: The netfs page that was being cached. 719 * 720 * Tell the cache that we no longer want a page to be cached and that it should 721 * remove any knowledge of the netfs page it may have. 722 * 723 * Note that this cannot cancel any outstanding I/O operations between this 724 * page and the cache. 725 * 726 * See Documentation/filesystems/caching/netfs-api.rst for a complete 727 * description. 728 */ 729static inline 730void fscache_uncache_page(struct fscache_cookie *cookie, 731 struct page *page) 732{ 733 if (fscache_cookie_valid(cookie)) 734 __fscache_uncache_page(cookie, page); 735} 736 737/** 738 * fscache_check_page_write - Ask if a page is being writing to the cache 739 * @cookie: The cookie representing the cache object 740 * @page: The netfs page that is being cached. 741 * 742 * Ask the cache if a page is being written to the cache. 743 * 744 * See Documentation/filesystems/caching/netfs-api.rst for a complete 745 * description. 746 */ 747static inline 748bool fscache_check_page_write(struct fscache_cookie *cookie, 749 struct page *page) 750{ 751 if (fscache_cookie_valid(cookie)) 752 return __fscache_check_page_write(cookie, page); 753 return false; 754} 755 756/** 757 * fscache_wait_on_page_write - Wait for a page to complete writing to the cache 758 * @cookie: The cookie representing the cache object 759 * @page: The netfs page that is being cached. 760 * 761 * Ask the cache to wake us up when a page is no longer being written to the 762 * cache. 763 * 764 * See Documentation/filesystems/caching/netfs-api.rst for a complete 765 * description. 766 */ 767static inline 768void fscache_wait_on_page_write(struct fscache_cookie *cookie, 769 struct page *page) 770{ 771 if (fscache_cookie_valid(cookie)) 772 __fscache_wait_on_page_write(cookie, page); 773} 774 775/** 776 * fscache_maybe_release_page - Consider releasing a page, cancelling a store 777 * @cookie: The cookie representing the cache object 778 * @page: The netfs page that is being cached. 779 * @gfp: The gfp flags passed to releasepage() 780 * 781 * Consider releasing a page for the vmscan algorithm, on behalf of the netfs's 782 * releasepage() call. A storage request on the page may cancelled if it is 783 * not currently being processed. 784 * 785 * The function returns true if the page no longer has a storage request on it, 786 * and false if a storage request is left in place. If true is returned, the 787 * page will have been passed to fscache_uncache_page(). If false is returned 788 * the page cannot be freed yet. 789 */ 790static inline 791bool fscache_maybe_release_page(struct fscache_cookie *cookie, 792 struct page *page, 793 gfp_t gfp) 794{ 795 if (fscache_cookie_valid(cookie) && PageFsCache(page)) 796 return __fscache_maybe_release_page(cookie, page, gfp); 797 return true; 798} 799 800/** 801 * fscache_uncache_all_inode_pages - Uncache all an inode's pages 802 * @cookie: The cookie representing the inode's cache object. 803 * @inode: The inode to uncache pages from. 804 * 805 * Uncache all the pages in an inode that are marked PG_fscache, assuming them 806 * to be associated with the given cookie. 807 * 808 * This function may sleep. It will wait for pages that are being written out 809 * and will wait whilst the PG_fscache mark is removed by the cache. 810 */ 811static inline 812void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie, 813 struct inode *inode) 814{ 815 if (fscache_cookie_valid(cookie)) 816 __fscache_uncache_all_inode_pages(cookie, inode); 817} 818 819#endif /* FSCACHE_USE_NEW_IO_API */ 820 821/** 822 * fscache_disable_cookie - Disable a cookie 823 * @cookie: The cookie representing the cache object 824 * @aux_data: The updated auxiliary data for the cookie (may be NULL) 825 * @invalidate: Invalidate the backing object 826 * 827 * Disable a cookie from accepting further alloc, read, write, invalidate, 828 * update or acquire operations. Outstanding operations can still be waited 829 * upon and pages can still be uncached and the cookie relinquished. 830 * 831 * This will not return until all outstanding operations have completed. 832 * 833 * If @invalidate is set, then the backing object will be invalidated and 834 * detached, otherwise it will just be detached. 835 * 836 * If @aux_data is set, then auxiliary data will be updated from that. 837 */ 838static inline 839void fscache_disable_cookie(struct fscache_cookie *cookie, 840 const void *aux_data, 841 bool invalidate) 842{ 843 if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie)) 844 __fscache_disable_cookie(cookie, aux_data, invalidate); 845} 846 847/** 848 * fscache_enable_cookie - Reenable a cookie 849 * @cookie: The cookie representing the cache object 850 * @aux_data: The updated auxiliary data for the cookie (may be NULL) 851 * @object_size: Current size of object 852 * @can_enable: A function to permit enablement once lock is held 853 * @data: Data for can_enable() 854 * 855 * Reenable a previously disabled cookie, allowing it to accept further alloc, 856 * read, write, invalidate, update or acquire operations. An attempt will be 857 * made to immediately reattach the cookie to a backing object. If @aux_data 858 * is set, the auxiliary data attached to the cookie will be updated. 859 * 860 * The can_enable() function is called (if not NULL) once the enablement lock 861 * is held to rule on whether enablement is still permitted to go ahead. 862 */ 863static inline 864void fscache_enable_cookie(struct fscache_cookie *cookie, 865 const void *aux_data, 866 loff_t object_size, 867 bool (*can_enable)(void *data), 868 void *data) 869{ 870 if (fscache_cookie_valid(cookie) && !fscache_cookie_enabled(cookie)) 871 __fscache_enable_cookie(cookie, aux_data, object_size, 872 can_enable, data); 873} 874 875#endif /* _LINUX_FSCACHE_H */ 876