man: Revise internal man page generation process.

For each section 8 man page, a .8_gen file is created from one of:
  .8_main            - Old-style man page - content used directly
  .8_des and .8_end  - Description and end section of a generated page
  .8_pregen	     - Pre-generated page used if the generator fails

Other man sections are not generated and use the suffix .5_main or .7_main.

Developers should use 'make generate' to regenerate the .8_pregen files.

1 files changed, 419 insertions, 0 deletions

diff --git a/man/lvmcache.7_main b/man/lvmcache.7_main
new file mode 100644
index 000000000..45bb5b1a6
--- /dev/null
+++ b/man/lvmcache.7_main
@@ -0,0 +1,419 @@
+.TH "LVMCACHE" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\""
+.SH NAME
+lvmcache \(em LVM caching
+
+.SH DESCRIPTION
+
+The \fBcache\fP logical volume type uses a small and fast LV to improve
+the performance of a large and slow LV.  It does this by storing the
+frequently used blocks on the faster LV.
+LVM refers to the small fast LV as a \fBcache pool LV\fP.  The large
+slow LV is called the \fBorigin LV\fP.  Due to requirements from dm-cache
+(the kernel driver), LVM further splits the cache pool LV into two
+devices - the \fBcache data LV\fP and \fBcache metadata LV\fP.  The cache
+data LV is where copies of data blocks are kept from the
+origin LV to increase speed.  The cache metadata LV holds the
+accounting information that specifies where data blocks are stored (e.g.
+on the origin LV or on the cache data LV).  Users should be familiar with
+these LVs if they wish to create the best and most robust cached
+logical volumes.  All of these associated LVs must be in the same VG.
+
+.SH Cache Terms
+.nf
+origin LV           OriginLV      large slow LV
+cache data LV       CacheDataLV   small fast LV for cache pool data
+cache metadata LV   CacheMetaLV   small fast LV for cache pool metadata
+cache pool LV       CachePoolLV   CacheDataLV + CacheMetaLV
+cache LV            CacheLV       OriginLV + CachePoolLV
+.fi
+
+.SH Cache Usage
+
+The primary method for using a cache type logical volume:
+
+
+.SS 0. create OriginLV
+
+Create an LV or identify an existing LV to be the origin LV.
+
+.B lvcreate \-n OriginLV \-L LargeSize VG SlowPVs
+
+.I Example
+.br
+# lvcreate \-n lvol0 \-L 100G vg
+
+
+.SS 1. create CacheDataLV
+
+Create the cache data LV.  This LV will hold data blocks from the
+OriginLV.  The size of this LV is the size of the cache and will be
+reported as the size of the cache pool LV.  
+
+.B lvcreate \-n CacheDataLV \-L CacheSize VG FastPVs
+
+.I Example
+.br
+# lvcreate \-n cache0 \-L 10G vg /dev/fast
+
+
+.SS 2. create CacheMetaLV
+
+Create the cache metadata LV.  This LV will hold cache pool metadata.  The
+size of this LV should be 1000 times smaller than the cache data LV, with
+a minimum size of 8MiB.
+
+.B lvcreate \-n CacheMetaLV \-L MetaSize VG FastPVs
+
+.I Example
+.br
+# lvcreate \-n cache0meta \-L 12M vg /dev/fast
+
+.nf
+# lvs -a vg
+  LV         VG   Attr       LSize   Pool Origin
+  cache0     vg   -wi-a-----  10.00g                                                    
+  cache0meta vg   -wi-a-----  12.00m                                                    
+  lvol0      vg   -wi-a----- 100.00g
+.fi
+
+
+.SS 3. create CachePoolLV
+
+Combine the data and metadata LVs into a cache pool LV.
+The behavior of the cache pool LV can be set in this step.
+.br
+CachePoolLV takes the name of CacheDataLV.
+.br
+CacheDataLV is renamed CachePoolLV_cdata and becomes hidden.
+.br
+CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden.
+
+.B lvconvert \-\-type cache-pool \-\-poolmetadata VG/CacheMetaLV
+.RS
+.B VG/CacheDataLV
+.RE
+
+.I Example
+.br
+# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache0meta vg/cache0
+
+.nf
+# lvs -a vg
+  LV              VG   Attr       LSize   Pool Origin
+  cache0          vg   Cwi---C---  10.00g
+  [cache0_cdata]  vg   Cwi-------  10.00g
+  [cache0_cmeta]  vg   ewi-------  12.00m
+  lvol0           vg   -wi-a----- 100.00g
+.fi
+
+
+.SS 4. create CacheLV
+
+Create a cache LV by linking the cache pool LV to the origin LV.
+The user accessible cache LV takes the name of the origin LV,
+while the origin LV becomes a hidden LV with the name
+OriginLV_corig.  This can be done while the origin LV is in use.
+.br
+CacheLV takes the name of OriginLV.
+.br
+OriginLV is renamed OriginLV_corig and becomes hidden.
+
+.B lvconvert \-\-type cache \-\-cachepool VG/CachePoolLV VG/OriginLV
+
+.I Example
+.br
+# lvconvert \-\-type cache \-\-cachepool vg/cache0 vg/lvol0
+
+.nf
+# lvs -a vg
+  LV              VG   Attr       LSize   Pool   Origin
+  cache0          vg   Cwi---C---  10.00g                                                             
+  [cache0_cdata]  vg   Cwi-ao----  10.00g                                                             
+  [cache0_cmeta]  vg   ewi-ao----  12.00m                                                             
+  lvol0           vg   Cwi-a-C--- 100.00g cache0 [lvol0_corig]                                        
+  [lvol0_corig]   vg   -wi-ao---- 100.00g                                                             
+.fi
+
+
+.SH Cache Removal
+
+.SS Split a cache pool LV off of a cache LV
+
+\&
+
+A cache pool LV can be disconnected from a cache LV, leaving an
+unused cache pool LV, and an uncached origin LV.  This command
+writes back data from the cache pool to the origin LV when necessary.
+
+.B lvconvert --splitcache VG/CacheLV
+
+.SS Removing a cache pool LV without removing its linked origin LV
+
+\&
+
+This writes back data from the cache pool to the origin LV when necessary,
+then removes the cache pool LV, leaving the uncached origin LV.
+
+.B lvremove VG/CachePoolLV
+
+An alternative command that also disconnects the cache pool from the cache
+LV, and deletes the cache pool:
+
+.B lvconvert --uncache VG/CacheLV
+
+.I Example
+.nf
+# lvs vg
+  LV     VG   Attr       LSize   Pool   Origin
+  cache0 vg   Cwi---C---  10.00g
+  lvol0  vg   Cwi-a-C--- 100.00g cache0 [lvol0_corig]
+
+# lvremove vg/cache0
+
+# lvs vg
+  LV    VG   Attr       LSize   Pool Origin
+  lvol0 vg   -wi-a----- 100.00g
+.fi
+
+.SS Removing a cache LV: both origin LV and the cache pool LV
+
+\&
+
+Removing a cache LV removes both the origin LV and the linked cache pool
+LV.
+
+.B lvremove VG/CacheLV
+
+
+.SH Cache Topics
+
+.SS Tolerate device failures in a cache pool LV
+
+\&
+
+Users who are concerned about the possibility of failures in their fast
+devices that could lead to data loss might consider making their cache
+pool sub-LVs redundant.
+
+.I Example
+.nf
+0. Create an origin LV we wish to cache
+# lvcreate \-L 10G \-n lv1 vg /dev/slow_devs
+
+1. Create a 2-way RAID1 cache data LV
+# lvcreate \-\-type raid1 \-m 1 \-L 1G -n cache1 vg \\
+	/dev/fast1 /dev/fast2
+
+2. Create a 2-way RAID1 cache metadata LV
+# lvcreate \-\-type raid1 \-m 1 \-L 8M -n cache1meta vg \\
+	/dev/fast1 /dev/fast2
+
+3. Create a cache pool LV combining cache data LV and cache metadata LV
+# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache1meta vg/cache1
+
+4. Create a cached LV by combining the cache pool LV and origin LV
+# lvconvert \-\-type cache \-\-cachepool vg/cache1 vg/lv1
+.fi
+
+.SS Cache mode
+
+\&
+
+The default cache mode is "writethrough".  Writethrough ensures that any
+data written will be stored both in the cache pool LV and on the origin
+LV.  The loss of a device associated with the cache pool LV in this case
+would not mean the loss of any data.
+
+A second cache mode is "writeback".  Writeback delays writing data blocks
+from the cache pool back to the origin LV.  This mode will increase
+performance, but the loss of a device associated with the cache pool LV
+can result in lost data.
+
+With the \-\-cachemode option, the cache mode can be set when creating a
+cache LV, or changed on an existing cache LV.  The current cache mode of a
+cache LV can be displayed with the cache_mode reporting option:
+
+.B lvs \-o+cache_mode VG/CacheLV
+
+.BR lvm.conf (5)
+.B allocation/cache_mode
+.br
+defines the default cache mode.
+
+.I Example
+.nf
+0. Create an origin LV we wish to cache (yours may already exist)
+# lvcreate \-L 10G \-n lv1 vg /dev/slow
+
+1. Create a cache data LV
+# lvcreate \-L 1G \-n cache1 vg /dev/fast
+
+2. Create a cache metadata LV
+# lvcreate \-L 8M \-n cache1meta vg /dev/fast
+
+3. Create a cache pool LV
+# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache1meta vg/cache1
+
+4. Create a cache LV by combining the cache pool LV and origin LV,
+   and use the writethrough cache mode.
+# lvconvert \-\-type cache \-\-cachepool vg/cache1 \\
+	\-\-cachemode writethrough vg/lv1
+.fi
+
+
+.SS Cache policy
+
+\&
+
+The cache subsystem has additional per-LV parameters: the cache policy to
+use, and possibly tunable parameters for the cache policy.  Three policies
+are currently available: "smq" is the default policy, "mq" is an older
+implementation, and "cleaner" is used to force the cache to write back
+(flush) all cached writes to the origin LV.
+
+The "mq" policy has a number of tunable parameters. The defaults are
+chosen to be suitable for the majority of systems, but in special
+circumstances, changing the settings can improve performance.
+
+With the \-\-cachepolicy and \-\-cachesettings options, the cache policy
+and settings can be set when creating a cache LV, or changed on an
+existing cache LV (both options can be used together).  The current cache
+policy and settings of a cache LV can be displayed with the cache_policy
+and cache_settings reporting options:
+
+.B lvs \-o+cache_policy,cache_settings VG/CacheLV
+
+.I Example
+.nf
+Change the cache policy and settings of an existing cache LV.
+# lvchange \-\-cachepolicy mq \-\-cachesettings \\
+	\(aqmigration_threshold=2048 random_threshold=4\(aq vg/lv1
+.fi
+
+.BR lvm.conf (5)
+.B allocation/cache_policy
+.br
+defines the default cache policy.
+
+.BR lvm.conf (5)
+.B allocation/cache_settings
+.br
+defines the default cache settings.
+
+
+.SS Chunk size
+
+\&
+
+The size of data blocks managed by a cache pool can be specified with the
+\-\-chunksize option when the cache LV is created.  The default unit
+is KiB. The value must be a multiple of 32KiB between 32KiB and 1GiB.
+
+Using a chunk size that is too large can result in wasteful use of the
+cache, where small reads and writes can cause large sections of an LV to
+be mapped into the cache.  However, choosing a chunk size that is too
+small can result in more overhead trying to manage the numerous chunks
+that become mapped into the cache.  Overhead can include both excessive
+CPU time searching for chunks, and excessive memory tracking chunks.
+
+Command to display the cache pool LV chunk size:
+.br
+.B lvs \-o+chunksize VG/CacheLV
+
+.BR lvm.conf (5)
+.B cache_pool_chunk_size
+.br
+controls the default chunk size used when creating a cache LV.
+
+The default value is shown by:
+.br
+.B lvmconfig \-\-type default allocation/cache_pool_chunk_size
+
+
+.SS Spare metadata LV
+
+\&
+
+See
+.BR lvmthin (7)
+for a description of the "pool metadata spare" LV.
+The same concept is used for cache pools.
+
+.SS Automatic pool metadata LV
+
+\&
+
+A cache data LV can be converted to cache pool LV without specifying a
+cache pool metadata LV.  LVM will automatically create a metadata LV from
+the same VG.
+
+.B lvcreate -n CacheDataLV -L CacheSize VG
+.br
+.B lvconvert --type cache\-pool VG/CacheDataLV
+
+
+.SS Create a new cache LV without an existing origin LV
+
+\&
+
+A cache LV can be created using an existing cache pool without an existing
+origin LV.  A new origin LV is created and linked to the cache pool in a
+single step.
+
+.B lvcreate \-\-type cache \-L LargeSize \-n CacheLV
+.RS
+.B \-\-cachepool VG/CachePoolLV VG SlowPVs
+.RE
+
+
+.SS Single step cache pool LV creation
+
+\&
+
+A cache pool LV can be created with a single lvcreate command, rather than
+using lvconvert on existing LVs.  This one command creates a cache data
+LV, a cache metadata LV, and combines the two into a cache pool LV.
+
+.B lvcreate \-\-type cache\-pool \-L CacheSize \-n CachePoolLV VG FastPVs
+
+
+.SS Convert existing LVs to cache types
+
+\&
+
+When an existing origin LV is converted to a cache LV, the specified cache
+pool may be a normal LV, rather than a cache pool LV.  In this case, lvm
+will first convert the normal LV to a cache pool LV.  A pool metadata LV
+may optionally be specified.
+
+.B lvcreate -n OriginLV -L LargeSize VG
+.br
+.B lvcreate -n CacheDataLV -L CacheSize VG
+.br
+.B lvconvert --type cache --cachepool VG/CataDataLV VG/OriginLV
+
+This is equivalent to:
+
+.B lvcreate -n OriginLV -L LargeSize VG
+.br
+.B lvcreate -n CacheDataLV -L CacheSize VG
+.br
+.B lvconvert --type cache-pool VG/CacheDataLV
+.br
+.B lvconvert --type cache --cachepool VG/CachePoolLV VG/OriginLV
+
+
+.SH SEE ALSO
+.BR lvm.conf (5),
+.BR lvchange (8),
+.BR lvcreate (8),
+.BR lvdisplay (8),
+.BR lvextend (8),
+.BR lvremove (8),
+.BR lvrename (8),
+.BR lvresize (8),
+.BR lvs (8),
+.BR vgchange (8),
+.BR vgmerge (8),
+.BR vgreduce (8),
+.BR vgsplit (8)