Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
fscache.h
Go to the documentation of this file.
1 /* General filesystem caching interface
2  *
3  * Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.
4  * Written by David Howells ([email protected])
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 
26 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
27 #define fscache_available() (1)
28 #define fscache_cookie_valid(cookie) (cookie)
29 #else
30 #define fscache_available() (0)
31 #define fscache_cookie_valid(cookie) (0)
32 #endif
33 
34 
35 /*
36  * overload PG_private_2 to give us PG_fscache - this is used to indicate that
37  * a page is currently backed by a local disk cache
38  */
39 #define PageFsCache(page) PagePrivate2((page))
40 #define SetPageFsCache(page) SetPagePrivate2((page))
41 #define ClearPageFsCache(page) ClearPagePrivate2((page))
42 #define TestSetPageFsCache(page) TestSetPagePrivate2((page))
43 #define TestClearPageFsCache(page) TestClearPagePrivate2((page))
44 
45 /* pattern used to fill dead space in an index entry */
46 #define FSCACHE_INDEX_DEADFILL_PATTERN 0x79
47 
48 struct pagevec;
49 struct fscache_cache_tag;
50 struct fscache_cookie;
51 struct fscache_netfs;
52 
53 typedef void (*fscache_rw_complete_t)(struct page *page,
54  void *context,
55  int error);
56 
57 /* result of index entry consultation */
59  FSCACHE_CHECKAUX_OKAY, /* entry okay as is */
60  FSCACHE_CHECKAUX_NEEDS_UPDATE, /* entry requires update */
61  FSCACHE_CHECKAUX_OBSOLETE, /* entry requires deletion */
62 };
63 
64 /*
65  * fscache cookie definition
66  */
68  /* name of cookie type */
69  char name[16];
70 
71  /* cookie type */
73 #define FSCACHE_COOKIE_TYPE_INDEX 0
74 #define FSCACHE_COOKIE_TYPE_DATAFILE 1
75 
76  /* select the cache into which to insert an entry in this index
77  * - optional
78  * - should return a cache identifier or NULL to cause the cache to be
79  * inherited from the parent if possible or the first cache picked
80  * for a non-index file if not
81  */
82  struct fscache_cache_tag *(*select_cache)(
83  const void *parent_netfs_data,
84  const void *cookie_netfs_data);
85 
86  /* get an index key
87  * - should store the key data in the buffer
88  * - should return the amount of data stored
89  * - not permitted to return an error
90  * - the netfs data from the cookie being used as the source is
91  * presented
92  */
93  uint16_t (*get_key)(const void *cookie_netfs_data,
94  void *buffer,
95  uint16_t bufmax);
96 
97  /* get certain file attributes from the netfs data
98  * - this function can be absent for an index
99  * - not permitted to return an error
100  * - the netfs data from the cookie being used as the source is
101  * presented
102  */
103  void (*get_attr)(const void *cookie_netfs_data, uint64_t *size);
104 
105  /* get the auxiliary data from netfs data
106  * - this function can be absent if the index carries no state data
107  * - should store the auxiliary data in the buffer
108  * - should return the amount of amount stored
109  * - not permitted to return an error
110  * - the netfs data from the cookie being used as the source is
111  * presented
112  */
113  uint16_t (*get_aux)(const void *cookie_netfs_data,
114  void *buffer,
115  uint16_t bufmax);
116 
117  /* consult the netfs about the state of an object
118  * - this function can be absent if the index carries no state data
119  * - the netfs data from the cookie being used as the target is
120  * presented, as is the auxiliary data
121  */
122  enum fscache_checkaux (*check_aux)(void *cookie_netfs_data,
123  const void *data,
124  uint16_t datalen);
125 
126  /* get an extra reference on a read context
127  * - this function can be absent if the completion function doesn't
128  * require a context
129  */
130  void (*get_context)(void *cookie_netfs_data, void *context);
131 
132  /* release an extra reference on a read context
133  * - this function can be absent if the completion function doesn't
134  * require a context
135  */
136  void (*put_context)(void *cookie_netfs_data, void *context);
137 
138  /* indicate pages that now have cache metadata retained
139  * - this function should mark the specified pages as now being cached
140  * - the pages will have been marked with PG_fscache before this is
141  * called, so this is optional
142  */
143  void (*mark_pages_cached)(void *cookie_netfs_data,
144  struct address_space *mapping,
145  struct pagevec *cached_pvec);
146 
147  /* indicate the cookie is no longer cached
148  * - this function is called when the backing store currently caching
149  * a cookie is removed
150  * - the netfs should use this to clean up any markers indicating
151  * cached pages
152  * - this is mandatory for any object that may have data
153  */
154  void (*now_uncached)(void *cookie_netfs_data);
155 };
156 
157 /*
158  * fscache cached network filesystem type
159  * - name, version and ops must be filled in before registration
160  * - all other fields will be set during registration
161  */
163  uint32_t version; /* indexing version */
164  const char *name; /* filesystem name */
166  struct list_head link; /* internal link */
167 };
168 
169 /*
170  * slow-path functions for when there is actually caching available, and the
171  * netfs does actually have a valid token
172  * - these are not to be called directly
173  * - these are undefined symbols when FS-Cache is not configured and the
174  * optimiser takes care of not using them
175  */
176 extern int __fscache_register_netfs(struct fscache_netfs *);
177 extern void __fscache_unregister_netfs(struct fscache_netfs *);
178 extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *);
179 extern void __fscache_release_cache_tag(struct fscache_cache_tag *);
180 
182  struct fscache_cookie *,
183  const struct fscache_cookie_def *,
184  void *);
185 extern void __fscache_relinquish_cookie(struct fscache_cookie *, int);
186 extern void __fscache_update_cookie(struct fscache_cookie *);
187 extern int __fscache_attr_changed(struct fscache_cookie *);
188 extern int __fscache_read_or_alloc_page(struct fscache_cookie *,
189  struct page *,
191  void *,
192  gfp_t);
194  struct address_space *,
195  struct list_head *,
196  unsigned *,
198  void *,
199  gfp_t);
200 extern int __fscache_alloc_page(struct fscache_cookie *, struct page *, gfp_t);
201 extern int __fscache_write_page(struct fscache_cookie *, struct page *, gfp_t);
202 extern void __fscache_uncache_page(struct fscache_cookie *, struct page *);
203 extern bool __fscache_check_page_write(struct fscache_cookie *, struct page *);
204 extern void __fscache_wait_on_page_write(struct fscache_cookie *, struct page *);
205 extern bool __fscache_maybe_release_page(struct fscache_cookie *, struct page *,
206  gfp_t);
208  struct inode *);
209 
219 static inline
220 int fscache_register_netfs(struct fscache_netfs *netfs)
221 {
222  if (fscache_available())
223  return __fscache_register_netfs(netfs);
224  else
225  return 0;
226 }
227 
239 static inline
240 void fscache_unregister_netfs(struct fscache_netfs *netfs)
241 {
242  if (fscache_available())
244 }
245 
256 static inline
257 struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
258 {
259  if (fscache_available())
260  return __fscache_lookup_cache_tag(name);
261  else
262  return NULL;
263 }
264 
274 static inline
275 void fscache_release_cache_tag(struct fscache_cache_tag *tag)
276 {
277  if (fscache_available())
279 }
280 
295 static inline
296 struct fscache_cookie *fscache_acquire_cookie(
297  struct fscache_cookie *parent,
298  const struct fscache_cookie_def *def,
299  void *netfs_data)
300 {
301  if (fscache_cookie_valid(parent))
302  return __fscache_acquire_cookie(parent, def, netfs_data);
303  else
304  return NULL;
305 }
306 
319 static inline
320 void fscache_relinquish_cookie(struct fscache_cookie *cookie, int retire)
321 {
322  if (fscache_cookie_valid(cookie))
323  __fscache_relinquish_cookie(cookie, retire);
324 }
325 
336 static inline
337 void fscache_update_cookie(struct fscache_cookie *cookie)
338 {
339  if (fscache_cookie_valid(cookie))
340  __fscache_update_cookie(cookie);
341 }
342 
352 static inline
353 int fscache_pin_cookie(struct fscache_cookie *cookie)
354 {
355  return -ENOBUFS;
356 }
357 
367 static inline
368 void fscache_unpin_cookie(struct fscache_cookie *cookie)
369 {
370 }
371 
383 static inline
384 int fscache_attr_changed(struct fscache_cookie *cookie)
385 {
386  if (fscache_cookie_valid(cookie))
387  return __fscache_attr_changed(cookie);
388  else
389  return -ENOBUFS;
390 }
391 
404 static inline
405 int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
406 {
407  return -ENOBUFS;
408 }
409 
439 static inline
440 int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
441  struct page *page,
442  fscache_rw_complete_t end_io_func,
443  void *context,
444  gfp_t gfp)
445 {
446  if (fscache_cookie_valid(cookie))
447  return __fscache_read_or_alloc_page(cookie, page, end_io_func,
448  context, gfp);
449  else
450  return -ENOBUFS;
451 }
452 
488 static inline
489 int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
490  struct address_space *mapping,
491  struct list_head *pages,
492  unsigned *nr_pages,
493  fscache_rw_complete_t end_io_func,
494  void *context,
495  gfp_t gfp)
496 {
497  if (fscache_cookie_valid(cookie))
498  return __fscache_read_or_alloc_pages(cookie, mapping, pages,
499  nr_pages, end_io_func,
500  context, gfp);
501  else
502  return -ENOBUFS;
503 }
504 
523 static inline
524 int fscache_alloc_page(struct fscache_cookie *cookie,
525  struct page *page,
526  gfp_t gfp)
527 {
528  if (fscache_cookie_valid(cookie))
529  return __fscache_alloc_page(cookie, page, gfp);
530  else
531  return -ENOBUFS;
532 }
533 
552 static inline
553 int fscache_write_page(struct fscache_cookie *cookie,
554  struct page *page,
555  gfp_t gfp)
556 {
557  if (fscache_cookie_valid(cookie))
558  return __fscache_write_page(cookie, page, gfp);
559  else
560  return -ENOBUFS;
561 }
562 
577 static inline
578 void fscache_uncache_page(struct fscache_cookie *cookie,
579  struct page *page)
580 {
581  if (fscache_cookie_valid(cookie))
582  __fscache_uncache_page(cookie, page);
583 }
584 
595 static inline
596 bool fscache_check_page_write(struct fscache_cookie *cookie,
597  struct page *page)
598 {
599  if (fscache_cookie_valid(cookie))
600  return __fscache_check_page_write(cookie, page);
601  return false;
602 }
603 
615 static inline
616 void fscache_wait_on_page_write(struct fscache_cookie *cookie,
617  struct page *page)
618 {
619  if (fscache_cookie_valid(cookie))
620  __fscache_wait_on_page_write(cookie, page);
621 }
622 
638 static inline
639 bool fscache_maybe_release_page(struct fscache_cookie *cookie,
640  struct page *page,
641  gfp_t gfp)
642 {
643  if (fscache_cookie_valid(cookie) && PageFsCache(page))
644  return __fscache_maybe_release_page(cookie, page, gfp);
645  return false;
646 }
647 
659 static inline
660 void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,
661  struct inode *inode)
662 {
663  if (fscache_cookie_valid(cookie))
664  __fscache_uncache_all_inode_pages(cookie, inode);
665 }
666 
667 #endif /* _LINUX_FSCACHE_H */