========================== General Filesystem Caching ========================== ======== OVERVIEW ======== This facility is a general purpose cache for network filesystems, though it could be used for caching other things such as ISO9660 filesystems too. FS-Cache mediates between cache backends (such as CacheFS) and network filesystems: +---------+ | | +--------------+ | NFS |--+ | | | | | +-->| CacheFS | +---------+ | +----------+ | | /dev/hda5 | | | | | +--------------+ +---------+ +-->| | | | | | |--+ | AFS |----->| FS-Cache | | | | |--+ +---------+ +-->| | | | | | | +--------------+ +---------+ | +----------+ | | | | | | +-->| CacheFiles | | ISOFS |--+ | /var/cache | | | +--------------+ +---------+ FS-Cache does not follow the idea of completely loading every netfs file opened in its entirety into a cache before permitting it to be accessed and then serving the pages out of that cache rather than the netfs inode because: (1) It must be practical to operate without a cache. (2) The size of any accessible file must not be limited to the size of the cache. (3) The combined size of all opened files (this includes mapped libraries) must not be limited to the size of the cache. (4) The user should not be forced to download an entire file just to do a one-off access of a small portion of it (such as might be done with the "file" program). It instead serves the cache out in PAGE_SIZE chunks as and when requested by the netfs('s) using it. FS-Cache provides the following facilities: (1) More than one cache can be used at once. Caches can be selected explicitly by use of tags. (2) Caches can be added / removed at any time. (3) The netfs is provided with an interface that allows either party to withdraw caching facilities from a file (required for (2)). (4) The interface to the netfs returns as few errors as possible, preferring rather to let the netfs remain oblivious. (5) Cookies are used to represent indices, files and other objects to the netfs. The simplest cookie is just a NULL pointer - indicating nothing cached there. (6) The netfs is allowed to propose - dynamically - any index hierarchy it desires, though it must be aware that the index search function is recursive, stack space is limited, and indices can only be children of indices. (7) Data I/O is done direct to and from the netfs's pages. The netfs indicates that page A is at index B of the data-file represented by cookie C, and that it should be read or written. The cache backend may or may not start I/O on that page, but if it does, a netfs callback will be invoked to indicate completion. The I/O may be either synchronous or asynchronous. (8) Cookies can be "retired" upon release. At this point FS-Cache will mark them as obsolete and the index hierarchy rooted at that point will get recycled. (9) The netfs provides a "match" function for index searches. In addition to saying whether a match was made or not, this can also specify that an entry should be updated or deleted. FS-Cache maintains a virtual indexing tree in which all indices, files, objects and pages are kept. Bits of this tree may actually reside in one or more caches. FSDEF | +------------------------------------+ | | NFS AFS | | +--------------------------+ +-----------+ | | | | homedir mirror afs.org redhat.com | | | +------------+ +---------------+ +----------+ | | | | | | 00001 00002 00007 00125 vol00001 vol00002 | | | | | +---+---+ +-----+ +---+ +------+------+ +-----+----+ | | | | | | | | | | | | | PG0 PG1 PG2 PG0 XATTR PG0 PG1 DIRENT DIRENT DIRENT R/W R/O Bak | | PG0 +-------+ | | 00001 00003 | +---+---+ | | | PG0 PG1 PG2 In the example above, you can see two netfs's being backed: NFS and AFS. These have different index hierarchies: (*) The NFS primary index contains per-server indices. Each server index is indexed by NFS file handles to get data file objects. Each data file objects can have an array of pages, but may also have further child objects, such as extended attributes and directory entries. Extended attribute objects themselves have page-array contents. (*) The AFS primary index contains per-cell indices. Each cell index contains per-logical-volume indices. Each of volume index contains up to three indices for the read-write, read-only and backup mirrors of those volumes. Each of these contains vnode data file objects, each of which contains an array of pages. The very top index is the FS-Cache master index in which individual netfs's have entries. Any index object may reside in more than one cache, provided it only has index children. Any index with non-index object children will be assumed to only reside in one cache. The netfs API to FS-Cache can be found in: Documentation/filesystems/caching/netfs-api.txt The cache backend API to FS-Cache can be found in: Documentation/filesystems/caching/backend-api.txt