1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ================= !! 3 ==========================
4 Cache Backend API !! 4 FS-Cache Cache backend API
5 ================= !! 5 ==========================
6 6
7 The FS-Cache system provides an API by which a 7 The FS-Cache system provides an API by which actual caches can be supplied to
8 FS-Cache for it to then serve out to network f 8 FS-Cache for it to then serve out to network filesystems and other interested
9 parties. This API is used by:: !! 9 parties.
10 10
11 #include <linux/fscache-cache.h>. !! 11 This API is declared in <linux/fscache-cache.h>.
12 12
13 13
14 Overview !! 14 Initialising and Registering a Cache
15 ======== !! 15 ====================================
16 16
17 Interaction with the API is handled on three l !! 17 To start off, a cache definition must be initialised and registered for each
18 storage, and each level has its own type of co !! 18 cache the backend wants to make available. For instance, CacheFS does this in
>> 19 the fill_super() operation on mounting.
19 20
20 ======================= ============== !! 21 The cache definition (struct fscache_cache) should be initialised by calling::
21 COOKIE C TYPE <<
22 ======================= ============== <<
23 Cache cookie struct fscache <<
24 Volume cookie struct fscache <<
25 Data storage cookie struct fscache <<
26 ======================= ============== <<
27 <<
28 Cookies are used to provide some filesystem da <<
29 pin the cache during access in addition to act <<
30 API functions. Each cookie has a debugging ID <<
31 to make it easier to correlate traces. Note, <<
32 simply allocated from incrementing counters an <<
33 <<
34 The cache backend and the network filesystem c <<
35 and if they ask for one of the same name, they <<
36 and data cookies, however, are created at the <<
37 <<
38 <<
39 Cache Cookies <<
40 ============= <<
41 <<
42 Caches are represented in the API by cache coo <<
43 type:: <<
44 <<
45 struct fscache_cache { <<
46 void *cache_priv; <<
47 unsigned int debug_id; <<
48 char *name; <<
49 ... <<
50 }; <<
51 22
52 There are a few fields that the cache backend !! 23 void fscache_init_cache(struct fscache_cache *cache,
53 ``debug_id`` can be used in tracing to match l !! 24 struct fscache_cache_ops *ops,
54 and ``name`` is the name the cache was registe !! 25 const char *idfmt,
55 member is private data provided by the cache w !! 26 ...);
56 other fields are for internal use. <<
57 27
>> 28 Where:
58 29
59 Registering a Cache !! 30 * "cache" is a pointer to the cache definition;
60 =================== <<
61 31
62 When a cache backend wants to bring a cache on !! 32 * "ops" is a pointer to the table of operations that the backend supports on
63 the cache name and that will get it a cache co !! 33 this cache; and
64 34
65 struct fscache_cache *fscache_acquire_ !! 35 * "idfmt" is a format and printf-style arguments for constructing a label
>> 36 for the cache.
66 37
67 This will look up and potentially create a cac <<
68 have already been created by a network filesys <<
69 that cache cookie will be used. If the cache <<
70 cache, it will be moved into the preparing sta <<
71 busy. <<
72 38
73 If successful, the cache backend can then star !! 39 The cache should then be registered with FS-Cache by passing a pointer to the
74 event that the initialisation fails, the cache !! 40 previously initialised cache definition to::
75 41
76 void fscache_relinquish_cache(struct f !! 42 int fscache_add_cache(struct fscache_cache *cache,
>> 43 struct fscache_object *fsdef,
>> 44 const char *tagname);
77 45
78 to reset and discard the cookie. !! 46 Two extra arguments should also be supplied:
79 47
>> 48 * "fsdef" which should point to the object representation for the FS-Cache
>> 49 master index in this cache. Netfs primary index entries will be created
>> 50 here. FS-Cache keeps the caller's reference to the index object if
>> 51 successful and will release it upon withdrawal of the cache.
80 52
81 Bringing a Cache Online !! 53 * "tagname" which, if given, should be a text string naming this cache. If
82 ======================= !! 54 this is NULL, the identifier will be used instead. For CacheFS, the
>> 55 identifier is set to name the underlying block device and the tag can be
>> 56 supplied by mount.
83 57
84 Once the cache is set up, it can be brought on !! 58 This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag
>> 59 is already in use. 0 will be returned on success.
85 60
86 int fscache_add_cache(struct fscache_c <<
87 const struct fsc <<
88 void *cache_priv <<
89 61
90 This stores the cache operations table pointer !! 62 Unregistering a Cache
91 cache cookie and moves the cache to the active !! 63 =====================
92 to take place. <<
93 64
>> 65 A cache can be withdrawn from the system by calling this function with a
>> 66 pointer to the cache definition::
94 67
95 Withdrawing a Cache From Service !! 68 void fscache_withdraw_cache(struct fscache_cache *cache);
96 ================================ <<
97 69
98 The cache backend can withdraw a cache from se !! 70 In CacheFS's case, this is called by put_super().
99 71
100 void fscache_withdraw_cache(struct fsc <<
101 72
102 This moves the cache to the withdrawn state to !! 73 Security
103 volume-level accesses from starting and then w !! 74 ========
104 accesses to complete. <<
105 75
106 The cache must then go through the data storag !! 76 The cache methods are executed one of two contexts:
107 to withdraw them, calling:: <<
108 77
109 void fscache_withdraw_cookie(struct fs !! 78 (1) that of the userspace process that issued the netfs operation that caused
>> 79 the cache method to be invoked, or
110 80
111 on the cookie that each object belongs to. Th !! 81 (2) that of one of the processes in the FS-Cache thread pool.
112 for withdrawal. This gets offloaded to a work <<
113 wait for completion by calling:: <<
114 82
115 void fscache_wait_for_objects(struct f !! 83 In either case, this may not be an appropriate context in which to access the
>> 84 cache.
116 85
117 Once all the cookies are withdrawn, a cache ba !! 86 The calling process's fsuid, fsgid and SELinux security identities may need to
118 volumes, calling:: !! 87 be masqueraded for the duration of the cache driver's access to the cache.
>> 88 This is left to the cache to handle; FS-Cache makes no effort in this regard.
119 89
120 void fscache_withdraw_volume(struct fs <<
121 90
122 to tell fscache that a volume has been withdra !! 91 Control and Statistics Presentation
123 outstanding accesses on the volume to complete !! 92 ===================================
124 93
125 When the cache is completely withdrawn, fscach !! 94 The cache may present data to the outside world through FS-Cache's interfaces
126 calling:: !! 95 in sysfs and procfs - the former for control and the latter for statistics.
127 96
128 void fscache_relinquish_cache(struct f !! 97 A sysfs directory called /sys/fs/fscache/<cachetag>/ is created if CONFIG_SYSFS
>> 98 is enabled. This is accessible through the kobject struct fscache_cache::kobj
>> 99 and is for use by the cache as it sees fit.
129 100
130 to clear fields in the cookie and discard the <<
131 101
>> 102 Relevant Data Structures
>> 103 ========================
132 104
133 Volume Cookies !! 105 * Index/Data file FS-Cache representation cookie::
134 ============== <<
135 106
136 Within a cache, the data storage objects are o !! 107 struct fscache_cookie {
137 These are represented in the API as objects of !! 108 struct fscache_object_def *def;
>> 109 struct fscache_netfs *netfs;
>> 110 void *netfs_data;
>> 111 ...
>> 112 };
138 113
139 struct fscache_volume { !! 114 The fields that might be of use to the backend describe the object
>> 115 definition, the netfs definition and the netfs's data for this cookie.
>> 116 The object definition contain functions supplied by the netfs for loading
>> 117 and matching index entries; these are required to provide some of the
>> 118 cache operations.
>> 119
>> 120
>> 121 * In-cache object representation::
>> 122
>> 123 struct fscache_object {
>> 124 int debug_id;
>> 125 enum {
>> 126 FSCACHE_OBJECT_RECYCLING,
>> 127 ...
>> 128 } state;
>> 129 spinlock_t lock
140 struct fscache_cache 130 struct fscache_cache *cache;
141 void !! 131 struct fscache_cookie *cookie;
142 unsigned int <<
143 char <<
144 unsigned int <<
145 ... 132 ...
146 u8 <<
147 u8 <<
148 }; 133 };
149 134
150 There are a number of fields here that are of !! 135 Structures of this type should be allocated by the cache backend and
>> 136 passed to FS-Cache when requested by the appropriate cache operation. In
>> 137 the case of CacheFS, they're embedded in CacheFS's internal object
>> 138 structures.
>> 139
>> 140 The debug_id is a simple integer that can be used in debugging messages
>> 141 that refer to a particular object. In such a case it should be printed
>> 142 using "OBJ%x" to be consistent with FS-Cache.
>> 143
>> 144 Each object contains a pointer to the cookie that represents the object it
>> 145 is backing. An object should retired when put_object() is called if it is
>> 146 in state FSCACHE_OBJECT_RECYCLING. The fscache_object struct should be
>> 147 initialised by calling fscache_object_init(object).
>> 148
>> 149
>> 150 * FS-Cache operation record::
>> 151
>> 152 struct fscache_operation {
>> 153 atomic_t usage;
>> 154 struct fscache_object *object;
>> 155 unsigned long flags;
>> 156 #define FSCACHE_OP_EXCLUSIVE
>> 157 void (*processor)(struct fscache_operation *op);
>> 158 void (*release)(struct fscache_operation *op);
>> 159 ...
>> 160 };
151 161
152 * ``cache`` - The parent cache cookie. !! 162 FS-Cache has a pool of threads that it uses to give CPU time to the
>> 163 various asynchronous operations that need to be done as part of driving
>> 164 the cache. These are represented by the above structure. The processor
>> 165 method is called to give the op CPU time, and the release method to get
>> 166 rid of it when its usage count reaches 0.
>> 167
>> 168 An operation can be made exclusive upon an object by setting the
>> 169 appropriate flag before enqueuing it with fscache_enqueue_operation(). If
>> 170 an operation needs more processing time, it should be enqueued again.
>> 171
>> 172
>> 173 * FS-Cache retrieval operation record::
>> 174
>> 175 struct fscache_retrieval {
>> 176 struct fscache_operation op;
>> 177 struct address_space *mapping;
>> 178 struct list_head *to_do;
>> 179 ...
>> 180 };
153 181
154 * ``cache_priv`` - A place for the cache to !! 182 A structure of this type is allocated by FS-Cache to record retrieval and
>> 183 allocation requests made by the netfs. This struct is then passed to the
>> 184 backend to do the operation. The backend may get extra refs to it by
>> 185 calling fscache_get_retrieval() and refs may be discarded by calling
>> 186 fscache_put_retrieval().
>> 187
>> 188 A retrieval operation can be used by the backend to do retrieval work. To
>> 189 do this, the retrieval->op.processor method pointer should be set
>> 190 appropriately by the backend and fscache_enqueue_retrieval() called to
>> 191 submit it to the thread pool. CacheFiles, for example, uses this to queue
>> 192 page examination when it detects PG_lock being cleared.
>> 193
>> 194 The to_do field is an empty list available for the cache backend to use as
>> 195 it sees fit.
>> 196
>> 197
>> 198 * FS-Cache storage operation record::
>> 199
>> 200 struct fscache_storage {
>> 201 struct fscache_operation op;
>> 202 pgoff_t store_limit;
>> 203 ...
>> 204 };
155 205
156 * ``debug_id`` - A debugging ID for logging !! 206 A structure of this type is allocated by FS-Cache to record outstanding
>> 207 writes to be made. FS-Cache itself enqueues this operation and invokes
>> 208 the write_page() method on the object at appropriate times to effect
>> 209 storage.
157 210
158 * ``key`` - A printable string with no '/' <<
159 the index key for the volume. The key is <<
160 a multiple of 4 bytes. <<
161 211
162 * ``key_hash`` - A hash of the index key. !! 212 Cache Operations
163 matter the cpu arch and endianness. !! 213 ================
164 214
165 * ``coherency`` - A piece of coherency data !! 215 The cache backend provides FS-Cache with a table of operations that can be
166 volume is bound to in the cache. !! 216 performed on the denizens of the cache. These are held in a structure of type:
167 217
168 * ``coherency_len`` - The amount of data in !! 218 ::
169 219
>> 220 struct fscache_cache_ops
170 221
171 Data Storage Cookies !! 222 * Name of cache provider [mandatory]::
172 ==================== <<
173 223
174 A volume is a logical group of data storage ob !! 224 const char *name
175 represented to the network filesystem by a coo <<
176 the API as objects of type:: <<
177 225
178 struct fscache_cookie { !! 226 This isn't strictly an operation, but should be pointed at a string naming
179 struct fscache_volume !! 227 the backend.
180 void <<
181 unsigned long <<
182 unsigned int <<
183 unsigned int <<
184 loff_t <<
185 u8 <<
186 u32 <<
187 u8 <<
188 u8 <<
189 ... <<
190 }; <<
191 228
192 The fields in the cookie that are of interest <<
193 229
194 * ``volume`` - The parent volume cookie. !! 230 * Allocate a new object [mandatory]::
195 231
196 * ``cache_priv`` - A place for the cache to !! 232 struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
>> 233 struct fscache_cookie *cookie)
197 234
198 * ``flags`` - A collection of bit flags, in !! 235 This method is used to allocate a cache object representation to back a
>> 236 cookie in a particular cache. fscache_object_init() should be called on
>> 237 the object to initialise it prior to returning.
199 238
200 * FSCACHE_COOKIE_NO_DATA_TO_READ - There !! 239 This function may also be used to parse the index key to be used for
201 cache to be read as the cookie has bee !! 240 multiple lookup calls to turn it into a more convenient form. FS-Cache
>> 241 will call the lookup_complete() method to allow the cache to release the
>> 242 form once lookup is complete or aborted.
202 243
203 * FSCACHE_COOKIE_NEEDS_UPDATE - The cohe <<
204 been changed and needs committing. <<
205 244
206 * FSCACHE_COOKIE_LOCAL_WRITE - The netfs !! 245 * Look up and create object [mandatory]::
207 locally, so the cache object may be in <<
208 to the server. <<
209 246
210 * FSCACHE_COOKIE_HAVE_DATA - The backend !! 247 void (*lookup_object)(struct fscache_object *object)
211 successfully stores data into the cach <<
212 248
213 * FSCACHE_COOKIE_RETIRED - The cookie wa !! 249 This method is used to look up an object, given that the object is already
214 relinquished and the cached data shoul !! 250 allocated and attached to the cookie. This should instantiate that object
>> 251 in the cache if it can.
215 252
216 * ``debug_id`` - A debugging ID for logging !! 253 The method should call fscache_object_lookup_negative() as soon as
>> 254 possible if it determines the object doesn't exist in the cache. If the
>> 255 object is found to exist and the netfs indicates that it is valid then
>> 256 fscache_obtained_object() should be called once the object is in a
>> 257 position to have data stored in it. Similarly, fscache_obtained_object()
>> 258 should also be called once a non-present object has been created.
217 259
218 * ``inval_counter`` - The number of invalid !! 260 If a lookup error occurs, fscache_object_lookup_error() should be called
>> 261 to abort the lookup of that object.
219 262
220 * ``advice`` - Information about how the co <<
221 263
222 * ``key_hash`` - A hash of the index key. !! 264 * Release lookup data [mandatory]::
223 matter the cpu arch and endianness. <<
224 265
225 * ``key_len`` - The length of the index key !! 266 void (*lookup_complete)(struct fscache_object *object)
226 267
227 * ``aux_len`` - The length of the coherency !! 268 This method is called to ask the cache to release any resources it was
>> 269 using to perform a lookup.
228 270
229 Each cookie has an index key, which may be sto <<
230 elsewhere. A pointer to this can be obtained <<
231 271
232 void *fscache_get_key(struct fscache_c !! 272 * Increment object refcount [mandatory]::
233 273
234 The index key is a binary blob, the storage fo !! 274 struct fscache_object *(*grab_object)(struct fscache_object *object)
235 multiple of 4 bytes. <<
236 275
237 Each cookie also has a buffer for coherency da !! 276 This method is called to increment the reference count on an object. It
238 detached from the cookie and a pointer is obta !! 277 may fail (for instance if the cache is being withdrawn) by returning NULL.
>> 278 It should return the object pointer if successful.
239 279
240 void *fscache_get_aux(struct fscache_c <<
241 280
>> 281 * Lock/Unlock object [mandatory]::
242 282
>> 283 void (*lock_object)(struct fscache_object *object)
>> 284 void (*unlock_object)(struct fscache_object *object)
243 285
244 Cookie Accounting !! 286 These methods are used to exclusively lock an object. It must be possible
245 ================= !! 287 to schedule with the lock held, so a spinlock isn't sufficient.
246 288
247 Data storage cookies are counted and this is u <<
248 completion until all objects have been destroy <<
249 provided to the cache to deal with that:: <<
250 289
251 void fscache_count_object(struct fscac !! 290 * Pin/Unpin object [optional]::
252 void fscache_uncount_object(struct fsc <<
253 void fscache_wait_for_objects(struct f <<
254 291
255 The count function records the allocation of a !! 292 int (*pin_object)(struct fscache_object *object)
256 uncount function records its destruction. War !! 293 void (*unpin_object)(struct fscache_object *object)
257 function returns, the cache may have been dest <<
258 294
259 The wait function can be used during the withd !! 295 These methods are used to pin an object into the cache. Once pinned an
260 fscache to finish withdrawing all the objects !! 296 object cannot be reclaimed to make space. Return -ENOSPC if there's not
261 there will be no remaining objects referring t !! 297 enough space in the cache to permit this.
262 objects. <<
263 298
264 299
265 Cache Management API !! 300 * Check coherency state of an object [mandatory]::
266 ==================== <<
267 301
268 The cache backend implements the cache managem !! 302 int (*check_consistency)(struct fscache_object *object)
269 operations that fscache can use to manage vari <<
270 are held in a structure of type:: <<
271 303
272 struct fscache_cache_ops { !! 304 This method is called to have the cache check the saved auxiliary data of
273 const char *name; !! 305 the object against the netfs's idea of the state. 0 should be returned
274 ... !! 306 if they're consistent and -ESTALE otherwise. -ENOMEM and -ERESTARTSYS
275 }; !! 307 may also be returned.
>> 308
>> 309 * Update object [mandatory]::
>> 310
>> 311 int (*update_object)(struct fscache_object *object)
>> 312
>> 313 This is called to update the index entry for the specified object. The
>> 314 new information should be in object->cookie->netfs_data. This can be
>> 315 obtained by calling object->cookie->def->get_aux()/get_attr().
276 316
277 This contains a printable name for the cache b <<
278 pointers to methods to allow fscache to reques <<
279 317
280 * Set up a volume cookie [optional]:: !! 318 * Invalidate data object [mandatory]::
281 319
282 void (*acquire_volume)(struct fscache_ !! 320 int (*invalidate_object)(struct fscache_operation *op)
283 321
284 This method is called when a volume cooki !! 322 This is called to invalidate a data object (as pointed to by op->object).
285 holds a cache-level access pin to prevent !! 323 All the data stored for this object should be discarded and an
286 the duration. This method should set up !! 324 attr_changed operation should be performed. The caller will follow up
287 in the cache and should not return until !! 325 with an object update operation.
288 326
289 If successful, it can set ``cache_priv`` !! 327 fscache_op_complete() must be called on op before returning.
290 328
291 329
292 * Clean up volume cookie [optional]:: !! 330 * Discard object [mandatory]::
293 331
294 void (*free_volume)(struct fscache_volu !! 332 void (*drop_object)(struct fscache_object *object)
295 333
296 This method is called when a volume cooki !! 334 This method is called to indicate that an object has been unbound from its
297 ``cache_priv`` is set. !! 335 cookie, and that the cache should release the object's resources and
>> 336 retire it if it's in state FSCACHE_OBJECT_RECYCLING.
298 337
>> 338 This method should not attempt to release any references held by the
>> 339 caller. The caller will invoke the put_object() method as appropriate.
299 340
300 * Look up a cookie in the cache [mandatory] <<
301 341
302 bool (*lookup_cookie)(struct fscache_c !! 342 * Release object reference [mandatory]::
303 343
304 This method is called to look up/create t !! 344 void (*put_object)(struct fscache_object *object)
305 data storage for a cookie. It is called <<
306 volume-level access pin in the cache to p <<
307 345
308 True should be returned if successful and !! 346 This method is used to discard a reference to an object. The object may
309 returned, the withdraw_cookie op (see bel !! 347 be freed when all the references to it are released.
310 348
311 If lookup fails, but the object could sti <<
312 been cached before), then:: <<
313 349
314 void fscache_cookie_lookup_neg !! 350 * Synchronise a cache [mandatory]::
315 struct fscache_cookie <<
316 351
317 can be called to let the network filesyst !! 352 void (*sync)(struct fscache_cache *cache)
318 stuff whilst the cache backend gets on wi <<
319 353
320 If successful, ``cookie->cache_priv`` can !! 354 This is called to ask the backend to synchronise a cache with its backing
>> 355 device.
321 356
322 357
323 * Withdraw an object without any cookie acc !! 358 * Dissociate a cache [mandatory]::
324 359
325 void (*withdraw_cookie)(struct fscache !! 360 void (*dissociate_pages)(struct fscache_cache *cache)
326 361
327 This method is called to withdraw a cooki !! 362 This is called to ask a cache to perform any page dissociations as part of
328 called when the cookie is relinquished by !! 363 cache withdrawal.
329 by the cache backend or closed after a pe <<
330 364
331 The caller doesn't hold any access pins, <<
332 non-reentrant work item to manage races b <<
333 withdrawal can occur. <<
334 365
335 The cookie will have the ``FSCACHE_COOKIE !! 366 * Notification that the attributes on a netfs file changed [mandatory]::
336 associated data is to be removed from the <<
337 367
>> 368 int (*attr_changed)(struct fscache_object *object);
338 369
339 * Change the size of a data storage object !! 370 This is called to indicate to the cache that certain attributes on a netfs
>> 371 file have changed (for example the maximum size a file may reach). The
>> 372 cache can read these from the netfs by calling the cookie's get_attr()
>> 373 method.
340 374
341 void (*resize_cookie)(struct netfs_cac !! 375 The cache may use the file size information to reserve space on the cache.
342 loff_t new_size) !! 376 It should also call fscache_set_store_limit() to indicate to FS-Cache the
>> 377 highest byte it's willing to store for an object.
343 378
344 This method is called to inform the cache !! 379 This method may return -ve if an error occurred or the cache object cannot
345 the netfs file due to local truncation. !! 380 be expanded. In such a case, the object will be withdrawn from service.
346 of the changes it needs to make before re <<
347 netfs inode mutex. <<
348 381
349 The caller holds a cookie-level access pi !! 382 This operation is run asynchronously from FS-Cache's thread pool, and
350 withdrawal and the netfs must have the co !! 383 storage and retrieval operations from the netfs are excluded during the
351 garbage collection or culling from removi !! 384 execution of this operation.
352 385
353 386
354 * Invalidate a data storage object [mandato !! 387 * Reserve cache space for an object's data [optional]::
355 388
356 bool (*invalidate_cookie)(struct fscac !! 389 int (*reserve_space)(struct fscache_object *object, loff_t size);
357 390
358 This is called when the network filesyste !! 391 This is called to request that cache space be reserved to hold the data
359 modification or when an O_DIRECT write is !! 392 for an object and the metadata used to track it. Zero size should be
360 that the cache backend should throw away !! 393 taken as request to cancel a reservation.
361 this object and start afresh. It should <<
362 false otherwise. <<
363 394
364 On entry, new I O/operations are blocked. !! 395 This should return 0 if successful, -ENOSPC if there isn't enough space
365 to accept I/O again, the backend should r !! 396 available, or -ENOMEM or -EIO on other errors.
366 397
367 void fscache_resume_after_invalidation !! 398 The reservation may exceed the current size of the object, thus permitting
>> 399 future expansion. If the amount of space consumed by an object would
>> 400 exceed the reservation, it's permitted to refuse requests to allocate
>> 401 pages, but not required. An object may be pruned down to its reservation
>> 402 size if larger than that already.
368 403
369 If the method returns false, caching will <<
370 404
>> 405 * Request page be read from cache [mandatory]::
371 406
372 * Prepare to make local modifications to th !! 407 int (*read_or_alloc_page)(struct fscache_retrieval *op,
>> 408 struct page *page,
>> 409 gfp_t gfp)
373 410
374 void (*prepare_to_write)(struct fscach !! 411 This is called to attempt to read a netfs page from the cache, or to
>> 412 reserve a backing block if not. FS-Cache will have done as much checking
>> 413 as it can before calling, but most of the work belongs to the backend.
375 414
376 This method is called when the network fi !! 415 If there's no page in the cache, then -ENODATA should be returned if the
377 to need to modify the contents of the cac !! 416 backend managed to reserve a backing block; -ENOBUFS or -ENOMEM if it
378 truncations. This gives the cache a chan !! 417 didn't.
379 may be incoherent with respect to the ser <<
380 later. This may also cause the cached da <<
381 rebinding if not properly committed. <<
382 418
>> 419 If there is suitable data in the cache, then a read operation should be
>> 420 queued and 0 returned. When the read finishes, fscache_end_io() should be
>> 421 called.
383 422
384 * Begin an operation for the netfs lib [man !! 423 The fscache_mark_pages_cached() should be called for the page if any cache
>> 424 metadata is retained. This will indicate to the netfs that the page needs
>> 425 explicit uncaching. This operation takes a pagevec, thus allowing several
>> 426 pages to be marked at once.
385 427
386 bool (*begin_operation)(struct netfs_c !! 428 The retrieval record pointed to by op should be retained for each page
387 enum fscache_w !! 429 queued and released when I/O on the page has been formally ended.
>> 430 fscache_get/put_retrieval() are available for this purpose.
388 431
389 This method is called when an I/O operati !! 432 The retrieval record may be used to get CPU time via the FS-Cache thread
390 or resize). The caller holds an access p !! 433 pool. If this is desired, the op->op.processor should be set to point to
391 marked the cookie as in-use. !! 434 the appropriate processing routine, and fscache_enqueue_retrieval() should
>> 435 be called at an appropriate point to request CPU time. For instance, the
>> 436 retrieval routine could be enqueued upon the completion of a disk read.
>> 437 The to_do field in the retrieval record is provided to aid in this.
392 438
393 If it can, the backend should attach any !! 439 If an I/O error occurs, fscache_io_error() should be called and -ENOBUFS
394 to the netfs_cache_resources object and r !! 440 returned if possible or fscache_end_io() called with a suitable error
>> 441 code.
395 442
396 If it can't complete the setup, it should !! 443 fscache_put_retrieval() should be called after a page or pages are dealt
>> 444 with. This will complete the operation when all pages are dealt with.
397 445
398 The want_state parameter indicates the st <<
399 object to be in and what it wants to do d <<
400 446
401 * ``FSCACHE_WANT_PARAMS`` - The caller !! 447 * Request pages be read from cache [mandatory]::
402 object parameters; it doesn't need t <<
403 448
404 * ``FSCACHE_WANT_READ`` - The caller w !! 449 int (*read_or_alloc_pages)(struct fscache_retrieval *op,
>> 450 struct list_head *pages,
>> 451 unsigned *nr_pages,
>> 452 gfp_t gfp)
405 453
406 * ``FSCACHE_WANT_WRITE`` - The caller !! 454 This is like the read_or_alloc_page() method, except it is handed a list
407 cache object. !! 455 of pages instead of one page. Any pages on which a read operation is
>> 456 started must be added to the page cache for the specified mapping and also
>> 457 to the LRU. Such pages must also be removed from the pages list and
>> 458 ``*nr_pages`` decremented per page.
408 459
409 Note that there won't necessarily be anyt !! 460 If there was an error such as -ENOMEM, then that should be returned; else
410 cache_priv yet if the cookie is still bei !! 461 if one or more pages couldn't be read or allocated, then -ENOBUFS should
>> 462 be returned; else if one or more pages couldn't be read, then -ENODATA
>> 463 should be returned. If all the pages are dispatched then 0 should be
>> 464 returned.
411 465
412 466
413 Data I/O API !! 467 * Request page be allocated in the cache [mandatory]::
414 ============ <<
415 468
416 A cache backend provides a data I/O API by thr !! 469 int (*allocate_page)(struct fscache_retrieval *op,
417 netfs_cache_ops`` attached to a ``struct netfs !! 470 struct page *page,
418 ``begin_operation`` method described above. !! 471 gfp_t gfp)
419 472
420 See the Documentation/filesystems/netfs_librar !! 473 This is like the read_or_alloc_page() method, except that it shouldn't
>> 474 read from the cache, even if there's data there that could be retrieved.
>> 475 It should, however, set up any internal metadata required such that
>> 476 the write_page() method can write to the cache.
421 477
>> 478 If there's no backing block available, then -ENOBUFS should be returned
>> 479 (or -ENOMEM if there were other problems). If a block is successfully
>> 480 allocated, then the netfs page should be marked and 0 returned.
422 481
423 Miscellaneous Functions !! 482
424 ======================= !! 483 * Request pages be allocated in the cache [mandatory]::
>> 484
>> 485 int (*allocate_pages)(struct fscache_retrieval *op,
>> 486 struct list_head *pages,
>> 487 unsigned *nr_pages,
>> 488 gfp_t gfp)
>> 489
>> 490 This is an multiple page version of the allocate_page() method. pages and
>> 491 nr_pages should be treated as for the read_or_alloc_pages() method.
>> 492
>> 493
>> 494 * Request page be written to cache [mandatory]::
>> 495
>> 496 int (*write_page)(struct fscache_storage *op,
>> 497 struct page *page);
>> 498
>> 499 This is called to write from a page on which there was a previously
>> 500 successful read_or_alloc_page() call or similar. FS-Cache filters out
>> 501 pages that don't have mappings.
>> 502
>> 503 This method is called asynchronously from the FS-Cache thread pool. It is
>> 504 not required to actually store anything, provided -ENODATA is then
>> 505 returned to the next read of this page.
>> 506
>> 507 If an error occurred, then a negative error code should be returned,
>> 508 otherwise zero should be returned. FS-Cache will take appropriate action
>> 509 in response to an error, such as withdrawing this object.
>> 510
>> 511 If this method returns success then FS-Cache will inform the netfs
>> 512 appropriately.
>> 513
>> 514
>> 515 * Discard retained per-page metadata [mandatory]::
>> 516
>> 517 void (*uncache_page)(struct fscache_object *object, struct page *page)
>> 518
>> 519 This is called when a netfs page is being evicted from the pagecache. The
>> 520 cache backend should tear down any internal representation or tracking it
>> 521 maintains for this page.
>> 522
>> 523
>> 524 FS-Cache Utilities
>> 525 ==================
425 526
426 FS-Cache provides some utilities that a cache 527 FS-Cache provides some utilities that a cache backend may make use of:
427 528
428 * Note occurrence of an I/O error in a cach 529 * Note occurrence of an I/O error in a cache::
429 530
430 void fscache_io_error(struct fscache_c !! 531 void fscache_io_error(struct fscache_cache *cache)
431 532
432 This tells FS-Cache that an I/O error occ !! 533 This tells FS-Cache that an I/O error occurred in the cache. After this
433 prevents any new I/O from being started o !! 534 has been called, only resource dissociation operations (object and page
>> 535 release) will be passed from the netfs to the cache backend for the
>> 536 specified cache.
434 537
435 This does not actually withdraw the cache 538 This does not actually withdraw the cache. That must be done separately.
436 539
437 * Note cessation of caching on a cookie due <<
438 540
439 void fscache_caching_failed(struct fsc !! 541 * Invoke the retrieval I/O completion function::
>> 542
>> 543 void fscache_end_io(struct fscache_retrieval *op, struct page *page,
>> 544 int error);
>> 545
>> 546 This is called to note the end of an attempt to retrieve a page. The
>> 547 error value should be 0 if successful and an error otherwise.
>> 548
>> 549
>> 550 * Record that one or more pages being retrieved or allocated have been dealt
>> 551 with::
>> 552
>> 553 void fscache_retrieval_complete(struct fscache_retrieval *op,
>> 554 int n_pages);
>> 555
>> 556 This is called to record the fact that one or more pages have been dealt
>> 557 with and are no longer the concern of this operation. When the number of
>> 558 pages remaining in the operation reaches 0, the operation will be
>> 559 completed.
>> 560
>> 561
>> 562 * Record operation completion::
>> 563
>> 564 void fscache_op_complete(struct fscache_operation *op);
>> 565
>> 566 This is called to record the completion of an operation. This deducts
>> 567 this operation from the parent object's run state, potentially permitting
>> 568 one or more pending operations to start running.
>> 569
>> 570
>> 571 * Set highest store limit::
>> 572
>> 573 void fscache_set_store_limit(struct fscache_object *object,
>> 574 loff_t i_size);
>> 575
>> 576 This sets the limit FS-Cache imposes on the highest byte it's willing to
>> 577 try and store for a netfs. Any page over this limit is automatically
>> 578 rejected by fscache_read_alloc_page() and co with -ENOBUFS.
>> 579
>> 580
>> 581 * Mark pages as being cached::
>> 582
>> 583 void fscache_mark_pages_cached(struct fscache_retrieval *op,
>> 584 struct pagevec *pagevec);
>> 585
>> 586 This marks a set of pages as being cached. After this has been called,
>> 587 the netfs must call fscache_uncache_page() to unmark the pages.
>> 588
>> 589
>> 590 * Perform coherency check on an object::
>> 591
>> 592 enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
>> 593 const void *data,
>> 594 uint16_t datalen);
>> 595
>> 596 This asks the netfs to perform a coherency check on an object that has
>> 597 just been looked up. The cookie attached to the object will determine the
>> 598 netfs to use. data and datalen should specify where the auxiliary data
>> 599 retrieved from the cache can be found.
>> 600
>> 601 One of three values will be returned:
>> 602
>> 603 FSCACHE_CHECKAUX_OKAY
>> 604 The coherency data indicates the object is valid as is.
>> 605
>> 606 FSCACHE_CHECKAUX_NEEDS_UPDATE
>> 607 The coherency data needs updating, but otherwise the object is
>> 608 valid.
>> 609
>> 610 FSCACHE_CHECKAUX_OBSOLETE
>> 611 The coherency data indicates that the object is obsolete and should
>> 612 be discarded.
>> 613
>> 614
>> 615 * Initialise a freshly allocated object::
>> 616
>> 617 void fscache_object_init(struct fscache_object *object);
>> 618
>> 619 This initialises all the fields in an object representation.
>> 620
>> 621
>> 622 * Indicate the destruction of an object::
>> 623
>> 624 void fscache_object_destroyed(struct fscache_cache *cache);
>> 625
>> 626 This must be called to inform FS-Cache that an object that belonged to a
>> 627 cache has been destroyed and deallocated. This will allow continuation
>> 628 of the cache withdrawal process when it is stopped pending destruction of
>> 629 all the objects.
>> 630
>> 631
>> 632 * Indicate negative lookup on an object::
>> 633
>> 634 void fscache_object_lookup_negative(struct fscache_object *object);
>> 635
>> 636 This is called to indicate to FS-Cache that a lookup process for an object
>> 637 found a negative result.
>> 638
>> 639 This changes the state of an object to permit reads pending on lookup
>> 640 completion to go off and start fetching data from the netfs server as it's
>> 641 known at this point that there can't be any data in the cache.
>> 642
>> 643 This may be called multiple times on an object. Only the first call is
>> 644 significant - all subsequent calls are ignored.
>> 645
>> 646
>> 647 * Indicate an object has been obtained::
>> 648
>> 649 void fscache_obtained_object(struct fscache_object *object);
>> 650
>> 651 This is called to indicate to FS-Cache that a lookup process for an object
>> 652 produced a positive result, or that an object was created. This should
>> 653 only be called once for any particular object.
>> 654
>> 655 This changes the state of an object to indicate:
>> 656
>> 657 (1) if no call to fscache_object_lookup_negative() has been made on
>> 658 this object, that there may be data available, and that reads can
>> 659 now go and look for it; and
>> 660
>> 661 (2) that writes may now proceed against this object.
>> 662
>> 663
>> 664 * Indicate that object lookup failed::
>> 665
>> 666 void fscache_object_lookup_error(struct fscache_object *object);
>> 667
>> 668 This marks an object as having encountered a fatal error (usually EIO)
>> 669 and causes it to move into a state whereby it will be withdrawn as soon
>> 670 as possible.
>> 671
>> 672
>> 673 * Indicate that a stale object was found and discarded::
>> 674
>> 675 void fscache_object_retrying_stale(struct fscache_object *object);
>> 676
>> 677 This is called to indicate that the lookup procedure found an object in
>> 678 the cache that the netfs decided was stale. The object has been
>> 679 discarded from the cache and the lookup will be performed again.
>> 680
>> 681
>> 682 * Indicate that the caching backend killed an object::
>> 683
>> 684 void fscache_object_mark_killed(struct fscache_object *object,
>> 685 enum fscache_why_object_killed why);
>> 686
>> 687 This is called to indicate that the cache backend preemptively killed an
>> 688 object. The why parameter should be set to indicate the reason:
440 689
441 This notes that a the caching that was be !! 690 FSCACHE_OBJECT_IS_STALE
442 some way, for instance the backing storag !! 691 - the object was stale and needs discarding.
443 invalidation failed and that no further I <<
444 on it until the cache is reset. <<
445 692
446 * Count I/O requests:: !! 693 FSCACHE_OBJECT_NO_SPACE
>> 694 - there was insufficient cache space
447 695
448 void fscache_count_read(void); !! 696 FSCACHE_OBJECT_WAS_RETIRED
449 void fscache_count_write(void); !! 697 - the object was retired when relinquished.
450 698
451 These record reads and writes from/to the !! 699 FSCACHE_OBJECT_WAS_CULLED
452 displayed in /proc/fs/fscache/stats. !! 700 - the object was culled to make space.
453 701
454 * Count out-of-space errors:: <<
455 702
456 void fscache_count_no_write_space(void !! 703 * Get and release references on a retrieval record::
457 void fscache_count_no_create_space(voi <<
458 704
459 These record ENOSPC errors in the cache, !! 705 void fscache_get_retrieval(struct fscache_retrieval *op);
460 writes and failures of filesystem object !! 706 void fscache_put_retrieval(struct fscache_retrieval *op);
461 707
462 * Count objects culled:: !! 708 These two functions are used to retain a retrieval record while doing
>> 709 asynchronous data retrieval and block allocation.
463 710
464 void fscache_count_culled(void); <<
465 711
466 This records the culling of an object. !! 712 * Enqueue a retrieval record for processing::
467 713
468 * Get the cookie from a set of cache resour !! 714 void fscache_enqueue_retrieval(struct fscache_retrieval *op);
469 715
470 struct fscache_cookie *fscache_cres_co !! 716 This enqueues a retrieval record for processing by the FS-Cache thread
>> 717 pool. One of the threads in the pool will invoke the retrieval record's
>> 718 op->op.processor callback function. This function may be called from
>> 719 within the callback function.
471 720
472 Pull a pointer to the cookie from the cac <<
473 NULL cookie if no cookie was set. <<
474 721
>> 722 * List of object state names::
475 723
476 API Function Reference !! 724 const char *fscache_object_states[];
477 ====================== <<
478 725
479 .. kernel-doc:: include/linux/fscache-cache.h !! 726 For debugging purposes, this may be used to turn the state that an object
>> 727 is in into a text string for display purposes.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.