1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* General filesystem caching backing cache 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/backend-api.rst 10 * 11 * for a description of the cache backend interface declared here. 12 */ 13 14 #ifndef _LINUX_FSCACHE_CACHE_H 15 #define _LINUX_FSCACHE_CACHE_H 16 17 #include <linux/fscache.h> 18 #include <linux/sched.h> 19 #include <linux/workqueue.h> 20 21 #define NR_MAXCACHES BITS_PER_LONG 22 23 struct fscache_cache; 24 struct fscache_cache_ops; 25 struct fscache_object; 26 struct fscache_operation; 27 28 enum fscache_obj_ref_trace { 29 fscache_obj_get_add_to_deps, 30 fscache_obj_get_queue, 31 fscache_obj_put_alloc_fail, 32 fscache_obj_put_attach_fail, 33 fscache_obj_put_drop_obj, 34 fscache_obj_put_enq_dep, 35 fscache_obj_put_queue, 36 fscache_obj_put_work, 37 fscache_obj_ref__nr_traces 38 }; 39 40 /* 41 * cache tag definition 42 */ 43 struct fscache_cache_tag { 44 struct list_head link; 45 struct fscache_cache *cache; /* cache referred to by this tag */ 46 unsigned long flags; 47 #define FSCACHE_TAG_RESERVED 0 /* T if tag is reserved for a cache */ 48 atomic_t usage; 49 char name[]; /* tag name */ 50 }; 51 52 /* 53 * cache definition 54 */ 55 struct fscache_cache { 56 const struct fscache_cache_ops *ops; 57 struct fscache_cache_tag *tag; /* tag representing this cache */ 58 struct kobject *kobj; /* system representation of this cache */ 59 struct list_head link; /* link in list of caches */ 60 size_t max_index_size; /* maximum size of index data */ 61 char identifier[36]; /* cache label */ 62 63 /* node management */ 64 struct work_struct op_gc; /* operation garbage collector */ 65 struct list_head object_list; /* list of data/index objects */ 66 struct list_head op_gc_list; /* list of ops to be deleted */ 67 spinlock_t object_list_lock; 68 spinlock_t op_gc_list_lock; 69 atomic_t object_count; /* no. of live objects in this cache */ 70 struct fscache_object *fsdef; /* object for the fsdef index */ 71 unsigned long flags; 72 #define FSCACHE_IOERROR 0 /* cache stopped on I/O error */ 73 #define FSCACHE_CACHE_WITHDRAWN 1 /* cache has been withdrawn */ 74 }; 75 76 extern wait_queue_head_t fscache_cache_cleared_wq; 77 78 /* 79 * operation to be applied to a cache object 80 * - retrieval initiation operations are done in the context of the process 81 * that issued them, and not in an async thread pool 82 */ 83 typedef void (*fscache_operation_release_t)(struct fscache_operation *op); 84 typedef void (*fscache_operation_processor_t)(struct fscache_operation *op); 85 typedef void (*fscache_operation_cancel_t)(struct fscache_operation *op); 86 87 enum fscache_operation_state { 88 FSCACHE_OP_ST_BLANK, /* Op is not yet submitted */ 89 FSCACHE_OP_ST_INITIALISED, /* Op is initialised */ 90 FSCACHE_OP_ST_PENDING, /* Op is blocked from running */ 91 FSCACHE_OP_ST_IN_PROGRESS, /* Op is in progress */ 92 FSCACHE_OP_ST_COMPLETE, /* Op is complete */ 93 FSCACHE_OP_ST_CANCELLED, /* Op has been cancelled */ 94 FSCACHE_OP_ST_DEAD /* Op is now dead */ 95 }; 96 97 struct fscache_operation { 98 struct work_struct work; /* record for async ops */ 99 struct list_head pend_link; /* link in object->pending_ops */ 100 struct fscache_object *object; /* object to be operated upon */ 101 102 unsigned long flags; 103 #define FSCACHE_OP_TYPE 0x000f /* operation type */ 104 #define FSCACHE_OP_ASYNC 0x0001 /* - async op, processor may sleep for disk */ 105 #define FSCACHE_OP_MYTHREAD 0x0002 /* - processing is done be issuing thread, not pool */ 106 #define FSCACHE_OP_WAITING 4 /* cleared when op is woken */ 107 #define FSCACHE_OP_EXCLUSIVE 5 /* exclusive op, other ops must wait */ 108 #define FSCACHE_OP_DEC_READ_CNT 6 /* decrement object->n_reads on destruction */ 109 #define FSCACHE_OP_UNUSE_COOKIE 7 /* call fscache_unuse_cookie() on completion */ 110 #define FSCACHE_OP_KEEP_FLAGS 0x00f0 /* flags to keep when repurposing an op */ 111 112 enum fscache_operation_state state; 113 atomic_t usage; 114 unsigned debug_id; /* debugging ID */ 115 116 /* operation processor callback 117 * - can be NULL if FSCACHE_OP_WAITING is going to be used to perform 118 * the op in a non-pool thread */ 119 fscache_operation_processor_t processor; 120 121 /* Operation cancellation cleanup (optional) */ 122 fscache_operation_cancel_t cancel; 123 124 /* operation releaser */ 125 fscache_operation_release_t release; 126 }; 127 128 extern atomic_t fscache_op_debug_id; 129 extern void fscache_op_work_func(struct work_struct *work); 130 131 extern void fscache_enqueue_operation(struct fscache_operation *); 132 extern void fscache_op_complete(struct fscache_operation *, bool); 133 extern void fscache_put_operation(struct fscache_operation *); 134 extern void fscache_operation_init(struct fscache_cookie *, 135 struct fscache_operation *, 136 fscache_operation_processor_t, 137 fscache_operation_cancel_t, 138 fscache_operation_release_t); 139 140 /* 141 * data read operation 142 */ 143 struct fscache_retrieval { 144 struct fscache_operation op; 145 struct fscache_cookie *cookie; /* The netfs cookie */ 146 struct address_space *mapping; /* netfs pages */ 147 fscache_rw_complete_t end_io_func; /* function to call on I/O completion */ 148 void *context; /* netfs read context (pinned) */ 149 struct list_head to_do; /* list of things to be done by the backend */ 150 unsigned long start_time; /* time at which retrieval started */ 151 atomic_t n_pages; /* number of pages to be retrieved */ 152 }; 153 154 typedef int (*fscache_page_retrieval_func_t)(struct fscache_retrieval *op, 155 struct page *page, 156 gfp_t gfp); 157 158 typedef int (*fscache_pages_retrieval_func_t)(struct fscache_retrieval *op, 159 struct list_head *pages, 160 unsigned *nr_pages, 161 gfp_t gfp); 162 163 /** 164 * fscache_get_retrieval - Get an extra reference on a retrieval operation 165 * @op: The retrieval operation to get a reference on 166 * 167 * Get an extra reference on a retrieval operation. 168 */ 169 static inline 170 struct fscache_retrieval *fscache_get_retrieval(struct fscache_retrieval *op) 171 { 172 atomic_inc(&op->op.usage); 173 return op; 174 } 175 176 /** 177 * fscache_enqueue_retrieval - Enqueue a retrieval operation for processing 178 * @op: The retrieval operation affected 179 * 180 * Enqueue a retrieval operation for processing by the FS-Cache thread pool. 181 */ 182 static inline void fscache_enqueue_retrieval(struct fscache_retrieval *op) 183 { 184 fscache_enqueue_operation(&op->op); 185 } 186 187 /** 188 * fscache_retrieval_complete - Record (partial) completion of a retrieval 189 * @op: The retrieval operation affected 190 * @n_pages: The number of pages to account for 191 */ 192 static inline void fscache_retrieval_complete(struct fscache_retrieval *op, 193 int n_pages) 194 { 195 if (atomic_sub_return_relaxed(n_pages, &op->n_pages) <= 0) 196 fscache_op_complete(&op->op, false); 197 } 198 199 /** 200 * fscache_put_retrieval - Drop a reference to a retrieval operation 201 * @op: The retrieval operation affected 202 * 203 * Drop a reference to a retrieval operation. 204 */ 205 static inline void fscache_put_retrieval(struct fscache_retrieval *op) 206 { 207 fscache_put_operation(&op->op); 208 } 209 210 /* 211 * cached page storage work item 212 * - used to do three things: 213 * - batch writes to the cache 214 * - do cache writes asynchronously 215 * - defer writes until cache object lookup completion 216 */ 217 struct fscache_storage { 218 struct fscache_operation op; 219 pgoff_t store_limit; /* don't write more than this */ 220 }; 221 222 /* 223 * cache operations 224 */ 225 struct fscache_cache_ops { 226 /* name of cache provider */ 227 const char *name; 228 229 /* allocate an object record for a cookie */ 230 struct fscache_object *(*alloc_object)(struct fscache_cache *cache, 231 struct fscache_cookie *cookie); 232 233 /* look up the object for a cookie 234 * - return -ETIMEDOUT to be requeued 235 */ 236 int (*lookup_object)(struct fscache_object *object); 237 238 /* finished looking up */ 239 void (*lookup_complete)(struct fscache_object *object); 240 241 /* increment the usage count on this object (may fail if unmounting) */ 242 struct fscache_object *(*grab_object)(struct fscache_object *object, 243 enum fscache_obj_ref_trace why); 244 245 /* pin an object in the cache */ 246 int (*pin_object)(struct fscache_object *object); 247 248 /* unpin an object in the cache */ 249 void (*unpin_object)(struct fscache_object *object); 250 251 /* check the consistency between the backing cache and the FS-Cache 252 * cookie */ 253 int (*check_consistency)(struct fscache_operation *op); 254 255 /* store the updated auxiliary data on an object */ 256 void (*update_object)(struct fscache_object *object); 257 258 /* Invalidate an object */ 259 void (*invalidate_object)(struct fscache_operation *op); 260 261 /* discard the resources pinned by an object and effect retirement if 262 * necessary */ 263 void (*drop_object)(struct fscache_object *object); 264 265 /* dispose of a reference to an object */ 266 void (*put_object)(struct fscache_object *object, 267 enum fscache_obj_ref_trace why); 268 269 /* sync a cache */ 270 void (*sync_cache)(struct fscache_cache *cache); 271 272 /* notification that the attributes of a non-index object (such as 273 * i_size) have changed */ 274 int (*attr_changed)(struct fscache_object *object); 275 276 /* reserve space for an object's data and associated metadata */ 277 int (*reserve_space)(struct fscache_object *object, loff_t i_size); 278 279 /* request a backing block for a page be read or allocated in the 280 * cache */ 281 fscache_page_retrieval_func_t read_or_alloc_page; 282 283 /* request backing blocks for a list of pages be read or allocated in 284 * the cache */ 285 fscache_pages_retrieval_func_t read_or_alloc_pages; 286 287 /* request a backing block for a page be allocated in the cache so that 288 * it can be written directly */ 289 fscache_page_retrieval_func_t allocate_page; 290 291 /* request backing blocks for pages be allocated in the cache so that 292 * they can be written directly */ 293 fscache_pages_retrieval_func_t allocate_pages; 294 295 /* write a page to its backing block in the cache */ 296 int (*write_page)(struct fscache_storage *op, struct page *page); 297 298 /* detach backing block from a page (optional) 299 * - must release the cookie lock before returning 300 * - may sleep 301 */ 302 void (*uncache_page)(struct fscache_object *object, 303 struct page *page); 304 305 /* dissociate a cache from all the pages it was backing */ 306 void (*dissociate_pages)(struct fscache_cache *cache); 307 308 /* Begin a read operation for the netfs lib */ 309 int (*begin_read_operation)(struct netfs_read_request *rreq, 310 struct fscache_retrieval *op); 311 }; 312 313 extern struct fscache_cookie fscache_fsdef_index; 314 315 /* 316 * Event list for fscache_object::{event_mask,events} 317 */ 318 enum { 319 FSCACHE_OBJECT_EV_NEW_CHILD, /* T if object has a new child */ 320 FSCACHE_OBJECT_EV_PARENT_READY, /* T if object's parent is ready */ 321 FSCACHE_OBJECT_EV_UPDATE, /* T if object should be updated */ 322 FSCACHE_OBJECT_EV_INVALIDATE, /* T if cache requested object invalidation */ 323 FSCACHE_OBJECT_EV_CLEARED, /* T if accessors all gone */ 324 FSCACHE_OBJECT_EV_ERROR, /* T if fatal error occurred during processing */ 325 FSCACHE_OBJECT_EV_KILL, /* T if netfs relinquished or cache withdrew object */ 326 NR_FSCACHE_OBJECT_EVENTS 327 }; 328 329 #define FSCACHE_OBJECT_EVENTS_MASK ((1UL << NR_FSCACHE_OBJECT_EVENTS) - 1) 330 331 /* 332 * States for object state machine. 333 */ 334 struct fscache_transition { 335 unsigned long events; 336 const struct fscache_state *transit_to; 337 }; 338 339 struct fscache_state { 340 char name[24]; 341 char short_name[8]; 342 const struct fscache_state *(*work)(struct fscache_object *object, 343 int event); 344 const struct fscache_transition transitions[]; 345 }; 346 347 /* 348 * on-disk cache file or index handle 349 */ 350 struct fscache_object { 351 const struct fscache_state *state; /* Object state machine state */ 352 const struct fscache_transition *oob_table; /* OOB state transition table */ 353 int debug_id; /* debugging ID */ 354 int n_children; /* number of child objects */ 355 int n_ops; /* number of extant ops on object */ 356 int n_obj_ops; /* number of object ops outstanding on object */ 357 int n_in_progress; /* number of ops in progress */ 358 int n_exclusive; /* number of exclusive ops queued or in progress */ 359 atomic_t n_reads; /* number of read ops in progress */ 360 spinlock_t lock; /* state and operations lock */ 361 362 unsigned long lookup_jif; /* time at which lookup started */ 363 unsigned long oob_event_mask; /* OOB events this object is interested in */ 364 unsigned long event_mask; /* events this object is interested in */ 365 unsigned long events; /* events to be processed by this object 366 * (order is important - using fls) */ 367 368 unsigned long flags; 369 #define FSCACHE_OBJECT_LOCK 0 /* T if object is busy being processed */ 370 #define FSCACHE_OBJECT_PENDING_WRITE 1 /* T if object has pending write */ 371 #define FSCACHE_OBJECT_WAITING 2 /* T if object is waiting on its parent */ 372 #define FSCACHE_OBJECT_IS_LIVE 3 /* T if object is not withdrawn or relinquished */ 373 #define FSCACHE_OBJECT_IS_LOOKED_UP 4 /* T if object has been looked up */ 374 #define FSCACHE_OBJECT_IS_AVAILABLE 5 /* T if object has become active */ 375 #define FSCACHE_OBJECT_RETIRED 6 /* T if object was retired on relinquishment */ 376 #define FSCACHE_OBJECT_KILLED_BY_CACHE 7 /* T if object was killed by the cache */ 377 #define FSCACHE_OBJECT_RUN_AFTER_DEAD 8 /* T if object has been dispatched after death */ 378 379 struct list_head cache_link; /* link in cache->object_list */ 380 struct hlist_node cookie_link; /* link in cookie->backing_objects */ 381 struct fscache_cache *cache; /* cache that supplied this object */ 382 struct fscache_cookie *cookie; /* netfs's file/index object */ 383 struct fscache_object *parent; /* parent object */ 384 struct work_struct work; /* attention scheduling record */ 385 struct list_head dependents; /* FIFO of dependent objects */ 386 struct list_head dep_link; /* link in parent's dependents list */ 387 struct list_head pending_ops; /* unstarted operations on this object */ 388 #ifdef CONFIG_FSCACHE_OBJECT_LIST 389 struct rb_node objlist_link; /* link in global object list */ 390 #endif 391 pgoff_t store_limit; /* current storage limit */ 392 loff_t store_limit_l; /* current storage limit */ 393 }; 394 395 extern void fscache_object_init(struct fscache_object *, struct fscache_cookie *, 396 struct fscache_cache *); 397 extern void fscache_object_destroy(struct fscache_object *); 398 399 extern void fscache_object_lookup_negative(struct fscache_object *object); 400 extern void fscache_obtained_object(struct fscache_object *object); 401 402 static inline bool fscache_object_is_live(struct fscache_object *object) 403 { 404 return test_bit(FSCACHE_OBJECT_IS_LIVE, &object->flags); 405 } 406 407 static inline bool fscache_object_is_dying(struct fscache_object *object) 408 { 409 return !fscache_object_is_live(object); 410 } 411 412 static inline bool fscache_object_is_available(struct fscache_object *object) 413 { 414 return test_bit(FSCACHE_OBJECT_IS_AVAILABLE, &object->flags); 415 } 416 417 static inline bool fscache_cache_is_broken(struct fscache_object *object) 418 { 419 return test_bit(FSCACHE_IOERROR, &object->cache->flags); 420 } 421 422 static inline bool fscache_object_is_active(struct fscache_object *object) 423 { 424 return fscache_object_is_available(object) && 425 fscache_object_is_live(object) && 426 !fscache_cache_is_broken(object); 427 } 428 429 /** 430 * fscache_object_destroyed - Note destruction of an object in a cache 431 * @cache: The cache from which the object came 432 * 433 * Note the destruction and deallocation of an object record in a cache. 434 */ 435 static inline void fscache_object_destroyed(struct fscache_cache *cache) 436 { 437 if (atomic_dec_and_test(&cache->object_count)) 438 wake_up_all(&fscache_cache_cleared_wq); 439 } 440 441 /** 442 * fscache_object_lookup_error - Note an object encountered an error 443 * @object: The object on which the error was encountered 444 * 445 * Note that an object encountered a fatal error (usually an I/O error) and 446 * that it should be withdrawn as soon as possible. 447 */ 448 static inline void fscache_object_lookup_error(struct fscache_object *object) 449 { 450 set_bit(FSCACHE_OBJECT_EV_ERROR, &object->events); 451 } 452 453 /** 454 * fscache_set_store_limit - Set the maximum size to be stored in an object 455 * @object: The object to set the maximum on 456 * @i_size: The limit to set in bytes 457 * 458 * Set the maximum size an object is permitted to reach, implying the highest 459 * byte that may be written. Intended to be called by the attr_changed() op. 460 * 461 * See Documentation/filesystems/caching/backend-api.rst for a complete 462 * description. 463 */ 464 static inline 465 void fscache_set_store_limit(struct fscache_object *object, loff_t i_size) 466 { 467 object->store_limit_l = i_size; 468 object->store_limit = i_size >> PAGE_SHIFT; 469 if (i_size & ~PAGE_MASK) 470 object->store_limit++; 471 } 472 473 /** 474 * fscache_end_io - End a retrieval operation on a page 475 * @op: The FS-Cache operation covering the retrieval 476 * @page: The page that was to be fetched 477 * @error: The error code (0 if successful) 478 * 479 * Note the end of an operation to retrieve a page, as covered by a particular 480 * operation record. 481 */ 482 static inline void fscache_end_io(struct fscache_retrieval *op, 483 struct page *page, int error) 484 { 485 op->end_io_func(page, op->context, error); 486 } 487 488 static inline void __fscache_use_cookie(struct fscache_cookie *cookie) 489 { 490 atomic_inc(&cookie->n_active); 491 } 492 493 /** 494 * fscache_use_cookie - Request usage of cookie attached to an object 495 * @object: Object description 496 * 497 * Request usage of the cookie attached to an object. NULL is returned if the 498 * relinquishment had reduced the cookie usage count to 0. 499 */ 500 static inline bool fscache_use_cookie(struct fscache_object *object) 501 { 502 struct fscache_cookie *cookie = object->cookie; 503 return atomic_inc_not_zero(&cookie->n_active) != 0; 504 } 505 506 static inline bool __fscache_unuse_cookie(struct fscache_cookie *cookie) 507 { 508 return atomic_dec_and_test(&cookie->n_active); 509 } 510 511 static inline void __fscache_wake_unused_cookie(struct fscache_cookie *cookie) 512 { 513 wake_up_var(&cookie->n_active); 514 } 515 516 /** 517 * fscache_unuse_cookie - Cease usage of cookie attached to an object 518 * @object: Object description 519 * 520 * Cease usage of the cookie attached to an object. When the users count 521 * reaches zero then the cookie relinquishment will be permitted to proceed. 522 */ 523 static inline void fscache_unuse_cookie(struct fscache_object *object) 524 { 525 struct fscache_cookie *cookie = object->cookie; 526 if (__fscache_unuse_cookie(cookie)) 527 __fscache_wake_unused_cookie(cookie); 528 } 529 530 /* 531 * out-of-line cache backend functions 532 */ 533 extern __printf(3, 4) 534 void fscache_init_cache(struct fscache_cache *cache, 535 const struct fscache_cache_ops *ops, 536 const char *idfmt, ...); 537 538 extern int fscache_add_cache(struct fscache_cache *cache, 539 struct fscache_object *fsdef, 540 const char *tagname); 541 extern void fscache_withdraw_cache(struct fscache_cache *cache); 542 543 extern void fscache_io_error(struct fscache_cache *cache); 544 545 extern void fscache_mark_page_cached(struct fscache_retrieval *op, 546 struct page *page); 547 548 extern void fscache_mark_pages_cached(struct fscache_retrieval *op, 549 struct pagevec *pagevec); 550 551 extern bool fscache_object_sleep_till_congested(signed long *timeoutp); 552 553 extern enum fscache_checkaux fscache_check_aux(struct fscache_object *object, 554 const void *data, 555 uint16_t datalen, 556 loff_t object_size); 557 558 extern void fscache_object_retrying_stale(struct fscache_object *object); 559 560 enum fscache_why_object_killed { 561 FSCACHE_OBJECT_IS_STALE, 562 FSCACHE_OBJECT_NO_SPACE, 563 FSCACHE_OBJECT_WAS_RETIRED, 564 FSCACHE_OBJECT_WAS_CULLED, 565 }; 566 extern void fscache_object_mark_killed(struct fscache_object *object, 567 enum fscache_why_object_killed why); 568 569 #endif /* _LINUX_FSCACHE_CACHE_H */ 570