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 CacheFS) 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 | | | |--+
26 +---------+ +-->| lib | | !! 26 +---------+ +-->| | |
27 | | | | !! 27 | | | | +--------------+
28 +---------+ | +-------+ +-------- !! 28 +---------+ | +----------+ | | |
29 | | | !! 29 | | | +-->| CacheFiles |
30 | 9P |--+ !! 30 | ISOFS |--+ | /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 PAGE_SIZE chunks as and when requested by
88 using it. !! 88 the netfs('s) 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 (1) 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 (2) Caches can be added / removed at any time.
97 97
98 * The netfs is provided with an interface t !! 98 (3) 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 (4) 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 (5) Cookies are used to represent indices, files and other objects to the
105 Cache cookies represent the cache as a wh !! 105 netfs. The simplest cookie is just a NULL pointer - indicating nothing
106 to the netfs; the netfs gets a volume coo !! 106 cached there.
107 files (typically something that a netfs w !! 107
108 data file cookies are used to cache data !! 108 (6) The netfs is allowed to propose - dynamically - any index hierarchy it
109 an inode). !! 109 desires, though it must be aware that the index search function is
110 !! 110 recursive, stack space is limited, and indices can only be children of
111 * Volumes are matched using a key. This is !! 111 indices.
112 to encode all the information that might !! 112
113 superblock, say, from another. This woul !! 113 (7) Data I/O is done direct to and from the netfs's pages. The netfs
114 cell name or server address, volume name !! 114 indicates that page A is at index B of the data-file represented by cookie
115 valid pathname. !! 115 C, and that it should be read or written. The cache backend may or may
116 !! 116 not start I/O on that page, but if it does, a netfs callback will be
117 * Cookies are matched using a key. This is !! 117 invoked to indicate completion. The I/O may be either synchronous or
118 represent the object within a volume (so !! 118 asynchronous.
119 part of the blob). This might include th !! 119
120 uniquifier or a file handle. !! 120 (8) Cookies can be "retired" upon release. At this point FS-Cache will mark
121 !! 121 them as obsolete and the index hierarchy rooted at that point will get
122 * Cookie resources are set up and pinned by !! 122 recycled.
123 This prevents the backing resources from !! 123
124 collection is employed to eliminate cooki !! 124 (9) The netfs provides a "match" function for index searches. In addition to
125 short while, thereby reducing resource ov !! 125 saying whether a match was made or not, this can also specify that an
126 used when a file is opened or closed. !! 126 entry should be updated or deleted.
127 !! 127
128 A cookie can be marked in-use multiple ti !! 128 (10) As much as possible is done asynchronously.
129 must be unused. !! 129
130 !! 130
131 * Begin/end access functions are provided t !! 131 FS-Cache maintains a virtual indexing tree in which all indices, files, objects
132 duration of an operation and prevent stru !! 132 and pages are kept. Bits of this tree may actually reside in one or more
133 we're looking at them. !! 133 caches::
134 !! 134
135 * Data I/O is done by asynchronous DIO to/f !! 135 FSDEF
136 netfs using an iov_iter. !! 136 |
137 !! 137 +------------------------------------+
138 * An invalidation facility is available to !! 138 | |
139 to deal with I/O that's in progress that !! 139 NFS AFS
140 !! 140 | |
141 * Cookies can be "retired" upon release, th !! 141 +--------------------------+ +-----------+
142 removed from the cache. !! 142 | | | |
>> 143 homedir mirror afs.org redhat.com
>> 144 | | |
>> 145 +------------+ +---------------+ +----------+
>> 146 | | | | | |
>> 147 00001 00002 00007 00125 vol00001 vol00002
>> 148 | | | | |
>> 149 +---+---+ +-----+ +---+ +------+------+ +-----+----+
>> 150 | | | | | | | | | | | | |
>> 151 PG0 PG1 PG2 PG0 XATTR PG0 PG1 DIRENT DIRENT DIRENT R/W R/O Bak
>> 152 | |
>> 153 PG0 +-------+
>> 154 | |
>> 155 00001 00003
>> 156 |
>> 157 +---+---+
>> 158 | | |
>> 159 PG0 PG1 PG2
>> 160
>> 161 In the example above, you can see two netfs's being backed: NFS and AFS. These
>> 162 have different index hierarchies:
>> 163
>> 164 * The NFS primary index contains per-server indices. Each server index is
>> 165 indexed by NFS file handles to get data file objects. Each data file
>> 166 objects can have an array of pages, but may also have further child
>> 167 objects, such as extended attributes and directory entries. Extended
>> 168 attribute objects themselves have page-array contents.
>> 169
>> 170 * The AFS primary index contains per-cell indices. Each cell index contains
>> 171 per-logical-volume indices. Each of volume index contains up to three
>> 172 indices for the read-write, read-only and backup mirrors of those volumes.
>> 173 Each of these contains vnode data file objects, each of which contains an
>> 174 array of pages.
>> 175
>> 176 The very top index is the FS-Cache master index in which individual netfs's
>> 177 have entries.
>> 178
>> 179 Any index object may reside in more than one cache, provided it only has index
>> 180 children. Any index with non-index object children will be assumed to only
>> 181 reside in one cache.
143 182
144 183
145 The netfs API to FS-Cache can be found in: 184 The netfs API to FS-Cache can be found in:
146 185
147 Documentation/filesystems/caching/netf 186 Documentation/filesystems/caching/netfs-api.rst
148 187
149 The cache backend API to FS-Cache can be found 188 The cache backend API to FS-Cache can be found in:
150 189
151 Documentation/filesystems/caching/back 190 Documentation/filesystems/caching/backend-api.rst
152 191
>> 192 A description of the internal representations and object state machine can be
>> 193 found in:
>> 194
>> 195 Documentation/filesystems/caching/object.rst
>> 196
153 197
154 Statistical Information 198 Statistical Information
155 ======================= 199 =======================
156 200
157 If FS-Cache is compiled with the following opt 201 If FS-Cache is compiled with the following options enabled::
158 202
159 CONFIG_FSCACHE_STATS=y 203 CONFIG_FSCACHE_STATS=y
>> 204 CONFIG_FSCACHE_HISTOGRAM=y
160 205
161 then it will gather certain statistics and dis !! 206 then it will gather certain statistics and display them through a number of
>> 207 proc files.
162 208
163 /proc/fs/fscache/stats !! 209 /proc/fs/fscache/stats
>> 210 ----------------------
164 211
165 This shows counts of a number of events that c !! 212 This shows counts of a number of events that can happen in FS-Cache:
166 213
167 +--------------+-------+---------------------- 214 +--------------+-------+-------------------------------------------------------+
168 |CLASS |EVENT |MEANING 215 |CLASS |EVENT |MEANING |
169 +==============+=======+====================== 216 +==============+=======+=======================================================+
170 |Cookies |n=N |Number of data storage !! 217 |Cookies |idx=N |Number of index cookies allocated |
171 + +-------+---------------------- 218 + +-------+-------------------------------------------------------+
172 | |v=N |Number of volume index !! 219 | |dat=N |Number of data storage cookies allocated |
173 + +-------+---------------------- 220 + +-------+-------------------------------------------------------+
174 | |vcol=N |Number of volume index !! 221 | |spc=N |Number of special cookies allocated |
>> 222 +--------------+-------+-------------------------------------------------------+
>> 223 |Objects |alc=N |Number of objects allocated |
>> 224 + +-------+-------------------------------------------------------+
>> 225 | |nal=N |Number of object allocation failures |
>> 226 + +-------+-------------------------------------------------------+
>> 227 | |avl=N |Number of objects that reached the available state |
175 + +-------+---------------------- 228 + +-------+-------------------------------------------------------+
176 | |voom=N |Number of OOM events w !! 229 | |ded=N |Number of objects that reached the dead state |
>> 230 +--------------+-------+-------------------------------------------------------+
>> 231 |ChkAux |non=N |Number of objects that didn't have a coherency check |
>> 232 + +-------+-------------------------------------------------------+
>> 233 | |ok=N |Number of objects that passed a coherency check |
>> 234 + +-------+-------------------------------------------------------+
>> 235 | |upd=N |Number of objects that needed a coherency data update |
>> 236 + +-------+-------------------------------------------------------+
>> 237 | |obs=N |Number of objects that were declared obsolete |
>> 238 +--------------+-------+-------------------------------------------------------+
>> 239 |Pages |mrk=N |Number of pages marked as being cached |
>> 240 | |unc=N |Number of uncache page requests seen |
177 +--------------+-------+---------------------- 241 +--------------+-------+-------------------------------------------------------+
178 |Acquire |n=N |Number of acquire cook 242 |Acquire |n=N |Number of acquire cookie requests seen |
179 + +-------+---------------------- 243 + +-------+-------------------------------------------------------+
>> 244 | |nul=N |Number of acq reqs given a NULL parent |
>> 245 + +-------+-------------------------------------------------------+
>> 246 | |noc=N |Number of acq reqs rejected due to no cache available |
>> 247 + +-------+-------------------------------------------------------+
180 | |ok=N |Number of acq reqs suc 248 | |ok=N |Number of acq reqs succeeded |
181 + +-------+---------------------- 249 + +-------+-------------------------------------------------------+
>> 250 | |nbf=N |Number of acq reqs rejected due to error |
>> 251 + +-------+-------------------------------------------------------+
182 | |oom=N |Number of acq reqs fai 252 | |oom=N |Number of acq reqs failed on ENOMEM |
183 +--------------+-------+---------------------- 253 +--------------+-------+-------------------------------------------------------+
184 |LRU |n=N |Number of cookies curr !! 254 |Lookups |n=N |Number of lookup calls made on cache backends |
185 + +-------+---------------------- 255 + +-------+-------------------------------------------------------+
186 | |exp=N |Number of cookies expi !! 256 | |neg=N |Number of negative lookups made |
187 + +-------+---------------------- 257 + +-------+-------------------------------------------------------+
188 | |rmv=N |Number of cookies remo !! 258 | |pos=N |Number of positive lookups made |
189 + +-------+---------------------- 259 + +-------+-------------------------------------------------------+
190 | |drp=N |Number of LRU'd cookie !! 260 | |crt=N |Number of objects created by lookup |
191 + +-------+---------------------- 261 + +-------+-------------------------------------------------------+
192 | |at=N |Time till next LRU cul !! 262 | |tmo=N |Number of lookups timed out and requeued |
193 +--------------+-------+---------------------- <<
194 |Invals |n=N |Number of invalidation <<
195 +--------------+-------+---------------------- 263 +--------------+-------+-------------------------------------------------------+
196 |Updates |n=N |Number of update cooki 264 |Updates |n=N |Number of update cookie requests seen |
197 + +-------+---------------------- 265 + +-------+-------------------------------------------------------+
198 | |rsz=N |Number of resize reque !! 266 | |nul=N |Number of upd reqs given a NULL parent |
199 + +-------+---------------------- 267 + +-------+-------------------------------------------------------+
200 | |rsn=N |Number of skipped resi !! 268 | |run=N |Number of upd reqs granted CPU time |
201 +--------------+-------+---------------------- 269 +--------------+-------+-------------------------------------------------------+
202 |Relinqs |n=N |Number of relinquish c 270 |Relinqs |n=N |Number of relinquish cookie requests seen |
203 + +-------+---------------------- 271 + +-------+-------------------------------------------------------+
204 | |rtr=N |Number of rlq reqs wit !! 272 | |nul=N |Number of rlq reqs given a NULL parent |
205 + +-------+---------------------- 273 + +-------+-------------------------------------------------------+
206 | |drop=N |Number of cookies no l !! 274 | |wcr=N |Number of rlq reqs waited on completion of creation |
207 +--------------+-------+---------------------- 275 +--------------+-------+-------------------------------------------------------+
208 |NoSpace |nwr=N |Number of write reques !! 276 |AttrChg |n=N |Number of attribute changed requests seen |
209 + +-------+---------------------- 277 + +-------+-------------------------------------------------------+
210 | |ncr=N |Number of create reque !! 278 | |ok=N |Number of attr changed requests queued |
211 + +-------+---------------------- 279 + +-------+-------------------------------------------------------+
212 | |cull=N |Number of objects cull !! 280 | |nbf=N |Number of attr changed rejected -ENOBUFS |
>> 281 + +-------+-------------------------------------------------------+
>> 282 | |oom=N |Number of attr changed failed -ENOMEM |
>> 283 + +-------+-------------------------------------------------------+
>> 284 | |run=N |Number of attr changed ops given CPU time |
213 +--------------+-------+---------------------- 285 +--------------+-------+-------------------------------------------------------+
214 |IO |rd=N |Number of read operati !! 286 |Allocs |n=N |Number of allocation requests seen |
>> 287 + +-------+-------------------------------------------------------+
>> 288 | |ok=N |Number of successful alloc reqs |
>> 289 + +-------+-------------------------------------------------------+
>> 290 | |wt=N |Number of alloc reqs that waited on lookup completion |
>> 291 + +-------+-------------------------------------------------------+
>> 292 | |nbf=N |Number of alloc reqs rejected -ENOBUFS |
>> 293 + +-------+-------------------------------------------------------+
>> 294 | |int=N |Number of alloc reqs aborted -ERESTARTSYS |
215 + +-------+---------------------- 295 + +-------+-------------------------------------------------------+
216 | |wr=N |Number of write operat !! 296 | |ops=N |Number of alloc reqs submitted |
>> 297 + +-------+-------------------------------------------------------+
>> 298 | |owt=N |Number of alloc reqs waited for CPU time |
>> 299 + +-------+-------------------------------------------------------+
>> 300 | |abt=N |Number of alloc reqs aborted due to object death |
>> 301 +--------------+-------+-------------------------------------------------------+
>> 302 |Retrvls |n=N |Number of retrieval (read) requests seen |
>> 303 + +-------+-------------------------------------------------------+
>> 304 | |ok=N |Number of successful retr reqs |
>> 305 + +-------+-------------------------------------------------------+
>> 306 | |wt=N |Number of retr reqs that waited on lookup completion |
>> 307 + +-------+-------------------------------------------------------+
>> 308 | |nod=N |Number of retr reqs returned -ENODATA |
>> 309 + +-------+-------------------------------------------------------+
>> 310 | |nbf=N |Number of retr reqs rejected -ENOBUFS |
>> 311 + +-------+-------------------------------------------------------+
>> 312 | |int=N |Number of retr reqs aborted -ERESTARTSYS |
>> 313 + +-------+-------------------------------------------------------+
>> 314 | |oom=N |Number of retr reqs failed -ENOMEM |
>> 315 + +-------+-------------------------------------------------------+
>> 316 | |ops=N |Number of retr reqs submitted |
>> 317 + +-------+-------------------------------------------------------+
>> 318 | |owt=N |Number of retr reqs waited for CPU time |
>> 319 + +-------+-------------------------------------------------------+
>> 320 | |abt=N |Number of retr reqs aborted due to object death |
>> 321 +--------------+-------+-------------------------------------------------------+
>> 322 |Stores |n=N |Number of storage (write) requests seen |
>> 323 + +-------+-------------------------------------------------------+
>> 324 | |ok=N |Number of successful store reqs |
>> 325 + +-------+-------------------------------------------------------+
>> 326 | |agn=N |Number of store reqs on a page already pending storage |
>> 327 + +-------+-------------------------------------------------------+
>> 328 | |nbf=N |Number of store reqs rejected -ENOBUFS |
>> 329 + +-------+-------------------------------------------------------+
>> 330 | |oom=N |Number of store reqs failed -ENOMEM |
>> 331 + +-------+-------------------------------------------------------+
>> 332 | |ops=N |Number of store reqs submitted |
>> 333 + +-------+-------------------------------------------------------+
>> 334 | |run=N |Number of store reqs granted CPU time |
>> 335 + +-------+-------------------------------------------------------+
>> 336 | |pgs=N |Number of pages given store req processing time |
>> 337 + +-------+-------------------------------------------------------+
>> 338 | |rxd=N |Number of store reqs deleted from tracking tree |
>> 339 + +-------+-------------------------------------------------------+
>> 340 | |olm=N |Number of store reqs over store limit |
>> 341 +--------------+-------+-------------------------------------------------------+
>> 342 |VmScan |nos=N |Number of release reqs against pages with no |
>> 343 | | |pending store |
>> 344 + +-------+-------------------------------------------------------+
>> 345 | |gon=N |Number of release reqs against pages stored by |
>> 346 | | |time lock granted |
>> 347 + +-------+-------------------------------------------------------+
>> 348 | |bsy=N |Number of release reqs ignored due to in-progress store|
>> 349 + +-------+-------------------------------------------------------+
>> 350 | |can=N |Number of page stores cancelled due to release req |
>> 351 +--------------+-------+-------------------------------------------------------+
>> 352 |Ops |pend=N |Number of times async ops added to pending queues |
>> 353 + +-------+-------------------------------------------------------+
>> 354 | |run=N |Number of times async ops given CPU time |
>> 355 + +-------+-------------------------------------------------------+
>> 356 | |enq=N |Number of times async ops queued for processing |
>> 357 + +-------+-------------------------------------------------------+
>> 358 | |can=N |Number of async ops cancelled |
>> 359 + +-------+-------------------------------------------------------+
>> 360 | |rej=N |Number of async ops rejected due to object |
>> 361 | | |lookup/create failure |
>> 362 + +-------+-------------------------------------------------------+
>> 363 | |ini=N |Number of async ops initialised |
>> 364 + +-------+-------------------------------------------------------+
>> 365 | |dfr=N |Number of async ops queued for deferred release |
>> 366 + +-------+-------------------------------------------------------+
>> 367 | |rel=N |Number of async ops released |
>> 368 | | |(should equal ini=N when idle) |
>> 369 + +-------+-------------------------------------------------------+
>> 370 | |gc=N |Number of deferred-release async ops garbage collected |
>> 371 +--------------+-------+-------------------------------------------------------+
>> 372 |CacheOp |alo=N |Number of in-progress alloc_object() cache ops |
>> 373 + +-------+-------------------------------------------------------+
>> 374 | |luo=N |Number of in-progress lookup_object() cache ops |
>> 375 + +-------+-------------------------------------------------------+
>> 376 | |luc=N |Number of in-progress lookup_complete() cache ops |
>> 377 + +-------+-------------------------------------------------------+
>> 378 | |gro=N |Number of in-progress grab_object() cache ops |
>> 379 + +-------+-------------------------------------------------------+
>> 380 | |upo=N |Number of in-progress update_object() cache ops |
>> 381 + +-------+-------------------------------------------------------+
>> 382 | |dro=N |Number of in-progress drop_object() cache ops |
>> 383 + +-------+-------------------------------------------------------+
>> 384 | |pto=N |Number of in-progress put_object() cache ops |
>> 385 + +-------+-------------------------------------------------------+
>> 386 | |syn=N |Number of in-progress sync_cache() cache ops |
>> 387 + +-------+-------------------------------------------------------+
>> 388 | |atc=N |Number of in-progress attr_changed() cache ops |
>> 389 + +-------+-------------------------------------------------------+
>> 390 | |rap=N |Number of in-progress read_or_alloc_page() cache ops |
>> 391 + +-------+-------------------------------------------------------+
>> 392 | |ras=N |Number of in-progress read_or_alloc_pages() cache ops |
>> 393 + +-------+-------------------------------------------------------+
>> 394 | |alp=N |Number of in-progress allocate_page() cache ops |
>> 395 + +-------+-------------------------------------------------------+
>> 396 | |als=N |Number of in-progress allocate_pages() cache ops |
>> 397 + +-------+-------------------------------------------------------+
>> 398 | |wrp=N |Number of in-progress write_page() cache ops |
>> 399 + +-------+-------------------------------------------------------+
>> 400 | |ucp=N |Number of in-progress uncache_page() cache ops |
>> 401 + +-------+-------------------------------------------------------+
>> 402 | |dsp=N |Number of in-progress dissociate_pages() cache ops |
>> 403 +--------------+-------+-------------------------------------------------------+
>> 404 |CacheEv |nsp=N |Number of object lookups/creations rejected due to |
>> 405 | | |lack of space |
>> 406 + +-------+-------------------------------------------------------+
>> 407 | |stl=N |Number of stale objects deleted |
>> 408 + +-------+-------------------------------------------------------+
>> 409 | |rtr=N |Number of objects retired when relinquished |
>> 410 + +-------+-------------------------------------------------------+
>> 411 | |cul=N |Number of objects culled |
217 +--------------+-------+---------------------- 412 +--------------+-------+-------------------------------------------------------+
218 <<
219 Netfslib will also add some stats counters of <<
220 413
221 414
222 Cache List <<
223 ========== <<
224 415
225 FS-Cache provides a list of cache cookies: !! 416 /proc/fs/fscache/histogram
>> 417 --------------------------
226 418
227 /proc/fs/fscache/cookies !! 419 ::
228 420
229 This will look something like:: !! 421 cat /proc/fs/fscache/histogram
>> 422 JIFS SECS OBJ INST OP RUNS OBJ RUNS RETRV DLY RETRIEVLS
>> 423 ===== ===== ========= ========= ========= ========= =========
230 424
231 # cat /proc/fs/fscache/caches !! 425 This shows the breakdown of the number of times each amount of time
232 CACHE REF VOLS OBJS ACCES S NAM !! 426 between 0 jiffies and HZ-1 jiffies a variety of tasks took to run. The
233 ======== ===== ===== ===== ===== = === !! 427 columns are as follows:
234 00000001 2 1 2123 1 A def <<
235 428
236 where the columns are: !! 429 ========= =======================================================
>> 430 COLUMN TIME MEASUREMENT
>> 431 ========= =======================================================
>> 432 OBJ INST Length of time to instantiate an object
>> 433 OP RUNS Length of time a call to process an operation took
>> 434 OBJ RUNS Length of time a call to process an object event took
>> 435 RETRV DLY Time between an requesting a read and lookup completing
>> 436 RETRIEVLS Time between beginning and end of a retrieval
>> 437 ========= =======================================================
237 438
238 ======= ============================== !! 439 Each row shows the number of events that took a particular range of times.
239 COLUMN DESCRIPTION !! 440 Each step is 1 jiffy in size. The JIFS column indicates the particular
240 ======= ============================== !! 441 jiffy range covered, and the SECS field the equivalent number of seconds.
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 442
250 The state can be (-) Inactive, (P)reparing, (A <<
251 443
252 444
253 Volume List !! 445 Object List
254 =========== 446 ===========
255 447
256 FS-Cache provides a list of volume cookies: !! 448 If CONFIG_FSCACHE_OBJECT_LIST is enabled, the FS-Cache facility will maintain a
>> 449 list of all the objects currently allocated and allow them to be viewed
>> 450 through::
257 451
258 /proc/fs/fscache/volumes !! 452 /proc/fs/fscache/objects
259 453
260 This will look something like:: 454 This will look something like::
261 455
262 VOLUME REF nCOOK ACC FL CACHE !! 456 [root@andromeda ~]# head /proc/fs/fscache/objects
263 ======== ===== ===== === == ========== !! 457 OBJECT PARENT STAT CHLDN OPS OOP IPR EX READS EM EV F S | NETFS_COOKIE_DEF TY FL NETFS_DATA OBJECT_KEY, AUX_DATA
264 00000001 55 54 1 00 default !! 458 ======== ======== ==== ===== === === === == ===== == == = = | ================ == == ================ ================
>> 459 17e4b 2 ACTV 0 0 0 0 0 0 7b 4 0 0 | NFS.fh DT 0 ffff88001dd82820 010006017edcf8bbc93b43298fdfbe71e50b57b13a172c0117f38472, e567634700000000000000000000000063f2404a000000000000000000000000c9030000000000000000000063f2404a
>> 460 1693a 2 ACTV 0 0 0 0 0 0 7b 4 0 0 | NFS.fh DT 0 ffff88002db23380 010006017edcf8bbc93b43298fdfbe71e50b57b1e0162c01a2df0ea6, 420ebc4a000000000000000000000000420ebc4a0000000000000000000000000e1801000000000000000000420ebc4a
265 461
266 where the columns are: !! 462 where the first set of columns before the '|' describe the object:
267 463
268 ======= ============================== 464 ======= ===============================================================
269 COLUMN DESCRIPTION 465 COLUMN DESCRIPTION
270 ======= ============================== 466 ======= ===============================================================
271 VOLUME The volume cookie debug ID (al !! 467 OBJECT Object debugging ID (appears as OBJ%x in some debug messages)
272 REF Number of references on the vo !! 468 PARENT Debugging ID of parent object
273 nCOOK Number of cookies in the volum !! 469 STAT Object state
274 ACC Number of accesses pinning the !! 470 CHLDN Number of child objects of this object
275 FL Flags on the volume cookie !! 471 OPS Number of outstanding operations on this object
276 CACHE Name of the cache or "-" !! 472 OOP Number of outstanding child object management operations
277 KEY The indexing key for the volum !! 473 IPR
>> 474 EX Number of outstanding exclusive operations
>> 475 READS Number of outstanding read operations
>> 476 EM Object's event mask
>> 477 EV Events raised on this object
>> 478 F Object flags
>> 479 S Object work item busy state mask (1:pending 2:running)
278 ======= ============================== 480 ======= ===============================================================
279 481
>> 482 and the second set of columns describe the object's cookie, if present:
280 483
281 Cookie List !! 484 ================ ======================================================
282 =========== !! 485 COLUMN DESCRIPTION
283 !! 486 ================ ======================================================
284 FS-Cache provides a list of cookies: !! 487 NETFS_COOKIE_DEF Name of netfs cookie definition
285 !! 488 TY Cookie type (IX - index, DT - data, hex - special)
286 /proc/fs/fscache/cookies !! 489 FL Cookie flags
287 !! 490 NETFS_DATA Netfs private data stored in the cookie
288 This will look something like:: !! 491 OBJECT_KEY Object key } 1 column, with separating comma
289 !! 492 AUX_DATA Object aux data } presence may be configured
290 # head /proc/fs/fscache/cookies !! 493 ================ ======================================================
291 COOKIE VOLUME REF ACT ACC S FL DEF !! 494
292 ======== ======== === === === = == === !! 495 The data shown may be filtered by attaching the a key to an appropriate keyring
293 00000435 00000001 1 0 -1 - 08 000 !! 496 before viewing the file. Something like::
294 00000436 00000001 1 0 -1 - 00 000 !! 497
295 00000437 00000001 1 0 -1 - 08 000 !! 498 keyctl add user fscache:objlist <restrictions> @s
296 00000438 00000001 1 0 -1 - 08 000 !! 499
297 00000439 00000001 1 0 -1 - 08 000 !! 500 where <restrictions> are a selection of the following letters:
298 0000043a 00000001 1 0 -1 - 08 000 !! 501
299 0000043b 00000001 1 0 -1 - 08 000 !! 502 == =========================================================
300 0000043c 00000001 1 0 -1 - 08 000 !! 503 K Show hexdump of object key (don't show if not given)
301 !! 504 A Show hexdump of object aux data (don't show if not given)
302 where the columns are: !! 505 == =========================================================
>> 506
>> 507 and the following paired letters:
>> 508
>> 509 == =========================================================
>> 510 C Show objects that have a cookie
>> 511 c Show objects that don't have a cookie
>> 512 B Show objects that are busy
>> 513 b Show objects that aren't busy
>> 514 W Show objects that have pending writes
>> 515 w Show objects that don't have pending writes
>> 516 R Show objects that have outstanding reads
>> 517 r Show objects that don't have outstanding reads
>> 518 S Show objects that have work queued
>> 519 s Show objects that don't have work queued
>> 520 == =========================================================
>> 521
>> 522 If neither side of a letter pair is given, then both are implied. For example:
>> 523
>> 524 keyctl add user fscache:objlist KB @s
>> 525
>> 526 shows objects that are busy, and lists their object keys, but does not dump
>> 527 their auxiliary data. It also implies "CcWwRrSs", but as 'B' is given, 'b' is
>> 528 not implied.
303 529
304 ======= ============================== !! 530 By default all objects and all fields will be shown.
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 531
317 532
318 Debugging 533 Debugging
319 ========= 534 =========
320 535
321 If CONFIG_NETFS_DEBUG is enabled, the FS-Cache !! 536 If CONFIG_FSCACHE_DEBUG is enabled, the FS-Cache facility can have runtime
322 have runtime debugging enabled by adjusting th !! 537 debugging enabled by adjusting the value in::
323 538
324 /sys/module/netfs/parameters/debug !! 539 /sys/module/fscache/parameters/debug
325 540
326 This is a bitmask of debugging streams to enab 541 This is a bitmask of debugging streams to enable:
327 542
328 ======= ======= ====================== 543 ======= ======= =============================== =======================
329 BIT VALUE STREAM 544 BIT VALUE STREAM POINT
330 ======= ======= ====================== 545 ======= ======= =============================== =======================
331 0 1 Cache management 546 0 1 Cache management Function entry trace
332 1 2 547 1 2 Function exit trace
333 2 4 548 2 4 General
334 3 8 Cookie management 549 3 8 Cookie management Function entry trace
335 4 16 550 4 16 Function exit trace
336 5 32 551 5 32 General
337 6-8 !! 552 6 64 Page handling Function entry trace
338 9 512 I/O operation manageme !! 553 7 128 Function exit trace
>> 554 8 256 General
>> 555 9 512 Operation management Function entry trace
339 10 1024 556 10 1024 Function exit trace
340 11 2048 557 11 2048 General
341 ======= ======= ====================== 558 ======= ======= =============================== =======================
342 559
343 The appropriate set of values should be OR'd t 560 The appropriate set of values should be OR'd together and the result written to
344 the control file. For example:: 561 the control file. For example::
345 562
346 echo $((1|8|512)) >/sys/module/netfs/p !! 563 echo $((1|8|64)) >/sys/module/fscache/parameters/debug
347 564
348 will turn on all function entry debugging. 565 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.