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