fscache.h 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695
  1. /* SPDX-License-Identifier: GPL-2.0-or-later */
  2. /* General filesystem caching interface
  3. *
  4. * Copyright (C) 2021 Red Hat, Inc. All Rights Reserved.
  5. * Written by David Howells ([email protected])
  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. #ifndef _LINUX_FSCACHE_H
  14. #define _LINUX_FSCACHE_H
  15. #include <linux/fs.h>
  16. #include <linux/netfs.h>
  17. #include <linux/writeback.h>
  18. #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
  19. #define __fscache_available (1)
  20. #define fscache_available() (1)
  21. #define fscache_volume_valid(volume) (volume)
  22. #define fscache_cookie_valid(cookie) (cookie)
  23. #define fscache_resources_valid(cres) ((cres)->cache_priv)
  24. #define fscache_cookie_enabled(cookie) (cookie && !test_bit(FSCACHE_COOKIE_DISABLED, &cookie->flags))
  25. #else
  26. #define __fscache_available (0)
  27. #define fscache_available() (0)
  28. #define fscache_volume_valid(volume) (0)
  29. #define fscache_cookie_valid(cookie) (0)
  30. #define fscache_resources_valid(cres) (false)
  31. #define fscache_cookie_enabled(cookie) (0)
  32. #endif
  33. struct fscache_cookie;
  34. #define FSCACHE_ADV_SINGLE_CHUNK 0x01 /* The object is a single chunk of data */
  35. #define FSCACHE_ADV_WRITE_CACHE 0x00 /* Do cache if written to locally */
  36. #define FSCACHE_ADV_WRITE_NOCACHE 0x02 /* Don't cache if written to locally */
  37. #define FSCACHE_ADV_WANT_CACHE_SIZE 0x04 /* Retrieve cache size at runtime */
  38. #define FSCACHE_INVAL_DIO_WRITE 0x01 /* Invalidate due to DIO write */
  39. enum fscache_want_state {
  40. FSCACHE_WANT_PARAMS,
  41. FSCACHE_WANT_WRITE,
  42. FSCACHE_WANT_READ,
  43. };
  44. /*
  45. * Data object state.
  46. */
  47. enum fscache_cookie_state {
  48. FSCACHE_COOKIE_STATE_QUIESCENT, /* The cookie is uncached */
  49. FSCACHE_COOKIE_STATE_LOOKING_UP, /* The cache object is being looked up */
  50. FSCACHE_COOKIE_STATE_CREATING, /* The cache object is being created */
  51. FSCACHE_COOKIE_STATE_ACTIVE, /* The cache is active, readable and writable */
  52. FSCACHE_COOKIE_STATE_INVALIDATING, /* The cache is being invalidated */
  53. FSCACHE_COOKIE_STATE_FAILED, /* The cache failed, withdraw to clear */
  54. FSCACHE_COOKIE_STATE_LRU_DISCARDING, /* The cookie is being discarded by the LRU */
  55. FSCACHE_COOKIE_STATE_WITHDRAWING, /* The cookie is being withdrawn */
  56. FSCACHE_COOKIE_STATE_RELINQUISHING, /* The cookie is being relinquished */
  57. FSCACHE_COOKIE_STATE_DROPPED, /* The cookie has been dropped */
  58. #define FSCACHE_COOKIE_STATE__NR (FSCACHE_COOKIE_STATE_DROPPED + 1)
  59. } __attribute__((mode(byte)));
  60. /*
  61. * Volume representation cookie.
  62. */
  63. struct fscache_volume {
  64. refcount_t ref;
  65. atomic_t n_cookies; /* Number of data cookies in volume */
  66. atomic_t n_accesses; /* Number of cache accesses in progress */
  67. unsigned int debug_id;
  68. unsigned int key_hash; /* Hash of key string */
  69. u8 *key; /* Volume ID, eg. "[email protected]@1234" */
  70. struct list_head proc_link; /* Link in /proc/fs/fscache/volumes */
  71. struct hlist_bl_node hash_link; /* Link in hash table */
  72. struct work_struct work;
  73. struct fscache_cache *cache; /* The cache in which this resides */
  74. void *cache_priv; /* Cache private data */
  75. spinlock_t lock;
  76. unsigned long flags;
  77. #define FSCACHE_VOLUME_RELINQUISHED 0 /* Volume is being cleaned up */
  78. #define FSCACHE_VOLUME_INVALIDATE 1 /* Volume was invalidated */
  79. #define FSCACHE_VOLUME_COLLIDED_WITH 2 /* Volume was collided with */
  80. #define FSCACHE_VOLUME_ACQUIRE_PENDING 3 /* Volume is waiting to complete acquisition */
  81. #define FSCACHE_VOLUME_CREATING 4 /* Volume is being created on disk */
  82. u8 coherency_len; /* Length of the coherency data */
  83. u8 coherency[]; /* Coherency data */
  84. };
  85. /*
  86. * Data file representation cookie.
  87. * - a file will only appear in one cache
  88. * - a request to cache a file may or may not be honoured, subject to
  89. * constraints such as disk space
  90. * - indices are created on disk just-in-time
  91. */
  92. struct fscache_cookie {
  93. refcount_t ref;
  94. atomic_t n_active; /* number of active users of cookie */
  95. atomic_t n_accesses; /* Number of cache accesses in progress */
  96. unsigned int debug_id;
  97. unsigned int inval_counter; /* Number of invalidations made */
  98. spinlock_t lock;
  99. struct fscache_volume *volume; /* Parent volume of this file. */
  100. void *cache_priv; /* Cache-side representation */
  101. struct hlist_bl_node hash_link; /* Link in hash table */
  102. struct list_head proc_link; /* Link in proc list */
  103. struct list_head commit_link; /* Link in commit queue */
  104. struct work_struct work; /* Commit/relinq/withdraw work */
  105. loff_t object_size; /* Size of the netfs object */
  106. unsigned long unused_at; /* Time at which unused (jiffies) */
  107. unsigned long flags;
  108. #define FSCACHE_COOKIE_RELINQUISHED 0 /* T if cookie has been relinquished */
  109. #define FSCACHE_COOKIE_RETIRED 1 /* T if this cookie has retired on relinq */
  110. #define FSCACHE_COOKIE_IS_CACHING 2 /* T if this cookie is cached */
  111. #define FSCACHE_COOKIE_NO_DATA_TO_READ 3 /* T if this cookie has nothing to read */
  112. #define FSCACHE_COOKIE_NEEDS_UPDATE 4 /* T if attrs have been updated */
  113. #define FSCACHE_COOKIE_HAS_BEEN_CACHED 5 /* T if cookie needs withdraw-on-relinq */
  114. #define FSCACHE_COOKIE_DISABLED 6 /* T if cookie has been disabled */
  115. #define FSCACHE_COOKIE_LOCAL_WRITE 7 /* T if cookie has been modified locally */
  116. #define FSCACHE_COOKIE_NO_ACCESS_WAKE 8 /* T if no wake when n_accesses goes 0 */
  117. #define FSCACHE_COOKIE_DO_RELINQUISH 9 /* T if this cookie needs relinquishment */
  118. #define FSCACHE_COOKIE_DO_WITHDRAW 10 /* T if this cookie needs withdrawing */
  119. #define FSCACHE_COOKIE_DO_LRU_DISCARD 11 /* T if this cookie needs LRU discard */
  120. #define FSCACHE_COOKIE_DO_PREP_TO_WRITE 12 /* T if cookie needs write preparation */
  121. #define FSCACHE_COOKIE_HAVE_DATA 13 /* T if this cookie has data stored */
  122. #define FSCACHE_COOKIE_IS_HASHED 14 /* T if this cookie is hashed */
  123. #define FSCACHE_COOKIE_DO_INVALIDATE 15 /* T if cookie needs invalidation */
  124. enum fscache_cookie_state state;
  125. u8 advice; /* FSCACHE_ADV_* */
  126. u8 key_len; /* Length of index key */
  127. u8 aux_len; /* Length of auxiliary data */
  128. u32 key_hash; /* Hash of volume, key, len */
  129. union {
  130. void *key; /* Index key */
  131. u8 inline_key[16]; /* - If the key is short enough */
  132. };
  133. union {
  134. void *aux; /* Auxiliary data */
  135. u8 inline_aux[8]; /* - If the aux data is short enough */
  136. };
  137. };
  138. /*
  139. * slow-path functions for when there is actually caching available, and the
  140. * netfs does actually have a valid token
  141. * - these are not to be called directly
  142. * - these are undefined symbols when FS-Cache is not configured and the
  143. * optimiser takes care of not using them
  144. */
  145. extern struct fscache_volume *__fscache_acquire_volume(const char *, const char *,
  146. const void *, size_t);
  147. extern void __fscache_relinquish_volume(struct fscache_volume *, const void *, bool);
  148. extern struct fscache_cookie *__fscache_acquire_cookie(
  149. struct fscache_volume *,
  150. u8,
  151. const void *, size_t,
  152. const void *, size_t,
  153. loff_t);
  154. extern void __fscache_use_cookie(struct fscache_cookie *, bool);
  155. extern void __fscache_unuse_cookie(struct fscache_cookie *, const void *, const loff_t *);
  156. extern void __fscache_relinquish_cookie(struct fscache_cookie *, bool);
  157. extern void __fscache_resize_cookie(struct fscache_cookie *, loff_t);
  158. extern void __fscache_invalidate(struct fscache_cookie *, const void *, loff_t, unsigned int);
  159. extern int __fscache_begin_read_operation(struct netfs_cache_resources *, struct fscache_cookie *);
  160. extern int __fscache_begin_write_operation(struct netfs_cache_resources *, struct fscache_cookie *);
  161. extern void __fscache_write_to_cache(struct fscache_cookie *, struct address_space *,
  162. loff_t, size_t, loff_t, netfs_io_terminated_t, void *,
  163. bool);
  164. extern void __fscache_clear_page_bits(struct address_space *, loff_t, size_t);
  165. /**
  166. * fscache_acquire_volume - Register a volume as desiring caching services
  167. * @volume_key: An identification string for the volume
  168. * @cache_name: The name of the cache to use (or NULL for the default)
  169. * @coherency_data: Piece of arbitrary coherency data to check (or NULL)
  170. * @coherency_len: The size of the coherency data
  171. *
  172. * Register a volume as desiring caching services if they're available. The
  173. * caller must provide an identifier for the volume and may also indicate which
  174. * cache it should be in. If a preexisting volume entry is found in the cache,
  175. * the coherency data must match otherwise the entry will be invalidated.
  176. *
  177. * Returns a cookie pointer on success, -ENOMEM if out of memory or -EBUSY if a
  178. * cache volume of that name is already acquired. Note that "NULL" is a valid
  179. * cookie pointer and can be returned if caching is refused.
  180. */
  181. static inline
  182. struct fscache_volume *fscache_acquire_volume(const char *volume_key,
  183. const char *cache_name,
  184. const void *coherency_data,
  185. size_t coherency_len)
  186. {
  187. if (!fscache_available())
  188. return NULL;
  189. return __fscache_acquire_volume(volume_key, cache_name,
  190. coherency_data, coherency_len);
  191. }
  192. /**
  193. * fscache_relinquish_volume - Cease caching a volume
  194. * @volume: The volume cookie
  195. * @coherency_data: Piece of arbitrary coherency data to set (or NULL)
  196. * @invalidate: True if the volume should be invalidated
  197. *
  198. * Indicate that a filesystem no longer desires caching services for a volume.
  199. * The caller must have relinquished all file cookies prior to calling this.
  200. * The stored coherency data is updated.
  201. */
  202. static inline
  203. void fscache_relinquish_volume(struct fscache_volume *volume,
  204. const void *coherency_data,
  205. bool invalidate)
  206. {
  207. if (fscache_volume_valid(volume))
  208. __fscache_relinquish_volume(volume, coherency_data, invalidate);
  209. }
  210. /**
  211. * fscache_acquire_cookie - Acquire a cookie to represent a cache object
  212. * @volume: The volume in which to locate/create this cookie
  213. * @advice: Advice flags (FSCACHE_COOKIE_ADV_*)
  214. * @index_key: The index key for this cookie
  215. * @index_key_len: Size of the index key
  216. * @aux_data: The auxiliary data for the cookie (may be NULL)
  217. * @aux_data_len: Size of the auxiliary data buffer
  218. * @object_size: The initial size of object
  219. *
  220. * Acquire a cookie to represent a data file within the given cache volume.
  221. *
  222. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  223. * description.
  224. */
  225. static inline
  226. struct fscache_cookie *fscache_acquire_cookie(struct fscache_volume *volume,
  227. u8 advice,
  228. const void *index_key,
  229. size_t index_key_len,
  230. const void *aux_data,
  231. size_t aux_data_len,
  232. loff_t object_size)
  233. {
  234. if (!fscache_volume_valid(volume))
  235. return NULL;
  236. return __fscache_acquire_cookie(volume, advice,
  237. index_key, index_key_len,
  238. aux_data, aux_data_len,
  239. object_size);
  240. }
  241. /**
  242. * fscache_use_cookie - Request usage of cookie attached to an object
  243. * @cookie: The cookie representing the cache object
  244. * @will_modify: If cache is expected to be modified locally
  245. *
  246. * Request usage of the cookie attached to an object. The caller should tell
  247. * the cache if the object's contents are about to be modified locally and then
  248. * the cache can apply the policy that has been set to handle this case.
  249. */
  250. static inline void fscache_use_cookie(struct fscache_cookie *cookie,
  251. bool will_modify)
  252. {
  253. if (fscache_cookie_valid(cookie))
  254. __fscache_use_cookie(cookie, will_modify);
  255. }
  256. /**
  257. * fscache_unuse_cookie - Cease usage of cookie attached to an object
  258. * @cookie: The cookie representing the cache object
  259. * @aux_data: Updated auxiliary data (or NULL)
  260. * @object_size: Revised size of the object (or NULL)
  261. *
  262. * Cease usage of the cookie attached to an object. When the users count
  263. * reaches zero then the cookie relinquishment will be permitted to proceed.
  264. */
  265. static inline void fscache_unuse_cookie(struct fscache_cookie *cookie,
  266. const void *aux_data,
  267. const loff_t *object_size)
  268. {
  269. if (fscache_cookie_valid(cookie))
  270. __fscache_unuse_cookie(cookie, aux_data, object_size);
  271. }
  272. /**
  273. * fscache_relinquish_cookie - Return the cookie to the cache, maybe discarding
  274. * it
  275. * @cookie: The cookie being returned
  276. * @retire: True if the cache object the cookie represents is to be discarded
  277. *
  278. * This function returns a cookie to the cache, forcibly discarding the
  279. * associated cache object if retire is set to true.
  280. *
  281. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  282. * description.
  283. */
  284. static inline
  285. void fscache_relinquish_cookie(struct fscache_cookie *cookie, bool retire)
  286. {
  287. if (fscache_cookie_valid(cookie))
  288. __fscache_relinquish_cookie(cookie, retire);
  289. }
  290. /*
  291. * Find the auxiliary data on a cookie.
  292. */
  293. static inline void *fscache_get_aux(struct fscache_cookie *cookie)
  294. {
  295. if (cookie->aux_len <= sizeof(cookie->inline_aux))
  296. return cookie->inline_aux;
  297. else
  298. return cookie->aux;
  299. }
  300. /*
  301. * Update the auxiliary data on a cookie.
  302. */
  303. static inline
  304. void fscache_update_aux(struct fscache_cookie *cookie,
  305. const void *aux_data, const loff_t *object_size)
  306. {
  307. void *p = fscache_get_aux(cookie);
  308. if (aux_data && p)
  309. memcpy(p, aux_data, cookie->aux_len);
  310. if (object_size)
  311. cookie->object_size = *object_size;
  312. }
  313. #ifdef CONFIG_FSCACHE_STATS
  314. extern atomic_t fscache_n_updates;
  315. #endif
  316. static inline
  317. void __fscache_update_cookie(struct fscache_cookie *cookie, const void *aux_data,
  318. const loff_t *object_size)
  319. {
  320. #ifdef CONFIG_FSCACHE_STATS
  321. atomic_inc(&fscache_n_updates);
  322. #endif
  323. fscache_update_aux(cookie, aux_data, object_size);
  324. smp_wmb();
  325. set_bit(FSCACHE_COOKIE_NEEDS_UPDATE, &cookie->flags);
  326. }
  327. /**
  328. * fscache_update_cookie - Request that a cache object be updated
  329. * @cookie: The cookie representing the cache object
  330. * @aux_data: The updated auxiliary data for the cookie (may be NULL)
  331. * @object_size: The current size of the object (may be NULL)
  332. *
  333. * Request an update of the index data for the cache object associated with the
  334. * cookie. The auxiliary data on the cookie will be updated first if @aux_data
  335. * is set and the object size will be updated and the object possibly trimmed
  336. * if @object_size is set.
  337. *
  338. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  339. * description.
  340. */
  341. static inline
  342. void fscache_update_cookie(struct fscache_cookie *cookie, const void *aux_data,
  343. const loff_t *object_size)
  344. {
  345. if (fscache_cookie_enabled(cookie))
  346. __fscache_update_cookie(cookie, aux_data, object_size);
  347. }
  348. /**
  349. * fscache_resize_cookie - Request that a cache object be resized
  350. * @cookie: The cookie representing the cache object
  351. * @new_size: The new size of the object (may be NULL)
  352. *
  353. * Request that the size of an object be changed.
  354. *
  355. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  356. * description.
  357. */
  358. static inline
  359. void fscache_resize_cookie(struct fscache_cookie *cookie, loff_t new_size)
  360. {
  361. if (fscache_cookie_enabled(cookie))
  362. __fscache_resize_cookie(cookie, new_size);
  363. }
  364. /**
  365. * fscache_invalidate - Notify cache that an object needs invalidation
  366. * @cookie: The cookie representing the cache object
  367. * @aux_data: The updated auxiliary data for the cookie (may be NULL)
  368. * @size: The revised size of the object.
  369. * @flags: Invalidation flags (FSCACHE_INVAL_*)
  370. *
  371. * Notify the cache that an object is needs to be invalidated and that it
  372. * should abort any retrievals or stores it is doing on the cache. This
  373. * increments inval_counter on the cookie which can be used by the caller to
  374. * reconsider I/O requests as they complete.
  375. *
  376. * If @flags has FSCACHE_INVAL_DIO_WRITE set, this indicates that this is due
  377. * to a direct I/O write and will cause caching to be disabled on this cookie
  378. * until it is completely unused.
  379. *
  380. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  381. * description.
  382. */
  383. static inline
  384. void fscache_invalidate(struct fscache_cookie *cookie,
  385. const void *aux_data, loff_t size, unsigned int flags)
  386. {
  387. if (fscache_cookie_enabled(cookie))
  388. __fscache_invalidate(cookie, aux_data, size, flags);
  389. }
  390. /**
  391. * fscache_operation_valid - Return true if operations resources are usable
  392. * @cres: The resources to check.
  393. *
  394. * Returns a pointer to the operations table if usable or NULL if not.
  395. */
  396. static inline
  397. const struct netfs_cache_ops *fscache_operation_valid(const struct netfs_cache_resources *cres)
  398. {
  399. return fscache_resources_valid(cres) ? cres->ops : NULL;
  400. }
  401. /**
  402. * fscache_begin_read_operation - Begin a read operation for the netfs lib
  403. * @cres: The cache resources for the read being performed
  404. * @cookie: The cookie representing the cache object
  405. *
  406. * Begin a read operation on behalf of the netfs helper library. @cres
  407. * indicates the cache resources to which the operation state should be
  408. * attached; @cookie indicates the cache object that will be accessed.
  409. *
  410. * This is intended to be called from the ->begin_cache_operation() netfs lib
  411. * operation as implemented by the network filesystem.
  412. *
  413. * @cres->inval_counter is set from @cookie->inval_counter for comparison at
  414. * the end of the operation. This allows invalidation during the operation to
  415. * be detected by the caller.
  416. *
  417. * Returns:
  418. * * 0 - Success
  419. * * -ENOBUFS - No caching available
  420. * * Other error code from the cache, such as -ENOMEM.
  421. */
  422. static inline
  423. int fscache_begin_read_operation(struct netfs_cache_resources *cres,
  424. struct fscache_cookie *cookie)
  425. {
  426. if (fscache_cookie_enabled(cookie))
  427. return __fscache_begin_read_operation(cres, cookie);
  428. return -ENOBUFS;
  429. }
  430. /**
  431. * fscache_end_operation - End the read operation for the netfs lib
  432. * @cres: The cache resources for the read operation
  433. *
  434. * Clean up the resources at the end of the read request.
  435. */
  436. static inline void fscache_end_operation(struct netfs_cache_resources *cres)
  437. {
  438. const struct netfs_cache_ops *ops = fscache_operation_valid(cres);
  439. if (ops)
  440. ops->end_operation(cres);
  441. }
  442. /**
  443. * fscache_read - Start a read from the cache.
  444. * @cres: The cache resources to use
  445. * @start_pos: The beginning file offset in the cache file
  446. * @iter: The buffer to fill - and also the length
  447. * @read_hole: How to handle a hole in the data.
  448. * @term_func: The function to call upon completion
  449. * @term_func_priv: The private data for @term_func
  450. *
  451. * Start a read from the cache. @cres indicates the cache object to read from
  452. * and must be obtained by a call to fscache_begin_operation() beforehand.
  453. *
  454. * The data is read into the iterator, @iter, and that also indicates the size
  455. * of the operation. @start_pos is the start position in the file, though if
  456. * @seek_data is set appropriately, the cache can use SEEK_DATA to find the
  457. * next piece of data, writing zeros for the hole into the iterator.
  458. *
  459. * Upon termination of the operation, @term_func will be called and supplied
  460. * with @term_func_priv plus the amount of data written, if successful, or the
  461. * error code otherwise.
  462. *
  463. * @read_hole indicates how a partially populated region in the cache should be
  464. * handled. It can be one of a number of settings:
  465. *
  466. * NETFS_READ_HOLE_IGNORE - Just try to read (may return a short read).
  467. *
  468. * NETFS_READ_HOLE_CLEAR - Seek for data, clearing the part of the buffer
  469. * skipped over, then do as for IGNORE.
  470. *
  471. * NETFS_READ_HOLE_FAIL - Give ENODATA if we encounter a hole.
  472. */
  473. static inline
  474. int fscache_read(struct netfs_cache_resources *cres,
  475. loff_t start_pos,
  476. struct iov_iter *iter,
  477. enum netfs_read_from_hole read_hole,
  478. netfs_io_terminated_t term_func,
  479. void *term_func_priv)
  480. {
  481. const struct netfs_cache_ops *ops = fscache_operation_valid(cres);
  482. return ops->read(cres, start_pos, iter, read_hole,
  483. term_func, term_func_priv);
  484. }
  485. /**
  486. * fscache_begin_write_operation - Begin a write operation for the netfs lib
  487. * @cres: The cache resources for the write being performed
  488. * @cookie: The cookie representing the cache object
  489. *
  490. * Begin a write operation on behalf of the netfs helper library. @cres
  491. * indicates the cache resources to which the operation state should be
  492. * attached; @cookie indicates the cache object that will be accessed.
  493. *
  494. * @cres->inval_counter is set from @cookie->inval_counter for comparison at
  495. * the end of the operation. This allows invalidation during the operation to
  496. * be detected by the caller.
  497. *
  498. * Returns:
  499. * * 0 - Success
  500. * * -ENOBUFS - No caching available
  501. * * Other error code from the cache, such as -ENOMEM.
  502. */
  503. static inline
  504. int fscache_begin_write_operation(struct netfs_cache_resources *cres,
  505. struct fscache_cookie *cookie)
  506. {
  507. if (fscache_cookie_enabled(cookie))
  508. return __fscache_begin_write_operation(cres, cookie);
  509. return -ENOBUFS;
  510. }
  511. /**
  512. * fscache_write - Start a write to the cache.
  513. * @cres: The cache resources to use
  514. * @start_pos: The beginning file offset in the cache file
  515. * @iter: The data to write - and also the length
  516. * @term_func: The function to call upon completion
  517. * @term_func_priv: The private data for @term_func
  518. *
  519. * Start a write to the cache. @cres indicates the cache object to write to and
  520. * must be obtained by a call to fscache_begin_operation() beforehand.
  521. *
  522. * The data to be written is obtained from the iterator, @iter, and that also
  523. * indicates the size of the operation. @start_pos is the start position in
  524. * the file.
  525. *
  526. * Upon termination of the operation, @term_func will be called and supplied
  527. * with @term_func_priv plus the amount of data written, if successful, or the
  528. * error code otherwise.
  529. */
  530. static inline
  531. int fscache_write(struct netfs_cache_resources *cres,
  532. loff_t start_pos,
  533. struct iov_iter *iter,
  534. netfs_io_terminated_t term_func,
  535. void *term_func_priv)
  536. {
  537. const struct netfs_cache_ops *ops = fscache_operation_valid(cres);
  538. return ops->write(cres, start_pos, iter, term_func, term_func_priv);
  539. }
  540. /**
  541. * fscache_clear_page_bits - Clear the PG_fscache bits from a set of pages
  542. * @mapping: The netfs inode to use as the source
  543. * @start: The start position in @mapping
  544. * @len: The amount of data to unlock
  545. * @caching: If PG_fscache has been set
  546. *
  547. * Clear the PG_fscache flag from a sequence of pages and wake up anyone who's
  548. * waiting.
  549. */
  550. static inline void fscache_clear_page_bits(struct address_space *mapping,
  551. loff_t start, size_t len,
  552. bool caching)
  553. {
  554. if (caching)
  555. __fscache_clear_page_bits(mapping, start, len);
  556. }
  557. /**
  558. * fscache_write_to_cache - Save a write to the cache and clear PG_fscache
  559. * @cookie: The cookie representing the cache object
  560. * @mapping: The netfs inode to use as the source
  561. * @start: The start position in @mapping
  562. * @len: The amount of data to write back
  563. * @i_size: The new size of the inode
  564. * @term_func: The function to call upon completion
  565. * @term_func_priv: The private data for @term_func
  566. * @caching: If PG_fscache has been set
  567. *
  568. * Helper function for a netfs to write dirty data from an inode into the cache
  569. * object that's backing it.
  570. *
  571. * @start and @len describe the range of the data. This does not need to be
  572. * page-aligned, but to satisfy DIO requirements, the cache may expand it up to
  573. * the page boundaries on either end. All the pages covering the range must be
  574. * marked with PG_fscache.
  575. *
  576. * If given, @term_func will be called upon completion and supplied with
  577. * @term_func_priv. Note that the PG_fscache flags will have been cleared by
  578. * this point, so the netfs must retain its own pin on the mapping.
  579. */
  580. static inline void fscache_write_to_cache(struct fscache_cookie *cookie,
  581. struct address_space *mapping,
  582. loff_t start, size_t len, loff_t i_size,
  583. netfs_io_terminated_t term_func,
  584. void *term_func_priv,
  585. bool caching)
  586. {
  587. if (caching)
  588. __fscache_write_to_cache(cookie, mapping, start, len, i_size,
  589. term_func, term_func_priv, caching);
  590. else if (term_func)
  591. term_func(term_func_priv, -ENOBUFS, false);
  592. }
  593. #if __fscache_available
  594. bool fscache_dirty_folio(struct address_space *mapping, struct folio *folio,
  595. struct fscache_cookie *cookie);
  596. #else
  597. #define fscache_dirty_folio(MAPPING, FOLIO, COOKIE) \
  598. filemap_dirty_folio(MAPPING, FOLIO)
  599. #endif
  600. /**
  601. * fscache_unpin_writeback - Unpin writeback resources
  602. * @wbc: The writeback control
  603. * @cookie: The cookie referring to the cache object
  604. *
  605. * Unpin the writeback resources pinned by fscache_dirty_folio(). This is
  606. * intended to be called by the netfs's ->write_inode() method.
  607. */
  608. static inline void fscache_unpin_writeback(struct writeback_control *wbc,
  609. struct fscache_cookie *cookie)
  610. {
  611. if (wbc->unpinned_fscache_wb)
  612. fscache_unuse_cookie(cookie, NULL, NULL);
  613. }
  614. /**
  615. * fscache_clear_inode_writeback - Clear writeback resources pinned by an inode
  616. * @cookie: The cookie referring to the cache object
  617. * @inode: The inode to clean up
  618. * @aux: Auxiliary data to apply to the inode
  619. *
  620. * Clear any writeback resources held by an inode when the inode is evicted.
  621. * This must be called before clear_inode() is called.
  622. */
  623. static inline void fscache_clear_inode_writeback(struct fscache_cookie *cookie,
  624. struct inode *inode,
  625. const void *aux)
  626. {
  627. if (inode->i_state & I_PINNING_FSCACHE_WB) {
  628. loff_t i_size = i_size_read(inode);
  629. fscache_unuse_cookie(cookie, aux, &i_size);
  630. }
  631. }
  632. /**
  633. * fscache_note_page_release - Note that a netfs page got released
  634. * @cookie: The cookie corresponding to the file
  635. *
  636. * Note that a page that has been copied to the cache has been released. This
  637. * means that future reads will need to look in the cache to see if it's there.
  638. */
  639. static inline
  640. void fscache_note_page_release(struct fscache_cookie *cookie)
  641. {
  642. /* If we've written data to the cache (HAVE_DATA) and there wasn't any
  643. * data in the cache when we started (NO_DATA_TO_READ), it may no
  644. * longer be true that we can skip reading from the cache - so clear
  645. * the flag that causes reads to be skipped.
  646. */
  647. if (cookie &&
  648. test_bit(FSCACHE_COOKIE_HAVE_DATA, &cookie->flags) &&
  649. test_bit(FSCACHE_COOKIE_NO_DATA_TO_READ, &cookie->flags))
  650. clear_bit(FSCACHE_COOKIE_NO_DATA_TO_READ, &cookie->flags);
  651. }
  652. #endif /* _LINUX_FSCACHE_H */