filesystems/caching/fscache.txt

12 FS-Cache mediates between cache backends (such as CacheFS) and network
15 	+---------+
16 	|         |                        +--------------+
17 	|   NFS   |--+                     |              |
18 	|         |  |                 +-->|   CacheFS    |
19 	+---------+  |   +----------+  |   |  /dev/hda5   |
20 	             |   |          |  |   +--------------+
21 	+---------+  +-->|          |  |
22 	|         |      |          |--+
23 	|   AFS   |----->| FS-Cache |
24 	|         |      |          |--+
25 	+---------+  +-->|          |  |
26 	             |   |          |  |   +--------------+
27 	+---------+  |   +----------+  |   |              |
28 	|         |  |                 +-->|  CacheFiles  |
29 	|  ISOFS  |--+                     |  /var/cache  |
30 	|         |                        +--------------+
31 	+---------+
33 Or to look at it another way, FS-Cache is a module that provides a caching
37 	+---------+
41 	+---------+
45 	     |           +----------+
47 	+---------+      |          |
49 	|   NFS   |----->| FS-Cache |
50 	|         |      |          |--+
51 	+---------+      |          |  |   +--------------+   +--------------+
53 	     V           +----------+  +-->|  CacheFiles  |-->|  Ext3        |
54 	+---------+                        |  /var/cache  |   |  /dev/sda6   |
55 	|         |                        +--------------+   +--------------+
58 	+---------+                                +--------------+      |
63 	+---------+                                           +--------------+
67 	+---------+                                           +--------------+
70 FS-Cache does not follow the idea of completely loading every netfs file
83      one-off access of a small portion of it (such as might be done with the
90 FS-Cache provides the following facilities:
104      netfs.  The simplest cookie is just a NULL pointer - indicating nothing
107  (6) The netfs is allowed to propose - dynamically - any index hierarchy it
113      indicates that page A is at index B of the data-file represented by cookie
119  (8) Cookies can be "retired" upon release.  At this point FS-Cache will mark
130 FS-Cache maintains a virtual indexing tree in which all indices, files, objects
136                         +------------------------------------+
140            +--------------------------+                +-----------+
144      +------------+           +---------------+              +----------+
148  +---+---+     +-----+      +---+      +------+------+            +-----+----+
152                     PG0                                       +-------+
156                                                           +---+---+
163  (*) The NFS primary index contains per-server indices.  Each server index is
167      attribute objects themselves have page-array contents.
169  (*) The AFS primary index contains per-cell indices.  Each cell index contains
170      per-logical-volume indices.  Each of volume index contains up to three
171      indices for the read-write, read-only and backup mirrors of those volumes.
175 The very top index is the FS-Cache master index in which individual netfs's
179 children.  Any index with non-index object children will be assumed to only
183 The netfs API to FS-Cache can be found in:
185 	Documentation/filesystems/caching/netfs-api.txt
187 The cache backend API to FS-Cache can be found in:
189 	Documentation/filesystems/caching/backend-api.txt
201 If FS-Cache is compiled with the following options enabled:
211      This shows counts of a number of events that can happen in FS-Cache:
234 	Lookups	n=N	Number of lookup calls made on cache backends
247 		nbf=N	Number of attr changed rejected -ENOBUFS
248 		oom=N	Number of attr changed failed -ENOMEM
253 		nbf=N	Number of alloc reqs rejected -ENOBUFS
254 		int=N	Number of alloc reqs aborted -ERESTARTSYS
261 		nod=N	Number of retr reqs returned -ENODATA
262 		nbf=N	Number of retr reqs rejected -ENOBUFS
263 		int=N	Number of retr reqs aborted -ERESTARTSYS
264 		oom=N	Number of retr reqs failed -ENOMEM
271 		nbf=N	Number of store reqs rejected -ENOBUFS
272 		oom=N	Number of store reqs failed -ENOMEM
280 		bsy=N	Number of release reqs ignored due to in-progress store
289 		gc=N	Number of deferred-release async ops garbage collected
290 	CacheOp	alo=N	Number of in-progress alloc_object() cache ops
291 		luo=N	Number of in-progress lookup_object() cache ops
292 		luc=N	Number of in-progress lookup_complete() cache ops
293 		gro=N	Number of in-progress grab_object() cache ops
294 		upo=N	Number of in-progress update_object() cache ops
295 		dro=N	Number of in-progress drop_object() cache ops
296 		pto=N	Number of in-progress put_object() cache ops
297 		syn=N	Number of in-progress sync_cache() cache ops
298 		atc=N	Number of in-progress attr_changed() cache ops
299 		rap=N	Number of in-progress read_or_alloc_page() cache ops
300 		ras=N	Number of in-progress read_or_alloc_pages() cache ops
301 		alp=N	Number of in-progress allocate_page() cache ops
302 		als=N	Number of in-progress allocate_pages() cache ops
303 		wrp=N	Number of in-progress write_page() cache ops
304 		ucp=N	Number of in-progress uncache_page() cache ops
305 		dsp=N	Number of in-progress dissociate_pages() cache ops
315      between 0 jiffies and HZ-1 jiffies a variety of tasks took to run.  The
335 If CONFIG_FSCACHE_OBJECT_LIST is enabled, the FS-Cache facility will maintain a
372 	TY		Cookie type (IX - index, DT - data, hex - special)
416 If CONFIG_FSCACHE_DEBUG is enabled, the FS-Cache facility can have runtime
421 This is a bitmask of debugging streams to enable:
425 	0	1	Cache management		Function entry trace
426 	1	2					Function exit trace
428 	3	8	Cookie management		Function entry trace
429 	4	16					Function exit trace
431 	6	64	Page handling			Function entry trace
432 	7	128					Function exit trace
434 	9	512	Operation management		Function entry trace
435 	10	1024					Function exit trace