fscache.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548
  1. /* General filesystem caching interface
  2. *
  3. * Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.
  4. * Written by David Howells (dhowells@redhat.com)
  5. *
  6. * This program is free software; you can redistribute it and/or
  7. * modify it under the terms of the GNU General Public License
  8. * as published by the Free Software Foundation; either version
  9. * 2 of the License, or (at your option) any later version.
  10. *
  11. * NOTE!!! See:
  12. *
  13. * Documentation/filesystems/caching/netfs-api.txt
  14. *
  15. * for a description of the network filesystem interface declared here.
  16. */
  17. #ifndef _LINUX_FSCACHE_H
  18. #define _LINUX_FSCACHE_H
  19. #include <linux/fs.h>
  20. #include <linux/list.h>
  21. #include <linux/pagemap.h>
  22. #include <linux/pagevec.h>
  23. #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
  24. #define fscache_available() (1)
  25. #define fscache_cookie_valid(cookie) (cookie)
  26. #else
  27. #define fscache_available() (0)
  28. #define fscache_cookie_valid(cookie) (0)
  29. #endif
  30. /*
  31. * overload PG_private_2 to give us PG_fscache - this is used to indicate that
  32. * a page is currently backed by a local disk cache
  33. */
  34. #define PageFsCache(page) PagePrivate2((page))
  35. #define SetPageFsCache(page) SetPagePrivate2((page))
  36. #define ClearPageFsCache(page) ClearPagePrivate2((page))
  37. #define TestSetPageFsCache(page) TestSetPagePrivate2((page))
  38. #define TestClearPageFsCache(page) TestClearPagePrivate2((page))
  39. /* pattern used to fill dead space in an index entry */
  40. #define FSCACHE_INDEX_DEADFILL_PATTERN 0x79
  41. struct pagevec;
  42. struct fscache_cache_tag;
  43. struct fscache_cookie;
  44. struct fscache_netfs;
  45. typedef void (*fscache_rw_complete_t)(struct page *page,
  46. void *context,
  47. int error);
  48. /* result of index entry consultation */
  49. enum fscache_checkaux {
  50. FSCACHE_CHECKAUX_OKAY, /* entry okay as is */
  51. FSCACHE_CHECKAUX_NEEDS_UPDATE, /* entry requires update */
  52. FSCACHE_CHECKAUX_OBSOLETE, /* entry requires deletion */
  53. };
  54. /*
  55. * fscache cookie definition
  56. */
  57. struct fscache_cookie_def {
  58. /* name of cookie type */
  59. char name[16];
  60. /* cookie type */
  61. uint8_t type;
  62. #define FSCACHE_COOKIE_TYPE_INDEX 0
  63. #define FSCACHE_COOKIE_TYPE_DATAFILE 1
  64. /* select the cache into which to insert an entry in this index
  65. * - optional
  66. * - should return a cache identifier or NULL to cause the cache to be
  67. * inherited from the parent if possible or the first cache picked
  68. * for a non-index file if not
  69. */
  70. struct fscache_cache_tag *(*select_cache)(
  71. const void *parent_netfs_data,
  72. const void *cookie_netfs_data);
  73. /* get an index key
  74. * - should store the key data in the buffer
  75. * - should return the amount of amount stored
  76. * - not permitted to return an error
  77. * - the netfs data from the cookie being used as the source is
  78. * presented
  79. */
  80. uint16_t (*get_key)(const void *cookie_netfs_data,
  81. void *buffer,
  82. uint16_t bufmax);
  83. /* get certain file attributes from the netfs data
  84. * - this function can be absent for an index
  85. * - not permitted to return an error
  86. * - the netfs data from the cookie being used as the source is
  87. * presented
  88. */
  89. void (*get_attr)(const void *cookie_netfs_data, uint64_t *size);
  90. /* get the auxilliary data from netfs data
  91. * - this function can be absent if the index carries no state data
  92. * - should store the auxilliary data in the buffer
  93. * - should return the amount of amount stored
  94. * - not permitted to return an error
  95. * - the netfs data from the cookie being used as the source is
  96. * presented
  97. */
  98. uint16_t (*get_aux)(const void *cookie_netfs_data,
  99. void *buffer,
  100. uint16_t bufmax);
  101. /* consult the netfs about the state of an object
  102. * - this function can be absent if the index carries no state data
  103. * - the netfs data from the cookie being used as the target is
  104. * presented, as is the auxilliary data
  105. */
  106. enum fscache_checkaux (*check_aux)(void *cookie_netfs_data,
  107. const void *data,
  108. uint16_t datalen);
  109. /* get an extra reference on a read context
  110. * - this function can be absent if the completion function doesn't
  111. * require a context
  112. */
  113. void (*get_context)(void *cookie_netfs_data, void *context);
  114. /* release an extra reference on a read context
  115. * - this function can be absent if the completion function doesn't
  116. * require a context
  117. */
  118. void (*put_context)(void *cookie_netfs_data, void *context);
  119. /* indicate pages that now have cache metadata retained
  120. * - this function should mark the specified pages as now being cached
  121. * - the pages will have been marked with PG_fscache before this is
  122. * called, so this is optional
  123. */
  124. void (*mark_pages_cached)(void *cookie_netfs_data,
  125. struct address_space *mapping,
  126. struct pagevec *cached_pvec);
  127. /* indicate the cookie is no longer cached
  128. * - this function is called when the backing store currently caching
  129. * a cookie is removed
  130. * - the netfs should use this to clean up any markers indicating
  131. * cached pages
  132. * - this is mandatory for any object that may have data
  133. */
  134. void (*now_uncached)(void *cookie_netfs_data);
  135. };
  136. /*
  137. * fscache cached network filesystem type
  138. * - name, version and ops must be filled in before registration
  139. * - all other fields will be set during registration
  140. */
  141. struct fscache_netfs {
  142. uint32_t version; /* indexing version */
  143. const char *name; /* filesystem name */
  144. struct fscache_cookie *primary_index;
  145. struct list_head link; /* internal link */
  146. };
  147. /*
  148. * slow-path functions for when there is actually caching available, and the
  149. * netfs does actually have a valid token
  150. * - these are not to be called directly
  151. * - these are undefined symbols when FS-Cache is not configured and the
  152. * optimiser takes care of not using them
  153. */
  154. /**
  155. * fscache_register_netfs - Register a filesystem as desiring caching services
  156. * @netfs: The description of the filesystem
  157. *
  158. * Register a filesystem as desiring caching services if they're available.
  159. *
  160. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  161. * description.
  162. */
  163. static inline
  164. int fscache_register_netfs(struct fscache_netfs *netfs)
  165. {
  166. return 0;
  167. }
  168. /**
  169. * fscache_unregister_netfs - Indicate that a filesystem no longer desires
  170. * caching services
  171. * @netfs: The description of the filesystem
  172. *
  173. * Indicate that a filesystem no longer desires caching services for the
  174. * moment.
  175. *
  176. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  177. * description.
  178. */
  179. static inline
  180. void fscache_unregister_netfs(struct fscache_netfs *netfs)
  181. {
  182. }
  183. /**
  184. * fscache_lookup_cache_tag - Look up a cache tag
  185. * @name: The name of the tag to search for
  186. *
  187. * Acquire a specific cache referral tag that can be used to select a specific
  188. * cache in which to cache an index.
  189. *
  190. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  191. * description.
  192. */
  193. static inline
  194. struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
  195. {
  196. return NULL;
  197. }
  198. /**
  199. * fscache_release_cache_tag - Release a cache tag
  200. * @tag: The tag to release
  201. *
  202. * Release a reference to a cache referral tag previously looked up.
  203. *
  204. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  205. * description.
  206. */
  207. static inline
  208. void fscache_release_cache_tag(struct fscache_cache_tag *tag)
  209. {
  210. }
  211. /**
  212. * fscache_acquire_cookie - Acquire a cookie to represent a cache object
  213. * @parent: The cookie that's to be the parent of this one
  214. * @def: A description of the cache object, including callback operations
  215. * @netfs_data: An arbitrary piece of data to be kept in the cookie to
  216. * represent the cache object to the netfs
  217. *
  218. * This function is used to inform FS-Cache about part of an index hierarchy
  219. * that can be used to locate files. This is done by requesting a cookie for
  220. * each index in the path to the file.
  221. *
  222. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  223. * description.
  224. */
  225. static inline
  226. struct fscache_cookie *fscache_acquire_cookie(
  227. struct fscache_cookie *parent,
  228. const struct fscache_cookie_def *def,
  229. void *netfs_data)
  230. {
  231. return NULL;
  232. }
  233. /**
  234. * fscache_relinquish_cookie - Return the cookie to the cache, maybe discarding
  235. * it
  236. * @cookie: The cookie being returned
  237. * @retire: True if the cache object the cookie represents is to be discarded
  238. *
  239. * This function returns a cookie to the cache, forcibly discarding the
  240. * associated cache object if retire is set to true.
  241. *
  242. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  243. * description.
  244. */
  245. static inline
  246. void fscache_relinquish_cookie(struct fscache_cookie *cookie, int retire)
  247. {
  248. }
  249. /**
  250. * fscache_update_cookie - Request that a cache object be updated
  251. * @cookie: The cookie representing the cache object
  252. *
  253. * Request an update of the index data for the cache object associated with the
  254. * cookie.
  255. *
  256. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  257. * description.
  258. */
  259. static inline
  260. void fscache_update_cookie(struct fscache_cookie *cookie)
  261. {
  262. }
  263. /**
  264. * fscache_pin_cookie - Pin a data-storage cache object in its cache
  265. * @cookie: The cookie representing the cache object
  266. *
  267. * Permit data-storage cache objects to be pinned in the cache.
  268. *
  269. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  270. * description.
  271. */
  272. static inline
  273. int fscache_pin_cookie(struct fscache_cookie *cookie)
  274. {
  275. return -ENOBUFS;
  276. }
  277. /**
  278. * fscache_pin_cookie - Unpin a data-storage cache object in its cache
  279. * @cookie: The cookie representing the cache object
  280. *
  281. * Permit data-storage cache objects to be unpinned from the cache.
  282. *
  283. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  284. * description.
  285. */
  286. static inline
  287. void fscache_unpin_cookie(struct fscache_cookie *cookie)
  288. {
  289. }
  290. /**
  291. * fscache_attr_changed - Notify cache that an object's attributes changed
  292. * @cookie: The cookie representing the cache object
  293. *
  294. * Send a notification to the cache indicating that an object's attributes have
  295. * changed. This includes the data size. These attributes will be obtained
  296. * through the get_attr() cookie definition op.
  297. *
  298. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  299. * description.
  300. */
  301. static inline
  302. int fscache_attr_changed(struct fscache_cookie *cookie)
  303. {
  304. return -ENOBUFS;
  305. }
  306. /**
  307. * fscache_reserve_space - Reserve data space for a cached object
  308. * @cookie: The cookie representing the cache object
  309. * @i_size: The amount of space to be reserved
  310. *
  311. * Reserve an amount of space in the cache for the cache object attached to a
  312. * cookie so that a write to that object within the space can always be
  313. * honoured.
  314. *
  315. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  316. * description.
  317. */
  318. static inline
  319. int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
  320. {
  321. return -ENOBUFS;
  322. }
  323. /**
  324. * fscache_read_or_alloc_page - Read a page from the cache or allocate a block
  325. * in which to store it
  326. * @cookie: The cookie representing the cache object
  327. * @page: The netfs page to fill if possible
  328. * @end_io_func: The callback to invoke when and if the page is filled
  329. * @context: An arbitrary piece of data to pass on to end_io_func()
  330. * @gfp: The conditions under which memory allocation should be made
  331. *
  332. * Read a page from the cache, or if that's not possible make a potential
  333. * one-block reservation in the cache into which the page may be stored once
  334. * fetched from the server.
  335. *
  336. * If the page is not backed by the cache object, or if it there's some reason
  337. * it can't be, -ENOBUFS will be returned and nothing more will be done for
  338. * that page.
  339. *
  340. * Else, if that page is backed by the cache, a read will be initiated directly
  341. * to the netfs's page and 0 will be returned by this function. The
  342. * end_io_func() callback will be invoked when the operation terminates on a
  343. * completion or failure. Note that the callback may be invoked before the
  344. * return.
  345. *
  346. * Else, if the page is unbacked, -ENODATA is returned and a block may have
  347. * been allocated in the cache.
  348. *
  349. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  350. * description.
  351. */
  352. static inline
  353. int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
  354. struct page *page,
  355. fscache_rw_complete_t end_io_func,
  356. void *context,
  357. gfp_t gfp)
  358. {
  359. return -ENOBUFS;
  360. }
  361. /**
  362. * fscache_read_or_alloc_pages - Read pages from the cache and/or allocate
  363. * blocks in which to store them
  364. * @cookie: The cookie representing the cache object
  365. * @mapping: The netfs inode mapping to which the pages will be attached
  366. * @pages: A list of potential netfs pages to be filled
  367. * @end_io_func: The callback to invoke when and if each page is filled
  368. * @context: An arbitrary piece of data to pass on to end_io_func()
  369. * @gfp: The conditions under which memory allocation should be made
  370. *
  371. * Read a set of pages from the cache, or if that's not possible, attempt to
  372. * make a potential one-block reservation for each page in the cache into which
  373. * that page may be stored once fetched from the server.
  374. *
  375. * If some pages are not backed by the cache object, or if it there's some
  376. * reason they can't be, -ENOBUFS will be returned and nothing more will be
  377. * done for that pages.
  378. *
  379. * Else, if some of the pages are backed by the cache, a read will be initiated
  380. * directly to the netfs's page and 0 will be returned by this function. The
  381. * end_io_func() callback will be invoked when the operation terminates on a
  382. * completion or failure. Note that the callback may be invoked before the
  383. * return.
  384. *
  385. * Else, if a page is unbacked, -ENODATA is returned and a block may have
  386. * been allocated in the cache.
  387. *
  388. * Because the function may want to return all of -ENOBUFS, -ENODATA and 0 in
  389. * regard to different pages, the return values are prioritised in that order.
  390. * Any pages submitted for reading are removed from the pages list.
  391. *
  392. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  393. * description.
  394. */
  395. static inline
  396. int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
  397. struct address_space *mapping,
  398. struct list_head *pages,
  399. unsigned *nr_pages,
  400. fscache_rw_complete_t end_io_func,
  401. void *context,
  402. gfp_t gfp)
  403. {
  404. return -ENOBUFS;
  405. }
  406. /**
  407. * fscache_alloc_page - Allocate a block in which to store a page
  408. * @cookie: The cookie representing the cache object
  409. * @page: The netfs page to allocate a page for
  410. * @gfp: The conditions under which memory allocation should be made
  411. *
  412. * Request Allocation a block in the cache in which to store a netfs page
  413. * without retrieving any contents from the cache.
  414. *
  415. * If the page is not backed by a file then -ENOBUFS will be returned and
  416. * nothing more will be done, and no reservation will be made.
  417. *
  418. * Else, a block will be allocated if one wasn't already, and 0 will be
  419. * returned
  420. *
  421. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  422. * description.
  423. */
  424. static inline
  425. int fscache_alloc_page(struct fscache_cookie *cookie,
  426. struct page *page,
  427. gfp_t gfp)
  428. {
  429. return -ENOBUFS;
  430. }
  431. /**
  432. * fscache_write_page - Request storage of a page in the cache
  433. * @cookie: The cookie representing the cache object
  434. * @page: The netfs page to store
  435. * @gfp: The conditions under which memory allocation should be made
  436. *
  437. * Request the contents of the netfs page be written into the cache. This
  438. * request may be ignored if no cache block is currently allocated, in which
  439. * case it will return -ENOBUFS.
  440. *
  441. * If a cache block was already allocated, a write will be initiated and 0 will
  442. * be returned. The PG_fscache_write page bit is set immediately and will then
  443. * be cleared at the completion of the write to indicate the success or failure
  444. * of the operation. Note that the completion may happen before the return.
  445. *
  446. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  447. * description.
  448. */
  449. static inline
  450. int fscache_write_page(struct fscache_cookie *cookie,
  451. struct page *page,
  452. gfp_t gfp)
  453. {
  454. return -ENOBUFS;
  455. }
  456. /**
  457. * fscache_uncache_page - Indicate that caching is no longer required on a page
  458. * @cookie: The cookie representing the cache object
  459. * @page: The netfs page that was being cached.
  460. *
  461. * Tell the cache that we no longer want a page to be cached and that it should
  462. * remove any knowledge of the netfs page it may have.
  463. *
  464. * Note that this cannot cancel any outstanding I/O operations between this
  465. * page and the cache.
  466. *
  467. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  468. * description.
  469. */
  470. static inline
  471. void fscache_uncache_page(struct fscache_cookie *cookie,
  472. struct page *page)
  473. {
  474. }
  475. /**
  476. * fscache_check_page_write - Ask if a page is being writing to the cache
  477. * @cookie: The cookie representing the cache object
  478. * @page: The netfs page that is being cached.
  479. *
  480. * Ask the cache if a page is being written to the cache.
  481. *
  482. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  483. * description.
  484. */
  485. static inline
  486. bool fscache_check_page_write(struct fscache_cookie *cookie,
  487. struct page *page)
  488. {
  489. return false;
  490. }
  491. /**
  492. * fscache_wait_on_page_write - Wait for a page to complete writing to the cache
  493. * @cookie: The cookie representing the cache object
  494. * @page: The netfs page that is being cached.
  495. *
  496. * Ask the cache to wake us up when a page is no longer being written to the
  497. * cache.
  498. *
  499. * See Documentation/filesystems/caching/netfs-api.txt for a complete
  500. * description.
  501. */
  502. static inline
  503. void fscache_wait_on_page_write(struct fscache_cookie *cookie,
  504. struct page *page)
  505. {
  506. }
  507. #endif /* _LINUX_FSCACHE_H */