fscache.h 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843
  1. /* SPDX-License-Identifier: GPL-2.0-or-later */
  2. /* General filesystem caching interface
  3. *
  4. * Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.
  5. * Written by David Howells (dhowells@redhat.com)
  6. *
  7. * NOTE!!! See:
  8. *
  9. * Documentation/filesystems/caching/netfs-api.rst
  10. *
  11. * for a description of the network filesystem interface declared here.
  12. */
  13. #ifndef _LINUX_FSCACHE_H
  14. #define _LINUX_FSCACHE_H
  15. #include <linux/fs.h>
  16. #include <linux/list.h>
  17. #include <linux/pagemap.h>
  18. #include <linux/pagevec.h>
  19. #include <linux/list_bl.h>
  20. #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
  21. #define fscache_available() (1)
  22. #define fscache_cookie_valid(cookie) (cookie)
  23. #else
  24. #define fscache_available() (0)
  25. #define fscache_cookie_valid(cookie) (0)
  26. #endif
  27. /*
  28. * overload PG_private_2 to give us PG_fscache - this is used to indicate that
  29. * a page is currently backed by a local disk cache
  30. */
  31. #define PageFsCache(page) PagePrivate2((page))
  32. #define SetPageFsCache(page) SetPagePrivate2((page))
  33. #define ClearPageFsCache(page) ClearPagePrivate2((page))
  34. #define TestSetPageFsCache(page) TestSetPagePrivate2((page))
  35. #define TestClearPageFsCache(page) TestClearPagePrivate2((page))
  36. /* pattern used to fill dead space in an index entry */
  37. #define FSCACHE_INDEX_DEADFILL_PATTERN 0x79
  38. struct pagevec;
  39. struct fscache_cache_tag;
  40. struct fscache_cookie;
  41. struct fscache_netfs;
  42. typedef void (*fscache_rw_complete_t)(struct page *page,
  43. void *context,
  44. int error);
  45. /* result of index entry consultation */
  46. enum fscache_checkaux {
  47. FSCACHE_CHECKAUX_OKAY, /* entry okay as is */
  48. FSCACHE_CHECKAUX_NEEDS_UPDATE, /* entry requires update */
  49. FSCACHE_CHECKAUX_OBSOLETE, /* entry requires deletion */
  50. };
  51. /*
  52. * fscache cookie definition
  53. */
  54. struct fscache_cookie_def {
  55. /* name of cookie type */
  56. char name[16];
  57. /* cookie type */
  58. uint8_t type;
  59. #define FSCACHE_COOKIE_TYPE_INDEX 0
  60. #define FSCACHE_COOKIE_TYPE_DATAFILE 1
  61. /* select the cache into which to insert an entry in this index
  62. * - optional
  63. * - should return a cache identifier or NULL to cause the cache to be
  64. * inherited from the parent if possible or the first cache picked
  65. * for a non-index file if not
  66. */
  67. struct fscache_cache_tag *(*select_cache)(
  68. const void *parent_netfs_data,
  69. const void *cookie_netfs_data);
  70. /* consult the netfs about the state of an object
  71. * - this function can be absent if the index carries no state data
  72. * - the netfs data from the cookie being used as the target is
  73. * presented, as is the auxiliary data and the object size
  74. */
  75. enum fscache_checkaux (*check_aux)(void *cookie_netfs_data,
  76. const void *data,
  77. uint16_t datalen,
  78. loff_t object_size);
  79. /* get an extra reference on a read context
  80. * - this function can be absent if the completion function doesn't
  81. * require a context
  82. */
  83. void (*get_context)(void *cookie_netfs_data, void *context);
  84. /* release an extra reference on a read context
  85. * - this function can be absent if the completion function doesn't
  86. * require a context
  87. */
  88. void (*put_context)(void *cookie_netfs_data, void *context);
  89. /* indicate page that now have cache metadata retained
  90. * - this function should mark the specified page as now being cached
  91. * - the page will have been marked with PG_fscache before this is
  92. * called, so this is optional
  93. */
  94. void (*mark_page_cached)(void *cookie_netfs_data,
  95. struct address_space *mapping,
  96. struct page *page);
  97. };
  98. /*
  99. * fscache cached network filesystem type
  100. * - name, version and ops must be filled in before registration
  101. * - all other fields will be set during registration
  102. */
  103. struct fscache_netfs {
  104. uint32_t version; /* indexing version */
  105. const char *name; /* filesystem name */
  106. struct fscache_cookie *primary_index;
  107. };
  108. /*
  109. * data file or index object cookie
  110. * - a file will only appear in one cache
  111. * - a request to cache a file may or may not be honoured, subject to
  112. * constraints such as disk space
  113. * - indices are created on disk just-in-time
  114. */
  115. struct fscache_cookie {
  116. atomic_t usage; /* number of users of this cookie */
  117. atomic_t n_children; /* number of children of this cookie */
  118. atomic_t n_active; /* number of active users of netfs ptrs */
  119. spinlock_t lock;
  120. spinlock_t stores_lock; /* lock on page store tree */
  121. struct hlist_head backing_objects; /* object(s) backing this file/index */
  122. const struct fscache_cookie_def *def; /* definition */
  123. struct fscache_cookie *parent; /* parent of this entry */
  124. struct hlist_bl_node hash_link; /* Link in hash table */
  125. void *netfs_data; /* back pointer to netfs */
  126. struct radix_tree_root stores; /* pages to be stored on this cookie */
  127. #define FSCACHE_COOKIE_PENDING_TAG 0 /* pages tag: pending write to cache */
  128. #define FSCACHE_COOKIE_STORING_TAG 1 /* pages tag: writing to cache */
  129. unsigned long flags;
  130. #define FSCACHE_COOKIE_LOOKING_UP 0 /* T if non-index cookie being looked up still */
  131. #define FSCACHE_COOKIE_NO_DATA_YET 1 /* T if new object with no cached data yet */
  132. #define FSCACHE_COOKIE_UNAVAILABLE 2 /* T if cookie is unavailable (error, etc) */
  133. #define FSCACHE_COOKIE_INVALIDATING 3 /* T if cookie is being invalidated */
  134. #define FSCACHE_COOKIE_RELINQUISHED 4 /* T if cookie has been relinquished */
  135. #define FSCACHE_COOKIE_ENABLED 5 /* T if cookie is enabled */
  136. #define FSCACHE_COOKIE_ENABLEMENT_LOCK 6 /* T if cookie is being en/disabled */
  137. #define FSCACHE_COOKIE_AUX_UPDATED 8 /* T if the auxiliary data was updated */
  138. #define FSCACHE_COOKIE_ACQUIRED 9 /* T if cookie is in use */
  139. #define FSCACHE_COOKIE_RELINQUISHING 10 /* T if cookie is being relinquished */
  140. u8 type; /* Type of object */
  141. u8 key_len; /* Length of index key */
  142. u8 aux_len; /* Length of auxiliary data */
  143. u32 key_hash; /* Hash of parent, type, key, len */
  144. union {
  145. void *key; /* Index key */
  146. u8 inline_key[16]; /* - If the key is short enough */
  147. };
  148. union {
  149. void *aux; /* Auxiliary data */
  150. u8 inline_aux[8]; /* - If the aux data is short enough */
  151. };
  152. };
  153. static inline bool fscache_cookie_enabled(struct fscache_cookie *cookie)
  154. {
  155. return test_bit(FSCACHE_COOKIE_ENABLED, &cookie->flags);
  156. }
  157. /*
  158. * slow-path functions for when there is actually caching available, and the
  159. * netfs does actually have a valid token
  160. * - these are not to be called directly
  161. * - these are undefined symbols when FS-Cache is not configured and the
  162. * optimiser takes care of not using them
  163. */
  164. extern int __fscache_register_netfs(struct fscache_netfs *);
  165. extern void __fscache_unregister_netfs(struct fscache_netfs *);
  166. extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *);
  167. extern void __fscache_release_cache_tag(struct fscache_cache_tag *);
  168. extern struct fscache_cookie *__fscache_acquire_cookie(
  169. struct fscache_cookie *,
  170. const struct fscache_cookie_def *,
  171. const void *, size_t,
  172. const void *, size_t,
  173. void *, loff_t, bool);
  174. extern void __fscache_relinquish_cookie(struct fscache_cookie *, const void *, bool);
  175. extern int __fscache_check_consistency(struct fscache_cookie *, const void *);
  176. extern void __fscache_update_cookie(struct fscache_cookie *, const void *);
  177. extern int __fscache_attr_changed(struct fscache_cookie *);
  178. extern void __fscache_invalidate(struct fscache_cookie *);
  179. extern void __fscache_wait_on_invalidate(struct fscache_cookie *);
  180. extern int __fscache_read_or_alloc_page(struct fscache_cookie *,
  181. struct page *,
  182. fscache_rw_complete_t,
  183. void *,
  184. gfp_t);
  185. extern int __fscache_read_or_alloc_pages(struct fscache_cookie *,
  186. struct address_space *,
  187. struct list_head *,
  188. unsigned *,
  189. fscache_rw_complete_t,
  190. void *,
  191. gfp_t);
  192. extern int __fscache_alloc_page(struct fscache_cookie *, struct page *, gfp_t);
  193. extern int __fscache_write_page(struct fscache_cookie *, struct page *, loff_t, gfp_t);
  194. extern void __fscache_uncache_page(struct fscache_cookie *, struct page *);
  195. extern bool __fscache_check_page_write(struct fscache_cookie *, struct page *);
  196. extern void __fscache_wait_on_page_write(struct fscache_cookie *, struct page *);
  197. extern bool __fscache_maybe_release_page(struct fscache_cookie *, struct page *,
  198. gfp_t);
  199. extern void __fscache_uncache_all_inode_pages(struct fscache_cookie *,
  200. struct inode *);
  201. extern void __fscache_readpages_cancel(struct fscache_cookie *cookie,
  202. struct list_head *pages);
  203. extern void __fscache_disable_cookie(struct fscache_cookie *, const void *, bool);
  204. extern void __fscache_enable_cookie(struct fscache_cookie *, const void *, loff_t,
  205. bool (*)(void *), void *);
  206. /**
  207. * fscache_register_netfs - Register a filesystem as desiring caching services
  208. * @netfs: The description of the filesystem
  209. *
  210. * Register a filesystem as desiring caching services if they're available.
  211. *
  212. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  213. * description.
  214. */
  215. static inline
  216. int fscache_register_netfs(struct fscache_netfs *netfs)
  217. {
  218. if (fscache_available())
  219. return __fscache_register_netfs(netfs);
  220. else
  221. return 0;
  222. }
  223. /**
  224. * fscache_unregister_netfs - Indicate that a filesystem no longer desires
  225. * caching services
  226. * @netfs: The description of the filesystem
  227. *
  228. * Indicate that a filesystem no longer desires caching services for the
  229. * moment.
  230. *
  231. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  232. * description.
  233. */
  234. static inline
  235. void fscache_unregister_netfs(struct fscache_netfs *netfs)
  236. {
  237. if (fscache_available())
  238. __fscache_unregister_netfs(netfs);
  239. }
  240. /**
  241. * fscache_lookup_cache_tag - Look up a cache tag
  242. * @name: The name of the tag to search for
  243. *
  244. * Acquire a specific cache referral tag that can be used to select a specific
  245. * cache in which to cache an index.
  246. *
  247. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  248. * description.
  249. */
  250. static inline
  251. struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
  252. {
  253. if (fscache_available())
  254. return __fscache_lookup_cache_tag(name);
  255. else
  256. return NULL;
  257. }
  258. /**
  259. * fscache_release_cache_tag - Release a cache tag
  260. * @tag: The tag to release
  261. *
  262. * Release a reference to a cache referral tag previously looked up.
  263. *
  264. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  265. * description.
  266. */
  267. static inline
  268. void fscache_release_cache_tag(struct fscache_cache_tag *tag)
  269. {
  270. if (fscache_available())
  271. __fscache_release_cache_tag(tag);
  272. }
  273. /**
  274. * fscache_acquire_cookie - Acquire a cookie to represent a cache object
  275. * @parent: The cookie that's to be the parent of this one
  276. * @def: A description of the cache object, including callback operations
  277. * @index_key: The index key for this cookie
  278. * @index_key_len: Size of the index key
  279. * @aux_data: The auxiliary data for the cookie (may be NULL)
  280. * @aux_data_len: Size of the auxiliary data buffer
  281. * @netfs_data: An arbitrary piece of data to be kept in the cookie to
  282. * represent the cache object to the netfs
  283. * @object_size: The initial size of object
  284. * @enable: Whether or not to enable a data cookie immediately
  285. *
  286. * This function is used to inform FS-Cache about part of an index hierarchy
  287. * that can be used to locate files. This is done by requesting a cookie for
  288. * each index in the path to the file.
  289. *
  290. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  291. * description.
  292. */
  293. static inline
  294. struct fscache_cookie *fscache_acquire_cookie(
  295. struct fscache_cookie *parent,
  296. const struct fscache_cookie_def *def,
  297. const void *index_key,
  298. size_t index_key_len,
  299. const void *aux_data,
  300. size_t aux_data_len,
  301. void *netfs_data,
  302. loff_t object_size,
  303. bool enable)
  304. {
  305. if (fscache_cookie_valid(parent) && fscache_cookie_enabled(parent))
  306. return __fscache_acquire_cookie(parent, def,
  307. index_key, index_key_len,
  308. aux_data, aux_data_len,
  309. netfs_data, object_size, enable);
  310. else
  311. return NULL;
  312. }
  313. /**
  314. * fscache_relinquish_cookie - Return the cookie to the cache, maybe discarding
  315. * it
  316. * @cookie: The cookie being returned
  317. * @aux_data: The updated auxiliary data for the cookie (may be NULL)
  318. * @retire: True if the cache object the cookie represents is to be discarded
  319. *
  320. * This function returns a cookie to the cache, forcibly discarding the
  321. * associated cache object if retire is set to true. The opportunity is
  322. * provided to update the auxiliary data in the cache before the object is
  323. * disconnected.
  324. *
  325. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  326. * description.
  327. */
  328. static inline
  329. void fscache_relinquish_cookie(struct fscache_cookie *cookie,
  330. const void *aux_data,
  331. bool retire)
  332. {
  333. if (fscache_cookie_valid(cookie))
  334. __fscache_relinquish_cookie(cookie, aux_data, retire);
  335. }
  336. /**
  337. * fscache_check_consistency - Request validation of a cache's auxiliary data
  338. * @cookie: The cookie representing the cache object
  339. * @aux_data: The updated auxiliary data for the cookie (may be NULL)
  340. *
  341. * Request an consistency check from fscache, which passes the request to the
  342. * backing cache. The auxiliary data on the cookie will be updated first if
  343. * @aux_data is set.
  344. *
  345. * Returns 0 if consistent and -ESTALE if inconsistent. May also
  346. * return -ENOMEM and -ERESTARTSYS.
  347. */
  348. static inline
  349. int fscache_check_consistency(struct fscache_cookie *cookie,
  350. const void *aux_data)
  351. {
  352. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  353. return __fscache_check_consistency(cookie, aux_data);
  354. else
  355. return 0;
  356. }
  357. /**
  358. * fscache_update_cookie - Request that a cache object be updated
  359. * @cookie: The cookie representing the cache object
  360. * @aux_data: The updated auxiliary data for the cookie (may be NULL)
  361. *
  362. * Request an update of the index data for the cache object associated with the
  363. * cookie. The auxiliary data on the cookie will be updated first if @aux_data
  364. * is set.
  365. *
  366. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  367. * description.
  368. */
  369. static inline
  370. void fscache_update_cookie(struct fscache_cookie *cookie, const void *aux_data)
  371. {
  372. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  373. __fscache_update_cookie(cookie, aux_data);
  374. }
  375. /**
  376. * fscache_pin_cookie - Pin a data-storage cache object in its cache
  377. * @cookie: The cookie representing the cache object
  378. *
  379. * Permit data-storage cache objects to be pinned in the cache.
  380. *
  381. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  382. * description.
  383. */
  384. static inline
  385. int fscache_pin_cookie(struct fscache_cookie *cookie)
  386. {
  387. return -ENOBUFS;
  388. }
  389. /**
  390. * fscache_pin_cookie - Unpin a data-storage cache object in its cache
  391. * @cookie: The cookie representing the cache object
  392. *
  393. * Permit data-storage cache objects to be unpinned from the cache.
  394. *
  395. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  396. * description.
  397. */
  398. static inline
  399. void fscache_unpin_cookie(struct fscache_cookie *cookie)
  400. {
  401. }
  402. /**
  403. * fscache_attr_changed - Notify cache that an object's attributes changed
  404. * @cookie: The cookie representing the cache object
  405. *
  406. * Send a notification to the cache indicating that an object's attributes have
  407. * changed. This includes the data size. These attributes will be obtained
  408. * through the get_attr() cookie definition op.
  409. *
  410. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  411. * description.
  412. */
  413. static inline
  414. int fscache_attr_changed(struct fscache_cookie *cookie)
  415. {
  416. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  417. return __fscache_attr_changed(cookie);
  418. else
  419. return -ENOBUFS;
  420. }
  421. /**
  422. * fscache_invalidate - Notify cache that an object needs invalidation
  423. * @cookie: The cookie representing the cache object
  424. *
  425. * Notify the cache that an object is needs to be invalidated and that it
  426. * should abort any retrievals or stores it is doing on the cache. The object
  427. * is then marked non-caching until such time as the invalidation is complete.
  428. *
  429. * This can be called with spinlocks held.
  430. *
  431. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  432. * description.
  433. */
  434. static inline
  435. void fscache_invalidate(struct fscache_cookie *cookie)
  436. {
  437. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  438. __fscache_invalidate(cookie);
  439. }
  440. /**
  441. * fscache_wait_on_invalidate - Wait for invalidation to complete
  442. * @cookie: The cookie representing the cache object
  443. *
  444. * Wait for the invalidation of an object to complete.
  445. *
  446. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  447. * description.
  448. */
  449. static inline
  450. void fscache_wait_on_invalidate(struct fscache_cookie *cookie)
  451. {
  452. if (fscache_cookie_valid(cookie))
  453. __fscache_wait_on_invalidate(cookie);
  454. }
  455. /**
  456. * fscache_reserve_space - Reserve data space for a cached object
  457. * @cookie: The cookie representing the cache object
  458. * @i_size: The amount of space to be reserved
  459. *
  460. * Reserve an amount of space in the cache for the cache object attached to a
  461. * cookie so that a write to that object within the space can always be
  462. * honoured.
  463. *
  464. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  465. * description.
  466. */
  467. static inline
  468. int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
  469. {
  470. return -ENOBUFS;
  471. }
  472. /**
  473. * fscache_read_or_alloc_page - Read a page from the cache or allocate a block
  474. * in which to store it
  475. * @cookie: The cookie representing the cache object
  476. * @page: The netfs page to fill if possible
  477. * @end_io_func: The callback to invoke when and if the page is filled
  478. * @context: An arbitrary piece of data to pass on to end_io_func()
  479. * @gfp: The conditions under which memory allocation should be made
  480. *
  481. * Read a page from the cache, or if that's not possible make a potential
  482. * one-block reservation in the cache into which the page may be stored once
  483. * fetched from the server.
  484. *
  485. * If the page is not backed by the cache object, or if it there's some reason
  486. * it can't be, -ENOBUFS will be returned and nothing more will be done for
  487. * that page.
  488. *
  489. * Else, if that page is backed by the cache, a read will be initiated directly
  490. * to the netfs's page and 0 will be returned by this function. The
  491. * end_io_func() callback will be invoked when the operation terminates on a
  492. * completion or failure. Note that the callback may be invoked before the
  493. * return.
  494. *
  495. * Else, if the page is unbacked, -ENODATA is returned and a block may have
  496. * been allocated in the cache.
  497. *
  498. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  499. * description.
  500. */
  501. static inline
  502. int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
  503. struct page *page,
  504. fscache_rw_complete_t end_io_func,
  505. void *context,
  506. gfp_t gfp)
  507. {
  508. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  509. return __fscache_read_or_alloc_page(cookie, page, end_io_func,
  510. context, gfp);
  511. else
  512. return -ENOBUFS;
  513. }
  514. /**
  515. * fscache_read_or_alloc_pages - Read pages from the cache and/or allocate
  516. * blocks in which to store them
  517. * @cookie: The cookie representing the cache object
  518. * @mapping: The netfs inode mapping to which the pages will be attached
  519. * @pages: A list of potential netfs pages to be filled
  520. * @nr_pages: Number of pages to be read and/or allocated
  521. * @end_io_func: The callback to invoke when and if each page is filled
  522. * @context: An arbitrary piece of data to pass on to end_io_func()
  523. * @gfp: The conditions under which memory allocation should be made
  524. *
  525. * Read a set of pages from the cache, or if that's not possible, attempt to
  526. * make a potential one-block reservation for each page in the cache into which
  527. * that page may be stored once fetched from the server.
  528. *
  529. * If some pages are not backed by the cache object, or if it there's some
  530. * reason they can't be, -ENOBUFS will be returned and nothing more will be
  531. * done for that pages.
  532. *
  533. * Else, if some of the pages are backed by the cache, a read will be initiated
  534. * directly to the netfs's page and 0 will be returned by this function. The
  535. * end_io_func() callback will be invoked when the operation terminates on a
  536. * completion or failure. Note that the callback may be invoked before the
  537. * return.
  538. *
  539. * Else, if a page is unbacked, -ENODATA is returned and a block may have
  540. * been allocated in the cache.
  541. *
  542. * Because the function may want to return all of -ENOBUFS, -ENODATA and 0 in
  543. * regard to different pages, the return values are prioritised in that order.
  544. * Any pages submitted for reading are removed from the pages list.
  545. *
  546. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  547. * description.
  548. */
  549. static inline
  550. int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
  551. struct address_space *mapping,
  552. struct list_head *pages,
  553. unsigned *nr_pages,
  554. fscache_rw_complete_t end_io_func,
  555. void *context,
  556. gfp_t gfp)
  557. {
  558. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  559. return __fscache_read_or_alloc_pages(cookie, mapping, pages,
  560. nr_pages, end_io_func,
  561. context, gfp);
  562. else
  563. return -ENOBUFS;
  564. }
  565. /**
  566. * fscache_alloc_page - Allocate a block in which to store a page
  567. * @cookie: The cookie representing the cache object
  568. * @page: The netfs page to allocate a page for
  569. * @gfp: The conditions under which memory allocation should be made
  570. *
  571. * Request Allocation a block in the cache in which to store a netfs page
  572. * without retrieving any contents from the cache.
  573. *
  574. * If the page is not backed by a file then -ENOBUFS will be returned and
  575. * nothing more will be done, and no reservation will be made.
  576. *
  577. * Else, a block will be allocated if one wasn't already, and 0 will be
  578. * returned
  579. *
  580. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  581. * description.
  582. */
  583. static inline
  584. int fscache_alloc_page(struct fscache_cookie *cookie,
  585. struct page *page,
  586. gfp_t gfp)
  587. {
  588. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  589. return __fscache_alloc_page(cookie, page, gfp);
  590. else
  591. return -ENOBUFS;
  592. }
  593. /**
  594. * fscache_readpages_cancel - Cancel read/alloc on pages
  595. * @cookie: The cookie representing the inode's cache object.
  596. * @pages: The netfs pages that we canceled write on in readpages()
  597. *
  598. * Uncache/unreserve the pages reserved earlier in readpages() via
  599. * fscache_readpages_or_alloc() and similar. In most successful caches in
  600. * readpages() this doesn't do anything. In cases when the underlying netfs's
  601. * readahead failed we need to clean up the pagelist (unmark and uncache).
  602. *
  603. * This function may sleep as it may have to clean up disk state.
  604. */
  605. static inline
  606. void fscache_readpages_cancel(struct fscache_cookie *cookie,
  607. struct list_head *pages)
  608. {
  609. if (fscache_cookie_valid(cookie))
  610. __fscache_readpages_cancel(cookie, pages);
  611. }
  612. /**
  613. * fscache_write_page - Request storage of a page in the cache
  614. * @cookie: The cookie representing the cache object
  615. * @page: The netfs page to store
  616. * @object_size: Updated size of object
  617. * @gfp: The conditions under which memory allocation should be made
  618. *
  619. * Request the contents of the netfs page be written into the cache. This
  620. * request may be ignored if no cache block is currently allocated, in which
  621. * case it will return -ENOBUFS.
  622. *
  623. * If a cache block was already allocated, a write will be initiated and 0 will
  624. * be returned. The PG_fscache_write page bit is set immediately and will then
  625. * be cleared at the completion of the write to indicate the success or failure
  626. * of the operation. Note that the completion may happen before the return.
  627. *
  628. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  629. * description.
  630. */
  631. static inline
  632. int fscache_write_page(struct fscache_cookie *cookie,
  633. struct page *page,
  634. loff_t object_size,
  635. gfp_t gfp)
  636. {
  637. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  638. return __fscache_write_page(cookie, page, object_size, gfp);
  639. else
  640. return -ENOBUFS;
  641. }
  642. /**
  643. * fscache_uncache_page - Indicate that caching is no longer required on a page
  644. * @cookie: The cookie representing the cache object
  645. * @page: The netfs page that was being cached.
  646. *
  647. * Tell the cache that we no longer want a page to be cached and that it should
  648. * remove any knowledge of the netfs page it may have.
  649. *
  650. * Note that this cannot cancel any outstanding I/O operations between this
  651. * page and the cache.
  652. *
  653. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  654. * description.
  655. */
  656. static inline
  657. void fscache_uncache_page(struct fscache_cookie *cookie,
  658. struct page *page)
  659. {
  660. if (fscache_cookie_valid(cookie))
  661. __fscache_uncache_page(cookie, page);
  662. }
  663. /**
  664. * fscache_check_page_write - Ask if a page is being writing to the cache
  665. * @cookie: The cookie representing the cache object
  666. * @page: The netfs page that is being cached.
  667. *
  668. * Ask the cache if a page is being written to the cache.
  669. *
  670. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  671. * description.
  672. */
  673. static inline
  674. bool fscache_check_page_write(struct fscache_cookie *cookie,
  675. struct page *page)
  676. {
  677. if (fscache_cookie_valid(cookie))
  678. return __fscache_check_page_write(cookie, page);
  679. return false;
  680. }
  681. /**
  682. * fscache_wait_on_page_write - Wait for a page to complete writing to the cache
  683. * @cookie: The cookie representing the cache object
  684. * @page: The netfs page that is being cached.
  685. *
  686. * Ask the cache to wake us up when a page is no longer being written to the
  687. * cache.
  688. *
  689. * See Documentation/filesystems/caching/netfs-api.rst for a complete
  690. * description.
  691. */
  692. static inline
  693. void fscache_wait_on_page_write(struct fscache_cookie *cookie,
  694. struct page *page)
  695. {
  696. if (fscache_cookie_valid(cookie))
  697. __fscache_wait_on_page_write(cookie, page);
  698. }
  699. /**
  700. * fscache_maybe_release_page - Consider releasing a page, cancelling a store
  701. * @cookie: The cookie representing the cache object
  702. * @page: The netfs page that is being cached.
  703. * @gfp: The gfp flags passed to releasepage()
  704. *
  705. * Consider releasing a page for the vmscan algorithm, on behalf of the netfs's
  706. * releasepage() call. A storage request on the page may cancelled if it is
  707. * not currently being processed.
  708. *
  709. * The function returns true if the page no longer has a storage request on it,
  710. * and false if a storage request is left in place. If true is returned, the
  711. * page will have been passed to fscache_uncache_page(). If false is returned
  712. * the page cannot be freed yet.
  713. */
  714. static inline
  715. bool fscache_maybe_release_page(struct fscache_cookie *cookie,
  716. struct page *page,
  717. gfp_t gfp)
  718. {
  719. if (fscache_cookie_valid(cookie) && PageFsCache(page))
  720. return __fscache_maybe_release_page(cookie, page, gfp);
  721. return true;
  722. }
  723. /**
  724. * fscache_uncache_all_inode_pages - Uncache all an inode's pages
  725. * @cookie: The cookie representing the inode's cache object.
  726. * @inode: The inode to uncache pages from.
  727. *
  728. * Uncache all the pages in an inode that are marked PG_fscache, assuming them
  729. * to be associated with the given cookie.
  730. *
  731. * This function may sleep. It will wait for pages that are being written out
  732. * and will wait whilst the PG_fscache mark is removed by the cache.
  733. */
  734. static inline
  735. void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,
  736. struct inode *inode)
  737. {
  738. if (fscache_cookie_valid(cookie))
  739. __fscache_uncache_all_inode_pages(cookie, inode);
  740. }
  741. /**
  742. * fscache_disable_cookie - Disable a cookie
  743. * @cookie: The cookie representing the cache object
  744. * @aux_data: The updated auxiliary data for the cookie (may be NULL)
  745. * @invalidate: Invalidate the backing object
  746. *
  747. * Disable a cookie from accepting further alloc, read, write, invalidate,
  748. * update or acquire operations. Outstanding operations can still be waited
  749. * upon and pages can still be uncached and the cookie relinquished.
  750. *
  751. * This will not return until all outstanding operations have completed.
  752. *
  753. * If @invalidate is set, then the backing object will be invalidated and
  754. * detached, otherwise it will just be detached.
  755. *
  756. * If @aux_data is set, then auxiliary data will be updated from that.
  757. */
  758. static inline
  759. void fscache_disable_cookie(struct fscache_cookie *cookie,
  760. const void *aux_data,
  761. bool invalidate)
  762. {
  763. if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
  764. __fscache_disable_cookie(cookie, aux_data, invalidate);
  765. }
  766. /**
  767. * fscache_enable_cookie - Reenable a cookie
  768. * @cookie: The cookie representing the cache object
  769. * @aux_data: The updated auxiliary data for the cookie (may be NULL)
  770. * @object_size: Current size of object
  771. * @can_enable: A function to permit enablement once lock is held
  772. * @data: Data for can_enable()
  773. *
  774. * Reenable a previously disabled cookie, allowing it to accept further alloc,
  775. * read, write, invalidate, update or acquire operations. An attempt will be
  776. * made to immediately reattach the cookie to a backing object. If @aux_data
  777. * is set, the auxiliary data attached to the cookie will be updated.
  778. *
  779. * The can_enable() function is called (if not NULL) once the enablement lock
  780. * is held to rule on whether enablement is still permitted to go ahead.
  781. */
  782. static inline
  783. void fscache_enable_cookie(struct fscache_cookie *cookie,
  784. const void *aux_data,
  785. loff_t object_size,
  786. bool (*can_enable)(void *data),
  787. void *data)
  788. {
  789. if (fscache_cookie_valid(cookie) && !fscache_cookie_enabled(cookie))
  790. __fscache_enable_cookie(cookie, aux_data, object_size,
  791. can_enable, data);
  792. }
  793. #endif /* _LINUX_FSCACHE_H */