1 /* fscache.h: general filesystem caching interface
3 * Copyright (C) 2004-5 Red Hat, Inc. All Rights Reserved.
4 * Written by David Howells (dhowells@redhat.com)
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.
13 * Documentation/filesystems/caching/netfs-api.txt
15 * for a description of the network filesystem interface declared here.
18 #ifndef _LINUX_FSCACHE_H
19 #define _LINUX_FSCACHE_H
22 #include <linux/list.h>
23 #include <linux/pagemap.h>
24 #include <linux/pagevec.h>
27 struct fscache_cache_tag;
28 struct fscache_cookie;
30 struct fscache_netfs_operations;
32 typedef void (*fscache_rw_complete_t)(struct page *page,
36 /* result of index entry consultation */
38 FSCACHE_CHECKAUX_OKAY, /* entry okay as is */
39 FSCACHE_CHECKAUX_NEEDS_UPDATE, /* entry requires update */
40 FSCACHE_CHECKAUX_OBSOLETE, /* entry requires deletion */
43 /*****************************************************************************/
45 * fscache cookie definition
47 struct fscache_cookie_def
49 /* name of cookie type */
54 #define FSCACHE_COOKIE_TYPE_INDEX 0
55 #define FSCACHE_COOKIE_TYPE_DATAFILE 1
57 /* select the cache into which to insert an entry in this index
59 * - should return a cache identifier or NULL to cause the cache to be
60 * inherited from the parent if possible or the first cache picked
61 * for a non-index file if not
63 struct fscache_cache_tag *(*select_cache)(const void *parent_netfs_data,
64 const void *cookie_netfs_data);
67 * - should store the key data in the buffer
68 * - should return the amount of amount stored
69 * - not permitted to return an error
70 * - the netfs data from the cookie being used as the source is
73 uint16_t (*get_key)(const void *cookie_netfs_data,
77 /* get certain file attributes from the netfs data
78 * - this function can be absent for an index
79 * - not permitted to return an error
80 * - the netfs data from the cookie being used as the source is
83 void (*get_attr)(const void *cookie_netfs_data, uint64_t *size);
85 /* get the auxilliary data from netfs data
86 * - this function can be absent if the index carries no state data
87 * - should store the auxilliary data in the buffer
88 * - should return the amount of amount stored
89 * - not permitted to return an error
90 * - the netfs data from the cookie being used as the source is
93 uint16_t (*get_aux)(const void *cookie_netfs_data,
97 /* consult the netfs about the state of an object
98 * - this function can be absent if the index carries no state data
99 * - the netfs data from the cookie being used as the target is
100 * presented, as is the auxilliary data
102 fscache_checkaux_t (*check_aux)(void *cookie_netfs_data,
106 /* get an extra reference on a read context
107 * - this function can be absent if the completion function doesn't
110 void (*get_context)(void *cookie_netfs_data, void *context);
112 /* release an extra reference on a read context
113 * - this function can be absent if the completion function doesn't
116 void (*put_context)(void *cookie_netfs_data, void *context);
118 /* indicate pages that now have cache metadata retained
119 * - this function should mark the specified pages as now being cached
121 void (*mark_pages_cached)(void *cookie_netfs_data,
122 struct address_space *mapping,
123 struct pagevec *cached_pvec);
125 /* indicate the cookie is no longer cached
126 * - this function is called when the backing store currently caching
127 * a cookie is removed
128 * - the netfs should use this to clean up any markers indicating
130 * - this is mandatory for any object that may have data
132 void (*now_uncached)(void *cookie_netfs_data);
135 /* pattern used to fill dead space in an index entry */
136 #define FSCACHE_INDEX_DEADFILL_PATTERN 0x79
138 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
139 extern struct fscache_cookie *__fscache_acquire_cookie(struct fscache_cookie *parent,
140 struct fscache_cookie_def *def,
143 extern void __fscache_relinquish_cookie(struct fscache_cookie *cookie,
146 extern void __fscache_update_cookie(struct fscache_cookie *cookie);
150 struct fscache_cookie *fscache_acquire_cookie(struct fscache_cookie *parent,
151 struct fscache_cookie_def *def,
154 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
156 return __fscache_acquire_cookie(parent, def, netfs_data);
162 void fscache_relinquish_cookie(struct fscache_cookie *cookie,
165 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
167 __fscache_relinquish_cookie(cookie, retire);
172 void fscache_update_cookie(struct fscache_cookie *cookie)
174 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
176 __fscache_update_cookie(cookie);
180 /*****************************************************************************/
182 * pin or unpin a cookie in a cache
183 * - only available for data cookies
185 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
186 extern int __fscache_pin_cookie(struct fscache_cookie *cookie);
187 extern void __fscache_unpin_cookie(struct fscache_cookie *cookie);
191 int fscache_pin_cookie(struct fscache_cookie *cookie)
193 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
195 return __fscache_pin_cookie(cookie);
201 void fscache_unpin_cookie(struct fscache_cookie *cookie)
203 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
205 __fscache_unpin_cookie(cookie);
209 /*****************************************************************************/
211 * fscache cached network filesystem type
212 * - name, version and ops must be filled in before registration
213 * - all other fields will be set during registration
217 uint32_t version; /* indexing version */
218 const char *name; /* filesystem name */
219 struct fscache_cookie *primary_index;
220 struct fscache_netfs_operations *ops;
221 struct list_head link; /* internal link */
224 struct fscache_netfs_operations
228 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
229 extern int __fscache_register_netfs(struct fscache_netfs *netfs);
230 extern void __fscache_unregister_netfs(struct fscache_netfs *netfs);
234 int fscache_register_netfs(struct fscache_netfs *netfs)
236 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
237 return __fscache_register_netfs(netfs);
244 void fscache_unregister_netfs(struct fscache_netfs *netfs)
246 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
247 __fscache_unregister_netfs(netfs);
251 /*****************************************************************************/
253 * look up a cache tag
254 * - cache tags are used to select specific caches in which to cache indexes
256 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
257 extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *name);
258 extern void __fscache_release_cache_tag(struct fscache_cache_tag *tag);
262 struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
264 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
265 return __fscache_lookup_cache_tag(name);
272 void fscache_release_cache_tag(struct fscache_cache_tag *tag)
274 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
275 __fscache_release_cache_tag(tag);
279 /*****************************************************************************/
281 * set the data size on a cached object
282 * - no pages beyond the end of the object will be accessible
283 * - returns -ENOBUFS if the file is not backed
284 * - returns -ENOSPC if a pinned file of that size can't be stored
285 * - returns 0 if okay
287 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
288 extern int __fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size);
292 int fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size)
294 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
296 return __fscache_set_i_size(cookie, i_size);
301 /*****************************************************************************/
303 * reserve data space for a cached object
304 * - returns -ENOBUFS if the file is not backed
305 * - returns -ENOSPC if there isn't enough space to honour the reservation
306 * - returns 0 if okay
308 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
309 extern int __fscache_reserve_space(struct fscache_cookie *cookie, loff_t size);
313 int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
315 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
317 return __fscache_reserve_space(cookie, size);
322 /*****************************************************************************/
324 * read a page from the cache or allocate a block in which to store it
325 * - if the page is not backed by a file:
326 * - -ENOBUFS will be returned and nothing more will be done
327 * - else if the page is backed by a block in the cache:
328 * - a read will be started which will call end_io_func on completion
329 * - else if the page is unbacked:
330 * - a block will be allocated
331 * - -ENODATA will be returned
333 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
334 extern int __fscache_read_or_alloc_page(struct fscache_cookie *cookie,
336 fscache_rw_complete_t end_io_func,
342 int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
344 fscache_rw_complete_t end_io_func,
348 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
350 return __fscache_read_or_alloc_page(cookie, page, end_io_func,
356 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
357 extern int __fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
358 struct address_space *mapping,
359 struct list_head *pages,
361 fscache_rw_complete_t end_io_func,
367 int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
368 struct address_space *mapping,
369 struct list_head *pages,
371 fscache_rw_complete_t end_io_func,
375 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
377 return __fscache_read_or_alloc_pages(cookie, mapping, pages,
378 nr_pages, end_io_func,
385 * allocate a block in which to store a page
386 * - if the page is not backed by a file:
387 * - -ENOBUFS will be returned and nothing more will be done
389 * - a block will be allocated if there isn't one
390 * - 0 will be returned
392 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
393 extern int __fscache_alloc_page(struct fscache_cookie *cookie,
399 int fscache_alloc_page(struct fscache_cookie *cookie,
403 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
405 return __fscache_alloc_page(cookie, page, gfp);
411 * request a page be stored in the cache
412 * - this request may be ignored if no cache block is currently allocated, in
415 * - if a cache block was already allocated:
416 * - a BIO will be dispatched to write the page (end_io_func will be called
417 * from the completion function)
420 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
421 extern int __fscache_write_page(struct fscache_cookie *cookie,
423 fscache_rw_complete_t end_io_func,
427 extern int __fscache_write_pages(struct fscache_cookie *cookie,
428 struct pagevec *pagevec,
429 fscache_rw_complete_t end_io_func,
435 int fscache_write_page(struct fscache_cookie *cookie,
437 fscache_rw_complete_t end_io_func,
441 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
443 return __fscache_write_page(cookie, page, end_io_func,
450 int fscache_write_pages(struct fscache_cookie *cookie,
451 struct pagevec *pagevec,
452 fscache_rw_complete_t end_io_func,
456 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
458 return __fscache_write_pages(cookie, pagevec, end_io_func,
465 * indicate that caching is no longer required on a page
466 * - note: cannot cancel any outstanding BIOs between this page and the cache
468 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
469 extern void __fscache_uncache_page(struct fscache_cookie *cookie,
471 extern void __fscache_uncache_pages(struct fscache_cookie *cookie,
472 struct pagevec *pagevec);
476 void fscache_uncache_page(struct fscache_cookie *cookie,
479 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
481 __fscache_uncache_page(cookie, page);
486 void fscache_uncache_pagevec(struct fscache_cookie *cookie,
487 struct pagevec *pagevec)
489 #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
491 __fscache_uncache_pages(cookie, pagevec);
495 #endif /* _LINUX_FSCACHE_H */