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