1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /* General filesystem caching backing cache interface
3 *
4 * Copyright (C) 2021 Red Hat, Inc. All Rights Reserved.
5 * Written by David Howells (dhowells@redhat.com)
6 *
7 * NOTE!!! See:
8 *
9 * Documentation/filesystems/caching/backend-api.rst
10 *
11 * for a description of the cache backend interface declared here.
12 */
13
14 #ifndef _LINUX_FSCACHE_CACHE_H
15 #define _LINUX_FSCACHE_CACHE_H
16
17 #include <linux/fscache.h>
18
19 enum fscache_cache_trace;
20 enum fscache_cookie_trace;
21 enum fscache_access_trace;
22 enum fscache_volume_trace;
23
24 enum fscache_cache_state {
25 FSCACHE_CACHE_IS_NOT_PRESENT, /* No cache is present for this name */
26 FSCACHE_CACHE_IS_PREPARING, /* A cache is preparing to come live */
27 FSCACHE_CACHE_IS_ACTIVE, /* Attached cache is active and can be used */
28 FSCACHE_CACHE_GOT_IOERROR, /* Attached cache stopped on I/O error */
29 FSCACHE_CACHE_IS_WITHDRAWN, /* Attached cache is being withdrawn */
30 #define NR__FSCACHE_CACHE_STATE (FSCACHE_CACHE_IS_WITHDRAWN + 1)
31 };
32
33 /*
34 * Cache cookie.
35 */
36 struct fscache_cache {
37 const struct fscache_cache_ops *ops;
38 struct list_head cache_link; /* Link in cache list */
39 void *cache_priv; /* Private cache data (or NULL) */
40 refcount_t ref;
41 atomic_t n_volumes; /* Number of active volumes; */
42 atomic_t n_accesses; /* Number of in-progress accesses on the cache */
43 atomic_t object_count; /* no. of live objects in this cache */
44 unsigned int debug_id;
45 enum fscache_cache_state state;
46 char *name;
47 };
48
49 /*
50 * cache operations
51 */
52 struct fscache_cache_ops {
53 /* name of cache provider */
54 const char *name;
55
56 /* Acquire a volume */
57 void (*acquire_volume)(struct fscache_volume *volume);
58
59 /* Free the cache's data attached to a volume */
60 void (*free_volume)(struct fscache_volume *volume);
61
62 /* Look up a cookie in the cache */
63 bool (*lookup_cookie)(struct fscache_cookie *cookie);
64
65 /* Withdraw an object without any cookie access counts held */
66 void (*withdraw_cookie)(struct fscache_cookie *cookie);
67
68 /* Change the size of a data object */
69 void (*resize_cookie)(struct netfs_cache_resources *cres,
70 loff_t new_size);
71
72 /* Invalidate an object */
73 bool (*invalidate_cookie)(struct fscache_cookie *cookie);
74
75 /* Begin an operation for the netfs lib */
76 bool (*begin_operation)(struct netfs_cache_resources *cres,
77 enum fscache_want_state want_state);
78
79 /* Prepare to write to a live cache object */
80 void (*prepare_to_write)(struct fscache_cookie *cookie);
81 };
82
83 extern struct workqueue_struct *fscache_wq;
84 extern wait_queue_head_t fscache_clearance_waiters;
85
86 /*
87 * out-of-line cache backend functions
88 */
89 extern struct rw_semaphore fscache_addremove_sem;
90 extern struct fscache_cache *fscache_acquire_cache(const char *name);
91 extern void fscache_relinquish_cache(struct fscache_cache *cache);
92 extern int fscache_add_cache(struct fscache_cache *cache,
93 const struct fscache_cache_ops *ops,
94 void *cache_priv);
95 extern void fscache_withdraw_cache(struct fscache_cache *cache);
96 extern void fscache_withdraw_volume(struct fscache_volume *volume);
97 extern void fscache_withdraw_cookie(struct fscache_cookie *cookie);
98
99 extern void fscache_io_error(struct fscache_cache *cache);
100
101 extern struct fscache_volume *
102 fscache_try_get_volume(struct fscache_volume *volume,
103 enum fscache_volume_trace where);
104 extern void fscache_put_volume(struct fscache_volume *volume,
105 enum fscache_volume_trace where);
106 extern void fscache_end_volume_access(struct fscache_volume *volume,
107 struct fscache_cookie *cookie,
108 enum fscache_access_trace why);
109
110 extern struct fscache_cookie *fscache_get_cookie(struct fscache_cookie *cookie,
111 enum fscache_cookie_trace where);
112 extern void fscache_put_cookie(struct fscache_cookie *cookie,
113 enum fscache_cookie_trace where);
114 extern void fscache_end_cookie_access(struct fscache_cookie *cookie,
115 enum fscache_access_trace why);
116 extern void fscache_cookie_lookup_negative(struct fscache_cookie *cookie);
117 extern void fscache_resume_after_invalidation(struct fscache_cookie *cookie);
118 extern void fscache_caching_failed(struct fscache_cookie *cookie);
119 extern bool fscache_wait_for_operation(struct netfs_cache_resources *cred,
120 enum fscache_want_state state);
121
122 /**
123 * fscache_cookie_state - Read the state of a cookie
124 * @cookie: The cookie to query
125 *
126 * Get the state of a cookie, imposing an ordering between the cookie contents
127 * and the state value. Paired with fscache_set_cookie_state().
128 */
129 static inline
fscache_cookie_state(struct fscache_cookie * cookie)130 enum fscache_cookie_state fscache_cookie_state(struct fscache_cookie *cookie)
131 {
132 return smp_load_acquire(&cookie->state);
133 }
134
135 /**
136 * fscache_get_key - Get a pointer to the cookie key
137 * @cookie: The cookie to query
138 *
139 * Return a pointer to the where a cookie's key is stored.
140 */
fscache_get_key(struct fscache_cookie * cookie)141 static inline void *fscache_get_key(struct fscache_cookie *cookie)
142 {
143 if (cookie->key_len <= sizeof(cookie->inline_key))
144 return cookie->inline_key;
145 else
146 return cookie->key;
147 }
148
fscache_cres_cookie(struct netfs_cache_resources * cres)149 static inline struct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres)
150 {
151 return cres->cache_priv;
152 }
153
154 /**
155 * fscache_count_object - Tell fscache that an object has been added
156 * @cache: The cache to account to
157 *
158 * Tell fscache that an object has been added to the cache. This prevents the
159 * cache from tearing down the cache structure until the object is uncounted.
160 */
fscache_count_object(struct fscache_cache * cache)161 static inline void fscache_count_object(struct fscache_cache *cache)
162 {
163 atomic_inc(&cache->object_count);
164 }
165
166 /**
167 * fscache_uncount_object - Tell fscache that an object has been removed
168 * @cache: The cache to account to
169 *
170 * Tell fscache that an object has been removed from the cache and will no
171 * longer be accessed. After this point, the cache cookie may be destroyed.
172 */
fscache_uncount_object(struct fscache_cache * cache)173 static inline void fscache_uncount_object(struct fscache_cache *cache)
174 {
175 if (atomic_dec_and_test(&cache->object_count))
176 wake_up_all(&fscache_clearance_waiters);
177 }
178
179 /**
180 * fscache_wait_for_objects - Wait for all objects to be withdrawn
181 * @cache: The cache to query
182 *
183 * Wait for all extant objects in a cache to finish being withdrawn
184 * and go away.
185 */
fscache_wait_for_objects(struct fscache_cache * cache)186 static inline void fscache_wait_for_objects(struct fscache_cache *cache)
187 {
188 wait_event(fscache_clearance_waiters,
189 atomic_read(&cache->object_count) == 0);
190 }
191
192 #ifdef CONFIG_FSCACHE_STATS
193 extern atomic_t fscache_n_read;
194 extern atomic_t fscache_n_write;
195 extern atomic_t fscache_n_no_write_space;
196 extern atomic_t fscache_n_no_create_space;
197 extern atomic_t fscache_n_culled;
198 #define fscache_count_read() atomic_inc(&fscache_n_read)
199 #define fscache_count_write() atomic_inc(&fscache_n_write)
200 #define fscache_count_no_write_space() atomic_inc(&fscache_n_no_write_space)
201 #define fscache_count_no_create_space() atomic_inc(&fscache_n_no_create_space)
202 #define fscache_count_culled() atomic_inc(&fscache_n_culled)
203 #else
204 #define fscache_count_read() do {} while(0)
205 #define fscache_count_write() do {} while(0)
206 #define fscache_count_no_write_space() do {} while(0)
207 #define fscache_count_no_create_space() do {} while(0)
208 #define fscache_count_culled() do {} while(0)
209 #endif
210
211 #endif /* _LINUX_FSCACHE_CACHE_H */
212