16 files changed, 4866 insertions, 0 deletions

diff --git a/Documentation/filesystems/caching/cachefiles.txt b/Documentation/filesystems/caching/cachefiles.txt
new file mode 100644
index 000000000000..c78a49b7bba6
--- /dev/null
+++ b/Documentation/filesystems/caching/cachefiles.txt
@@ -0,0 +1,501 @@
+               ===============================================
+               CacheFiles: CACHE ON ALREADY MOUNTED FILESYSTEM
+               ===============================================
+
+Contents:
+
+ (*) Overview.
+
+ (*) Requirements.
+
+ (*) Configuration.
+
+ (*) Starting the cache.
+
+ (*) Things to avoid.
+
+ (*) Cache culling.
+
+ (*) Cache structure.
+
+ (*) Security model and SELinux.
+
+ (*) A note on security.
+
+ (*) Statistical information.
+
+ (*) Debugging.
+
+
+========
+OVERVIEW
+========
+
+CacheFiles is a caching backend that's meant to use as a cache a directory on
+an already mounted filesystem of a local type (such as Ext3).
+
+CacheFiles uses a userspace daemon to do some of the cache management - such as
+reaping stale nodes and culling.  This is called cachefilesd and lives in
+/sbin.
+
+The filesystem and data integrity of the cache are only as good as those of the
+filesystem providing the backing services.  Note that CacheFiles does not
+attempt to journal anything since the journalling interfaces of the various
+filesystems are very specific in nature.
+
+CacheFiles creates a misc character device - "/dev/cachefiles" - that is used
+to communication with the daemon.  Only one thing may have this open at once,
+and whilst it is open, a cache is at least partially in existence.  The daemon
+opens this and sends commands down it to control the cache.
+
+CacheFiles is currently limited to a single cache.
+
+CacheFiles attempts to maintain at least a certain percentage of free space on
+the filesystem, shrinking the cache by culling the objects it contains to make
+space if necessary - see the "Cache Culling" section.  This means it can be
+placed on the same medium as a live set of data, and will expand to make use of
+spare space and automatically contract when the set of data requires more
+space.
+
+
+============
+REQUIREMENTS
+============
+
+The use of CacheFiles and its daemon requires the following features to be
+available in the system and in the cache filesystem:
+
+        - dnotify.
+
+        - extended attributes (xattrs).
+
+        - openat() and friends.
+
+        - bmap() support on files in the filesystem (FIBMAP ioctl).
+
+        - The use of bmap() to detect a partial page at the end of the file.
+
+It is strongly recommended that the "dir_index" option is enabled on Ext3
+filesystems being used as a cache.
+
+
+=============
+CONFIGURATION
+=============
+
+The cache is configured by a script in /etc/cachefilesd.conf.  These commands
+set up cache ready for use.  The following script commands are available:
+
+ (*) brun <N>%
+ (*) bcull <N>%
+ (*) bstop <N>%
+ (*) frun <N>%
+ (*) fcull <N>%
+ (*) fstop <N>%
+
+        Configure the culling limits.  Optional.  See the section on culling
+        The defaults are 7% (run), 5% (cull) and 1% (stop) respectively.
+
+        The commands beginning with a 'b' are file space (block) limits, those
+        beginning with an 'f' are file count limits.
+
+ (*) dir <path>
+
+        Specify the directory containing the root of the cache.  Mandatory.
+
+ (*) tag <name>
+
+        Specify a tag to FS-Cache to use in distinguishing multiple caches.
+        Optional.  The default is "CacheFiles".
+
+ (*) debug <mask>
+
+        Specify a numeric bitmask to control debugging in the kernel module.
+        Optional.  The default is zero (all off).  The following values can be
+        OR'd into the mask to collect various information:
+
+                1       Turn on trace of function entry (_enter() macros)
+                2       Turn on trace of function exit (_leave() macros)
+                4       Turn on trace of internal debug points (_debug())
+
+        This mask can also be set through sysfs, eg:
+
+                echo 5 >/sys/modules/cachefiles/parameters/debug
+
+
+==================
+STARTING THE CACHE
+==================
+
+The cache is started by running the daemon.  The daemon opens the cache device,
+configures the cache and tells it to begin caching.  At that point the cache
+binds to fscache and the cache becomes live.
+
+The daemon is run as follows:
+
+        /sbin/cachefilesd [-d]* [-s] [-n] [-f <configfile>]
+
+The flags are:
+
+ (*) -d
+
+        Increase the debugging level.  This can be specified multiple times and
+        is cumulative with itself.
+
+ (*) -s
+
+        Send messages to stderr instead of syslog.
+
+ (*) -n
+
+        Don't daemonise and go into background.
+
+ (*) -f <configfile>
+
+        Use an alternative configuration file rather than the default one.
+
+
+===============
+THINGS TO AVOID
+===============
+
+Do not mount other things within the cache as this will cause problems.  The
+kernel module contains its own very cut-down path walking facility that ignores
+mountpoints, but the daemon can't avoid them.
+
+Do not create, rename or unlink files and directories in the cache whilst the
+cache is active, as this may cause the state to become uncertain.
+
+Renaming files in the cache might make objects appe