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