docs: filesystems: caching/cachefiles.txt: convert to ReST

- Add a SPDX header; - Adjust document title; - Mark literal blocks as such; - Add table markups; - Comment out text ToC for html/pdf output; - Add lists markups; - Add it to filesystems/caching/index.rst.

Mauro Carvalho Chehab committed 6 years ago

Commit d74802a1 parent 09eac7c4 files · +65 −81Browse files

Unified · Split

4 files

Documentation/filesystems/caching/cachefiles.rst +61 −78
Documentation/filesystems/caching/index.rst +1 −0
MAINTAINERS +1 −1
fs/cachefiles/Kconfig +2 −2

Documentation/filesystems/caching/cachefiles.rstrenamed from Documentation/filesystems/caching/cachefiles.txt+61−78

@@ -1,8 +1,10 @@
1		− ===============================================
2		− CacheFiles: CACHE ON ALREADY MOUNTED FILESYSTEM
3		− ===============================================
	1	+.. SPDX-License-Identifier: GPL-2.0
4	2
5		−Contents:
	3	+===============================================
	4	+CacheFiles: CACHE ON ALREADY MOUNTED FILESYSTEM
	5	+===============================================
	6	+
	7	+.. Contents:
6	8
7	9	(*) Overview.
8	10
@@ -27,8 +29,8 @@ Contents: · 18 unmodified lines
27	29	(*) Debugging.
28	30
29	31
30		−========
31		−OVERVIEW
	32	+
	33	+Overview
32	34	========
33	35
34	36	CacheFiles is a caching backend that's meant to use as a cache a directory on
@@ -58,8 +60,8 @@ spare space and automatically contract when the set of data requires more · 23 unmodified lines
58	60	space.
59	61
60	62
61		−============
62		−REQUIREMENTS
	63	+
	64	+Requirements
63	65	============
64	66
65	67	The use of CacheFiles and its daemon requires the following features to be
@@ -79,84 +81,70 @@ It is strongly recommended that the "dir_index" option is enabled on Ext3 · 13 unmodified lines
79	81	filesystems being used as a cache.
80	82
81	83
82		−=============
83		−CONFIGURATION
	84	+Configuration
84	85	=============
85	86
86	87	The cache is configured by a script in /etc/cachefilesd.conf. These commands
87	88	set up cache ready for use. The following script commands are available:
88	89
89		− (*) brun <N>%
90		− (*) bcull <N>%
91		− (*) bstop <N>%
92		− (*) frun <N>%
93		− (*) fcull <N>%
94		− (*) fstop <N>%
95		−
	90	+ brun <N>%, bcull <N>%, bstop <N>%, frun <N>%, fcull <N>%, fstop <N>%
96	91	Configure the culling limits. Optional. See the section on culling
97	92	The defaults are 7% (run), 5% (cull) and 1% (stop) respectively.
98	93
99	94	The commands beginning with a 'b' are file space (block) limits, those
100	95	beginning with an 'f' are file count limits.
101	96
102		− (*) dir <path>
103		−
	97	+ dir <path>
104	98	Specify the directory containing the root of the cache. Mandatory.
105	99
106		− (*) tag <name>
107		−
	100	+ tag <name>
108	101	Specify a tag to FS-Cache to use in distinguishing multiple caches.
109	102	Optional. The default is "CacheFiles".
110	103
111		− (*) debug <mask>
112		−
	104	+ debug <mask>
113	105	Specify a numeric bitmask to control debugging in the kernel module.
114	106	Optional. The default is zero (all off). The following values can be
115	107	OR'd into the mask to collect various information:
116	108
	109	+ == =================================================
117	110	1 Turn on trace of function entry (_enter() macros)
118	111	2 Turn on trace of function exit (_leave() macros)
119	112	4 Turn on trace of internal debug points (_debug())
	113	+ == =================================================
120	114
121		− This mask can also be set through sysfs, eg:
	115	+ This mask can also be set through sysfs, eg::
122	116
123	117	echo 5 >/sys/modules/cachefiles/parameters/debug
124	118
125	119
126		−==================
127		−STARTING THE CACHE
	120	+Starting the Cache
128	121	==================
129	122
130	123	The cache is started by running the daemon. The daemon opens the cache device,
131	124	configures the cache and tells it to begin caching. At that point the cache
132	125	binds to fscache and the cache becomes live.
133	126
134		−The daemon is run as follows:
	127	+The daemon is run as follows::
135	128
136	129	/sbin/cachefilesd [-d]* [-s] [-n] [-f <configfile>]
137	130
138	131	The flags are:
139	132
140		− (*) -d
141		−
	133	+ ``-d``
142	134	Increase the debugging level. This can be specified multiple times and
143	135	is cumulative with itself.
144	136
145		− (*) -s
146		−
	137	+ ``-s``
147	138	Send messages to stderr instead of syslog.
148	139
149		− (*) -n
150		−
	140	+ ``-n``
151	141	Don't daemonise and go into background.
152	142
153		− (*) -f <configfile>
154		−
	143	+ ``-f <configfile>``
155	144	Use an alternative configuration file rather than the default one.
156	145
157	146
158		−===============
159		−THINGS TO AVOID
	147	+Things to Avoid
160	148	===============
161	149
162	150	Do not mount other things within the cache as this will cause problems. The
@@ -179,8 +167,7 @@ Do not chmod files in the cache. The module creates things with minimal · 16 unmodified lines
179	167	permissions to prevent random users being able to access them directly.
180	168
181	169
182		−=============
183		−CACHE CULLING
	170	+Cache Culling
184	171	=============
185	172
186	173	The cache may need culling occasionally to make space. This involves
@@ -192,27 +179,21 @@ Cache culling is done on the basis of the percentage of blocks and the · 5 unmodified lines
192	179	percentage of files available in the underlying filesystem. There are six
193	180	"limits":
194	181
195		− (*) brun
196		− (*) frun
197		−
	182	+ brun, frun
198	183	If the amount of free space and the number of available files in the cache
199	184	rises above both these limits, then culling is turned off.
200	185
201		− (*) bcull
202		− (*) fcull
203		−
	186	+ bcull, fcull
204	187	If the amount of available space or the number of available files in the
205	188	cache falls below either of these limits, then culling is started.
206	189
207		− (*) bstop
208		− (*) fstop
209		−
	190	+ bstop, fstop
210	191	If the amount of available space or the number of available files in the
211	192	cache falls below either of these limits, then no further allocation of
212	193	disk space or files is permitted until culling has raised things above
213	194	these limits again.
214	195
215		−These must be configured thusly:
	196	+These must be configured thusly::
216	197
217	198	0 <= bstop < bcull < brun < 100
218	199	0 <= fstop < fcull < frun < 100
@@ -226,16 +207,14 @@ started as soon as space is made in the table. Objects will be skipped if · 7 unmodified lines
226	207	their atimes have changed or if the kernel module says it is still using them.
227	208
228	209
229		−===============
230		−CACHE STRUCTURE
	210	+Cache Structure
231	211	===============
232	212
233	213	The CacheFiles module will create two directories in the directory it was
234	214	given:
235	215
236		− (*) cache/
237		−
238		− (*) graveyard/
	216	+ * cache/
	217	+ * graveyard/
239	218
240	219	The active cache objects all reside in the first directory. The CacheFiles
241	220	kernel module moves any retired or culled objects that it can't simply unlink
@@ -261,10 +240,10 @@ If an object has children, then it will be represented as a directory. · 19 unmodified lines
261	240	Immediately in the representative directory are a collection of directories
262	241	named for hash values of the child object keys with an '@' prepended. Into
263	242	this directory, if possible, will be placed the representations of the child
264		−objects:
	243	+objects::
265	244
266		− INDEX INDEX INDEX DATA FILES
267		− ========= ========== ================================= ================
	245	+ /INDEX /INDEX /INDEX /DATA FILES
	246	+ /=========/==========/=================================/================
268	247	cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400
269	248	cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...DB1ry
270	249	cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...N22ry
@@ -275,7 +254,7 @@ If the key is so long that it exceeds NAME_MAX with the decorations added on to · 4 unmodified lines
275	254	it, then it will be cut into pieces, the first few of which will be used to
276	255	make a nest of directories, and the last one of which will be the objects
277	256	inside the last directory. The names of the intermediate directories will have
278		−'+' prepended:
	257	+'+' prepended::
279	258
280	259	J1223/@23/+xy...z/+kl...m/Epqr
281	260
@@ -288,11 +267,13 @@ To handle this, CacheFiles will use a suitably printable filename directly and · 6 unmodified lines
288	267	"base-64" encode ones that aren't directly suitable. The two versions of
289	268	object filenames indicate the encoding:
290	269
	270	+ =============== =============== ===============
291	271	OBJECT TYPE PRINTABLE ENCODED
292	272	=============== =============== ===============
293	273	Index "I..." "J..."
294	274	Data "D..." "E..."
295	275	Special "S..." "T..."
	276	+ =============== =============== ===============
296	277
297	278	Intermediate directories are always "@" or "+" as appropriate.
298	279
@@ -307,8 +288,7 @@ Note that CacheFiles will erase from the cache any file it doesn't recognise or · 8 unmodified lines
307	288	any file of an incorrect type (such as a FIFO file or a device file).
308	289
309	290
310		−==========================
311		−SECURITY MODEL AND SELINUX
	291	+Security Model and SELinux
312	292	==========================
313	293
314	294	CacheFiles is implemented to deal properly with the LSM security features of
@@ -331,26 +311,26 @@ When the CacheFiles module is asked to bind to its cache, it: · 16 unmodified lines
331	311
332	312	(1) Finds the security label attached to the root cache directory and uses
333	313	that as the security label with which it will create files. By default,
334		− this is:
	314	+ this is::
335	315
336	316	cachefiles_var_t
337	317
338	318	(2) Finds the security label of the process which issued the bind request
339		− (presumed to be the cachefilesd daemon), which by default will be:
	319	+ (presumed to be the cachefilesd daemon), which by default will be::
340	320
341	321	cachefilesd_t
342	322
343	323	and asks LSM to supply a security ID as which it should act given the
344		− daemon's label. By default, this will be:
	324	+ daemon's label. By default, this will be::
345	325
346	326	cachefiles_kernel_t
347	327
348	328	SELinux transitions the daemon's security ID to the module's security ID
349		− based on a rule of this form in the policy.
	329	+ based on a rule of this form in the policy::
350	330
351	331	type_transition <daemon's-ID> kernel_t : process <module's-ID>;
352	332
353		− For instance:
	333	+ For instance::
354	334
355	335	type_transition cachefilesd_t kernel_t : process cachefiles_kernel_t;
356	336
@@ -370,7 +350,7 @@ There are policy source files available in: · 13 unmodified lines
370	350
371	351	http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2
372	352
373		−and later versions. In that tarball, see the files:
	353	+and later versions. In that tarball, see the files::
374	354
375	355	cachefilesd.te
376	356	cachefilesd.fc
@@ -379,7 +359,7 @@ and later versions. In that tarball, see the files: · 2 unmodified lines
379	359	They are built and installed directly by the RPM.
380	360
381	361	If a non-RPM based system is being used, then copy the above files to their own
382		−directory and run:
	362	+directory and run::
383	363
384	364	make -f /usr/share/selinux/devel/Makefile
385	365	semodule -i cachefilesd.pp
@@ -394,7 +374,7 @@ an auxiliary policy must be installed to label the alternate location of the · 8 unmodified lines
394	374	cache.
395	375
396	376	For instructions on how to add an auxiliary policy to enable the cache to be
397		−located elsewhere when SELinux is in enforcing mode, please see:
	377	+located elsewhere when SELinux is in enforcing mode, please see::
398	378
399	379	/usr/share/doc/cachefilesd-*/move-cache.txt
400	380
@@ -402,8 +382,7 @@ When the cachefilesd rpm is installed; alternatively, the document can be found · 1 unmodified line
402	382	in the sources.
403	383
404	384
405		−==================
406		−A NOTE ON SECURITY
	385	+A Note on Security
407	386	==================
408	387
409	388	CacheFiles makes use of the split security in the task_struct. It allocates
@@ -445,17 +424,18 @@ for CacheFiles to run in a context of a specific security label, or to create · 35 unmodified lines
445	424	files and directories with another security label.
446	425
447	426
448		−=======================
449		−STATISTICAL INFORMATION
	427	+Statistical Information
450	428	=======================
451	429
452		−If FS-Cache is compiled with the following option enabled:
	430	+If FS-Cache is compiled with the following option enabled::
453	431
454	432	CONFIG_CACHEFILES_HISTOGRAM=y
455	433
456	434	then it will gather certain statistics and display them through a proc file.
457	435
458		− (*) /proc/fs/cachefiles/histogram
	436	+ /proc/fs/cachefiles/histogram
	437	+
	438	+ ::
459	439
460	440	cat /proc/fs/cachefiles/histogram
461	441	JIFS SECS LOOKUPS MKDIRS CREATES
@@ -465,36 +445,39 @@ then it will gather certain statistics and display them through a proc file. · 3 unmodified lines
465	445	between 0 jiffies and HZ-1 jiffies a variety of tasks took to run. The
466	446	columns are as follows:
467	447
	448	+ ======= =======================================================
468	449	COLUMN TIME MEASUREMENT
469	450	======= =======================================================
470	451	LOOKUPS Length of time to perform a lookup on the backing fs
471	452	MKDIRS Length of time to perform a mkdir on the backing fs
472	453	CREATES Length of time to perform a create on the backing fs
	454	+ ======= =======================================================
473	455
474	456	Each row shows the number of events that took a particular range of times.
475	457	Each step is 1 jiffy in size. The JIFS column indicates the particular
476	458	jiffy range covered, and the SECS field the equivalent number of seconds.
477	459
478	460
479		−=========
480		−DEBUGGING
	461	+Debugging
481	462	=========
482	463
483	464	If CONFIG_CACHEFILES_DEBUG is enabled, the CacheFiles facility can have runtime
484		−debugging enabled by adjusting the value in:
	465	+debugging enabled by adjusting the value in::
485	466
486	467	/sys/module/cachefiles/parameters/debug
487	468
488	469	This is a bitmask of debugging streams to enable:
489	470
	471	+ ======= ======= =============================== =======================
490	472	BIT VALUE STREAM POINT
491	473	======= ======= =============================== =======================
492	474	0 1 General Function entry trace
493	475	1 2 Function exit trace
494	476	2 4 General
	477	+ ======= ======= =============================== =======================
495	478
496	479	The appropriate set of values should be OR'd together and the result written to
497		−the control file. For example:
	480	+the control file. For example::
498	481
499	482	echo $((1\|4\|8)) >/sys/module/cachefiles/parameters/debug
500	483

Documentation/filesystems/caching/index.rst+1−0

@@ -8,5 +8,6 @@ Filesystem Caching · 7 unmodified lines
8	8
9	9	fscache
10	10	object
	11	+ cachefiles
11	12	netfs-api
12	13	operations

MAINTAINERS+1−1

@@ -3731,7 +3731,7 @@ CACHEFILES: FS-CACHE BACKEND FOR CACHING ON MOUNTED FILESYSTEMS · 3730 unmodified lines
3731	3731	M: David Howells <dhowells@redhat.com>
3732	3732	L: linux-cachefs@redhat.com (moderated for non-subscribers)
3733	3733	S: Supported
3734		−F: Documentation/filesystems/caching/cachefiles.txt
	3734	+F: Documentation/filesystems/caching/cachefiles.rst
3735	3735	F: fs/cachefiles/
3736	3736
3737	3737	CADENCE MIPI-CSI2 BRIDGES

fs/cachefiles/Kconfig+2−2

@@ -8,7 +8,7 @@ config CACHEFILES · 7 unmodified lines
8	8	filesystems - primarily networking filesystems - thus allowing fast
9	9	local disk to enhance the speed of slower devices.
10	10
11		− See Documentation/filesystems/caching/cachefiles.txt for more
	11	+ See Documentation/filesystems/caching/cachefiles.rst for more
12	12	information.
13	13
14	14	config CACHEFILES_DEBUG
@@ -36,5 +36,5 @@ config CACHEFILES_HISTOGRAM · 21 unmodified lines
36	36	bouncing between CPUs. On the other hand, the histogram may be
37	37	useful for debugging purposes. Saying 'N' here is recommended.
38	38
39		− See Documentation/filesystems/caching/cachefiles.txt for more
	39	+ See Documentation/filesystems/caching/cachefiles.rst for more
40	40	information.