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