Merge pull request facebookarchive#52 from onlyjob/master

man pages

man/Makefile

@@ -0,0 +1,17 @@
+#!/usr/bin/make -f
+# -*- makefile -*-
+
+PREFIX ?= /usr
+MANPAGES := $(patsubst %.mdwn, %.8, $(wildcard *.mdwn))
+
+all: $(MANPAGES)
+
+clean:
+	$(RM) $(MANPAGES)
+
+$(MANPAGES):
+	pandoc --standalone --to=man --output=$@ $(@:.8=.mdwn)
+
+install: $(MANPAGES)
+	install -m0644 $(MANPAGES) $(DESTDIR)${PREFIX}/share/man/man8
+

man/flashcache.mdwn

@@ -0,0 +1,69 @@
+% FLASHCACHE(7) flashcache
+%
+% September 2011
+
+# NAME
+
+flashcache - overview of operation
+
+# SYNOPSIS
+
+modprobe flashcache
+
+Flashcache consists of a kernel module and userspace utilities. The module is
+named "flashcache". The kernel module can be controlled with *flashcache_create*(8),
+*flashcache_load*(8) and *flashcache_destroy*(8) utilities.
+
+
+# DESCRIPTION
+
+Flashcache is a block cache for Linux, built as a kernel module,
+using the device mapper. Flashcache supports **writeback**, **writethrough** and
+**writearound** caching modes. See *flashcache_create*(8) for a description
+of caching modes.
+
+Flascache allows one to use a fast block device such as Solid State Drives (SSD)
+as cache to accelerate a slower drive used as backstore. 
+
+Originally, Flashcache was built as a block device cache for I/O intensive
+database applications, for example to run an accelerated InnoDB store for
+*mysqld*(8), but it can be used as general purpose backend for filesystems as
+well.
+
+
+# USAGE
+
+Before using Flashcache, it might be a good idea to check if device mapper works
+properly. Assuming the partition /dev/md0p1 shall be used as flash cache, one
+may try to create a linear device with following command:
+
+**echo 0 1024 linear /dev/md0p1 0 | dmsetup create tmpdisk**
+
+It this works, *flashcache_create* should be able to create its device.
+
+Remove tmpdisk with command:
+
+**dmsetup remove tmpdisk**
+
+Before creating a flashcache device using the *flashcache_create* command, the
+deivce must not be mounted.
+
+
+# SEE ALSO
+
+`flashcache_create`(8), `flashcache_load`(8), `flashcache_destroy`(8)
+
+*README* and other documents in **/usr/share/doc/flashcache-utils**. In
+particular, see **flashcache-sa-guide.txt** for configuring the flashcache
+kernel module through its */proc* interface.
+
+The flashcache source code and all documentation may be downloaded from
+<https://github.com/facebook/flashcache/>.
+
+
+# AUTHORS
+
+Flashcache is developed by Mohan Srinivasan <mohan@fb.com>
+
+This man page was written by Dmitry Smirnov <onlyjob@member.fsf.org>
+for Debian GNU/Linux (but may be used by others).

man/flashcache_create.mdwn

@@ -0,0 +1,110 @@
+% FLASHCACHE_CREATE(8) flashcache_create
+%
+% September 2011
+
+# NAME
+
+flashcache_create - create a new flashcache volume
+
+# DESCRIPTION
+
+**flashcache_create** initializes a new flashcache volume from unformated block
+devices. It creates flashcache meta data and provides new volumes though their
+volume mappings.
+
+# SYNOPSIS
+
+flashcache_create -p *back*|*around*|*thru* [-s *cache size*] [-b *block size*] [-v]
+*cachedevname*  *cache_devname*  *disk_devname*
+
+
+# OPTIONS
+
+-v
+:    verbose
+
+-p
+:    *cache mode*. Required argument. Specify any supported option:
+     (write-)**back**, (write-)**thru** or (write-)**around**. Their respective
+     implications are denoted below.
+
+-s
+:    *cache size*. Optional argument. By default, flashcache will use the
+     auto-detected full cache device size. When present, the given cache size is used
+     instead. The expected units are sectors, however any value can be suffixed by
+     "k", "m" or "g" to interpret the argument in kilo-, mega- or gigabytes
+     respectively.
+
+-b
+:    *block size*. Optional argument. Defaults to 4KB. Must be a power of 2.
+     The default units is sectors. However, *k* can be specified as unit type as
+     well. (A 4KB blocksize is the correct choice for the vast majority of
+     applications.
+
+-f
+:    force create. Bypass all sanity checks (for example for the sector size).
+Use with care.
+
+
+# CACHING MODES
+
+The following caching modes are supported:
+
+*Writethrough* (**thru**) - safest mode, all writes are cached to the cache
+device but are also being written to disk immediately.  If the used cache device has
+a lower write performance than the backend disk (many early generation SSD
+drives manufactured between 2008-2010 are known for such a poor write
+performance) enabling the writethrough mode may decrease the system write
+performance. All disk reads are cached (tunable through flashcache's */proc*
+interface).
+
+*Writearound* (**ardound**) - again, very safe, writes are not written to the
+cache device, but directly to the backend disk instead.  Disk blocks will only
+be cached after they are read.  All disk reads are cached (tunable through
+flashcache's */proc* interface).
+
+*Writeback* (**back**) - fastest mode but less safe.  Writes only go to the
+cache device initially, and are being written to the backend disk later,
+depending on configured system policie.  All disk reads are
+cached (tunable through flashcache's */proc* interface).
+
+
+# CACHE PERSISTENCE
+
+Writethru and Writearound caches are not persistent across a device removal
+or a reboot. Only Writeback caches are persistent across device removals
+and reboots.  This reinforces 'writeback is fastest', 'writethrough is safest'.
+
+
+# EXAMPLES
+
+**flashcache_create** -p back -s 1g -b 4k cachedev /dev/sdc /dev/sdb
+:   Creates a 1GB writeback cache volume with a 4KB block size on the cache
+    device /dev/sdc to cache the disk volume /dev/sdb. The name of the device
+    created is "cachedev".
+
+
+**flashcache_create** -p thru -s 2097152 -b 8 cachedev /dev/sdc /dev/sdb
+:   Same as above but creates a write through cache with units specified in
+    sectors instead. The name of the device created is "cachedev".
+
+
+# SEE ALSO
+
+`flashcache_load`(8), `flashcache_destroy`(8)
+
+*README* and other documents in **/usr/share/doc/flashcache-utils**. In
+particular, see **flashcache-sa-guide.txt** for configuring the flashcache
+kernel module through its */proc* interface.
+
+The flashcache source code and all documentation may be downloaded from
+<https://github.com/facebook/flashcache/>.
+
+
+# AUTHORS
+
+Flashcache is developed by Mohan Srinivasan <mohan@fb.com>
+
+This man page was written by Dmitry Smirnov <onlyjob@member.fsf.org>
+for Debian GNU/Linux (but may be used by others).
+

man/flashcache_destroy.mdwn

@@ -0,0 +1,43 @@
+% FLASHCACHE_DESTROY(8) flashcache_destroy
+%
+% September 2011
+
+# NAME
+
+flashcache_load - destroy an existing flashcache volume
+
+
+# DESCRIPTION
+
+The purpose of the **flashcache_load** command is to Clear all meta data from
+cache device. Beware, this will cause data loss on the affected devices. 
+
+
+# SYNOPSIS
+
+flashcache_destroy *cache_devname*
+
+
+# EXAMPLE
+
+flashcache_destroy */dev/sdc*
+:   Destroy the existing cache on /dev/sdc. All data is lost!
+
+
+# SEE ALSO
+
+`flashcache_create`(8), `flashcache_load`(8)
+
+*README* and other documents in **/usr/share/doc/flashcache-utils**
+
+The flashcache source code and all documentation may be downloaded from
+<https://github.com/facebook/flashcache/>.
+
+
+# AUTHORS
+
+Flashcache is developed by Mohan Srinivasan <mohan@fb.com>
+
+This man page was written by Dmitry Smirnov <onlyjob@member.fsf.org>
+for Debian GNU/Linux (but may be used by others).
+