Documentation/filesystems/caching/fscache.txt

   1                           ==========================
   2                           General Filesystem Caching
   3                           ==========================
   4
   5 ========
   6 OVERVIEW
   7 ========
   8
   9 This facility is a general purpose cache for network filesystems, though it
  10 could be used for caching other things such as ISO9660 filesystems too.
  11
  12 FS-Cache mediates between cache backends (such as CacheFS) and network
  13 filesystems:
  14
  15         +---------+
  16         |         |                        +--------------+
  17         |   NFS   |--+                     |              |
  18         |         |  |                 +-->|   CacheFS    |
  19         +---------+  |   +----------+  |   |  /dev/hda5   |
  20                      |   |          |  |   +--------------+
  21         +---------+  +-->|          |  |
  22         |         |      |          |--+
  23         |   AFS   |----->| FS-Cache |
  24         |         |      |          |--+
  25         +---------+  +-->|          |  |
  26                      |   |          |  |   +--------------+
  27         +---------+  |   +----------+  |   |              |
  28         |         |  |                 +-->|  CacheFiles  |
  29         |  ISOFS  |--+                     |  /var/cache  |
  30         |         |                        +--------------+
  31         +---------+
  32
  33
  34 FS-Cache does not follow the idea of completely loading every netfs file
  35 opened in its entirety into a cache before permitting it to be accessed and
  36 then serving the pages out of that cache rather than the netfs inode because:
  37
  38  (1) It must be practical to operate without a cache.
  39
  40  (2) The size of any accessible file must not be limited to the size of the
  41      cache.
  42
  43  (3) The combined size of all opened files (this includes mapped libraries)
  44      must not be limited to the size of the cache.
  45
  46  (4) The user should not be forced to download an entire file just to do a
  47      one-off access of a small portion of it (such as might be done with the
  48      "file" program).
  49
  50 It instead serves the cache out in PAGE_SIZE chunks as and when requested by
  51 the netfs('s) using it.
  52
  53
  54 FS-Cache provides the following facilities:
  55
  56  (1) More than one cache can be used at once.  Caches can be selected
  57      explicitly by use of tags.
  58
  59  (2) Caches can be added / removed at any time.
  60
  61  (3) The netfs is provided with an interface that allows either party to
  62      withdraw caching facilities from a file (required for (2)).
  63
  64  (4) The interface to the netfs returns as few errors as possible, preferring
  65      rather to let the netfs remain oblivious.
  66
  67  (5) Cookies are used to represent indices, files and other objects to the
  68      netfs.  The simplest cookie is just a NULL pointer - indicating nothing
  69      cached there.
  70
  71  (6) The netfs is allowed to propose - dynamically - any index hierarchy it
  72      desires, though it must be aware that the index search function is
  73      recursive, stack space is limited, and indices can only be children of
  74      indices.
  75
  76  (7) Data I/O is done direct to and from the netfs's pages.  The netfs
  77      indicates that page A is at index B of the data-file represented by cookie
  78      C, and that it should be read or written.  The cache backend may or may
  79      not start I/O on that page, but if it does, a netfs callback will be
  80      invoked to indicate completion.  The I/O may be either synchronous or
  81      asynchronous.
  82
  83  (8) Cookies can be "retired" upon release.  At this point FS-Cache will mark
  84      them as obsolete and the index hierarchy rooted at that point will get
  85      recycled.
  86
  87  (9) The netfs provides a "match" function for index searches.  In addition to
  88      saying whether a match was made or not, this can also specify that an
  89      entry should be updated or deleted.
  90
  91
  92 FS-Cache maintains a virtual indexing tree in which all indices, files, objects
  93 and pages are kept.  Bits of this tree may actually reside in one or more
  94 caches.
  95
  96                                            FSDEF
  97                                              |
  98                         +------------------------------------+
  99                         |                                    |
 100                        NFS                                  AFS
 101                         |                                    |
 102            +--------------------------+                +-----------+
 103            |                          |                |           |
 104         homedir                     mirror          afs.org   redhat.com
 105            |                          |                            |
 106      +------------+           +---------------+              +----------+
 107      |            |           |               |              |          |
 108    00001        00002       00007           00125        vol00001   vol00002
 109      |            |           |               |                         |
 110  +---+---+     +-----+      +---+      +------+------+            +-----+----+
 111  |   |   |     |     |      |   |      |      |      |            |     |    |
 112 PG0 PG1 PG2   PG0  XATTR   PG0 PG1   DIRENT DIRENT DIRENT        R/W   R/O  Bak
 113                      |                                            |
 114                     PG0                                       +-------+
 115                                                               |       |
 116                                                             00001   00003
 117                                                               |
 118                                                           +---+---+
 119                                                           |   |   |
 120                                                          PG0 PG1 PG2
 121
 122 In the example above, you can see two netfs's being backed: NFS and AFS.  These
 123 have different index hierarchies:
 124
 125  (*) The NFS primary index contains per-server indices.  Each server index is
 126      indexed by NFS file handles to get data file objects.  Each data file
 127      objects can have an array of pages, but may also have further child
 128      objects, such as extended attributes and directory entries.  Extended
 129      attribute objects themselves have page-array contents.
 130
 131  (*) The AFS primary index contains per-cell indices.  Each cell index contains
 132      per-logical-volume indices.  Each of volume index contains up to three
 133      indices for the read-write, read-only and backup mirrors of those volumes.
 134      Each of these contains vnode data file objects, each of which contains an
 135      array of pages.
 136
 137 The very top index is the FS-Cache master index in which individual netfs's
 138 have entries.
 139
 140 Any index object may reside in more than one cache, provided it only has index
 141 children.  Any index with non-index object children will be assumed to only
 142 reside in one cache.
 143
 144
 145 The netfs API to FS-Cache can be found in:
 146
 147         Documentation/filesystems/caching/netfs-api.txt
 148
 149 The cache backend API to FS-Cache can be found in:
 150
 151         Documentation/filesystems/caching/backend-api.txt