fscache: remove unused ->now_uncached callback
[sfrench/cifs-2.6.git] / Documentation / filesystems / caching / netfs-api.txt
1                         ===============================
2                         FS-CACHE NETWORK FILESYSTEM API
3                         ===============================
4
5 There's an API by which a network filesystem can make use of the FS-Cache
6 facilities.  This is based around a number of principles:
7
8  (1) Caches can store a number of different object types.  There are two main
9      object types: indices and files.  The first is a special type used by
10      FS-Cache to make finding objects faster and to make retiring of groups of
11      objects easier.
12
13  (2) Every index, file or other object is represented by a cookie.  This cookie
14      may or may not have anything associated with it, but the netfs doesn't
15      need to care.
16
17  (3) Barring the top-level index (one entry per cached netfs), the index
18      hierarchy for each netfs is structured according the whim of the netfs.
19
20 This API is declared in <linux/fscache.h>.
21
22 This document contains the following sections:
23
24          (1) Network filesystem definition
25          (2) Index definition
26          (3) Object definition
27          (4) Network filesystem (un)registration
28          (5) Cache tag lookup
29          (6) Index registration
30          (7) Data file registration
31          (8) Miscellaneous object registration
32          (9) Setting the data file size
33         (10) Page alloc/read/write
34         (11) Page uncaching
35         (12) Index and data file consistency
36         (13) Cookie enablement
37         (14) Miscellaneous cookie operations
38         (15) Cookie unregistration
39         (16) Index invalidation
40         (17) Data file invalidation
41         (18) FS-Cache specific page flags.
42
43
44 =============================
45 NETWORK FILESYSTEM DEFINITION
46 =============================
47
48 FS-Cache needs a description of the network filesystem.  This is specified
49 using a record of the following structure:
50
51         struct fscache_netfs {
52                 uint32_t                        version;
53                 const char                      *name;
54                 struct fscache_cookie           *primary_index;
55                 ...
56         };
57
58 This first two fields should be filled in before registration, and the third
59 will be filled in by the registration function; any other fields should just be
60 ignored and are for internal use only.
61
62 The fields are:
63
64  (1) The name of the netfs (used as the key in the toplevel index).
65
66  (2) The version of the netfs (if the name matches but the version doesn't, the
67      entire in-cache hierarchy for this netfs will be scrapped and begun
68      afresh).
69
70  (3) The cookie representing the primary index will be allocated according to
71      another parameter passed into the registration function.
72
73 For example, kAFS (linux/fs/afs/) uses the following definitions to describe
74 itself:
75
76         struct fscache_netfs afs_cache_netfs = {
77                 .version        = 0,
78                 .name           = "afs",
79         };
80
81
82 ================
83 INDEX DEFINITION
84 ================
85
86 Indices are used for two purposes:
87
88  (1) To aid the finding of a file based on a series of keys (such as AFS's
89      "cell", "volume ID", "vnode ID").
90
91  (2) To make it easier to discard a subset of all the files cached based around
92      a particular key - for instance to mirror the removal of an AFS volume.
93
94 However, since it's unlikely that any two netfs's are going to want to define
95 their index hierarchies in quite the same way, FS-Cache tries to impose as few
96 restraints as possible on how an index is structured and where it is placed in
97 the tree.  The netfs can even mix indices and data files at the same level, but
98 it's not recommended.
99
100 Each index entry consists of a key of indeterminate length plus some auxiliary
101 data, also of indeterminate length.
102
103 There are some limits on indices:
104
105  (1) Any index containing non-index objects should be restricted to a single
106      cache.  Any such objects created within an index will be created in the
107      first cache only.  The cache in which an index is created can be
108      controlled by cache tags (see below).
109
110  (2) The entry data must be atomically journallable, so it is limited to about
111      400 bytes at present.  At least 400 bytes will be available.
112
113  (3) The depth of the index tree should be judged with care as the search
114      function is recursive.  Too many layers will run the kernel out of stack.
115
116
117 =================
118 OBJECT DEFINITION
119 =================
120
121 To define an object, a structure of the following type should be filled out:
122
123         struct fscache_cookie_def
124         {
125                 uint8_t name[16];
126                 uint8_t type;
127
128                 struct fscache_cache_tag *(*select_cache)(
129                         const void *parent_netfs_data,
130                         const void *cookie_netfs_data);
131
132                 uint16_t (*get_key)(const void *cookie_netfs_data,
133                                     void *buffer,
134                                     uint16_t bufmax);
135
136                 void (*get_attr)(const void *cookie_netfs_data,
137                                  uint64_t *size);
138
139                 uint16_t (*get_aux)(const void *cookie_netfs_data,
140                                     void *buffer,
141                                     uint16_t bufmax);
142
143                 enum fscache_checkaux (*check_aux)(void *cookie_netfs_data,
144                                                    const void *data,
145                                                    uint16_t datalen);
146
147                 void (*get_context)(void *cookie_netfs_data, void *context);
148
149                 void (*put_context)(void *cookie_netfs_data, void *context);
150
151                 void (*mark_pages_cached)(void *cookie_netfs_data,
152                                           struct address_space *mapping,
153                                           struct pagevec *cached_pvec);
154         };
155
156 This has the following fields:
157
158  (1) The type of the object [mandatory].
159
160      This is one of the following values:
161
162         (*) FSCACHE_COOKIE_TYPE_INDEX
163
164             This defines an index, which is a special FS-Cache type.
165
166         (*) FSCACHE_COOKIE_TYPE_DATAFILE
167
168             This defines an ordinary data file.
169
170         (*) Any other value between 2 and 255
171
172             This defines an extraordinary object such as an XATTR.
173
174  (2) The name of the object type (NUL terminated unless all 16 chars are used)
175      [optional].
176
177  (3) A function to select the cache in which to store an index [optional].
178
179      This function is invoked when an index needs to be instantiated in a cache
180      during the instantiation of a non-index object.  Only the immediate index
181      parent for the non-index object will be queried.  Any indices above that
182      in the hierarchy may be stored in multiple caches.  This function does not
183      need to be supplied for any non-index object or any index that will only
184      have index children.
185
186      If this function is not supplied or if it returns NULL then the first
187      cache in the parent's list will be chosen, or failing that, the first
188      cache in the master list.
189
190  (4) A function to retrieve an object's key from the netfs [mandatory].
191
192      This function will be called with the netfs data that was passed to the
193      cookie acquisition function and the maximum length of key data that it may
194      provide.  It should write the required key data into the given buffer and
195      return the quantity it wrote.
196
197  (5) A function to retrieve attribute data from the netfs [optional].
198
199      This function will be called with the netfs data that was passed to the
200      cookie acquisition function.  It should return the size of the file if
201      this is a data file.  The size may be used to govern how much cache must
202      be reserved for this file in the cache.
203
204      If the function is absent, a file size of 0 is assumed.
205
206  (6) A function to retrieve auxiliary data from the netfs [optional].
207
208      This function will be called with the netfs data that was passed to the
209      cookie acquisition function and the maximum length of auxiliary data that
210      it may provide.  It should write the auxiliary data into the given buffer
211      and return the quantity it wrote.
212
213      If this function is absent, the auxiliary data length will be set to 0.
214
215      The length of the auxiliary data buffer may be dependent on the key
216      length.  A netfs mustn't rely on being able to provide more than 400 bytes
217      for both.
218
219  (7) A function to check the auxiliary data [optional].
220
221      This function will be called to check that a match found in the cache for
222      this object is valid.  For instance with AFS it could check the auxiliary
223      data against the data version number returned by the server to determine
224      whether the index entry in a cache is still valid.
225
226      If this function is absent, it will be assumed that matching objects in a
227      cache are always valid.
228
229      If present, the function should return one of the following values:
230
231         (*) FSCACHE_CHECKAUX_OKAY               - the entry is okay as is
232         (*) FSCACHE_CHECKAUX_NEEDS_UPDATE       - the entry requires update
233         (*) FSCACHE_CHECKAUX_OBSOLETE           - the entry should be deleted
234
235      This function can also be used to extract data from the auxiliary data in
236      the cache and copy it into the netfs's structures.
237
238  (8) A pair of functions to manage contexts for the completion callback
239      [optional].
240
241      The cache read/write functions are passed a context which is then passed
242      to the I/O completion callback function.  To ensure this context remains
243      valid until after the I/O completion is called, two functions may be
244      provided: one to get an extra reference on the context, and one to drop a
245      reference to it.
246
247      If the context is not used or is a type of object that won't go out of
248      scope, then these functions are not required.  These functions are not
249      required for indices as indices may not contain data.  These functions may
250      be called in interrupt context and so may not sleep.
251
252  (9) A function to mark a page as retaining cache metadata [optional].
253
254      This is called by the cache to indicate that it is retaining in-memory
255      information for this page and that the netfs should uncache the page when
256      it has finished.  This does not indicate whether there's data on the disk
257      or not.  Note that several pages at once may be presented for marking.
258
259      The PG_fscache bit is set on the pages before this function would be
260      called, so the function need not be provided if this is sufficient.
261
262      This function is not required for indices as they're not permitted data.
263
264 (10) A function to unmark all the pages retaining cache metadata [mandatory].
265
266      This is called by FS-Cache to indicate that a backing store is being
267      unbound from a cookie and that all the marks on the pages should be
268      cleared to prevent confusion.  Note that the cache will have torn down all
269      its tracking information so that the pages don't need to be explicitly
270      uncached.
271
272      This function is not required for indices as they're not permitted data.
273
274
275 ===================================
276 NETWORK FILESYSTEM (UN)REGISTRATION
277 ===================================
278
279 The first step is to declare the network filesystem to the cache.  This also
280 involves specifying the layout of the primary index (for AFS, this would be the
281 "cell" level).
282
283 The registration function is:
284
285         int fscache_register_netfs(struct fscache_netfs *netfs);
286
287 It just takes a pointer to the netfs definition.  It returns 0 or an error as
288 appropriate.
289
290 For kAFS, registration is done as follows:
291
292         ret = fscache_register_netfs(&afs_cache_netfs);
293
294 The last step is, of course, unregistration:
295
296         void fscache_unregister_netfs(struct fscache_netfs *netfs);
297
298
299 ================
300 CACHE TAG LOOKUP
301 ================
302
303 FS-Cache permits the use of more than one cache.  To permit particular index
304 subtrees to be bound to particular caches, the second step is to look up cache
305 representation tags.  This step is optional; it can be left entirely up to
306 FS-Cache as to which cache should be used.  The problem with doing that is that
307 FS-Cache will always pick the first cache that was registered.
308
309 To get the representation for a named tag:
310
311         struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name);
312
313 This takes a text string as the name and returns a representation of a tag.  It
314 will never return an error.  It may return a dummy tag, however, if it runs out
315 of memory; this will inhibit caching with this tag.
316
317 Any representation so obtained must be released by passing it to this function:
318
319         void fscache_release_cache_tag(struct fscache_cache_tag *tag);
320
321 The tag will be retrieved by FS-Cache when it calls the object definition
322 operation select_cache().
323
324
325 ==================
326 INDEX REGISTRATION
327 ==================
328
329 The third step is to inform FS-Cache about part of an index hierarchy that can
330 be used to locate files.  This is done by requesting a cookie for each index in
331 the path to the file:
332
333         struct fscache_cookie *
334         fscache_acquire_cookie(struct fscache_cookie *parent,
335                                const struct fscache_object_def *def,
336                                void *netfs_data,
337                                bool enable);
338
339 This function creates an index entry in the index represented by parent,
340 filling in the index entry by calling the operations pointed to by def.
341
342 Note that this function never returns an error - all errors are handled
343 internally.  It may, however, return NULL to indicate no cookie.  It is quite
344 acceptable to pass this token back to this function as the parent to another
345 acquisition (or even to the relinquish cookie, read page and write page
346 functions - see below).
347
348 Note also that no indices are actually created in a cache until a non-index
349 object needs to be created somewhere down the hierarchy.  Furthermore, an index
350 may be created in several different caches independently at different times.
351 This is all handled transparently, and the netfs doesn't see any of it.
352
353 A cookie will be created in the disabled state if enabled is false.  A cookie
354 must be enabled to do anything with it.  A disabled cookie can be enabled by
355 calling fscache_enable_cookie() (see below).
356
357 For example, with AFS, a cell would be added to the primary index.  This index
358 entry would have a dependent inode containing a volume location index for the
359 volume mappings within this cell:
360
361         cell->cache =
362                 fscache_acquire_cookie(afs_cache_netfs.primary_index,
363                                        &afs_cell_cache_index_def,
364                                        cell, true);
365
366 Then when a volume location was accessed, it would be entered into the cell's
367 index and an inode would be allocated that acts as a volume type and hash chain
368 combination:
369
370         vlocation->cache =
371                 fscache_acquire_cookie(cell->cache,
372                                        &afs_vlocation_cache_index_def,
373                                        vlocation, true);
374
375 And then a particular flavour of volume (R/O for example) could be added to
376 that index, creating another index for vnodes (AFS inode equivalents):
377
378         volume->cache =
379                 fscache_acquire_cookie(vlocation->cache,
380                                        &afs_volume_cache_index_def,
381                                        volume, true);
382
383
384 ======================
385 DATA FILE REGISTRATION
386 ======================
387
388 The fourth step is to request a data file be created in the cache.  This is
389 identical to index cookie acquisition.  The only difference is that the type in
390 the object definition should be something other than index type.
391
392         vnode->cache =
393                 fscache_acquire_cookie(volume->cache,
394                                        &afs_vnode_cache_object_def,
395                                        vnode, true);
396
397
398 =================================
399 MISCELLANEOUS OBJECT REGISTRATION
400 =================================
401
402 An optional step is to request an object of miscellaneous type be created in
403 the cache.  This is almost identical to index cookie acquisition.  The only
404 difference is that the type in the object definition should be something other
405 than index type.  Whilst the parent object could be an index, it's more likely
406 it would be some other type of object such as a data file.
407
408         xattr->cache =
409                 fscache_acquire_cookie(vnode->cache,
410                                        &afs_xattr_cache_object_def,
411                                        xattr, true);
412
413 Miscellaneous objects might be used to store extended attributes or directory
414 entries for example.
415
416
417 ==========================
418 SETTING THE DATA FILE SIZE
419 ==========================
420
421 The fifth step is to set the physical attributes of the file, such as its size.
422 This doesn't automatically reserve any space in the cache, but permits the
423 cache to adjust its metadata for data tracking appropriately:
424
425         int fscache_attr_changed(struct fscache_cookie *cookie);
426
427 The cache will return -ENOBUFS if there is no backing cache or if there is no
428 space to allocate any extra metadata required in the cache.  The attributes
429 will be accessed with the get_attr() cookie definition operation.
430
431 Note that attempts to read or write data pages in the cache over this size may
432 be rebuffed with -ENOBUFS.
433
434 This operation schedules an attribute adjustment to happen asynchronously at
435 some point in the future, and as such, it may happen after the function returns
436 to the caller.  The attribute adjustment excludes read and write operations.
437
438
439 =====================
440 PAGE ALLOC/READ/WRITE
441 =====================
442
443 And the sixth step is to store and retrieve pages in the cache.  There are
444 three functions that are used to do this.
445
446 Note:
447
448  (1) A page should not be re-read or re-allocated without uncaching it first.
449
450  (2) A read or allocated page must be uncached when the netfs page is released
451      from the pagecache.
452
453  (3) A page should only be written to the cache if previous read or allocated.
454
455 This permits the cache to maintain its page tracking in proper order.
456
457
458 PAGE READ
459 ---------
460
461 Firstly, the netfs should ask FS-Cache to examine the caches and read the
462 contents cached for a particular page of a particular file if present, or else
463 allocate space to store the contents if not:
464
465         typedef
466         void (*fscache_rw_complete_t)(struct page *page,
467                                       void *context,
468                                       int error);
469
470         int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
471                                        struct page *page,
472                                        fscache_rw_complete_t end_io_func,
473                                        void *context,
474                                        gfp_t gfp);
475
476 The cookie argument must specify a cookie for an object that isn't an index,
477 the page specified will have the data loaded into it (and is also used to
478 specify the page number), and the gfp argument is used to control how any
479 memory allocations made are satisfied.
480
481 If the cookie indicates the inode is not cached:
482
483  (1) The function will return -ENOBUFS.
484
485 Else if there's a copy of the page resident in the cache:
486
487  (1) The mark_pages_cached() cookie operation will be called on that page.
488
489  (2) The function will submit a request to read the data from the cache's
490      backing device directly into the page specified.
491
492  (3) The function will return 0.
493
494  (4) When the read is complete, end_io_func() will be invoked with:
495
496      (*) The netfs data supplied when the cookie was created.
497
498      (*) The page descriptor.
499
500      (*) The context argument passed to the above function.  This will be
501          maintained with the get_context/put_context functions mentioned above.
502
503      (*) An argument that's 0 on success or negative for an error code.
504
505      If an error occurs, it should be assumed that the page contains no usable
506      data.  fscache_readpages_cancel() may need to be called.
507
508      end_io_func() will be called in process context if the read is results in
509      an error, but it might be called in interrupt context if the read is
510      successful.
511
512 Otherwise, if there's not a copy available in cache, but the cache may be able
513 to store the page:
514
515  (1) The mark_pages_cached() cookie operation will be called on that page.
516
517  (2) A block may be reserved in the cache and attached to the object at the
518      appropriate place.
519
520  (3) The function will return -ENODATA.
521
522 This function may also return -ENOMEM or -EINTR, in which case it won't have
523 read any data from the cache.
524
525
526 PAGE ALLOCATE
527 -------------
528
529 Alternatively, if there's not expected to be any data in the cache for a page
530 because the file has been extended, a block can simply be allocated instead:
531
532         int fscache_alloc_page(struct fscache_cookie *cookie,
533                                struct page *page,
534                                gfp_t gfp);
535
536 This is similar to the fscache_read_or_alloc_page() function, except that it
537 never reads from the cache.  It will return 0 if a block has been allocated,
538 rather than -ENODATA as the other would.  One or the other must be performed
539 before writing to the cache.
540
541 The mark_pages_cached() cookie operation will be called on the page if
542 successful.
543
544
545 PAGE WRITE
546 ----------
547
548 Secondly, if the netfs changes the contents of the page (either due to an
549 initial download or if a user performs a write), then the page should be
550 written back to the cache:
551
552         int fscache_write_page(struct fscache_cookie *cookie,
553                                struct page *page,
554                                gfp_t gfp);
555
556 The cookie argument must specify a data file cookie, the page specified should
557 contain the data to be written (and is also used to specify the page number),
558 and the gfp argument is used to control how any memory allocations made are
559 satisfied.
560
561 The page must have first been read or allocated successfully and must not have
562 been uncached before writing is performed.
563
564 If the cookie indicates the inode is not cached then:
565
566  (1) The function will return -ENOBUFS.
567
568 Else if space can be allocated in the cache to hold this page:
569
570  (1) PG_fscache_write will be set on the page.
571
572  (2) The function will submit a request to write the data to cache's backing
573      device directly from the page specified.
574
575  (3) The function will return 0.
576
577  (4) When the write is complete PG_fscache_write is cleared on the page and
578      anyone waiting for that bit will be woken up.
579
580 Else if there's no space available in the cache, -ENOBUFS will be returned.  It
581 is also possible for the PG_fscache_write bit to be cleared when no write took
582 place if unforeseen circumstances arose (such as a disk error).
583
584 Writing takes place asynchronously.
585
586
587 MULTIPLE PAGE READ
588 ------------------
589
590 A facility is provided to read several pages at once, as requested by the
591 readpages() address space operation:
592
593         int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
594                                         struct address_space *mapping,
595                                         struct list_head *pages,
596                                         int *nr_pages,
597                                         fscache_rw_complete_t end_io_func,
598                                         void *context,
599                                         gfp_t gfp);
600
601 This works in a similar way to fscache_read_or_alloc_page(), except:
602
603  (1) Any page it can retrieve data for is removed from pages and nr_pages and
604      dispatched for reading to the disk.  Reads of adjacent pages on disk may
605      be merged for greater efficiency.
606
607  (2) The mark_pages_cached() cookie operation will be called on several pages
608      at once if they're being read or allocated.
609
610  (3) If there was an general error, then that error will be returned.
611
612      Else if some pages couldn't be allocated or read, then -ENOBUFS will be
613      returned.
614
615      Else if some pages couldn't be read but were allocated, then -ENODATA will
616      be returned.
617
618      Otherwise, if all pages had reads dispatched, then 0 will be returned, the
619      list will be empty and *nr_pages will be 0.
620
621  (4) end_io_func will be called once for each page being read as the reads
622      complete.  It will be called in process context if error != 0, but it may
623      be called in interrupt context if there is no error.
624
625 Note that a return of -ENODATA, -ENOBUFS or any other error does not preclude
626 some of the pages being read and some being allocated.  Those pages will have
627 been marked appropriately and will need uncaching.
628
629
630 CANCELLATION OF UNREAD PAGES
631 ----------------------------
632
633 If one or more pages are passed to fscache_read_or_alloc_pages() but not then
634 read from the cache and also not read from the underlying filesystem then
635 those pages will need to have any marks and reservations removed.  This can be
636 done by calling:
637
638         void fscache_readpages_cancel(struct fscache_cookie *cookie,
639                                       struct list_head *pages);
640
641 prior to returning to the caller.  The cookie argument should be as passed to
642 fscache_read_or_alloc_pages().  Every page in the pages list will be examined
643 and any that have PG_fscache set will be uncached.
644
645
646 ==============
647 PAGE UNCACHING
648 ==============
649
650 To uncache a page, this function should be called:
651
652         void fscache_uncache_page(struct fscache_cookie *cookie,
653                                   struct page *page);
654
655 This function permits the cache to release any in-memory representation it
656 might be holding for this netfs page.  This function must be called once for
657 each page on which the read or write page functions above have been called to
658 make sure the cache's in-memory tracking information gets torn down.
659
660 Note that pages can't be explicitly deleted from the a data file.  The whole
661 data file must be retired (see the relinquish cookie function below).
662
663 Furthermore, note that this does not cancel the asynchronous read or write
664 operation started by the read/alloc and write functions, so the page
665 invalidation functions must use:
666
667         bool fscache_check_page_write(struct fscache_cookie *cookie,
668                                       struct page *page);
669
670 to see if a page is being written to the cache, and:
671
672         void fscache_wait_on_page_write(struct fscache_cookie *cookie,
673                                         struct page *page);
674
675 to wait for it to finish if it is.
676
677
678 When releasepage() is being implemented, a special FS-Cache function exists to
679 manage the heuristics of coping with vmscan trying to eject pages, which may
680 conflict with the cache trying to write pages to the cache (which may itself
681 need to allocate memory):
682
683         bool fscache_maybe_release_page(struct fscache_cookie *cookie,
684                                         struct page *page,
685                                         gfp_t gfp);
686
687 This takes the netfs cookie, and the page and gfp arguments as supplied to
688 releasepage().  It will return false if the page cannot be released yet for
689 some reason and if it returns true, the page has been uncached and can now be
690 released.
691
692 To make a page available for release, this function may wait for an outstanding
693 storage request to complete, or it may attempt to cancel the storage request -
694 in which case the page will not be stored in the cache this time.
695
696
697 BULK INODE PAGE UNCACHE
698 -----------------------
699
700 A convenience routine is provided to perform an uncache on all the pages
701 attached to an inode.  This assumes that the pages on the inode correspond on a
702 1:1 basis with the pages in the cache.
703
704         void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,
705                                              struct inode *inode);
706
707 This takes the netfs cookie that the pages were cached with and the inode that
708 the pages are attached to.  This function will wait for pages to finish being
709 written to the cache and for the cache to finish with the page generally.  No
710 error is returned.
711
712
713 ===============================
714 INDEX AND DATA FILE CONSISTENCY
715 ===============================
716
717 To find out whether auxiliary data for an object is up to data within the
718 cache, the following function can be called:
719
720         int fscache_check_consistency(struct fscache_cookie *cookie)
721
722 This will call back to the netfs to check whether the auxiliary data associated
723 with a cookie is correct.  It returns 0 if it is and -ESTALE if it isn't; it
724 may also return -ENOMEM and -ERESTARTSYS.
725
726 To request an update of the index data for an index or other object, the
727 following function should be called:
728
729         void fscache_update_cookie(struct fscache_cookie *cookie);
730
731 This function will refer back to the netfs_data pointer stored in the cookie by
732 the acquisition function to obtain the data to write into each revised index
733 entry.  The update method in the parent index definition will be called to
734 transfer the data.
735
736 Note that partial updates may happen automatically at other times, such as when
737 data blocks are added to a data file object.
738
739
740 =================
741 COOKIE ENABLEMENT
742 =================
743
744 Cookies exist in one of two states: enabled and disabled.  If a cookie is
745 disabled, it ignores all attempts to acquire child cookies; check, update or
746 invalidate its state; allocate, read or write backing pages - though it is
747 still possible to uncache pages and relinquish the cookie.
748
749 The initial enablement state is set by fscache_acquire_cookie(), but the cookie
750 can be enabled or disabled later.  To disable a cookie, call:
751     
752         void fscache_disable_cookie(struct fscache_cookie *cookie,
753                                     bool invalidate);
754     
755 If the cookie is not already disabled, this locks the cookie against other
756 enable and disable ops, marks the cookie as being disabled, discards or
757 invalidates any backing objects and waits for cessation of activity on any
758 associated object before unlocking the cookie.
759
760 All possible failures are handled internally.  The caller should consider
761 calling fscache_uncache_all_inode_pages() afterwards to make sure all page
762 markings are cleared up.
763     
764 Cookies can be enabled or reenabled with:
765     
766         void fscache_enable_cookie(struct fscache_cookie *cookie,
767                                    bool (*can_enable)(void *data),
768                                    void *data)
769     
770 If the cookie is not already enabled, this locks the cookie against other
771 enable and disable ops, invokes can_enable() and, if the cookie is not an index
772 cookie, will begin the procedure of acquiring backing objects.
773
774 The optional can_enable() function is passed the data argument and returns a
775 ruling as to whether or not enablement should actually be permitted to begin.
776
777 All possible failures are handled internally.  The cookie will only be marked
778 as enabled if provisional backing objects are allocated.
779
780
781 ===============================
782 MISCELLANEOUS COOKIE OPERATIONS
783 ===============================
784
785 There are a number of operations that can be used to control cookies:
786
787  (*) Cookie pinning:
788
789         int fscache_pin_cookie(struct fscache_cookie *cookie);
790         void fscache_unpin_cookie(struct fscache_cookie *cookie);
791
792      These operations permit data cookies to be pinned into the cache and to
793      have the pinning removed.  They are not permitted on index cookies.
794
795      The pinning function will return 0 if successful, -ENOBUFS in the cookie
796      isn't backed by a cache, -EOPNOTSUPP if the cache doesn't support pinning,
797      -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
798      -EIO if there's any other problem.
799
800  (*) Data space reservation:
801
802         int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size);
803
804      This permits a netfs to request cache space be reserved to store up to the
805      given amount of a file.  It is permitted to ask for more than the current
806      size of the file to allow for future file expansion.
807
808      If size is given as zero then the reservation will be cancelled.
809
810      The function will return 0 if successful, -ENOBUFS in the cookie isn't
811      backed by a cache, -EOPNOTSUPP if the cache doesn't support reservations,
812      -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
813      -EIO if there's any other problem.
814
815      Note that this doesn't pin an object in a cache; it can still be culled to
816      make space if it's not in use.
817
818
819 =====================
820 COOKIE UNREGISTRATION
821 =====================
822
823 To get rid of a cookie, this function should be called.
824
825         void fscache_relinquish_cookie(struct fscache_cookie *cookie,
826                                        bool retire);
827
828 If retire is non-zero, then the object will be marked for recycling, and all
829 copies of it will be removed from all active caches in which it is present.
830 Not only that but all child objects will also be retired.
831
832 If retire is zero, then the object may be available again when next the
833 acquisition function is called.  Retirement here will overrule the pinning on a
834 cookie.
835
836 One very important note - relinquish must NOT be called for a cookie unless all
837 the cookies for "child" indices, objects and pages have been relinquished
838 first.
839
840
841 ==================
842 INDEX INVALIDATION
843 ==================
844
845 There is no direct way to invalidate an index subtree.  To do this, the caller
846 should relinquish and retire the cookie they have, and then acquire a new one.
847
848
849 ======================
850 DATA FILE INVALIDATION
851 ======================
852
853 Sometimes it will be necessary to invalidate an object that contains data.
854 Typically this will be necessary when the server tells the netfs of a foreign
855 change - at which point the netfs has to throw away all the state it had for an
856 inode and reload from the server.
857
858 To indicate that a cache object should be invalidated, the following function
859 can be called:
860
861         void fscache_invalidate(struct fscache_cookie *cookie);
862
863 This can be called with spinlocks held as it defers the work to a thread pool.
864 All extant storage, retrieval and attribute change ops at this point are
865 cancelled and discarded.  Some future operations will be rejected until the
866 cache has had a chance to insert a barrier in the operations queue.  After
867 that, operations will be queued again behind the invalidation operation.
868
869 The invalidation operation will perform an attribute change operation and an
870 auxiliary data update operation as it is very likely these will have changed.
871
872 Using the following function, the netfs can wait for the invalidation operation
873 to have reached a point at which it can start submitting ordinary operations
874 once again:
875
876         void fscache_wait_on_invalidate(struct fscache_cookie *cookie);
877
878
879 ===========================
880 FS-CACHE SPECIFIC PAGE FLAG
881 ===========================
882
883 FS-Cache makes use of a page flag, PG_private_2, for its own purpose.  This is
884 given the alternative name PG_fscache.
885
886 PG_fscache is used to indicate that the page is known by the cache, and that
887 the cache must be informed if the page is going to go away.  It's an indication
888 to the netfs that the cache has an interest in this page, where an interest may
889 be a pointer to it, resources allocated or reserved for it, or I/O in progress
890 upon it.
891
892 The netfs can use this information in methods such as releasepage() to
893 determine whether it needs to uncache a page or update it.
894
895 Furthermore, if this bit is set, releasepage() and invalidatepage() operations
896 will be called on a page to get rid of it, even if PG_private is not set.  This
897 allows caching to attempted on a page before read_cache_pages() to be called
898 after fscache_read_or_alloc_pages() as the former will try and release pages it
899 was given under certain circumstances.
900
901 This bit does not overlap with such as PG_private.  This means that FS-Cache
902 can be used with a filesystem that uses the block buffering code.
903
904 There are a number of operations defined on this flag:
905
906         int PageFsCache(struct page *page);
907         void SetPageFsCache(struct page *page)
908         void ClearPageFsCache(struct page *page)
909         int TestSetPageFsCache(struct page *page)
910         int TestClearPageFsCache(struct page *page)
911
912 These functions are bit test, bit set, bit clear, bit test and set and bit
913 test and clear operations on PG_fscache.