History

docs: filesystems: caching/backend-api.txt: convert it to ReST

- Add a SPDX header; - Adjust document and section titles; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add table markups; - Add it to filesystems/caching/index.rst.

Mauro Carvalho Chehab committed 6 years ago

Commit 0e822141 parent d74802a6 files · +92 −90Browse files

Unified · Split

6 files
  1. Documentation/filesystems/caching/backend-api.rst +83 −82
  2. Documentation/filesystems/caching/fscache.rst +1 −1
  3. Documentation/filesystems/caching/index.rst +1 −0
  4. fs/fscache/cache.c +4 −4
  5. fs/fscache/object.c +1 −1
  6. include/linux/fscache-cache.h +2 −2
Documentation/filesystems/caching/backend-api.rstrenamed from Documentation/filesystems/caching/backend-api.txt+83−82
@@ -1,6 +1,8 @@
1 ==========================1.. SPDX-License-Identifier: GPL-2.0
2 FS-CACHE CACHE BACKEND API2
3 ==========================3==========================
4FS-Cache Cache backend API
5==========================
4 6
5The FS-Cache system provides an API by which actual caches can be supplied to7The FS-Cache system provides an API by which actual caches can be supplied to
6FS-Cache for it to then serve out to network filesystems and other interested8FS-Cache for it to then serve out to network filesystems and other interested
@@ -9,15 +11,14 @@ parties. · 2 unmodified lines
9This API is declared in <linux/fscache-cache.h>.11This API is declared in <linux/fscache-cache.h>.
10 12
11 13
12====================================14Initialising and Registering a Cache
13INITIALISING AND REGISTERING A CACHE
14====================================15====================================
15 16
16To start off, a cache definition must be initialised and registered for each17To start off, a cache definition must be initialised and registered for each
17cache the backend wants to make available. For instance, CacheFS does this in18cache the backend wants to make available. For instance, CacheFS does this in
18the fill_super() operation on mounting.19the fill_super() operation on mounting.
19 20
20The cache definition (struct fscache_cache) should be initialised by calling:21The cache definition (struct fscache_cache) should be initialised by calling::
21 22
22 void fscache_init_cache(struct fscache_cache *cache,23 void fscache_init_cache(struct fscache_cache *cache,
23 struct fscache_cache_ops *ops,24 struct fscache_cache_ops *ops,
@@ -26,17 +27,17 @@ The cache definition (struct fscache_cache) should be initialised by calling: · 2 unmodified lines
26 27
27Where:28Where:
28 29
29 (*) "cache" is a pointer to the cache definition;30 * "cache" is a pointer to the cache definition;
30 31
31 (*) "ops" is a pointer to the table of operations that the backend supports on32 * "ops" is a pointer to the table of operations that the backend supports on
32 this cache; and33 this cache; and
33 34
34 (*) "idfmt" is a format and printf-style arguments for constructing a label35 * "idfmt" is a format and printf-style arguments for constructing a label
35 for the cache.36 for the cache.
36 37
37 38
38The cache should then be registered with FS-Cache by passing a pointer to the39The cache should then be registered with FS-Cache by passing a pointer to the
39previously initialised cache definition to:40previously initialised cache definition to::
40 41
41 int fscache_add_cache(struct fscache_cache *cache,42 int fscache_add_cache(struct fscache_cache *cache,
42 struct fscache_object *fsdef,43 struct fscache_object *fsdef,
@@ -44,12 +45,12 @@ previously initialised cache definition to: · 1 unmodified line
44 45
45Two extra arguments should also be supplied:46Two extra arguments should also be supplied:
46 47
47 (*) "fsdef" which should point to the object representation for the FS-Cache48 * "fsdef" which should point to the object representation for the FS-Cache
48 master index in this cache. Netfs primary index entries will be created49 master index in this cache. Netfs primary index entries will be created
49 here. FS-Cache keeps the caller's reference to the index object if50 here. FS-Cache keeps the caller's reference to the index object if
50 successful and will release it upon withdrawal of the cache.51 successful and will release it upon withdrawal of the cache.
51 52
52 (*) "tagname" which, if given, should be a text string naming this cache. If53 * "tagname" which, if given, should be a text string naming this cache. If
53 this is NULL, the identifier will be used instead. For CacheFS, the54 this is NULL, the identifier will be used instead. For CacheFS, the
54 identifier is set to name the underlying block device and the tag can be55 identifier is set to name the underlying block device and the tag can be
55 supplied by mount.56 supplied by mount.
@@ -58,20 +59,18 @@ This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag · 2 unmodified lines
58is already in use. 0 will be returned on success.59is already in use. 0 will be returned on success.
59 60
60 61
61=====================62Unregistering a Cache
62UNREGISTERING A CACHE
63=====================63=====================
64 64
65A cache can be withdrawn from the system by calling this function with a65A cache can be withdrawn from the system by calling this function with a
66pointer to the cache definition:66pointer to the cache definition::
67 67
68 void fscache_withdraw_cache(struct fscache_cache *cache);68 void fscache_withdraw_cache(struct fscache_cache *cache);
69 69
70In CacheFS's case, this is called by put_super().70In CacheFS's case, this is called by put_super().
71 71
72 72
73========73Security
74SECURITY
75========74========
76 75
77The cache methods are executed one of two contexts:76The cache methods are executed one of two contexts:
@@ -89,8 +88,7 @@ be masqueraded for the duration of the cache driver's access to the cache. · 11 unmodified lines
89This is left to the cache to handle; FS-Cache makes no effort in this regard.88This is left to the cache to handle; FS-Cache makes no effort in this regard.
90 89
91 90
92===================================91Control and Statistics Presentation
93CONTROL AND STATISTICS PRESENTATION
94===================================92===================================
95 93
96The cache may present data to the outside world through FS-Cache's interfaces94The cache may present data to the outside world through FS-Cache's interfaces
@@ -101,11 +99,10 @@ is enabled. This is accessible through the kobject struct fscache_cache::kobj · 4 unmodified lines
101and is for use by the cache as it sees fit.99and is for use by the cache as it sees fit.
102 100
103 101
104========================102Relevant Data Structures
105RELEVANT DATA STRUCTURES
106========================103========================
107 104
108 (*) Index/Data file FS-Cache representation cookie:105 * Index/Data file FS-Cache representation cookie::
109 106
110 struct fscache_cookie {107 struct fscache_cookie {
111 struct fscache_object_def *def;108 struct fscache_object_def *def;
@@ -121,7 +118,7 @@ RELEVANT DATA STRUCTURES · 9 unmodified lines
121 cache operations.118 cache operations.
122 119
123 120
124 (*) In-cache object representation:121 * In-cache object representation::
125 122
126 struct fscache_object {123 struct fscache_object {
127 int debug_id;124 int debug_id;
@@ -150,7 +147,7 @@ RELEVANT DATA STRUCTURES · 22 unmodified lines
150 initialised by calling fscache_object_init(object).147 initialised by calling fscache_object_init(object).
151 148
152 149
153 (*) FS-Cache operation record:150 * FS-Cache operation record::
154 151
155 struct fscache_operation {152 struct fscache_operation {
156 atomic_t usage;153 atomic_t usage;
@@ -173,7 +170,7 @@ RELEVANT DATA STRUCTURES · 16 unmodified lines
173 an operation needs more processing time, it should be enqueued again.170 an operation needs more processing time, it should be enqueued again.
174 171
175 172
176 (*) FS-Cache retrieval operation record:173 * FS-Cache retrieval operation record::
177 174
178 struct fscache_retrieval {175 struct fscache_retrieval {
179 struct fscache_operation op;176 struct fscache_operation op;
@@ -198,7 +195,7 @@ RELEVANT DATA STRUCTURES · 18 unmodified lines
198 it sees fit.195 it sees fit.
199 196
200 197
201 (*) FS-Cache storage operation record:198 * FS-Cache storage operation record::
202 199
203 struct fscache_storage {200 struct fscache_storage {
204 struct fscache_operation op;201 struct fscache_operation op;
@@ -212,16 +209,17 @@ RELEVANT DATA STRUCTURES · 7 unmodified lines
212 storage.209 storage.
213 210
214 211
215================212Cache Operations
216CACHE OPERATIONS
217================213================
218 214
219The cache backend provides FS-Cache with a table of operations that can be215The cache backend provides FS-Cache with a table of operations that can be
220performed on the denizens of the cache. These are held in a structure of type:216performed on the denizens of the cache. These are held in a structure of type:
221 217
222 struct fscache_cache_ops218 ::
219
220 struct fscache_cache_ops
223 221
224 (*) Name of cache provider [mandatory]:222 * Name of cache provider [mandatory]::
225 223
226 const char *name224 const char *name
227 225
@@ -229,7 +227,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 1 unmodified line
229 the backend.227 the backend.
230 228
231 229
232 (*) Allocate a new object [mandatory]:230 * Allocate a new object [mandatory]::
233 231
234 struct fscache_object *(*alloc_object)(struct fscache_cache *cache,232 struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
235 struct fscache_cookie *cookie)233 struct fscache_cookie *cookie)
@@ -244,7 +242,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 8 unmodified lines
244 form once lookup is complete or aborted.242 form once lookup is complete or aborted.
245 243
246 244
247 (*) Look up and create object [mandatory]:245 * Look up and create object [mandatory]::
248 246
249 void (*lookup_object)(struct fscache_object *object)247 void (*lookup_object)(struct fscache_object *object)
250 248
@@ -263,7 +261,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 12 unmodified lines
263 to abort the lookup of that object.261 to abort the lookup of that object.
264 262
265 263
266 (*) Release lookup data [mandatory]:264 * Release lookup data [mandatory]::
267 265
268 void (*lookup_complete)(struct fscache_object *object)266 void (*lookup_complete)(struct fscache_object *object)
269 267
@@ -271,7 +269,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 1 unmodified line
271 using to perform a lookup.269 using to perform a lookup.
272 270
273 271
274 (*) Increment object refcount [mandatory]:272 * Increment object refcount [mandatory]::
275 273
276 struct fscache_object *(*grab_object)(struct fscache_object *object)274 struct fscache_object *(*grab_object)(struct fscache_object *object)
277 275
@@ -280,7 +278,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 2 unmodified lines
280 It should return the object pointer if successful.278 It should return the object pointer if successful.
281 279
282 280
283 (*) Lock/Unlock object [mandatory]:281 * Lock/Unlock object [mandatory]::
284 282
285 void (*lock_object)(struct fscache_object *object)283 void (*lock_object)(struct fscache_object *object)
286 void (*unlock_object)(struct fscache_object *object)284 void (*unlock_object)(struct fscache_object *object)
@@ -289,7 +287,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 2 unmodified lines
289 to schedule with the lock held, so a spinlock isn't sufficient.287 to schedule with the lock held, so a spinlock isn't sufficient.
290 288
291 289
292 (*) Pin/Unpin object [optional]:290 * Pin/Unpin object [optional]::
293 291
294 int (*pin_object)(struct fscache_object *object)292 int (*pin_object)(struct fscache_object *object)
295 void (*unpin_object)(struct fscache_object *object)293 void (*unpin_object)(struct fscache_object *object)
@@ -299,7 +297,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 3 unmodified lines
299 enough space in the cache to permit this.297 enough space in the cache to permit this.
300 298
301 299
302 (*) Check coherency state of an object [mandatory]:300 * Check coherency state of an object [mandatory]::
303 301
304 int (*check_consistency)(struct fscache_object *object)302 int (*check_consistency)(struct fscache_object *object)
305 303
@@ -308,7 +306,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 2 unmodified lines
308 if they're consistent and -ESTALE otherwise. -ENOMEM and -ERESTARTSYS306 if they're consistent and -ESTALE otherwise. -ENOMEM and -ERESTARTSYS
309 may also be returned.307 may also be returned.
310 308
311 (*) Update object [mandatory]:309 * Update object [mandatory]::
312 310
313 int (*update_object)(struct fscache_object *object)311 int (*update_object)(struct fscache_object *object)
314 312
@@ -317,7 +315,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 2 unmodified lines
317 obtained by calling object->cookie->def->get_aux()/get_attr().315 obtained by calling object->cookie->def->get_aux()/get_attr().
318 316
319 317
320 (*) Invalidate data object [mandatory]:318 * Invalidate data object [mandatory]::
321 319
322 int (*invalidate_object)(struct fscache_operation *op)320 int (*invalidate_object)(struct fscache_operation *op)
323 321
@@ -329,7 +327,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 5 unmodified lines
329 fscache_op_complete() must be called on op before returning.327 fscache_op_complete() must be called on op before returning.
330 328
331 329
332 (*) Discard object [mandatory]:330 * Discard object [mandatory]::
333 331
334 void (*drop_object)(struct fscache_object *object)332 void (*drop_object)(struct fscache_object *object)
335 333
@@ -341,7 +339,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 5 unmodified lines
341 caller. The caller will invoke the put_object() method as appropriate.339 caller. The caller will invoke the put_object() method as appropriate.
342 340
343 341
344 (*) Release object reference [mandatory]:342 * Release object reference [mandatory]::
345 343
346 void (*put_object)(struct fscache_object *object)344 void (*put_object)(struct fscache_object *object)
347 345
@@ -349,7 +347,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 1 unmodified line
349 be freed when all the references to it are released.347 be freed when all the references to it are released.
350 348
351 349
352 (*) Synchronise a cache [mandatory]:350 * Synchronise a cache [mandatory]::
353 351
354 void (*sync)(struct fscache_cache *cache)352 void (*sync)(struct fscache_cache *cache)
355 353
@@ -357,7 +355,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 1 unmodified line
357 device.355 device.
358 356
359 357
360 (*) Dissociate a cache [mandatory]:358 * Dissociate a cache [mandatory]::
361 359
362 void (*dissociate_pages)(struct fscache_cache *cache)360 void (*dissociate_pages)(struct fscache_cache *cache)
363 361
@@ -365,7 +363,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 1 unmodified line
365 cache withdrawal.363 cache withdrawal.
366 364
367 365
368 (*) Notification that the attributes on a netfs file changed [mandatory]:366 * Notification that the attributes on a netfs file changed [mandatory]::
369 367
370 int (*attr_changed)(struct fscache_object *object);368 int (*attr_changed)(struct fscache_object *object);
371 369
@@ -386,7 +384,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 14 unmodified lines
386 execution of this operation.384 execution of this operation.
387 385
388 386
389 (*) Reserve cache space for an object's data [optional]:387 * Reserve cache space for an object's data [optional]::
390 388
391 int (*reserve_space)(struct fscache_object *object, loff_t size);389 int (*reserve_space)(struct fscache_object *object, loff_t size);
392 390
@@ -404,7 +402,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 11 unmodified lines
404 size if larger than that already.402 size if larger than that already.
405 403
406 404
407 (*) Request page be read from cache [mandatory]:405 * Request page be read from cache [mandatory]::
408 406
409 int (*read_or_alloc_page)(struct fscache_retrieval *op,407 int (*read_or_alloc_page)(struct fscache_retrieval *op,
410 struct page *page,408 struct page *page,
@@ -446,7 +444,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 35 unmodified lines
446 with. This will complete the operation when all pages are dealt with.444 with. This will complete the operation when all pages are dealt with.
447 445
448 446
449 (*) Request pages be read from cache [mandatory]:447 * Request pages be read from cache [mandatory]::
450 448
451 int (*read_or_alloc_pages)(struct fscache_retrieval *op,449 int (*read_or_alloc_pages)(struct fscache_retrieval *op,
452 struct list_head *pages,450 struct list_head *pages,
@@ -457,7 +455,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 4 unmodified lines
457 of pages instead of one page. Any pages on which a read operation is455 of pages instead of one page. Any pages on which a read operation is
458 started must be added to the page cache for the specified mapping and also456 started must be added to the page cache for the specified mapping and also
459 to the LRU. Such pages must also be removed from the pages list and457 to the LRU. Such pages must also be removed from the pages list and
460 *nr_pages decremented per page.458 ``*nr_pages`` decremented per page.
461 459
462 If there was an error such as -ENOMEM, then that should be returned; else460 If there was an error such as -ENOMEM, then that should be returned; else
463 if one or more pages couldn't be read or allocated, then -ENOBUFS should461 if one or more pages couldn't be read or allocated, then -ENOBUFS should
@@ -466,7 +464,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 2 unmodified lines
466 returned.464 returned.
467 465
468 466
469 (*) Request page be allocated in the cache [mandatory]:467 * Request page be allocated in the cache [mandatory]::
470 468
471 int (*allocate_page)(struct fscache_retrieval *op,469 int (*allocate_page)(struct fscache_retrieval *op,
472 struct page *page,470 struct page *page,
@@ -482,7 +480,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 9 unmodified lines
482 allocated, then the netfs page should be marked and 0 returned.480 allocated, then the netfs page should be marked and 0 returned.
483 481
484 482
485 (*) Request pages be allocated in the cache [mandatory]:483 * Request pages be allocated in the cache [mandatory]::
486 484
487 int (*allocate_pages)(struct fscache_retrieval *op,485 int (*allocate_pages)(struct fscache_retrieval *op,
488 struct list_head *pages,486 struct list_head *pages,
@@ -493,7 +491,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 4 unmodified lines
493 nr_pages should be treated as for the read_or_alloc_pages() method.491 nr_pages should be treated as for the read_or_alloc_pages() method.
494 492
495 493
496 (*) Request page be written to cache [mandatory]:494 * Request page be written to cache [mandatory]::
497 495
498 int (*write_page)(struct fscache_storage *op,496 int (*write_page)(struct fscache_storage *op,
499 struct page *page);497 struct page *page);
@@ -514,7 +512,7 @@ performed on the denizens of the cache. These are held in a structure of type: · 14 unmodified lines
514 appropriately.512 appropriately.
515 513
516 514
517 (*) Discard retained per-page metadata [mandatory]:515 * Discard retained per-page metadata [mandatory]::
518 516
519 void (*uncache_page)(struct fscache_object *object, struct page *page)517 void (*uncache_page)(struct fscache_object *object, struct page *page)
520 518
@@ -523,13 +521,12 @@ performed on the denizens of the cache. These are held in a structure of type: · 2 unmodified lines
523 maintains for this page.521 maintains for this page.
524 522
525 523
526==================524FS-Cache Utilities
527FS-CACHE UTILITIES
528==================525==================
529 526
530FS-Cache provides some utilities that a cache backend may make use of:527FS-Cache provides some utilities that a cache backend may make use of:
531 528
532 (*) Note occurrence of an I/O error in a cache:529 * Note occurrence of an I/O error in a cache::
533 530
534 void fscache_io_error(struct fscache_cache *cache)531 void fscache_io_error(struct fscache_cache *cache)
535 532
@@ -541,7 +538,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 5 unmodified lines
541 This does not actually withdraw the cache. That must be done separately.538 This does not actually withdraw the cache. That must be done separately.
542 539
543 540
544 (*) Invoke the retrieval I/O completion function:541 * Invoke the retrieval I/O completion function::
545 542
546 void fscache_end_io(struct fscache_retrieval *op, struct page *page,543 void fscache_end_io(struct fscache_retrieval *op, struct page *page,
547 int error);544 int error);
@@ -550,8 +547,8 @@ FS-Cache provides some utilities that a cache backend may make use of: · 2 unmodified lines
550 error value should be 0 if successful and an error otherwise.547 error value should be 0 if successful and an error otherwise.
551 548
552 549
553 (*) Record that one or more pages being retrieved or allocated have been dealt550 * Record that one or more pages being retrieved or allocated have been dealt
554 with:551 with::
555 552
556 void fscache_retrieval_complete(struct fscache_retrieval *op,553 void fscache_retrieval_complete(struct fscache_retrieval *op,
557 int n_pages);554 int n_pages);
@@ -562,7 +559,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 4 unmodified lines
562 completed.559 completed.
563 560
564 561
565 (*) Record operation completion:562 * Record operation completion::
566 563
567 void fscache_op_complete(struct fscache_operation *op);564 void fscache_op_complete(struct fscache_operation *op);
568 565
@@ -571,7 +568,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 2 unmodified lines
571 one or more pending operations to start running.568 one or more pending operations to start running.
572 569
573 570
574 (*) Set highest store limit:571 * Set highest store limit::
575 572
576 void fscache_set_store_limit(struct fscache_object *object,573 void fscache_set_store_limit(struct fscache_object *object,
577 loff_t i_size);574 loff_t i_size);
@@ -581,7 +578,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 3 unmodified lines
581 rejected by fscache_read_alloc_page() and co with -ENOBUFS.578 rejected by fscache_read_alloc_page() and co with -ENOBUFS.
582 579
583 580
584 (*) Mark pages as being cached:581 * Mark pages as being cached::
585 582
586 void fscache_mark_pages_cached(struct fscache_retrieval *op,583 void fscache_mark_pages_cached(struct fscache_retrieval *op,
587 struct pagevec *pagevec);584 struct pagevec *pagevec);
@@ -590,7 +587,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 2 unmodified lines
590 the netfs must call fscache_uncache_page() to unmark the pages.587 the netfs must call fscache_uncache_page() to unmark the pages.
591 588
592 589
593 (*) Perform coherency check on an object:590 * Perform coherency check on an object::
594 591
595 enum fscache_checkaux fscache_check_aux(struct fscache_object *object,592 enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
596 const void *data,593 const void *data,
@@ -603,29 +600,26 @@ FS-Cache provides some utilities that a cache backend may make use of: · 6 unmodified lines
603 600
604 One of three values will be returned:601 One of three values will be returned:
605 602
606 (*) FSCACHE_CHECKAUX_OKAY603 FSCACHE_CHECKAUX_OKAY
607
608 The coherency data indicates the object is valid as is.604 The coherency data indicates the object is valid as is.
609 605
610 (*) FSCACHE_CHECKAUX_NEEDS_UPDATE606 FSCACHE_CHECKAUX_NEEDS_UPDATE
611
612 The coherency data needs updating, but otherwise the object is607 The coherency data needs updating, but otherwise the object is
613 valid.608 valid.
614 609
615 (*) FSCACHE_CHECKAUX_OBSOLETE610 FSCACHE_CHECKAUX_OBSOLETE
616
617 The coherency data indicates that the object is obsolete and should611 The coherency data indicates that the object is obsolete and should
618 be discarded.612 be discarded.
619 613
620 614
621 (*) Initialise a freshly allocated object:615 * Initialise a freshly allocated object::
622 616
623 void fscache_object_init(struct fscache_object *object);617 void fscache_object_init(struct fscache_object *object);
624 618
625 This initialises all the fields in an object representation.619 This initialises all the fields in an object representation.
626 620
627 621
628 (*) Indicate the destruction of an object:622 * Indicate the destruction of an object::
629 623
630 void fscache_object_destroyed(struct fscache_cache *cache);624 void fscache_object_destroyed(struct fscache_cache *cache);
631 625
@@ -635,7 +629,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 3 unmodified lines
635 all the objects.629 all the objects.
636 630
637 631
638 (*) Indicate negative lookup on an object:632 * Indicate negative lookup on an object::
639 633
640 void fscache_object_lookup_negative(struct fscache_object *object);634 void fscache_object_lookup_negative(struct fscache_object *object);
641 635
@@ -650,7 +644,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 8 unmodified lines
650 significant - all subsequent calls are ignored.644 significant - all subsequent calls are ignored.
651 645
652 646
653 (*) Indicate an object has been obtained:647 * Indicate an object has been obtained::
654 648
655 void fscache_obtained_object(struct fscache_object *object);649 void fscache_obtained_object(struct fscache_object *object);
656 650
@@ -667,7 +661,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 10 unmodified lines
667 (2) that writes may now proceed against this object.661 (2) that writes may now proceed against this object.
668 662
669 663
670 (*) Indicate that object lookup failed:664 * Indicate that object lookup failed::
671 665
672 void fscache_object_lookup_error(struct fscache_object *object);666 void fscache_object_lookup_error(struct fscache_object *object);
673 667
@@ -676,7 +670,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 2 unmodified lines
676 as possible.670 as possible.
677 671
678 672
679 (*) Indicate that a stale object was found and discarded:673 * Indicate that a stale object was found and discarded::
680 674
681 void fscache_object_retrying_stale(struct fscache_object *object);675 void fscache_object_retrying_stale(struct fscache_object *object);
682 676
@@ -685,7 +679,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 2 unmodified lines
685 discarded from the cache and the lookup will be performed again.679 discarded from the cache and the lookup will be performed again.
686 680
687 681
688 (*) Indicate that the caching backend killed an object:682 * Indicate that the caching backend killed an object::
689 683
690 void fscache_object_mark_killed(struct fscache_object *object,684 void fscache_object_mark_killed(struct fscache_object *object,
691 enum fscache_why_object_killed why);685 enum fscache_why_object_killed why);
@@ -693,13 +687,20 @@ FS-Cache provides some utilities that a cache backend may make use of: · 1 unmodified line
693 This is called to indicate that the cache backend preemptively killed an687 This is called to indicate that the cache backend preemptively killed an
694 object. The why parameter should be set to indicate the reason:688 object. The why parameter should be set to indicate the reason:
695 689
696 FSCACHE_OBJECT_IS_STALE - the object was stale and needs discarding.690 FSCACHE_OBJECT_IS_STALE
697 FSCACHE_OBJECT_NO_SPACE - there was insufficient cache space691 - the object was stale and needs discarding.
698 FSCACHE_OBJECT_WAS_RETIRED - the object was retired when relinquished.692
699 FSCACHE_OBJECT_WAS_CULLED - the object was culled to make space.693 FSCACHE_OBJECT_NO_SPACE
694 - there was insufficient cache space
695
696 FSCACHE_OBJECT_WAS_RETIRED
697 - the object was retired when relinquished.
698
699 FSCACHE_OBJECT_WAS_CULLED
700 - the object was culled to make space.
700 701
701 702
702 (*) Get and release references on a retrieval record:703 * Get and release references on a retrieval record::
703 704
704 void fscache_get_retrieval(struct fscache_retrieval *op);705 void fscache_get_retrieval(struct fscache_retrieval *op);
705 void fscache_put_retrieval(struct fscache_retrieval *op);706 void fscache_put_retrieval(struct fscache_retrieval *op);
@@ -708,7 +709,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 2 unmodified lines
708 asynchronous data retrieval and block allocation.709 asynchronous data retrieval and block allocation.
709 710
710 711
711 (*) Enqueue a retrieval record for processing.712 * Enqueue a retrieval record for processing::
712 713
713 void fscache_enqueue_retrieval(struct fscache_retrieval *op);714 void fscache_enqueue_retrieval(struct fscache_retrieval *op);
714 715
@@ -718,7 +719,7 @@ FS-Cache provides some utilities that a cache backend may make use of: · 3 unmodified lines
718 within the callback function.719 within the callback function.
719 720
720 721
721 (*) List of object state names:722 * List of object state names::
722 723
723 const char *fscache_object_states[];724 const char *fscache_object_states[];
724 725
Documentation/filesystems/caching/fscache.rst+1−1
@@ -187,7 +187,7 @@ The netfs API to FS-Cache can be found in: · 186 unmodified lines
187 187
188The cache backend API to FS-Cache can be found in:188The cache backend API to FS-Cache can be found in:
189 189
190 Documentation/filesystems/caching/backend-api.txt190 Documentation/filesystems/caching/backend-api.rst
191 191
192A description of the internal representations and object state machine can be192A description of the internal representations and object state machine can be
193found in:193found in:
Documentation/filesystems/caching/index.rst+1−0
@@ -8,6 +8,7 @@ Filesystem Caching · 7 unmodified lines
8 8
9 fscache9 fscache
10 object10 object
11 backend-api
11 cachefiles12 cachefiles
12 netfs-api13 netfs-api
13 operations14 operations
fs/fscache/cache.c+4−4
@@ -172,7 +172,7 @@ no_preference: · 171 unmodified lines
172 *172 *
173 * Initialise a record of a cache and fill in the name.173 * Initialise a record of a cache and fill in the name.
174 *174 *
175 * See Documentation/filesystems/caching/backend-api.txt for a complete175 * See Documentation/filesystems/caching/backend-api.rst for a complete
176 * description.176 * description.
177 */177 */
178void fscache_init_cache(struct fscache_cache *cache,178void fscache_init_cache(struct fscache_cache *cache,
@@ -207,7 +207,7 @@ EXPORT_SYMBOL(fscache_init_cache); · 28 unmodified lines
207 *207 *
208 * Add a cache to the system, making it available for netfs's to use.208 * Add a cache to the system, making it available for netfs's to use.
209 *209 *
210 * See Documentation/filesystems/caching/backend-api.txt for a complete210 * See Documentation/filesystems/caching/backend-api.rst for a complete
211 * description.211 * description.
212 */212 */
213int fscache_add_cache(struct fscache_cache *cache,213int fscache_add_cache(struct fscache_cache *cache,
@@ -307,7 +307,7 @@ EXPORT_SYMBOL(fscache_add_cache); · 93 unmodified lines
307 * Note that an I/O error occurred in a cache and that it should no longer be307 * Note that an I/O error occurred in a cache and that it should no longer be
308 * used for anything. This also reports the error into the kernel log.308 * used for anything. This also reports the error into the kernel log.
309 *309 *
310 * See Documentation/filesystems/caching/backend-api.txt for a complete310 * See Documentation/filesystems/caching/backend-api.rst for a complete
311 * description.311 * description.
312 */312 */
313void fscache_io_error(struct fscache_cache *cache)313void fscache_io_error(struct fscache_cache *cache)
@@ -355,7 +355,7 @@ static void fscache_withdraw_all_objects(struct fscache_cache *cache, · 41 unmodified lines
355 * Withdraw a cache from service, unbinding all its cache objects from the355 * Withdraw a cache from service, unbinding all its cache objects from the
356 * netfs cookies they're currently representing.356 * netfs cookies they're currently representing.
357 *357 *
358 * See Documentation/filesystems/caching/backend-api.txt for a complete358 * See Documentation/filesystems/caching/backend-api.rst for a complete
359 * description.359 * description.
360 */360 */
361void fscache_withdraw_cache(struct fscache_cache *cache)361void fscache_withdraw_cache(struct fscache_cache *cache)
fs/fscache/object.c+1−1
@@ -295,7 +295,7 @@ static void fscache_object_work_func(struct work_struct *work) · 294 unmodified lines
295 *295 *
296 * Initialise a cache object description to its basic values.296 * Initialise a cache object description to its basic values.
297 *297 *
298 * See Documentation/filesystems/caching/backend-api.txt for a complete298 * See Documentation/filesystems/caching/backend-api.rst for a complete
299 * description.299 * description.
300 */300 */
301void fscache_object_init(struct fscache_object *object,301void fscache_object_init(struct fscache_object *object,
include/linux/fscache-cache.h+2−2
@@ -6,7 +6,7 @@ · 5 unmodified lines
6 *6 *
7 * NOTE!!! See:7 * NOTE!!! See:
8 *8 *
9 * Documentation/filesystems/caching/backend-api.txt9 * Documentation/filesystems/caching/backend-api.rst
10 *10 *
11 * for a description of the cache backend interface declared here.11 * for a description of the cache backend interface declared here.
12 */12 */
@@ -454,7 +454,7 @@ static inline void fscache_object_lookup_error(struct fscache_object *object) · 441 unmodified lines
454 * Set the maximum size an object is permitted to reach, implying the highest454 * Set the maximum size an object is permitted to reach, implying the highest
455 * byte that may be written. Intended to be called by the attr_changed() op.455 * byte that may be written. Intended to be called by the attr_changed() op.
456 *456 *
457 * See Documentation/filesystems/caching/backend-api.txt for a complete457 * See Documentation/filesystems/caching/backend-api.rst for a complete
458 * description.458 * description.
459 */459 */
460static inline460static inline