0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==========================
0004 General Filesystem Caching
0005 ==========================
0006
0007 Overview
0008 ========
0009
0010 This facility is a general purpose cache for network filesystems, though it
0011 could be used for caching other things such as ISO9660 filesystems too.
0012
0013 FS-Cache mediates between cache backends (such as CacheFiles) and network
0014 filesystems::
0015
0016 +---------+
0017 | | +--------------+
0018 | NFS |--+ | |
0019 | | | +-->| CacheFS |
0020 +---------+ | +----------+ | | /dev/hda5 |
0021 | | | | +--------------+
0022 +---------+ +-------------->| | |
0023 | | +-------+ | |--+
0024 | AFS |----->| | | FS-Cache |
0025 | | | netfs |-->| |--+
0026 +---------+ +-->| lib | | | |
0027 | | | | | | +--------------+
0028 +---------+ | +-------+ +----------+ | | |
0029 | | | +-->| CacheFiles |
0030 | 9P |--+ | /var/cache |
0031 | | +--------------+
0032 +---------+
0033
0034 Or to look at it another way, FS-Cache is a module that provides a caching
0035 facility to a network filesystem such that the cache is transparent to the
0036 user::
0037
0038 +---------+
0039 | |
0040 | Server |
0041 | |
0042 +---------+
0043 | NETWORK
0044 ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0045 |
0046 | +----------+
0047 V | |
0048 +---------+ | |
0049 | | | |
0050 | NFS |----->| FS-Cache |
0051 | | | |--+
0052 +---------+ | | | +--------------+ +--------------+
0053 | | | | | | | |
0054 V +----------+ +-->| CacheFiles |-->| Ext3 |
0055 +---------+ | /var/cache | | /dev/sda6 |
0056 | | +--------------+ +--------------+
0057 | VFS | ^ ^
0058 | | | |
0059 +---------+ +--------------+ |
0060 | KERNEL SPACE | |
0061 ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|~~~~~~|~~~~
0062 | USER SPACE | |
0063 V | |
0064 +---------+ +--------------+
0065 | | | |
0066 | Process | | cachefilesd |
0067 | | | |
0068 +---------+ +--------------+
0069
0070
0071 FS-Cache does not follow the idea of completely loading every netfs file
0072 opened in its entirety into a cache before permitting it to be accessed and
0073 then serving the pages out of that cache rather than the netfs inode because:
0074
0075 (1) It must be practical to operate without a cache.
0076
0077 (2) The size of any accessible file must not be limited to the size of the
0078 cache.
0079
0080 (3) The combined size of all opened files (this includes mapped libraries)
0081 must not be limited to the size of the cache.
0082
0083 (4) The user should not be forced to download an entire file just to do a
0084 one-off access of a small portion of it (such as might be done with the
0085 "file" program).
0086
0087 It instead serves the cache out in chunks as and when requested by the netfs
0088 using it.
0089
0090
0091 FS-Cache provides the following facilities:
0092
0093 * More than one cache can be used at once. Caches can be selected
0094 explicitly by use of tags.
0095
0096 * Caches can be added / removed at any time, even whilst being accessed.
0097
0098 * The netfs is provided with an interface that allows either party to
0099 withdraw caching facilities from a file (required for (2)).
0100
0101 * The interface to the netfs returns as few errors as possible, preferring
0102 rather to let the netfs remain oblivious.
0103
0104 * There are three types of cookie: cache, volume and data file cookies.
0105 Cache cookies represent the cache as a whole and are not normally visible
0106 to the netfs; the netfs gets a volume cookie to represent a collection of
0107 files (typically something that a netfs would get for a superblock); and
0108 data file cookies are used to cache data (something that would be got for
0109 an inode).
0110
0111 * Volumes are matched using a key. This is a printable string that is used
0112 to encode all the information that might be needed to distinguish one
0113 superblock, say, from another. This would be a compound of things like
0114 cell name or server address, volume name or share path. It must be a
0115 valid pathname.
0116
0117 * Cookies are matched using a key. This is a binary blob and is used to
0118 represent the object within a volume (so the volume key need not form
0119 part of the blob). This might include things like an inode number and
0120 uniquifier or a file handle.
0121
0122 * Cookie resources are set up and pinned by marking the cookie in-use.
0123 This prevents the backing resources from being culled. Timed garbage
0124 collection is employed to eliminate cookies that haven't been used for a
0125 short while, thereby reducing resource overload. This is intended to be
0126 used when a file is opened or closed.
0127
0128 A cookie can be marked in-use multiple times simultaneously; each mark
0129 must be unused.
0130
0131 * Begin/end access functions are provided to delay cache withdrawal for the
0132 duration of an operation and prevent structs from being freed whilst
0133 we're looking at them.
0134
0135 * Data I/O is done by asynchronous DIO to/from a buffer described by the
0136 netfs using an iov_iter.
0137
0138 * An invalidation facility is available to discard data from the cache and
0139 to deal with I/O that's in progress that is accessing old data.
0140
0141 * Cookies can be "retired" upon release, thereby causing the object to be
0142 removed from the cache.
0143
0144
0145 The netfs API to FS-Cache can be found in:
0146
0147 Documentation/filesystems/caching/netfs-api.rst
0148
0149 The cache backend API to FS-Cache can be found in:
0150
0151 Documentation/filesystems/caching/backend-api.rst
0152
0153
0154 Statistical Information
0155 =======================
0156
0157 If FS-Cache is compiled with the following options enabled::
0158
0159 CONFIG_FSCACHE_STATS=y
0160
0161 then it will gather certain statistics and display them through:
0162
0163 /proc/fs/fscache/stats
0164
0165 This shows counts of a number of events that can happen in FS-Cache:
0166
0167 +--------------+-------+-------------------------------------------------------+
0168 |CLASS |EVENT |MEANING |
0169 +==============+=======+=======================================================+
0170 |Cookies |n=N |Number of data storage cookies allocated |
0171 + +-------+-------------------------------------------------------+
0172 | |v=N |Number of volume index cookies allocated |
0173 + +-------+-------------------------------------------------------+
0174 | |vcol=N |Number of volume index key collisions |
0175 + +-------+-------------------------------------------------------+
0176 | |voom=N |Number of OOM events when allocating volume cookies |
0177 +--------------+-------+-------------------------------------------------------+
0178 |Acquire |n=N |Number of acquire cookie requests seen |
0179 + +-------+-------------------------------------------------------+
0180 | |ok=N |Number of acq reqs succeeded |
0181 + +-------+-------------------------------------------------------+
0182 | |oom=N |Number of acq reqs failed on ENOMEM |
0183 +--------------+-------+-------------------------------------------------------+
0184 |LRU |n=N |Number of cookies currently on the LRU |
0185 + +-------+-------------------------------------------------------+
0186 | |exp=N |Number of cookies expired off of the LRU |
0187 + +-------+-------------------------------------------------------+
0188 | |rmv=N |Number of cookies removed from the LRU |
0189 + +-------+-------------------------------------------------------+
0190 | |drp=N |Number of LRU'd cookies relinquished/withdrawn |
0191 + +-------+-------------------------------------------------------+
0192 | |at=N |Time till next LRU cull (jiffies) |
0193 +--------------+-------+-------------------------------------------------------+
0194 |Invals |n=N |Number of invalidations |
0195 +--------------+-------+-------------------------------------------------------+
0196 |Updates |n=N |Number of update cookie requests seen |
0197 + +-------+-------------------------------------------------------+
0198 | |rsz=N |Number of resize requests |
0199 + +-------+-------------------------------------------------------+
0200 | |rsn=N |Number of skipped resize requests |
0201 +--------------+-------+-------------------------------------------------------+
0202 |Relinqs |n=N |Number of relinquish cookie requests seen |
0203 + +-------+-------------------------------------------------------+
0204 | |rtr=N |Number of rlq reqs with retire=true |
0205 + +-------+-------------------------------------------------------+
0206 | |drop=N |Number of cookies no longer blocking re-acquisition |
0207 +--------------+-------+-------------------------------------------------------+
0208 |NoSpace |nwr=N |Number of write requests refused due to lack of space |
0209 + +-------+-------------------------------------------------------+
0210 | |ncr=N |Number of create requests refused due to lack of space |
0211 + +-------+-------------------------------------------------------+
0212 | |cull=N |Number of objects culled to make space |
0213 +--------------+-------+-------------------------------------------------------+
0214 |IO |rd=N |Number of read operations in the cache |
0215 + +-------+-------------------------------------------------------+
0216 | |wr=N |Number of write operations in the cache |
0217 +--------------+-------+-------------------------------------------------------+
0218
0219 Netfslib will also add some stats counters of its own.
0220
0221
0222 Cache List
0223 ==========
0224
0225 FS-Cache provides a list of cache cookies:
0226
0227 /proc/fs/fscache/cookies
0228
0229 This will look something like::
0230
0231 # cat /proc/fs/fscache/caches
0232 CACHE REF VOLS OBJS ACCES S NAME
0233 ======== ===== ===== ===== ===== = ===============
0234 00000001 2 1 2123 1 A default
0235
0236 where the columns are:
0237
0238 ======= ===============================================================
0239 COLUMN DESCRIPTION
0240 ======= ===============================================================
0241 CACHE Cache cookie debug ID (also appears in traces)
0242 REF Number of references on the cache cookie
0243 VOLS Number of volumes cookies in this cache
0244 OBJS Number of cache objects in use
0245 ACCES Number of accesses pinning the cache
0246 S State
0247 NAME Name of the cache.
0248 ======= ===============================================================
0249
0250 The state can be (-) Inactive, (P)reparing, (A)ctive, (E)rror or (W)ithdrawing.
0251
0252
0253 Volume List
0254 ===========
0255
0256 FS-Cache provides a list of volume cookies:
0257
0258 /proc/fs/fscache/volumes
0259
0260 This will look something like::
0261
0262 VOLUME REF nCOOK ACC FL CACHE KEY
0263 ======== ===== ===== === == =============== ================
0264 00000001 55 54 1 00 default afs,example.com,100058
0265
0266 where the columns are:
0267
0268 ======= ===============================================================
0269 COLUMN DESCRIPTION
0270 ======= ===============================================================
0271 VOLUME The volume cookie debug ID (also appears in traces)
0272 REF Number of references on the volume cookie
0273 nCOOK Number of cookies in the volume
0274 ACC Number of accesses pinning the cache
0275 FL Flags on the volume cookie
0276 CACHE Name of the cache or "-"
0277 KEY The indexing key for the volume
0278 ======= ===============================================================
0279
0280
0281 Cookie List
0282 ===========
0283
0284 FS-Cache provides a list of cookies:
0285
0286 /proc/fs/fscache/cookies
0287
0288 This will look something like::
0289
0290 # head /proc/fs/fscache/cookies
0291 COOKIE VOLUME REF ACT ACC S FL DEF
0292 ======== ======== === === === = == ================
0293 00000435 00000001 1 0 -1 - 08 0000000201d080070000000000000000, 0000000000000000
0294 00000436 00000001 1 0 -1 - 00 0000005601d080080000000000000000, 0000000000000051
0295 00000437 00000001 1 0 -1 - 08 00023b3001d0823f0000000000000000, 0000000000000000
0296 00000438 00000001 1 0 -1 - 08 0000005801d0807b0000000000000000, 0000000000000000
0297 00000439 00000001 1 0 -1 - 08 00023b3201d080a10000000000000000, 0000000000000000
0298 0000043a 00000001 1 0 -1 - 08 00023b3401d080a30000000000000000, 0000000000000000
0299 0000043b 00000001 1 0 -1 - 08 00023b3601d080b30000000000000000, 0000000000000000
0300 0000043c 00000001 1 0 -1 - 08 00023b3801d080b40000000000000000, 0000000000000000
0301
0302 where the columns are:
0303
0304 ======= ===============================================================
0305 COLUMN DESCRIPTION
0306 ======= ===============================================================
0307 COOKIE The cookie debug ID (also appears in traces)
0308 VOLUME The parent volume cookie debug ID
0309 REF Number of references on the volume cookie
0310 ACT Number of times the cookie is marked for in use
0311 ACC Number of access pins in the cookie
0312 S State of the cookie
0313 FL Flags on the cookie
0314 DEF Key, auxiliary data
0315 ======= ===============================================================
0316
0317
0318 Debugging
0319 =========
0320
0321 If CONFIG_FSCACHE_DEBUG is enabled, the FS-Cache facility can have runtime
0322 debugging enabled by adjusting the value in::
0323
0324 /sys/module/fscache/parameters/debug
0325
0326 This is a bitmask of debugging streams to enable:
0327
0328 ======= ======= =============================== =======================
0329 BIT VALUE STREAM POINT
0330 ======= ======= =============================== =======================
0331 0 1 Cache management Function entry trace
0332 1 2 Function exit trace
0333 2 4 General
0334 3 8 Cookie management Function entry trace
0335 4 16 Function exit trace
0336 5 32 General
0337 6-8 (Not used)
0338 9 512 I/O operation management Function entry trace
0339 10 1024 Function exit trace
0340 11 2048 General
0341 ======= ======= =============================== =======================
0342
0343 The appropriate set of values should be OR'd together and the result written to
0344 the control file. For example::
0345
0346 echo $((1|8|512)) >/sys/module/fscache/parameters/debug
0347
0348 will turn on all function entry debugging.
