kernel - Update swapcache manual page, fix breakage in last commit
authorMatthew Dillon <dillon@apollo.backplane.com>
Sun, 21 Feb 2010 02:22:12 +0000 (18:22 -0800)
committerMatthew Dillon <dillon@apollo.backplane.com>
Sun, 21 Feb 2010 02:22:12 +0000 (18:22 -0800)
* Oops, a bunch of stuff was accidently removed in the last
  update, add it back in.

share/man/man8/swapcache.8

index 35228ae..54bf88e 100644 (file)
@@ -22,6 +22,77 @@ data and meta-data.
 .Cd sysctl vm.swapcache.maxfilesize=0
 .Cd sysctl vm.swapcache.maxburst=2000000000
 .Cd sysctl vm.swapcache.curburst=4000000000
+.Cd sysctl vm.swapcache.minburst=10000000
+.Cd sysctl vm.swapcache.read_enable=0
+.Cd sysctl vm.swapcache.meta_enable=0
+.Cd sysctl vm.swapcache.data_enable=0
+.Cd sysctl vm.swapcache.use_chflags=1
+.Cd sysctl vm.swapcache.maxlaunder=256
+.Sh DESCRIPTION
+.Nm
+is a system capability which allows a solid state disk (SSD) in a swap
+space configuration to be used to cache clean filesystem data and meta-data
+in addition to its normal function of backing anonymous memory.
+.Pp
+Sysctls are used to manage operational parameters and can be adjusted at
+any time.  Typically a large initial burst is desired after system boot,
+controlled by the initial
+.Cd vm.swapcache.curburst
+parameter.
+This parameter is reduced as data is written to swap by the swapcache
+and increased at a rate specified by
+.Cd vm.swapcache.accrate .
+Once this parameter reaches zero write activity ceases until it has
+recovered sufficiently for write activity to resume.
+.Pp
+.Cd vm.swapcache.meta_enable
+enables the writing of filesystem meta-data to the swapcache.  Filesystem
+metadata is any data which the filesystem accesses via the disk device
+using buffercache.  Meta-data is cached globally regardless of file
+or directory flags.
+.Pp
+.Cd vm.swapcache.data_enable
+enables the writing of filesystem file-data to the swapcache.  Filesystem
+filedata is any data which the filesystem accesses via a regular file.
+In technical terms, when the buffer cache is used to access a regular
+file through its vnode.  Please do not blindly turn on this option,
+see the PERFORMANCE TUNING section for more information.
+.Pp
+.Cd vm.swapcache.use_chflags
+enables the use of the
+.Cm cache
+and
+.Cm noscache
+.Xr chflags 1
+flags to control which files will be data-cached.
+If this sysctl is disabled and data_enable is enabled,
+the system will ignore file flags and attempt to swapcache all
+regular files.
+.Pp
+.Cd vm.swapcache.read_enable
+enables reading from the swapcache and should be set to 1 for normal
+operation.
+.Pp
+.Cd vm.swapcache.maxfilesize
+controls which files are to be cached based on their size.
+If set to non-zero only files smaller than the specified size
+will be cached.  Larger files will not be cached.
+.Sh PERFORMANCE TUNING
+Best operation is achieved when the active data set fits within the
+swapcache.
+.Pp
+.Bl -tag -width 4n -compact
+.It Cd vm.swapcache.accrate
+This specifies the burst accumulation rate in bytes per second and
+ultimately controls the write bandwidth to swap averaged over a long
+period of time.
+This parameter must be carefully chosen to manage the write endurance of
+the SSD in order to avoid wearing it out too quickly.
+Even though SSDs have limited write endurance, there is massive
+cost/performance benefit to using one in a swapcache configuration.
+.Pp
+Let's use the Intel X25V 40G MLC SATA SSD as an example.  This device
+has approximately a
 40TB (40 terabyte) write endurance, but see later
 notes on this, it is more a minimum value.
 Limiting the long term average bandwidth to 100K/sec leads to no more