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 ([email protected]) 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 309 extern struct fscache_cookie fscache_fsdef_index; 310 311 /* 312 * Event list for fscache_object::{event_mask,events} 313 */ 314 enum { 315 FSCACHE_OBJECT_EV_NEW_CHILD, /* T if object has a new child */ 316 FSCACHE_OBJECT_EV_PARENT_READY, /* T if object's parent is ready */ 317 FSCACHE_OBJECT_EV_UPDATE, /* T if object should be updated */ 318 FSCACHE_OBJECT_EV_INVALIDATE, /* T if cache requested object invalidation */ 319 FSCACHE_OBJECT_EV_CLEARED, /* T if accessors all gone */ 320 FSCACHE_OBJECT_EV_ERROR, /* T if fatal error occurred during processing */ 321 FSCACHE_OBJECT_EV_KILL, /* T if netfs relinquished or cache withdrew object */ 322 NR_FSCACHE_OBJECT_EVENTS 323 }; 324 325 #define FSCACHE_OBJECT_EVENTS_MASK ((1UL << NR_FSCACHE_OBJECT_EVENTS) - 1) 326 327 /* 328 * States for object state machine. 329 */ 330 struct fscache_transition { 331 unsigned long events; 332 const struct fscache_state *transit_to; 333 }; 334 335 struct fscache_state { 336 char name[24]; 337 char short_name[8]; 338 const struct fscache_state *(*work)(struct fscache_object *object, 339 int event); 340 const struct fscache_transition transitions[]; 341 }; 342 343 /* 344 * on-disk cache file or index handle 345 */ 346 struct fscache_object { 347 const struct fscache_state *state; /* Object state machine state */ 348 const struct fscache_transition *oob_table; /* OOB state transition table */ 349 int debug_id; /* debugging ID */ 350 int n_children; /* number of child objects */ 351 int n_ops; /* number of extant ops on object */ 352 int n_obj_ops; /* number of object ops outstanding on object */ 353 int n_in_progress; /* number of ops in progress */ 354 int n_exclusive; /* number of exclusive ops queued or in progress */ 355 atomic_t n_reads; /* number of read ops in progress */ 356 spinlock_t lock; /* state and operations lock */ 357 358 unsigned long lookup_jif; /* time at which lookup started */ 359 unsigned long oob_event_mask; /* OOB events this object is interested in */ 360 unsigned long event_mask; /* events this object is interested in */ 361 unsigned long events; /* events to be processed by this object 362 * (order is important - using fls) */ 363 364 unsigned long flags; 365 #define FSCACHE_OBJECT_LOCK 0 /* T if object is busy being processed */ 366 #define FSCACHE_OBJECT_PENDING_WRITE 1 /* T if object has pending write */ 367 #define FSCACHE_OBJECT_WAITING 2 /* T if object is waiting on its parent */ 368 #define FSCACHE_OBJECT_IS_LIVE 3 /* T if object is not withdrawn or relinquished */ 369 #define FSCACHE_OBJECT_IS_LOOKED_UP 4 /* T if object has been looked up */ 370 #define FSCACHE_OBJECT_IS_AVAILABLE 5 /* T if object has become active */ 371 #define FSCACHE_OBJECT_RETIRED 6 /* T if object was retired on relinquishment */ 372 #define FSCACHE_OBJECT_KILLED_BY_CACHE 7 /* T if object was killed by the cache */ 373 #define FSCACHE_OBJECT_RUN_AFTER_DEAD 8 /* T if object has been dispatched after death */ 374 375 struct list_head cache_link; /* link in cache->object_list */ 376 struct hlist_node cookie_link; /* link in cookie->backing_objects */ 377 struct fscache_cache *cache; /* cache that supplied this object */ 378 struct fscache_cookie *cookie; /* netfs's file/index object */ 379 struct fscache_object *parent; /* parent object */ 380 struct work_struct work; /* attention scheduling record */ 381 struct list_head dependents; /* FIFO of dependent objects */ 382 struct list_head dep_link; /* link in parent's dependents list */ 383 struct list_head pending_ops; /* unstarted operations on this object */ 384 #ifdef CONFIG_FSCACHE_OBJECT_LIST 385 struct rb_node objlist_link; /* link in global object list */ 386 #endif 387 pgoff_t store_limit; /* current storage limit */ 388 loff_t store_limit_l; /* current storage limit */ 389 }; 390 391 extern void fscache_object_init(struct fscache_object *, struct fscache_cookie *, 392 struct fscache_cache *); 393 extern void fscache_object_destroy(struct fscache_object *); 394 395 extern void fscache_object_lookup_negative(struct fscache_object *object); 396 extern void fscache_obtained_object(struct fscache_object *object); 397 398 static inline bool fscache_object_is_live(struct fscache_object *object) 399 { 400 return test_bit(FSCACHE_OBJECT_IS_LIVE, &object->flags); 401 } 402 403 static inline bool fscache_object_is_dying(struct fscache_object *object) 404 { 405 return !fscache_object_is_live(object); 406 } 407 408 static inline bool fscache_object_is_available(struct fscache_object *object) 409 { 410 return test_bit(FSCACHE_OBJECT_IS_AVAILABLE, &object->flags); 411 } 412 413 static inline bool fscache_cache_is_broken(struct fscache_object *object) 414 { 415 return test_bit(FSCACHE_IOERROR, &object->cache->flags); 416 } 417 418 static inline bool fscache_object_is_active(struct fscache_object *object) 419 { 420 return fscache_object_is_available(object) && 421 fscache_object_is_live(object) && 422 !fscache_cache_is_broken(object); 423 } 424 425 /** 426 * fscache_object_destroyed - Note destruction of an object in a cache 427 * @cache: The cache from which the object came 428 * 429 * Note the destruction and deallocation of an object record in a cache. 430 */ 431 static inline void fscache_object_destroyed(struct fscache_cache *cache) 432 { 433 if (atomic_dec_and_test(&cache->object_count)) 434 wake_up_all(&fscache_cache_cleared_wq); 435 } 436 437 /** 438 * fscache_object_lookup_error - Note an object encountered an error 439 * @object: The object on which the error was encountered 440 * 441 * Note that an object encountered a fatal error (usually an I/O error) and 442 * that it should be withdrawn as soon as possible. 443 */ 444 static inline void fscache_object_lookup_error(struct fscache_object *object) 445 { 446 set_bit(FSCACHE_OBJECT_EV_ERROR, &object->events); 447 } 448 449 /** 450 * fscache_set_store_limit - Set the maximum size to be stored in an object 451 * @object: The object to set the maximum on 452 * @i_size: The limit to set in bytes 453 * 454 * Set the maximum size an object is permitted to reach, implying the highest 455 * byte that may be written. Intended to be called by the attr_changed() op. 456 * 457 * See Documentation/filesystems/caching/backend-api.rst for a complete 458 * description. 459 */ 460 static inline 461 void fscache_set_store_limit(struct fscache_object *object, loff_t i_size) 462 { 463 object->store_limit_l = i_size; 464 object->store_limit = i_size >> PAGE_SHIFT; 465 if (i_size & ~PAGE_MASK) 466 object->store_limit++; 467 } 468 469 /** 470 * fscache_end_io - End a retrieval operation on a page 471 * @op: The FS-Cache operation covering the retrieval 472 * @page: The page that was to be fetched 473 * @error: The error code (0 if successful) 474 * 475 * Note the end of an operation to retrieve a page, as covered by a particular 476 * operation record. 477 */ 478 static inline void fscache_end_io(struct fscache_retrieval *op, 479 struct page *page, int error) 480 { 481 op->end_io_func(page, op->context, error); 482 } 483 484 static inline void __fscache_use_cookie(struct fscache_cookie *cookie) 485 { 486 atomic_inc(&cookie->n_active); 487 } 488 489 /** 490 * fscache_use_cookie - Request usage of cookie attached to an object 491 * @object: Object description 492 * 493 * Request usage of the cookie attached to an object. NULL is returned if the 494 * relinquishment had reduced the cookie usage count to 0. 495 */ 496 static inline bool fscache_use_cookie(struct fscache_object *object) 497 { 498 struct fscache_cookie *cookie = object->cookie; 499 return atomic_inc_not_zero(&cookie->n_active) != 0; 500 } 501 502 static inline bool __fscache_unuse_cookie(struct fscache_cookie *cookie) 503 { 504 return atomic_dec_and_test(&cookie->n_active); 505 } 506 507 static inline void __fscache_wake_unused_cookie(struct fscache_cookie *cookie) 508 { 509 wake_up_var(&cookie->n_active); 510 } 511 512 /** 513 * fscache_unuse_cookie - Cease usage of cookie attached to an object 514 * @object: Object description 515 * 516 * Cease usage of the cookie attached to an object. When the users count 517 * reaches zero then the cookie relinquishment will be permitted to proceed. 518 */ 519 static inline void fscache_unuse_cookie(struct fscache_object *object) 520 { 521 struct fscache_cookie *cookie = object->cookie; 522 if (__fscache_unuse_cookie(cookie)) 523 __fscache_wake_unused_cookie(cookie); 524 } 525 526 /* 527 * out-of-line cache backend functions 528 */ 529 extern __printf(3, 4) 530 void fscache_init_cache(struct fscache_cache *cache, 531 const struct fscache_cache_ops *ops, 532 const char *idfmt, ...); 533 534 extern int fscache_add_cache(struct fscache_cache *cache, 535 struct fscache_object *fsdef, 536 const char *tagname); 537 extern void fscache_withdraw_cache(struct fscache_cache *cache); 538 539 extern void fscache_io_error(struct fscache_cache *cache); 540 541 extern void fscache_mark_page_cached(struct fscache_retrieval *op, 542 struct page *page); 543 544 extern void fscache_mark_pages_cached(struct fscache_retrieval *op, 545 struct pagevec *pagevec); 546 547 extern bool fscache_object_sleep_till_congested(signed long *timeoutp); 548 549 extern enum fscache_checkaux fscache_check_aux(struct fscache_object *object, 550 const void *data, 551 uint16_t datalen, 552 loff_t object_size); 553 554 extern void fscache_object_retrying_stale(struct fscache_object *object); 555 556 enum fscache_why_object_killed { 557 FSCACHE_OBJECT_IS_STALE, 558 FSCACHE_OBJECT_NO_SPACE, 559 FSCACHE_OBJECT_WAS_RETIRED, 560 FSCACHE_OBJECT_WAS_CULLED, 561 }; 562 extern void fscache_object_mark_killed(struct fscache_object *object, 563 enum fscache_why_object_killed why); 564 565 #endif /* _LINUX_FSCACHE_CACHE_H */ 566