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