fscache-cache.h 19 KB

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