Add man pages

Thanks to Bas Zoetekouw <bas@debian.org> for providing these! And
shame on me for forgetting to add them to the git repo.

Signed-off-by: Jens Axboe <jens.axboe@oracle.com>

6 files changed, 1187 insertions, 0 deletions

diff --git a/doc/blkparse.1 b/doc/blkparse.1
new file mode 100644
index 0000000..825ca36
--- /dev/null
+++ b/doc/blkparse.1
@@ -0,0 +1,565 @@
+.TH BLKTPARSE 1 "March  6, 2007" "blktrace git\-20070306202522" ""
+
+
+.SH NAME
+blkparse \- produce formatted output of event streams of block devices
+
+
+.SH SYNOPSIS
+.B blkparse [ \fIoptions\fR ] 
+.br
+
+
+.SH DESCRIPTION
+The \fIblkparse\fR utility will attempt to combine streams of events for
+various devices on various CPUs, and produce a formatted output of the event
+information.  Specifically, it will take the (machine-readable) output of the
+\fIblktrace\fR utility and convert it to a nicely formatted and human-readable
+form.
+
+As with \fIblktrace\fR, some details concerning \fIblkparse\fR
+will help in understanding the command line options presented below.
+
+
+.TP 2
+\-
+By default, \fIblkparse\fR expects to run in a post-processing mode; one where
+the trace events have been saved by a previous run of blktrace, and blkparse
+is combining event streams and dumping formatted data.
+
+blkparse may be run in a live manner concurrently with blktrace by specifying
+\fB\-i \-\fR to blkparse, and combining it with the live option for blktrace.
+An example would be:
+
+   % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
+
+.TP 2
+\-
+You can set how many blkparse batches event reads via the \fB\-b\fR option, the
+default is to handle events in batches of 512.
+
+.TP 2
+\-
+If you have saved event traces in blktrace with different output names (via
+the \fB\-o\fR option to blktrace), you must specify the same input name via the
+\fB\-i\fR option.
+
+.TP 2
+\-
+The format of the output data can be controlled via the \fB\-f\fR or \fB\-F\fR
+options \-\- see OUTPUT DESCRIPTION AND FORMATTING for details.
+
+.PP
+By default, blkparse sends formatted data to standard output. This may
+be changed via the \fB\-o\fR option, or text output can be disabled via the
+\fB\-O\fR option. A merged binary stream can be produced using the \fB\-d\fR
+option.
+
+
+
+.SH OPTIONS
+
+\-b \fIbatch\fR
+.br
+\-\-batch={batch}
+.RS
+Standard input read batching
+.RE
+
+\-i \fIfile\fR
+.br
+\-\-input=\fIfile\fR
+.RS
+Specifies base name for input files \-\- default is \fIdevice\fR.blktrace.\fIcpu\fR.
+
+As noted above, specifying \fB\-i \-\fR runs in live mode with blktrace
+(reading data from standard in).
+.RE
+
+\-F \fItyp,fmt\fR
+.br
+\-\-format=\fItyp,fmt\fR
+.br
+\-f \fIfmt\fR
+.br
+\-\-format\-spec=\fIfmt\fR
+.RS
+Sets output format
+(See OUTPUT DESCRIPTION AND FORMATTING for details.)
+
+The \-f form specifies a format for all events
+
+The \-F form allows one to specify a format for a specific
+event type. The single\-character \fItyp\fR field is one of the
+action specifiers described in ACTION IDENTIFIERS.
+.RE
+
+\-m
+.br
+\-\-missing
+.RS
+Print missing entries
+.RE
+
+\-h
+.br
+\-\-hash\-by\-name
+.RS
+Hash processes by name, not by PID
+.RE
+
+\-o \fIfile\fR
+.br
+\-\-output=\fIfile\fR
+.RS
+Output file
+.RE
+
+\-O
+.br
+\-\-no\-text\-output
+.RS
+Do \fInot\fR produce text output, used for binary (\fB\-d\fR) only
+.RE
+
+\-d \fIfile\fR
+.br
+\-\-dump\-binary=\fIfile\fR
+.RS
+Binary output file
+.RE
+
+\-q
+.br
+\-\-quiet
+.RS
+Quiet mode
+.RE
+
+\-s
+.br
+\-\-per\-program\-stats
+.RS
+Displays data sorted by program
+.RE
+
+\-t
+.br
+\-\-track\-ios
+.RS
+Display time deltas per IO
+.RE
+
+\-w \fIspan\fR
+.br
+\-\-stopwatch=\fIspan\fR
+.RS
+Display traces for the \fIspan\fR specified \-\- where span can be:
+.br
+\fIend\-time\fR \-\- Display traces from time 0 through \fIend\-time\fR (in ns)
+.br
+or
+.br
+\fIstart:end\-time\fR \-\- Display traces from time \fIstart\fR
+through end\-time (in ns).
+.RE
+
+\-v
+.br
+\-\-verbose
+.RS
+More verbose marginal on marginal errors
+.RE
+
+\-V
+.br
+\-\-version
+.RS
+Display version
+.RE
+
+
+.SH "TRACE ACTIONS"
+The following trace actions are recognised:
+
+.HP 4
+\fBC -- complete\fR
+A previously issued request has been completed.  The output will detail the
+sector and size of that request, as well as the success or failure of it.
+
+.HP 4
+\fBD -- issued\fR
+A request that previously resided on the block layer queue or in the i/o
+scheduler has been sent to the driver.
+
+.HP 4
+\fBI -- inserted\fR
+A request is being sent to the i/o scheduler for addition to the internal queue
+and later service by the driver. The request is fully formed at this time.
+
+.HP 4
+\fBQ -- queued\fR
+This notes intent to queue i/o at the given location.  No real requests exists
+yet.
+
+.HP 4
+\fBB -- bounced\fR
+The data pages attached to this \fIbio\fR are not reachable by the hardware
+and must be bounced to a lower memory location. This causes a big slowdown in
+i/o performance, since the data must be copied to/from kernel buffers. Usually
+this can be fixed with using better hardware -- either a better i/o controller,
+or a platform with an IOMMU.
+
+.HP 4
+\fBM -- back merge\fR
+A previously inserted request exists that ends on the boundary of where this i/o
+begins, so the i/o scheduler can merge them together.
+
+.HP 4
+\fBF -- front merge\fR
+Same as the back merge, except this i/o ends where a previously inserted
+requests starts.
+
+.HP 4
+\fBM --front or back merge\fR
+One of the above
+
+.HP 4
+\fBM -- front or back merge\fR
+One of the above.
+
+.HP 4
+\fBG -- get request\fR
+To send any type of request to a block device, a \fIstruct request\fR
+container must be allocated first.
+
+.HP 4
+\fBS -- sleep\fR
+No available request structures were available, so the issuer has to wait for
+one to be freed.
+
+.HP 4
+\fBP -- plug\fR
+When i/o is queued to a previously empty block device queue, Linux will plug the
+queue in anticipation of future ios being added before this data is needed.
+
+.HP 4
+\fBU -- unplug\fR
+Some request data already queued in the device, start sending requests to the
+driver. This may happen automatically if a timeout period has passed (see next
+entry) or if a number of requests have been added to the queue.
+
+.HP 4
+\fBT -- unplug due to timer\fR
+If nobody requests the i/o that was queued after plugging the queue, Linux will
+automatically unplug it after a defined period has passed.
+
+.HP 4
+\fBX -- split\fR
+On raid or device mapper setups, an incoming i/o may straddle a device or
+internal zone and needs to be chopped up into smaller pieces for service. This
+may indicate a performance problem due to a bad setup of that raid/dm device,
+but may also just be part of normal boundary conditions. dm is notably bad at
+this and will clone lots of i/o.
+
+.HP 4
+\fBA -- remap\fR
+For stacked devices, incoming i/o is remapped to device below it in the i/o
+stack. The remap action details what exactly is being remapped to what.
+
+
+
+
+.SH "OUTPUT DESCRIPTION AND FORMATTING"
+
+The output from blkparse can be tailored for specific use -- in particular, to ease
+parsing of output, and/or limit output fields to those the user wants to see. The
+data for fields which can be output include:
+
+.IP \fBa\fR 4
+Action, a (small) string (1 or 2 characters) -- see table below for more details
+
+.IP \fBc\fR 4
+CPU id
+
+.IP \fBC\fR 4
+Command
+
+.IP \fBd\fR 4
+RWBS field, a (small) string (1-3 characters)  -- see section below for more details
+
+.IP \fBD\fR 4
+7-character string containing the major and minor numbers of
+the event's device (separated by a comma).
+
+.IP \fBe\fR 4
+Error value
+
+.IP \fBm\fR 4
+Minor number of event's device.
+
+.IP \fBM\fR 4
+Major number of event's device.
+
+.IP \fBn\fR 4
+Number of blocks
+
+.IP \fBN\fR 4
+Number of bytes
+
+.IP \fBp\fR 4
+Process ID
+
+.IP \fBP\fR 4
+Display packet data \-\- series of hexadecimal values
+
+.IP \fBs\fR 4
+Sequence numbers
+
+.IP \fBS\fR 4
+Sector number
+
+.IP \fBt\fR 4
+Time stamp (nanoseconds)
+
+.IP \fBT\fR 4
+Time stamp (seconds)
+
+.IP \fBu\fR 4
+Elapsed value in microseconds (\fI\-t\fR command line option)
+
+.IP \fBU\fR 4
+Payload unsigned integer
+
+.PP
+Note that the user can optionally specify field display width, and optionally a
+left-aligned specifier. These precede field specifiers, with a '%' character,
+followed by the optional left-alignment specifier (\-) followed by the width (a
+decimal number) and then the field.
+
+Thus, to specify the command in a 12-character field that is left aligned:
+
+    \-f "%\-12C"
+
+
+.SH "ACTION IDENTIFIERS"
+
+The following table shows the various actions which may be output:
+
+.IP A
+IO was remapped to a different device
+
+.IP B
+IO bounced
+
+.IP C
+IO completion
+
+.IP D
+IO issued to driver
+
+.IP F
+IO front merged with request on queue
+
+.IP G
+Get request
+
+.IP I
+IO inserted onto request queue
+
+.IP M
+IO back merged with request on queue
+
+.IP P
+Plug request
+
+.IP Q
+IO handled by request queue code
+
+.IP S
+Sleep request
+
+.IP T
+Unplug due to timeout
+
+.IP U
+Unplug request
+
+.IP X
+Split
+
+
+.SH "RWBS DESCRIPTION"
+
+This is a small string containing at least one character ('R' for read, 'W' for
+write operation), and optionally either a 'B' (for barrier operations) or 'S' (for
+synchronous operations).
+
+
+.SH "DEFAULT OUTPUT"
+
+The standard header (or initial fields displayed) include:
+
+    "%D %2c %8s %5T.%9t %5p %2a %3d"
+
+Breaking this down:
+
+.IP \fB%D\fR
+Displays the event's device major/minor as: %3d,%\-3d.
+
+.IP \fB%2c\fR
+CPU ID (2-character field).
+
+.IP \fB%8s\fR
+Sequence number
+
+.IP \fB%5T.%9t\fR
+5-character field for the seconds portion of the time stamp and a 9-character field for the nanoseconds in the time stamp.
+
+.IP \fB%5p\fR
+5-character field for the process ID.
+
+.IP \fB%2a\fR
+2-character field for one of the actions.
+
+.IP \fB%3d\fR
+3-character field for the RWBS data.
+
+Seeing this in action:
+
+    8,0    3        1     0.000000000   697  G   W 223490 + 8 [kjournald]
+
+The header is the data in this line up to the 223490 (starting block).
+The default output for all event types includes this header.
+
+
+
+.SH "DEFAULT OUTPUT PER ACTION"
+
+\fBC \-\- complete\fR
+.RS 4
+If a payload is present, this is presented between
+parenthesis following the header, followed by the error value.
+
+If no payload is present, the sector and number of blocks are presented
+(with an intervening plus (+) character). If the \fB\-t\fR option
+was specified, then the elapsed time is presented. In either case,
+it is followed by the error value for the completion.
+.RE
+
+\fBB \-\- bounced\fR
+.br
+\fBD \-\- issued\fR
+.br
+\fBI \-\- inserted\fR
+.br
+\fBQ \-\- queued\fR
+.RS 4
+If a payload is present, the number of payload bytes
+is output, followed by the payload in hexadecimal between parenthesis.
+
+If no payload is present, the sector and number of blocks are presented
+(with an intervening plus (+) character). If the \fB\-t\fR option was
+specified, then the elapsed time is presented (in parenthesis). In
+either case, it is followed by the command associated with the event
+(surrounded by square brackets).
+.RE
+
+\fBF \-\- front merge\fR
+.br
+\fBG \-\- get request\fR
+.br
+\fBM \-\- back merge\fR
+.br
+\fBS \-\- sleep\fR
+.RS 4
+The starting sector and number of blocks is output
+(with an intervening plus (+) character), followed by the command
+associated with the event (surrounded by square brackets).
+.RE
+
+\fBP \-\- plug\fR
+.RS 4
+The command associated with the event (surrounded by
+square brackets) is output.
+.RE
+
+\fBU \-\- unplug\fR
+.br
+\fBT \-\- unplug due to timer\fR
+.RS 4
+The command associated with the event
+(surrounded by square brackets) is output, followed by the number of
+requests outstanding.
+.RE
+
+\fBX \-\- split\fR
+.RS 4
+The original starting sector followed by the new
+sector (separated by a slash (/) is output, followed by the command
+associated with the event (surrounded by square brackets).
+.RE
+
+\fBA \-\- remap\fR
+.RS 4
+Sector and length is output, along with the original
+device and sector offset.
+.RE
+
+
+.SH EXAMPLES
+To trace the i/o on the device \fI/dev/hda\fB and parse the output to human
+readable form, use the following command:
+
+    % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
+
+(see \fIblktrace\fR (8) for more information).
+This same behaviour can be achieve with the convenience script \fIbtrace\fR.
+The command
+
+    % btrace /dev/sda
+
+has exactly the same effect as the previous command. See \fIbtrace\fR (8) for
+more information.
+
+To trace the i/o on a device and save the output for later processing with
+\fIblkparse\fR, use \fIblktrace\fR like this:
+
+    % blktrace /dev/sda /dev/sdb
+
+This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
+the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
+directory, for the two different devices, respectively.  This trace
+information can later be parsed by the \fIblkparse\fR utility:
+
+    % blkparse sda sdb
+
+which will output the previously recorded tracing information in human
+readable form to stdout. 
+
+
+.SH AUTHORS
+\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
+man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.
+
+
+.SH "REPORTING BUGS"
+Report bugs to <linux\-btrace@vger.kernel.org>
+
+.SH COPYRIGHT
+Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
+.br
+This is free software.  You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+.br
+This manual page was created for Debian by Bas Zoetekouw.  It was derived from
+the documentation provided by the authors and it may be used, distributed and
+modified under the terms of the GNU General Public License, version 2.
+.br
+On Debian systems, the text of the GNU General Public License can be found in
+/usr/share/common\-licenses/GPL\-2.
+
+.SH "SEE ALSO"
+btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt (1)
+
diff --git a/doc/blkrawverify.1 b/doc/blkrawverify.1
new file mode 100644
index 0000000..1c52292
--- /dev/null
+++ b/doc/blkrawverify.1
@@ -0,0 +1,47 @@
+.TH BLKRAWVERIFY 1 "March  6, 2007" "blktrace git\-20070306202522" ""
+
+
+.SH NAME
+blkrawverify \- verifies an output file produced by blkparse
+
+
+.SH SYNOPSIS
+.B verify_blkparse <\fIdev\fR> [<\fIdev\fR>...]
+.br
+
+
+.SH DESCRIPTION
+
+The \fIblkrawverify\fR utility can be used to verify data retrieved via
+\fIblktrace\fR. It will check for valid event formats, forward progressing
+sequence numbers and time stamps, also does reasonable checks for other
+potential issues within individual events.
+
+Errors found will be tracked in <\fIdev\fR>.verify.out.
+
+
+.SH AUTHORS
+\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
+man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.
+
+
+.SH "REPORTING BUGS"
+Report bugs to <linux\-btrace@vger.kernel.org>
+
+.SH COPYRIGHT
+Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
+.br
+This is free software.  You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+.br
+This manual page was created for Debian by Bas Zoetekouw.  It was derived from
+the documentation provided by the authors and it may be used, distributed and
+modified under the terms of the GNU General Public License, version 2.
+.br
+On Debian systems, the text of the GNU General Public License can be found in
+/usr/share/common\-licenses/GPL\-2.
+
+.SH "SEE ALSO"
+btrace (8), blktrace (8), blkparse (1), verify_blkparse (1), btt (1)
+
diff --git a/doc/blktrace.8 b/doc/blktrace.8
new file mode 100644
index 0000000..99383f1
--- /dev/null
+++ b/doc/blktrace.8
@@ -0,0 +1,255 @@
+.TH BLKTRACE 8 "March  6, 2007" "blktrace git\-20070306202522" ""
+
+
+.SH NAME
+blktrace \- generate traces of the i/o traffic on block devices
+
+
+.SH SYNOPSIS
+.B blktrace \-d \fIdev\fR [ \-r \fIdebugfs_path\fR ] [ \-o \fIoutput\fR ] [\-k ] [ \-w \fItime\fR ] [ \-a \fIaction\fR ] [ \-A \fIaction_mask\fR ] [ \-v ]
+.br
+
+
+.SH DESCRIPTION
+blktrace is a block layer IO tracing mechanism which provides detailed
+information about request queue operations up to user space. There are three
+major components: a kernel component, a utility to record the i/o trace
+information for the kernel to user space, and utilities to analyse and view the
+trace information.  This man page describes blktrace, which records the i/o event
+trace information for a specific block device to a file.
+
+The \fBblktrace\fR utility extracts event traces from the kernel (via
+the relaying through the debug file system). Some background details
+concerning the run\-time behaviour of blktrace will help to understand some
+of the more arcane command line options:
+
+.TP 2
+\-
+blktrace receives data from the kernel in buffers passed up through the
+debug file system (relay). Each device being traced has a file created in
+the mounted directory for the debugfs, which defaults to 
+\fI/sys/kernel/debug\fR \-\- this can be overridden with the \fB\-r\fR command
+line argument.
+
+.TP 2
+\-
+blktrace defaults to collecting all events that can be traced. To
+limit the events being captured, you can specify one or more filter masks
+via the \fB\-a\fR option.
+
+Alternatively, one may specify the entire mask utilising a hexadecimal
+value that is version\-specific. (Requires understanding of the internal
+representation of the filter mask.)
+
+.TP 2
+\-
+As noted above, the events are passed up via a series of buffers stored
+into debugfs files. The size and number of buffers can be specified via
+the \fB\-b\fR and \fB\-n\fR arguments respectively.
+
+.TP 2
+\-
+blktrace stores the extracted data into files stored in the
+local directory. The format of the file names is (by default)
+\fBdevice\fR.\fBblktrace\fR.\fBcpu\fR, where \fBdevice\fR is the base
+device name (e.g, if we are tracing /dev/sda, the base device name would
+be \fBsda\fR); and \fBcpu\fR identifies a CPU for the event stream.
+
+The \fBdevice\fR portion of the event file name can be changed via
+the \fB\-o\fR option.
+
+.TP 2
+\-
+blktrace may also be run concurrently with blkparse to produce
+\fBlive\fR output \-\- to do this specify \fB\-o \-\fR for blktrace.
+
+.TP 2
+\- 
+The default behaviour for blktrace is to run forever until explicitly
+killed by the user (via a control-C, or kill utility invocation).
+There are two ways to modify this:
+
+.TP 5
+  1. 
+You may utilise the blktrace utility itself to kill
+a running trace -- via the \fB\-k\fR option.
+
+.TP 5
+  2.
+You can specify a run-time duration for blktrace via the
+\fB\-w\fR option -- then blktrace will run for the specified number
+of seconds, and then halt.
+
+
+.SH OPTIONS
+
+\-A \fIhex-mask\fR 
+.br
+\-\-set-mask=\fIhex-mask\fR
+.RS
+Set filter mask to \fIhex-mask\fR (see below for masks)
+.RE
+
+\-a \fImask\fR      
+.br
+\-\-act-mask=\fImask\fR      
+.RS
+Add \fImask\fR to current filter (see below for masks) 
+.RE
+
+\-b \fIsize\fR    
+.br
+\-\-buffer\-size=\fIsize\fR   
+.RS
+Specifies buffer size for event extraction (scaled by 1024)
+.RE
+
+\-d \fIdev\fR
+.br
+\-\-dev=\fIdev\fR 
+.RS
+Adds \fIdev\fR as a device to trace  
+.RE
+
+\-I \fIfile\fR
+.br
+\-\-input-devs=\fIfile\fR 
+.RS
+Adds the devices found in \fIfile\fR as devices to trace
+
+\-k 
+.br
+\-\-kill 
+.RS
+Kill on-going trace  
+.RE
+
+\-n \fInum\-sub\fR 
+.br
+\-\-num\-sub=\fInum-sub\fR    
+.RS
+Specifies number of buffers to use  
+.RE
+
+\-o \fIfile\fR 
+.br
+\-\-output=\fIfile\fR        
+.RS
+Prepend \fIfile\fR to output file name(s)  
+.RE
+
+\-r \fIrel-path\fR
+.br
+\-\-relay=\fIrel-path\fR     
+.RS
+Specifies debugfs mount point  
+.RE
+
+\-V               
+.br
+\-\-version                  
+Outputs version  
+.RE
+
+\-w \fIseconds\fR 
+.br
+\-\-stopwatch=\fIseconds\fR  
+.RS
+Sets run time to the number of seconds specified  
+.RE
+
+
+.SH FILTER MASKS
+The following masks may be passed with the \fI\-a\fR command line
+option, multiple filters may be combined via multiple \fI\-a\fR command
+line options.
+
+.RS
+\fIbarrier\fR: barrier attribute 
+.br
+\fIcomplete\fR: completed} by driver
+.br
+\fIfs\fR: requests 
+.br
+\fIissue\fR: issued to driver 
+.br
+\fIpc\fR: packet command events
+.br
+\fIqueue\fR: queue operations 
+.br
+\fIread\fR: read traces 
+.br
+\fIrequeue\fR: requeue operations 
+.br
+\fIsync\fR: synchronous attribute 
+.br
+\fIwrite\fR: write traces
+.RE
+
+
+.SH REQUEST TYPES
+blktrace distinguishes between two types of block layer requests, file system
+and SCSI commands. The former are dubbed \fBfs\fR requests, the latter
+\fBpc\fR requests. File system requests are normal read/write operations, i.e.
+any type of read or write from a specific disk location at a given size. These
+requests typically originate from a user process, but they may also be
+initiated by the vm flushing dirty data to disk or the file system syncing a
+super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace
+sends the command data block as a payload so that blkparse can decode it.
+
+
+.SH EXAMPLES
+To trace the i/o on the device \fI/dev/hda\fB and parse the output to human
+readable form, use the following command:
+
+    % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
+
+This same behaviour can be achieve with the convenience script \fIbtrace\fR.
+The command
+
+    % btrace /dev/sda
+
+has exactly the same effect as the previous command. See \fIbtrace\fR (8) for
+more information.
+
+To trace the i/o on a device and save the output for later processing with
+\fIblkparse\fR, use \fIblktrace\fR like this:
+
+    % blktrace /dev/sda /dev/sdb
+
+This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
+the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
+directory, for the two different devices, respectively.  This trace
+information can later be parsed by the \fIblkparse\fR utility:
+
+    % blkparse sda sdb
+
+which will output the previously recorded tracing information in human
+readable form to stdout.  See \fIblkparse\fR (1) for more information.
+
+
+.SH AUTHORS
+blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
+man page was created from the blktrace documentation by Bas Zoetekouw.
+
+
+.SH "REPORTING BUGS"
+Report bugs to <linux\-btrace@vger.kernel.org>
+
+.SH COPYRIGHT
+Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
+.br
+This is free software.  You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+.br
+This manual page was created for Debian by Bas Zoetekouw.  It was derived from
+the documentation provided by the authors and it may be used, distributed and
+modified under the terms of the GNU General Public License, version 2.
+.br
+On Debian systems, the text of the GNU General Public License can be found in
+/usr/share/common\-licenses/GPL\-2.
+
+.SH "SEE ALSO"
+btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
+
diff --git a/doc/btrace.8 b/doc/btrace.8
new file mode 100644
index 0000000..dc99a59
--- /dev/null
+++ b/doc/btrace.8
@@ -0,0 +1,84 @@
+.TH BTRACE 8 "March  6, 2007" "blktrace git\-20070306202522" ""
+
+
+.SH NAME
+btrace \- verifies an output file produced by blkparse
+
+
+.SH SYNOPSIS
+.B Usage: btrace [\-s] [\-t] [\-w \fIN\fN] [\-n \fIN\fR] [\-b \fIN\fR]  [\-a <\fItrace\fR>...] <\fIdev\fR>...
+.br
+
+
+.SH DESCRIPTION
+
+The \fIbtrace\fR script provides a quick and easy way to to live tracing of
+block devices.  All it does is calling \fIblktrace\fR on the specified devices
+and piping its output through \fIblkparse\fR for formatting.  See blktrace (8)
+for more in-depth information about how \fIblktrace\fR works.  
+
+.SH OPTIONS
+
+.HP 4
+.B \-s
+Displays data sorted by program (see \fIblkparse\fR (1)).
+
+.HP 4
+.B \-t 
+Display time deltas per IO (see \fIblkparse\fR (1)).
+
+.HP 4
+.B \-w \fIN\fR
+Sets run time to the number of seconds specified (see \fIblktrace\fR (8)).
+
+.HP 4
+.B \-n \fIN\fR
+Specifies the number of buffers to use (see \fIblktrace\fR (8)).
+
+.HP 4
+.B \-b \fIN\fR
+Specifies buffer size for event extraction (scaled by 1024) (see
+\fIblktrace\fR (8)).
+
+.HP 4
+.B \-a <\fItrace\fR>...
+Add mask to current filter (see \fIblktrace\fR (8)).
+
+.HP 4
+.B <\fIdev\fR>
+Specifies the device to trace.
+
+
+.SH EXAMPLE
+Simply running
+
+    % blktrace /dev/sda
+
+will show a trace of the device \fI/dev/sda\fR.
+
+
+.SH AUTHORS
+\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
+man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.
+
+
+.SH "REPORTING BUGS"
+Report bugs to <linux\-btrace@vger.kernel.org>
+
+.SH COPYRIGHT
+Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
+.br
+This is free software.  You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+.br
+This manual page was created for Debian by Bas Zoetekouw.  It was derived from
+the documentation provided by the authors and it may be used, distributed and
+modified under the terms of the GNU General Public License, version 2.
+.br
+On Debian systems, the text of the GNU General Public License can be found in
+/usr/share/common\-licenses/GPL\-2.
+
+.SH "SEE ALSO"
+blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
+
diff --git a/doc/btt.1 b/doc/btt.1
new file mode 100644
index 0000000..febf784
--- /dev/null
+++ b/doc/btt.1
@@ -0,0 +1,192 @@
+.TH BTT 1 "March 06, 2007" "blktrace git\-20070306202522" ""
+
+
+.SH NAME
+btt \- analyse block i/o traces produces by blktrace
+
+
+.SH SYNOPSIS
+.B btt [options] \-i <\fIinput file\fR>
+.br
+.B btt \-h | \-\-help
+.br
+.B btt \-V | \-\-version
+.br
+
+
+.SH DESCRIPTION
+
+btt will take in binary dump data from blkparse, and analyse the events,
+producing a series of output from the analysis. It will also build .dat
+files containing "range data" -- showing things like Q activity (periods
+of time while Q events are being produced), C activity (likewise for
+command completions), and etc.
+
+
+.SH OPTIONS
+
+.B \-h
+.br
+.B \-\-help
+.RS 4
+Shows a short summary of possible command line option
+.RE
+
+.B \-V
+.br
+.B \-\-version
+.RS 4
+Shows the version of btt.
+.RE
+
+.B \-i
+.br
+.RS 4
+Specifies the input file to analyse.  This should be a trace file as produces
+by \fIblktrace\fR (8).
+.RE
+
+.B \-d <\fIseconds\fR>
+.br
+.B \-\-range\-delta=<\fIseconds\fR>
+.RS 4
+The \-d option allows you to specify the granularity which determines
+"activity" with regard to the .dat files \-\- this specific the time
+(in seconds) that must elapse without a particular event occurring to
+signify inactivity. The larger the number, the fewer ranges output \-\-
+the default is 0.1 seconds.
+.RE
+
+.B \-D <\fIdev;...\fR>
+.br
+.B \-\-devices=<\fIdev;...\fR>
+.RS 4
+The \-D option supplies the devices which should be looked at when
+analysing the input. This is a ":" separated list of devices, devices are
+specified by a mjr,mnr tuple (e.g.: \-D "8,0:8,8" specifies two devices
+with major 8 and minor 0 and 8 respectively).
+.RE
+
+.B \-e <\fIexe,...\fR>
+.br
+.B \-\-exes=<\fIexe,...\fR>
+.RS 4
+The \-e option supplies the list of executables that will have I/Os
+analysed.
+.RE
+
+.B \-I <\fIoutput name\fR>
+.br
+.B \-\-iostat=<\fIoutput name\fR>
+.RS 4
+The \-I option directs btt to output iostat\-like data to the specified
+file.  Refer to the iostat (sysstat) documentation for details on the
+data columns. 
+.RE
+
+.B \-l <\fIoutput name\fR>
+.br
+.B \-\-d2c\-latencies=<\fIoutput name\fR>
+.RS 4
+The \-l option allows one to output per\-IO D2C latencies
+respectively. The supplied argument provides the basis for the output
+name for each device.
+.RE
+
+.B \-M <\fIdev map\fR>
+.br
+.B \-\-dev\-maps=<\fIdev map\fR>
+.RS 4
+The \-M option takes in a file generated by the provided script
+(gen_disk_info.py), and allows for better output of device names.
+.RE
+
+.B \-o <\fIoutput name\fR>
+.br
+.B \-\-output\-file=<\fIoutput name\fR>
+.RS 4
+Specifies the output file name.
+.RE
+
+.B \-p <\fIoutput name\fR>
+.br
+.B \-\-per\-io\-dump=<\fIoutput name\fR>
+.RS 4
+The \-p option will generate a file that contains a list of all IO
+"sequences" \- showing the parts of each IO (Q, A, I/M, D, & C).
+.RE
+
+.B \-q <\fIoutput name\fR>
+.br
+.B \-\-q2c\-latencies=<\fIoutput name\fR>
+.RS 4
+The \-q option allows one to output per\-IO Q2C latencies
+respectively. The supplied argument provides the basis for the output
+name for each device.
+.RE
+
+.B \-s <\fIoutput name\fR>
+.br
+.B \-\-seeks=<\fIoutput name\fR>
+.RS 4
+The \-s option instructs btt to output seek data, the argument provided
+is the basis for file names output. There are two files per device,
+read seeks and write seeks.
+.RE
+
+.B \-S <\fIinterval\fR>
+.br
+.B \-\-iostat\-interval=<\fIinterval\fR>
+.RS 4
+The \-S option specifies the interval to use between data
+output, it defaults to once per second.
+.RE
+
+.B \-t <\fIsec\fR>
+.br
+.B \-\-time\-start=<\fIsec\fR>
+.br
+.B \-T <\fIsec\fR>
+.br
+.B \-\-time\-end=<\fIsec\fR>
+.RS 4
+The \-t/\-T options allow one to set a start and/or end time for analysing
+\- analysing will only be done for traces after \-t's argument and before
+\-T's argument. (\-t and \-T are optional, so if you specify just \-t,
+analysis will occur for all traces after the time specified. Similarly,
+if only \-T is specified, analysis stops after \-T's seconds.)
+.RE
+
+.B \-v
+.br
+.B \-\-verbose
+.RS 4
+Requests a more verbose output.
+.RE
+
+
+.SH AUTHORS
+\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
+man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.
+
+
+.SH "REPORTING BUGS"
+Report bugs to <linux\-btrace@vger.kernel.org>
+
+.SH COPYRIGHT
+Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
+.br
+This is free software.  You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+.br
+This manual page was created for Debian by Bas Zoetekouw.  It was derived from
+the documentation provided by the authors and it may be used, distributed and
+modified under the terms of the GNU General Public License, version 2.
+.br
+On Debian systems, the text of the GNU General Public License can be found in
+/usr/share/common\-licenses/GPL\-2.
+
+.SH "SEE ALSO"
+blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
+
diff --git a/doc/verify_blkparse.1 b/doc/verify_blkparse.1
new file mode 100644
index 0000000..c209ef8
--- /dev/null
+++ b/doc/verify_blkparse.1
@@ -0,0 +1,44 @@
+.TH VERIFY_BLKPARSE 1 "March  6, 2007" "blktrace git\-20070306202522" ""
+
+
+.SH NAME
+verify_blkparse \- verifies an output file produced by blkparse
+
+
+.SH SYNOPSIS
+.B verify_blkparse <\fIfilename\fR>
+.br
+
+
+.SH DESCRIPTION
+
+Verifies an output file from blkparse. All it does is check if the events in
+the file are correctly time ordered. If an entry is found that isn't ordered,
+it's dumped to stdout.
+
+
+.SH AUTHORS
+\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
+man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.
+
+
+.SH "REPORTING BUGS"
+Report bugs to <linux\-btrace@vger.kernel.org>
+
+.SH COPYRIGHT
+Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
+.br
+This is free software.  You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+.br
+This manual page was created for Debian by Bas Zoetekouw.  It was derived from
+the documentation provided by the authors and it may be used, distributed and
+modified under the terms of the GNU General Public License, version 2.
+.br
+On Debian systems, the text of the GNU General Public License can be found in
+/usr/share/common\-licenses/GPL\-2.
+
+.SH "SEE ALSO"
+btrace (8), blktrace (8), blkparse (1), blkrawverify (1), btt (1)
+