1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ========================== 3 ==========================
4 General Filesystem Caching 4 General Filesystem Caching
5 ========================== 5 ==========================
6 6
7 Overview 7 Overview
8 ======== 8 ========
9 9
10 This facility is a general purpose cache for n 10 This facility is a general purpose cache for network filesystems, though it
11 could be used for caching other things such as 11 could be used for caching other things such as ISO9660 filesystems too.
12 12
13 FS-Cache mediates between cache backends (such 13 FS-Cache mediates between cache backends (such as CacheFiles) and network
14 filesystems:: 14 filesystems::
15 15
16 +---------+ 16 +---------+
17 | | 17 | | +--------------+
18 | NFS |--+ 18 | NFS |--+ | |
19 | | | 19 | | | +-->| CacheFS |
20 +---------+ | +-------- 20 +---------+ | +----------+ | | /dev/hda5 |
21 | | 21 | | | | +--------------+
22 +---------+ +-------------->| 22 +---------+ +-------------->| | |
23 | | +-------+ | 23 | | +-------+ | |--+
24 | AFS |----->| | | FS-Cach 24 | AFS |----->| | | FS-Cache |
25 | | | netfs |-->| 25 | | | netfs |-->| |--+
26 +---------+ +-->| lib | | 26 +---------+ +-->| lib | | | |
27 | | | | 27 | | | | | | +--------------+
28 +---------+ | +-------+ +-------- 28 +---------+ | +-------+ +----------+ | | |
29 | | | 29 | | | +-->| CacheFiles |
30 | 9P |--+ 30 | 9P |--+ | /var/cache |
31 | | 31 | | +--------------+
32 +---------+ 32 +---------+
33 33
34 Or to look at it another way, FS-Cache is a mo 34 Or to look at it another way, FS-Cache is a module that provides a caching
35 facility to a network filesystem such that the 35 facility to a network filesystem such that the cache is transparent to the
36 user:: 36 user::
37 37
38 +---------+ 38 +---------+
39 | | 39 | |
40 | Server | 40 | Server |
41 | | 41 | |
42 +---------+ 42 +---------+
43 | NETWORK 43 | NETWORK
44 ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44 ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
45 | 45 |
46 | +----------+ 46 | +----------+
47 V | | 47 V | |
48 +---------+ | | 48 +---------+ | |
49 | | | | 49 | | | |
50 | NFS |----->| FS-Cache | 50 | NFS |----->| FS-Cache |
51 | | | |--+ 51 | | | |--+
52 +---------+ | | | +-- 52 +---------+ | | | +--------------+ +--------------+
53 | | | | | 53 | | | | | | | |
54 V +----------+ +-->| 54 V +----------+ +-->| CacheFiles |-->| Ext3 |
55 +---------+ | 55 +---------+ | /var/cache | | /dev/sda6 |
56 | | +-- 56 | | +--------------+ +--------------+
57 | VFS | 57 | VFS | ^ ^
58 | | 58 | | | |
59 +---------+ 59 +---------+ +--------------+ |
60 | KERNEL SPACE 60 | KERNEL SPACE | |
61 ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|~~~~~~|~~~~
62 | USER SPACE 62 | USER SPACE | |
63 V 63 V | |
64 +---------+ 64 +---------+ +--------------+
65 | | 65 | | | |
66 | Process | 66 | Process | | cachefilesd |
67 | | 67 | | | |
68 +---------+ 68 +---------+ +--------------+
69 69
70 70
71 FS-Cache does not follow the idea of completel 71 FS-Cache does not follow the idea of completely loading every netfs file
72 opened in its entirety into a cache before per 72 opened in its entirety into a cache before permitting it to be accessed and
73 then serving the pages out of that cache rathe 73 then serving the pages out of that cache rather than the netfs inode because:
74 74
75 (1) It must be practical to operate without a 75 (1) It must be practical to operate without a cache.
76 76
77 (2) The size of any accessible file must not 77 (2) The size of any accessible file must not be limited to the size of the
78 cache. 78 cache.
79 79
80 (3) The combined size of all opened files (th 80 (3) The combined size of all opened files (this includes mapped libraries)
81 must not be limited to the size of the ca 81 must not be limited to the size of the cache.
82 82
83 (4) The user should not be forced to download 83 (4) The user should not be forced to download an entire file just to do a
84 one-off access of a small portion of it ( 84 one-off access of a small portion of it (such as might be done with the
85 "file" program). 85 "file" program).
86 86
87 It instead serves the cache out in chunks as a 87 It instead serves the cache out in chunks as and when requested by the netfs
88 using it. 88 using it.
89 89
90 90
91 FS-Cache provides the following facilities: 91 FS-Cache provides the following facilities:
92 92
93 * More than one cache can be used at once. 93 * More than one cache can be used at once. Caches can be selected
94 explicitly by use of tags. 94 explicitly by use of tags.
95 95
96 * Caches can be added / removed at any time 96 * Caches can be added / removed at any time, even whilst being accessed.
97 97
98 * The netfs is provided with an interface t 98 * The netfs is provided with an interface that allows either party to
99 withdraw caching facilities from a file ( 99 withdraw caching facilities from a file (required for (2)).
100 100
101 * The interface to the netfs returns as few 101 * The interface to the netfs returns as few errors as possible, preferring
102 rather to let the netfs remain oblivious. 102 rather to let the netfs remain oblivious.
103 103
104 * There are three types of cookie: cache, v 104 * There are three types of cookie: cache, volume and data file cookies.
105 Cache cookies represent the cache as a wh 105 Cache cookies represent the cache as a whole and are not normally visible
106 to the netfs; the netfs gets a volume coo 106 to the netfs; the netfs gets a volume cookie to represent a collection of
107 files (typically something that a netfs w 107 files (typically something that a netfs would get for a superblock); and
108 data file cookies are used to cache data 108 data file cookies are used to cache data (something that would be got for
109 an inode). 109 an inode).
110 110
111 * Volumes are matched using a key. This is 111 * Volumes are matched using a key. This is a printable string that is used
112 to encode all the information that might 112 to encode all the information that might be needed to distinguish one
113 superblock, say, from another. This woul 113 superblock, say, from another. This would be a compound of things like
114 cell name or server address, volume name 114 cell name or server address, volume name or share path. It must be a
115 valid pathname. 115 valid pathname.
116 116
117 * Cookies are matched using a key. This is 117 * Cookies are matched using a key. This is a binary blob and is used to
118 represent the object within a volume (so 118 represent the object within a volume (so the volume key need not form
119 part of the blob). This might include th 119 part of the blob). This might include things like an inode number and
120 uniquifier or a file handle. 120 uniquifier or a file handle.
121 121
122 * Cookie resources are set up and pinned by 122 * Cookie resources are set up and pinned by marking the cookie in-use.
123 This prevents the backing resources from 123 This prevents the backing resources from being culled. Timed garbage
124 collection is employed to eliminate cooki 124 collection is employed to eliminate cookies that haven't been used for a
125 short while, thereby reducing resource ov 125 short while, thereby reducing resource overload. This is intended to be
126 used when a file is opened or closed. 126 used when a file is opened or closed.
127 127
128 A cookie can be marked in-use multiple ti 128 A cookie can be marked in-use multiple times simultaneously; each mark
129 must be unused. 129 must be unused.
130 130
131 * Begin/end access functions are provided t 131 * Begin/end access functions are provided to delay cache withdrawal for the
132 duration of an operation and prevent stru 132 duration of an operation and prevent structs from being freed whilst
133 we're looking at them. 133 we're looking at them.
134 134
135 * Data I/O is done by asynchronous DIO to/f 135 * Data I/O is done by asynchronous DIO to/from a buffer described by the
136 netfs using an iov_iter. 136 netfs using an iov_iter.
137 137
138 * An invalidation facility is available to 138 * An invalidation facility is available to discard data from the cache and
139 to deal with I/O that's in progress that 139 to deal with I/O that's in progress that is accessing old data.
140 140
141 * Cookies can be "retired" upon release, th 141 * Cookies can be "retired" upon release, thereby causing the object to be
142 removed from the cache. 142 removed from the cache.
143 143
144 144
145 The netfs API to FS-Cache can be found in: 145 The netfs API to FS-Cache can be found in:
146 146
147 Documentation/filesystems/caching/netf 147 Documentation/filesystems/caching/netfs-api.rst
148 148
149 The cache backend API to FS-Cache can be found 149 The cache backend API to FS-Cache can be found in:
150 150
151 Documentation/filesystems/caching/back 151 Documentation/filesystems/caching/backend-api.rst
152 152
153 153
154 Statistical Information 154 Statistical Information
155 ======================= 155 =======================
156 156
157 If FS-Cache is compiled with the following opt 157 If FS-Cache is compiled with the following options enabled::
158 158
159 CONFIG_FSCACHE_STATS=y 159 CONFIG_FSCACHE_STATS=y
160 160
161 then it will gather certain statistics and dis 161 then it will gather certain statistics and display them through:
162 162
163 /proc/fs/fscache/stats 163 /proc/fs/fscache/stats
164 164
165 This shows counts of a number of events that c 165 This shows counts of a number of events that can happen in FS-Cache:
166 166
167 +--------------+-------+---------------------- 167 +--------------+-------+-------------------------------------------------------+
168 |CLASS |EVENT |MEANING 168 |CLASS |EVENT |MEANING |
169 +==============+=======+====================== 169 +==============+=======+=======================================================+
170 |Cookies |n=N |Number of data storage 170 |Cookies |n=N |Number of data storage cookies allocated |
171 + +-------+---------------------- 171 + +-------+-------------------------------------------------------+
172 | |v=N |Number of volume index 172 | |v=N |Number of volume index cookies allocated |
173 + +-------+---------------------- 173 + +-------+-------------------------------------------------------+
174 | |vcol=N |Number of volume index 174 | |vcol=N |Number of volume index key collisions |
175 + +-------+---------------------- 175 + +-------+-------------------------------------------------------+
176 | |voom=N |Number of OOM events w 176 | |voom=N |Number of OOM events when allocating volume cookies |
177 +--------------+-------+---------------------- 177 +--------------+-------+-------------------------------------------------------+
178 |Acquire |n=N |Number of acquire cook 178 |Acquire |n=N |Number of acquire cookie requests seen |
179 + +-------+---------------------- 179 + +-------+-------------------------------------------------------+
180 | |ok=N |Number of acq reqs suc 180 | |ok=N |Number of acq reqs succeeded |
181 + +-------+---------------------- 181 + +-------+-------------------------------------------------------+
182 | |oom=N |Number of acq reqs fai 182 | |oom=N |Number of acq reqs failed on ENOMEM |
183 +--------------+-------+---------------------- 183 +--------------+-------+-------------------------------------------------------+
184 |LRU |n=N |Number of cookies curr 184 |LRU |n=N |Number of cookies currently on the LRU |
185 + +-------+---------------------- 185 + +-------+-------------------------------------------------------+
186 | |exp=N |Number of cookies expi 186 | |exp=N |Number of cookies expired off of the LRU |
187 + +-------+---------------------- 187 + +-------+-------------------------------------------------------+
188 | |rmv=N |Number of cookies remo 188 | |rmv=N |Number of cookies removed from the LRU |
189 + +-------+---------------------- 189 + +-------+-------------------------------------------------------+
190 | |drp=N |Number of LRU'd cookie 190 | |drp=N |Number of LRU'd cookies relinquished/withdrawn |
191 + +-------+---------------------- 191 + +-------+-------------------------------------------------------+
192 | |at=N |Time till next LRU cul 192 | |at=N |Time till next LRU cull (jiffies) |
193 +--------------+-------+---------------------- 193 +--------------+-------+-------------------------------------------------------+
194 |Invals |n=N |Number of invalidation 194 |Invals |n=N |Number of invalidations |
195 +--------------+-------+---------------------- 195 +--------------+-------+-------------------------------------------------------+
196 |Updates |n=N |Number of update cooki 196 |Updates |n=N |Number of update cookie requests seen |
197 + +-------+---------------------- 197 + +-------+-------------------------------------------------------+
198 | |rsz=N |Number of resize reque 198 | |rsz=N |Number of resize requests |
199 + +-------+---------------------- 199 + +-------+-------------------------------------------------------+
200 | |rsn=N |Number of skipped resi 200 | |rsn=N |Number of skipped resize requests |
201 +--------------+-------+---------------------- 201 +--------------+-------+-------------------------------------------------------+
202 |Relinqs |n=N |Number of relinquish c 202 |Relinqs |n=N |Number of relinquish cookie requests seen |
203 + +-------+---------------------- 203 + +-------+-------------------------------------------------------+
204 | |rtr=N |Number of rlq reqs wit 204 | |rtr=N |Number of rlq reqs with retire=true |
205 + +-------+---------------------- 205 + +-------+-------------------------------------------------------+
206 | |drop=N |Number of cookies no l 206 | |drop=N |Number of cookies no longer blocking re-acquisition |
207 +--------------+-------+---------------------- 207 +--------------+-------+-------------------------------------------------------+
208 |NoSpace |nwr=N |Number of write reques 208 |NoSpace |nwr=N |Number of write requests refused due to lack of space |
209 + +-------+---------------------- 209 + +-------+-------------------------------------------------------+
210 | |ncr=N |Number of create reque 210 | |ncr=N |Number of create requests refused due to lack of space |
211 + +-------+---------------------- 211 + +-------+-------------------------------------------------------+
212 | |cull=N |Number of objects cull 212 | |cull=N |Number of objects culled to make space |
213 +--------------+-------+---------------------- 213 +--------------+-------+-------------------------------------------------------+
214 |IO |rd=N |Number of read operati 214 |IO |rd=N |Number of read operations in the cache |
215 + +-------+---------------------- 215 + +-------+-------------------------------------------------------+
216 | |wr=N |Number of write operat 216 | |wr=N |Number of write operations in the cache |
217 +--------------+-------+---------------------- 217 +--------------+-------+-------------------------------------------------------+
218 218
219 Netfslib will also add some stats counters of 219 Netfslib will also add some stats counters of its own.
220 220
221 221
222 Cache List 222 Cache List
223 ========== 223 ==========
224 224
225 FS-Cache provides a list of cache cookies: 225 FS-Cache provides a list of cache cookies:
226 226
227 /proc/fs/fscache/cookies 227 /proc/fs/fscache/cookies
228 228
229 This will look something like:: 229 This will look something like::
230 230
231 # cat /proc/fs/fscache/caches 231 # cat /proc/fs/fscache/caches
232 CACHE REF VOLS OBJS ACCES S NAM 232 CACHE REF VOLS OBJS ACCES S NAME
233 ======== ===== ===== ===== ===== = === 233 ======== ===== ===== ===== ===== = ===============
234 00000001 2 1 2123 1 A def 234 00000001 2 1 2123 1 A default
235 235
236 where the columns are: 236 where the columns are:
237 237
238 ======= ============================== 238 ======= ===============================================================
239 COLUMN DESCRIPTION 239 COLUMN DESCRIPTION
240 ======= ============================== 240 ======= ===============================================================
241 CACHE Cache cookie debug ID (also ap 241 CACHE Cache cookie debug ID (also appears in traces)
242 REF Number of references on the ca 242 REF Number of references on the cache cookie
243 VOLS Number of volumes cookies in t 243 VOLS Number of volumes cookies in this cache
244 OBJS Number of cache objects in use 244 OBJS Number of cache objects in use
245 ACCES Number of accesses pinning the 245 ACCES Number of accesses pinning the cache
246 S State 246 S State
247 NAME Name of the cache. 247 NAME Name of the cache.
248 ======= ============================== 248 ======= ===============================================================
249 249
250 The state can be (-) Inactive, (P)reparing, (A 250 The state can be (-) Inactive, (P)reparing, (A)ctive, (E)rror or (W)ithdrawing.
251 251
252 252
253 Volume List 253 Volume List
254 =========== 254 ===========
255 255
256 FS-Cache provides a list of volume cookies: 256 FS-Cache provides a list of volume cookies:
257 257
258 /proc/fs/fscache/volumes 258 /proc/fs/fscache/volumes
259 259
260 This will look something like:: 260 This will look something like::
261 261
262 VOLUME REF nCOOK ACC FL CACHE 262 VOLUME REF nCOOK ACC FL CACHE KEY
263 ======== ===== ===== === == ========== 263 ======== ===== ===== === == =============== ================
264 00000001 55 54 1 00 default 264 00000001 55 54 1 00 default afs,example.com,100058
265 265
266 where the columns are: 266 where the columns are:
267 267
268 ======= ============================== 268 ======= ===============================================================
269 COLUMN DESCRIPTION 269 COLUMN DESCRIPTION
270 ======= ============================== 270 ======= ===============================================================
271 VOLUME The volume cookie debug ID (al 271 VOLUME The volume cookie debug ID (also appears in traces)
272 REF Number of references on the vo 272 REF Number of references on the volume cookie
273 nCOOK Number of cookies in the volum 273 nCOOK Number of cookies in the volume
274 ACC Number of accesses pinning the 274 ACC Number of accesses pinning the cache
275 FL Flags on the volume cookie 275 FL Flags on the volume cookie
276 CACHE Name of the cache or "-" 276 CACHE Name of the cache or "-"
277 KEY The indexing key for the volum 277 KEY The indexing key for the volume
278 ======= ============================== 278 ======= ===============================================================
279 279
280 280
281 Cookie List 281 Cookie List
282 =========== 282 ===========
283 283
284 FS-Cache provides a list of cookies: 284 FS-Cache provides a list of cookies:
285 285
286 /proc/fs/fscache/cookies 286 /proc/fs/fscache/cookies
287 287
288 This will look something like:: 288 This will look something like::
289 289
290 # head /proc/fs/fscache/cookies 290 # head /proc/fs/fscache/cookies
291 COOKIE VOLUME REF ACT ACC S FL DEF 291 COOKIE VOLUME REF ACT ACC S FL DEF
292 ======== ======== === === === = == === 292 ======== ======== === === === = == ================
293 00000435 00000001 1 0 -1 - 08 000 293 00000435 00000001 1 0 -1 - 08 0000000201d080070000000000000000, 0000000000000000
294 00000436 00000001 1 0 -1 - 00 000 294 00000436 00000001 1 0 -1 - 00 0000005601d080080000000000000000, 0000000000000051
295 00000437 00000001 1 0 -1 - 08 000 295 00000437 00000001 1 0 -1 - 08 00023b3001d0823f0000000000000000, 0000000000000000
296 00000438 00000001 1 0 -1 - 08 000 296 00000438 00000001 1 0 -1 - 08 0000005801d0807b0000000000000000, 0000000000000000
297 00000439 00000001 1 0 -1 - 08 000 297 00000439 00000001 1 0 -1 - 08 00023b3201d080a10000000000000000, 0000000000000000
298 0000043a 00000001 1 0 -1 - 08 000 298 0000043a 00000001 1 0 -1 - 08 00023b3401d080a30000000000000000, 0000000000000000
299 0000043b 00000001 1 0 -1 - 08 000 299 0000043b 00000001 1 0 -1 - 08 00023b3601d080b30000000000000000, 0000000000000000
300 0000043c 00000001 1 0 -1 - 08 000 300 0000043c 00000001 1 0 -1 - 08 00023b3801d080b40000000000000000, 0000000000000000
301 301
302 where the columns are: 302 where the columns are:
303 303
304 ======= ============================== 304 ======= ===============================================================
305 COLUMN DESCRIPTION 305 COLUMN DESCRIPTION
306 ======= ============================== 306 ======= ===============================================================
307 COOKIE The cookie debug ID (also appe 307 COOKIE The cookie debug ID (also appears in traces)
308 VOLUME The parent volume cookie debug 308 VOLUME The parent volume cookie debug ID
309 REF Number of references on the vo 309 REF Number of references on the volume cookie
310 ACT Number of times the cookie is 310 ACT Number of times the cookie is marked for in use
311 ACC Number of access pins in the c 311 ACC Number of access pins in the cookie
312 S State of the cookie 312 S State of the cookie
313 FL Flags on the cookie 313 FL Flags on the cookie
314 DEF Key, auxiliary data 314 DEF Key, auxiliary data
315 ======= ============================== 315 ======= ===============================================================
316 316
317 317
318 Debugging 318 Debugging
319 ========= 319 =========
320 320
321 If CONFIG_NETFS_DEBUG is enabled, the FS-Cache 321 If CONFIG_NETFS_DEBUG is enabled, the FS-Cache facility and NETFS support can
322 have runtime debugging enabled by adjusting th 322 have runtime debugging enabled by adjusting the value in::
323 323
324 /sys/module/netfs/parameters/debug 324 /sys/module/netfs/parameters/debug
325 325
326 This is a bitmask of debugging streams to enab 326 This is a bitmask of debugging streams to enable:
327 327
328 ======= ======= ====================== 328 ======= ======= =============================== =======================
329 BIT VALUE STREAM 329 BIT VALUE STREAM POINT
330 ======= ======= ====================== 330 ======= ======= =============================== =======================
331 0 1 Cache management 331 0 1 Cache management Function entry trace
332 1 2 332 1 2 Function exit trace
333 2 4 333 2 4 General
334 3 8 Cookie management 334 3 8 Cookie management Function entry trace
335 4 16 335 4 16 Function exit trace
336 5 32 336 5 32 General
337 6-8 337 6-8 (Not used)
338 9 512 I/O operation manageme 338 9 512 I/O operation management Function entry trace
339 10 1024 339 10 1024 Function exit trace
340 11 2048 340 11 2048 General
341 ======= ======= ====================== 341 ======= ======= =============================== =======================
342 342
343 The appropriate set of values should be OR'd t 343 The appropriate set of values should be OR'd together and the result written to
344 the control file. For example:: 344 the control file. For example::
345 345
346 echo $((1|8|512)) >/sys/module/netfs/p 346 echo $((1|8|512)) >/sys/module/netfs/parameters/debug
347 347
348 will turn on all function entry debugging. 348 will turn on all function entry debugging.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.