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