+++ /dev/null
-\documentclass{article}
-
-%
-% Copyright (C) 2005 Alan D. Brunelle <Alan.Brunelle@hp.com>
-%
-% This program is free software; you can redistribute it and/or modify
-% it under the terms of the GNU General Public License as published by
-% the Free Software Foundation; either version 2 of the License, or
-% (at your option) any later version.
-%
-% This program is distributed in the hope that it will be useful,
-% but WITHOUT ANY WARRANTY; without even the implied warranty of
-% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-% GNU General Public License for more details.
-%
-% You should have received a copy of the GNU General Public License
-% along with this program; if not, write to the Free Software
-% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-%
-
-\title{blktrace User Guide}
-\author{blktrace: Jens Axboe (axboe@suse.de)\\
- User Guide: Alan D. Brunelle (Alan.Brunelle@hp.com)}
-\date{4 October 2005}
-
-\begin{document}
-\maketitle
-%---------------------
-\section{\label{sec:intro}Introduction}
-
-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 that are provided:
-
-\begin{description}
- \item[Kernel patch] A patch to the Linux kernel which includes the
- kernel event logging interfaces, and patches to areas within the block
- layer to emit event traces.
-
- \item[blktrace] A utility which transfers event traces from the kernel
- into either long-term on-disk storage, or provides direct formatted
- output (via blkparse).
-
- \item[blkparse] A utility which formats events stored in files, or when
- run in \emph{live} mode directly outputs data collected by blktrace.
-\end{description}
-
-\subsection{\label{sec:quetions}Questions / Ideas}
-\begin{enumerate}
- \item Is the \emph{-b} scaling by $2^{10}$ correct?
-
- \item Better descriptions for FS and PC in section \ref{sec:filter-mask}.
-
- \item The long forms of options to blktrace and blkparse are not all
- right - for example, \emph{"hash by name".}
-
- \item Add \emph{-D} to specify directory to locate extracted data
- files into (blktrace) or to read from (blkparse).
-
- \item Add \emph{-a} and \emph{-A} to blkparse.
-\end{enumerate}
-
-\subsection{blktrace Download Area}
-
-The blktrace and blkparse utilities and associated kernel patch are provided
-as part of the following git repository:
-
-rsync://rsync.kernel.org/pub/scm/linux/kernel/git/axboe/blktrace.git
-
-%--------------------------
-\newpage\section{\label{sec:quick-start}Quick Start Guide}
-
-The following sections outline some quick steps towards utilizing
-blktrace. Some of the specific instructions below may need to be tailored
-to your environment.
-
-\subsection{\label{sec:get-blktrace}Retrieving blktrace}
-
-As noted above, the kernel patch along with the blktrace and blkparse utilities are stored in a git repository. One simple way to get going would be:
-
-\begin{verbatim}
-% git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/axboe/blktrace.git bt
-% cd bt
-% git-read-tree -m HEAD && git-checkout-cache -q -f -u -a
-\end{verbatim}
-
-\subsection{\label{sec:patching}Patching and configuring the Linux kernel}
-
-A patch for a \emph{specific Linux kernel} is provided in bt/kernel (where
-\emph{bt} is the name of the directory from the above git sequence). The
-detailed actual patching instructions for a Linux kernel is outside the
-scope of this document, but the following may be used as a sample template.
-
-As an example, bt/kernel contains blk-trace-2.6.14-rc1-git-G2, download
-linux-2.6.13.tar.bz2 and patch-2.6.14-rc1.bz2
-
-\begin{verbatim}
-% tar xjf linux-2.6.13.tar.bz2
-% mv linux-2.6.13 linux-2.6.14-rc1
-% cd linux-2.6.14-rc1
-% bunzip2 -c ../patch-2.6.14-rc1.bz2 | patch -p1
-\end{verbatim}
-
-At this point you may (optionally) remove linux-2.6.13.tar.bz2 and
-patch-2.6.14-rc1.bz2.
-
-At this point you should configure the Linux kernel for your specific
-system -- again, outside the scope of this document -- and then enable
-\emph{Support for tracing block io actions.} To do this, run
-
-\begin{verbatim}
-% make menuconfig or make xconfig, or edit .config, or ...
-\end{verbatim}
-
-and navigate through \emph{Device Drivers} and \emph{Block devices}
-and then down to \emph{Support for tracing block io actions} and hit Y.
-
-Install the new kernel (and modules\ldots) and reboot.
-
-\subsection{\label{sec:mount}Mounting the RelayFS file system}
-
-blktrace utilizes files under the Relay file system, and thus must have
-the mount point set up -- mounted on the directory /relay. To do this
-one may do either of the following:
-
-\begin{enumerate}
- \item Manually mount after each boot:
-\begin{verbatim}
-% mount -t relayfs relayfs /relay
-\end{verbatim}
-
- \item Add an entry into /etc/fstab, and have it done automatically at
- each boot\footnote{Note: after adding the entry to /etc/fstab, you
- could then mount the directory this time only by doing: \% mount /relay}:
-\begin{verbatim}
-relay /relay relayfs default 0 0
-\end{verbatim}
-\end{enumerate}
-
-\subsection{\label{sec:build}Build the tools}
-
-To build and install the tools, execute the following sequence (as root):
-
-\begin{verbatim}
-% cd bt
-% make && make install
-\end{verbatim}
-
-\subsection{\label{sec:live-blktrace}blktrace -- live}
-
-Now to simply watch what is going on for a specific disk (to stop the
-trace, hit control-C):
-
-\begin{verbatim}
-% blktrace -d /dev/sda -o - | blkparse -i -
- 8,0 3 1 0.000000000 697 G W 223490 + 8 [kjournald]
- 8,0 3 2 0.000001829 697 P R [kjournald]
- 8,0 3 3 0.000002197 697 Q W 223490 + 8 [kjournald]
- 8,0 3 4 0.000005533 697 M W 223498 + 8 [kjournald]
- 8,0 3 5 0.000008607 697 M W 223506 + 8 [kjournald]
- 8,0 3 6 0.000011569 697 M W 223514 + 8 [kjournald]
- 8,0 3 7 0.000014407 697 M W 223522 + 8 [kjournald]
- 8,0 3 8 0.000017367 697 M W 223530 + 8 [kjournald]
- 8,0 3 9 0.000020161 697 M W 223538 + 8 [kjournald]
- 8,0 3 10 0.000024062 697 D W 223490 + 56 [kjournald]
- 8,0 1 11 0.009507758 0 C W 223490 + 56 [0]
- 8,0 1 12 0.009538995 697 G W 223546 + 8 [kjournald]
- 8,0 1 13 0.009540033 697 P R [kjournald]
- 8,0 1 14 0.009540313 697 Q W 223546 + 8 [kjournald]
- 8,0 1 15 0.009542980 697 D W 223546 + 8 [kjournald]
- 8,0 1 16 0.013542170 0 C W 223546 + 8 [0]
-...
-^C
-...
-CPU1 (8,0):
- Reads Queued: 0, 0KiB Writes Queued: 7, 128KiB
- Read Dispatches: 0, 0KiB Write Dispatches: 7, 128KiB
- Reads Completed: 0, 0KiB Writes Completed: 11, 168KiB
- Read Merges: 0 Write Merges: 25
- IO unplugs: 0 Timer unplugs: 0
-...
-CPU3 (8,0):
- Reads Queued: 0, 0KiB Writes Queued: 1, 28KiB
- Read Dispatches: 0, 0KiB Write Dispatches: 1, 28KiB
- Reads Completed: 0, 0KiB Writes Completed: 0, 0KiB
- Read Merges: 0 Write Merges: 6
- IO unplugs: 0 Timer unplugs: 0
-
-Total (8,0):
- Reads Queued: 0, 0KiB Writes Queued: 11, 168KiB
- Read Dispatches: 0, 0KiB Write Dispatches: 11, 168KiB
- Reads Completed: 0, 0KiB Writes Completed: 11, 168KiB
- Read Merges: 0 Write Merges: 31
- IO unplugs: 0 Timer unplugs: 3
-
-Events (8,0): 89 entries, 0 skips
-\end{verbatim}
-
-\subsection{\label{sec:blktrace-post}blktrace -- post-processing}
-
-Another way to run blktrace is to have blktrace save data away for later
-formatting by blkparse. This would be useful if you want to get
-measurements while running specific loads.
-
-To do this, one would specify the device (or devices) to be watched. Then
-go run you test cases. Stop the trace, and at your leisure utilize
-blkparse to see the results.
-
-In this example, devices /dev/sdaa, /dev/sdc and /dev/sdo are used in an
-LVM volume called adb3/vol.
-
-\begin{verbatim}
-% blktrace /dev/sdaa /dev/sdc /dev/sdo &
-[1] 9713
-%
-% mkfs -t ext3 /dev/adb3/vol
-mke2fs 1.35 (28-Feb-2004)
-Filesystem label=
-OS type: Linux
-Block size=4096 (log=2)
-Fragment size=4096 (log=2)
-16793600 inodes, 33555456 blocks
-1677772 blocks (5.00%) reserved for the super user
-First data block=0
-Maximum filesystem blocks=4294967296
-1025 block groups
-32768 blocks per group, 32768 fragments per group
-16384 inodes per group
-Superblock backups stored on blocks:
- 32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
- 4096000, 7962624, 11239424, 20480000, 23887872
-
-Writing inode tables: done
-Creating journal (8192 blocks): done
-Writing superblocks and filesystem accounting information: done
-
-This filesystem will be automatically checked every 27 mounts or
-180 days, whichever comes first. Use tune2fs -c or -i to override.
-%
-% kill -15 9713
-\end{verbatim}
-
-Then you could process the events later:
-
-\begin{verbatim}
-%
-% blkparse sdaa sdc sdo > events
-% less events
- 8,32 1 1 0.000000000 9728 G R 384 + 32 [mkfs.ext3]
- 8,32 1 2 0.000001959 9728 P R [mkfs.ext3]
- 8,32 1 3 0.000002446 9728 Q R 384 + 32 [mkfs.ext3]
- 8,32 1 4 0.000005110 9728 D R 384 + 32 [mkfs.ext3]
- 8,32 3 5 0.000200570 0 C R 384 + 32 [0]
- 8,224 3 1 0.021658989 9728 G R 384 + 32 [mkfs.ext3]
-...
- 65,160 3 163392 41.117070504 0 C W 87469088 + 1376 [0]
- 8,32 3 163374 41.122683668 0 C W 88168160 + 1376 [0]
- 65,160 3 163393 41.129952433 0 C W 87905984 + 1376 [0]
- 65,160 3 163394 41.130049431 0 D W 89129344 + 1376 [swapper]
- 65,160 3 163395 41.130067135 0 D W 89216704 + 1376 [swapper]
- 65,160 3 163396 41.130083785 0 D W 89304096 + 1376 [swapper]
- 65,160 3 163397 41.130099455 0 D W 89391488 + 1376 [swapper]
- 65,160 3 163398 41.130114732 0 D W 89478848 + 1376 [swapper]
- 65,160 3 163399 41.130128885 0 D W 89481536 + 64 [swapper]
- 8,32 3 163375 41.134758196 0 C W 86333152 + 1376 [0]
- 65,160 3 163400 41.142229726 0 C W 89129344 + 1376 [0]
- 65,160 3 163401 41.144952314 0 C W 89481536 + 64 [0]
- 8,32 3 163376 41.147441930 0 C W 88342912 + 1376 [0]
- 65,160 3 163402 41.155869604 0 C W 89478848 + 1376 [0]
- 8,32 3 163377 41.159466082 0 C W 86245760 + 1376 [0]
- 65,160 3 163403 41.166944976 0 C W 89216704 + 1376 [0]
- 65,160 3 163404 41.178968252 0 C W 89304096 + 1376 [0]
- 65,160 3 163405 41.191860173 0 C W 89391488 + 1376 [0]
-...
-Events (sdo): 0 entries, 0 skips
-
-CPU0 (65,160):
- Reads Queued: 0, 0KiB Writes Queued: 9, 5,520KiB
- Read Dispatches: 0, 0KiB Write Dispatches: 0, 0KiB
- Reads Completed: 0, 0KiB Writes Completed: 0, 0KiB
- Read Merges: 0 Write Merges: 336
- IO unplugs: 0 Timer unplugs: 0
-CPU1 (65,160):
- Reads Queued: 2,411, 38,576KiB Writes Queued: 769, 425,408KiB
- Read Dispatches: 2,407, 38,512KiB Write Dispatches: 118, 61,680KiB
- Reads Completed: 0, 0KiB Writes Completed: 0, 0KiB
- Read Merges: 0 Write Merges: 25,819
- IO unplugs: 0 Timer unplugs: 4
-CPU2 (65,160):
- Reads Queued: 2, 32KiB Writes Queued: 18, 10,528KiB
- Read Dispatches: 2, 32KiB Write Dispatches: 3, 1,344KiB
- Reads Completed: 0, 0KiB Writes Completed: 0, 0KiB
- Read Merges: 0 Write Merges: 640
- IO unplugs: 0 Timer unplugs: 0
-CPU3 (65,160):
- Reads Queued: 20,572, 329,152KiB Writes Queued: 594, 279,712KiB
- Read Dispatches: 20,576, 329,216KiB Write Dispatches: 1,474, 740,720KiB
- Reads Completed: 22,985, 367,760KiB Writes Completed: 1,390, 721,168KiB
- Read Merges: 0 Write Merges: 16,888
- IO unplugs: 0 Timer unplugs: 0
-
-Total (65,160):
- Reads Queued: 22,985, 367,760KiB Writes Queued: 1,390, 721,168KiB
- Read Dispatches: 22,985, 367,760KiB Write Dispatches: 1,595, 803,744KiB
- Reads Completed: 22,985, 367,760KiB Writes Completed: 1,390, 721,168KiB
- Read Merges: 0 Write Merges: 43,683
- IO unplugs: 0 Timer unplugs: 4
-...
-\end{verbatim}
-
-%----------------------------
-\newpage\section{\label{sec:blktrace-ug}blktrace User Guide}
-
-The \emph{blktrace} utility extracts event traces from the kernel (via
-the relay file system). Some background details concerning the run-time
-behaviour of blktrace will help to understand some of the more arcane
-command line options:
-
-\begin{itemize}
- \item blktrace receives data from the kernel in buffers passed up
- through the Relay file system (RelayFS). Each device being traced has
- a file created in the mounted directory for the RelayFS, which defaults
- to \emph{/relay} -- this can be overridden with the \emph{-r} command
- line argument.
-
- \item blktrace defaults to collecting \emph{all} events that can be
- traced. To limit the events being captured, you can specify one or
- more filter masks via the \emph{-a} option.
-
- Alternatively, one may specify the entire mask utilizing a hexadecimal
- value that is version-specific. (Requires understanding of the internal
- representation of the filter mask.)
-
- \item As noted above, the events are passed up via a series of buffers
- stored into RelayFS files. The size and number of buffers can be
- specified via the \emph{-b} and \emph{-n} arguments respectively.
-
- \item blktrace stores the extracted data into files stored in the
- \emph{local} directory. The format of the file names is (by default)
- \emph{device}.blktrace.\emph{cpu}, where \emph{device} is the base
- device name (e.g, if we are tracing /dev/sda, the base device name would
- be \emph{sda}); and \emph{cpu} identifies a CPU for the event stream.
-
- The \emph{device} portion of the event file name can be changed via
- the \emph{-o} option.
-
- \item blktrace may also be run concurrently with blkparse to produce
- \emph{live} output -- to do this specify \emph{-o -} for blktrace.
-
- \item The default behaviour for blktrace is to run forever until explicitly killed by the user (via a control-C, or \emph{kill} utility invocation). There are two ways to modify this:
-
- \begin{enumerate}
- \item You may utilize the blktrace utility itself to \emph{kill}
- a running trace -- via the \emph{-k} option.
-
- \item You can specify a run-time duration for blktrace via the
- \emph{-w} option -- then blktrace will run for the specified number
- of seconds, and then halt.
- \end{enumerate}
-\end{itemize}
-
-\subsection{\label{sec:blktrace-args}Command line arguments}
-\begin{tabular}{|l|l|l|}\hline
-Short & Long & Description \\ \hline\hline
--A \emph{hex-mask} & --set-mask=\emph{hex-mask} & Set filter mask to \emph{hex-mask} \\ \hline
--a \emph{mask} & --act-mask=\emph{mask} & Add \emph{mask} to current filter (see below for masks) \\ \hline
--b \emph{size} & --buffer-size=\emph{size} & Specifies buffer size for event extraction (scaled by $2^{10}$) \\ \hline
--d \emph{dev} & --dev=\emph{dev} & Adds \emph{dev} as a device to trace \\ \hline
--k & --kill & Kill on-going trace \\ \hline
--n \emph{num-sub} & --num-sub=\emph{num-sub} & Specifies number of buffers to use \\ \hline
--o \emph{file} & --output=\emph{file} & Prepend \emph{file} to output file name(s) \\ \hline
--r \emph{rel-path} & --relay=\emph{rel-path} & Specifies RelayFS mount point \\ \hline
--v & --version & Outputs version \\ \hline
--w \emph{seconds} & --stopwatch=\emph{seconds} & Sets run time to the number of seconds specified \\ \hline
-\end{tabular}
-
-\subsubsection{\label{sec:filter-mask}Filter Masks}
-The following masks may be passed with the \emph{-a} command line
-option, multiple filters may be combined via multiple \emph{-a} command
-line options.\smallskip
-
-\begin{tabular}{|l|l|}\hline
-barrier & \emph{barrier} attribute \\ \hline
-complete & \emph{completed} by driver \\ \hline
-fs & \emph{FS} requests \\ \hline
-issue & \emph{issued} to driver \\ \hline
-pc & \emph{packet command} events \\ \hline
-queue & \emph{queue} operations \\ \hline
-read & \emph{read} traces \\ \hline
-requeue & \emph{requeue} operations \\ \hline
-sync & \emph{synchronous} attribute \\ \hline
-write & \emph{write} traces \\ \hline
-\end{tabular}
-
-%----------------------------
-\newpage\section{\label{sec:blkparse-ug}blkparse User Guide}
-
-The \emph{blkparse} utility will attempt to combine streams of events
-for various devices on various CPUs, and produce a formatted output of
-the event information. As with blktrace, some details concerning blkparse
-will help in understanding the command line options presented below.
-
-\begin{itemize}
- \item By default, blkparse 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 \emph{may} be run in a \emph{live} manner concurrently with
- blktrace by specifying \emph{-i -} to blkparse, and combining it with
- the live option for blktrace. An example would be:
-
- \begin{verbatim}
- % blktrace -d /dev/sda -o - | blkparse -i -
- \end{verbatim}
-
- \item You can set how many blkparse batches event reads via the
- \emph{-b} option, the default is to handle events in batches of 512.
-
- \item If you have saved event traces in blktrace with different output
- names (via the \emph{-o} option to blktrace), you must specify the
- same \emph{input} name via the \emph{-i} option.
-
- \item The format of the output data can be controlled via the \emph{-f}
- or \emph{-F} options -- see section~\ref{sec:blkparse-format} for details.
-
- By default, blkparse sends formatted data to standard output. This
- may be changed via the \emph{-o} option.
-
-\end{itemize}
-
-\newpage\subsection{\label{sec:blkparse-args}Command line arguments}
-\begin{tabular}{|l|l|l|}\hline
-Short & Long & Description \\ \hline\hline
--b \emph{batch} & --batch={batch} & Standard input read batching \\ \hline
-
--i \emph{file} & --input=\emph{file} & Specifies base name for input files -- default is \emph{device}.blktrace.\emph{cpu}. \\
- & & As noted above, specifying \emph{-i -} runs in \emph{live} mode with blktrace \\
- & & (reading data from standard in). \\ \hline
-
--F \emph{typ,fmt} & --format=\emph{typ,fmt} & Sets output format \\
--f \emph{fmt} & --format-spec=\emph{fmt} & (See section~\ref{sec:blkparse-format} 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 \emph{typ} field is one of the \\
- & & action specifiers in section~\ref{sec:act-table} \\ \hline
-
-
--m & --missing & Print missing entries\\ \hline
-
--n & --hash-by-name & Hash processes by name, not by PID\\ \hline
-
--o \emph{file} & --output=\emph{file} & Output file \\ \hline
-
--q & --quiet & Quite mode \\ \hline
-
--s & --per-program-stats & Displays data sorted by program \\ \hline
-
--t & --track-ios & Display time deltas per IO \\ \hline
-
--w \emph{span} & --stopwatch=\emph{span} & Display traces for the \emph{span} specified -- where span can be: \\
- & & \emph{end-time} -- Display traces from time 0 through \emph{end-time} (in ns) \\
- & & or \\
- & & \emph{start:end-time} -- Display traces from time \emph{start} \\
- & & through {end-time} (in ns). \\ \hline
-
--v & --version & Display version \\ \hline
-
-\end{tabular}
-
-\newpage
-\subsection{\label{sec:blkparse-format}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:
-
-\smallskip
-\begin{tabular}{|l|l|}\hline
-Field & Description \\
-Specifier & \\ \hline\hline
-\emph{a} & Action, a (small) string (1 or 2 characters) -- see table below for more details \\ \hline
-\emph{c} & CPU id \\ \hline
-\emph{C} & Command \\ \hline
-\emph{d} & RWBS field, a (small) string (1-3 characters) -- see section below for more details \\ \hline
-\emph{D} & 7-character string containing the major and minor numbers of
-the event's device \\
- & (separated by a comma). \\ \hline
-\emph{e} & Error value \\ \hline
-\emph{m} & Minor number of event's device. \\ \hline
-\emph{M} & Major number of event's device. \\ \hline
-\emph{n} & Number of blocks \\ \hline
-\emph{N} & Number of bytes \\ \hline
-\emph{p} & Process ID \\ \hline
-\emph{P} & Display packet data -- series of hexadecimal values\\ \hline
-\emph{s} & Sequence numbers \\ \hline
-\emph{S} & Sector number \\ \hline
-\emph{t} & Time stamp (nanoseconds) \\ \hline
-\emph{T} & Time stamp (seconds) \\ \hline
-\emph{u} & Elapsed value in microseconds (\emph{-t} command line option) \\ \hline
-\emph{U} & Payload unsigned integer \\ \hline
-\end{tabular}
-
-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 specifer
-(-) 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:
-
-\begin{verbatim}
--f "%-12C"
-\end{verbatim}
-
-\newpage
-\subsubsection{\label{sec:act-table}Action Table}
-The following table shows the various actions which may be output.
-
-\begin{tabular}{|l|l|}\hline
-Act & Description \\ \hline\hline
-B & IO back merged with request on queue \\ \hline
-C & IO completion \\ \hline
-D & IO issued to driver \\ \hline
-F & IO front merged with request on queue \\ \hline
-G & Get request \\ \hline
-I & IO inserted onto request queue \\ \hline
-P & Plug request \\ \hline
-Q & IO handled by request queue code \\ \hline
-S & Sleep request \\ \hline
-T & Unplug due to timeout \\ \hline
-U & Unplug request \\ \hline
-W & IO bounced \\ \hline
-X & Split \\ \hline
-\end{tabular}
-
-\subsubsection{\label{sec:act-table}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).
-
-\subsubsection{\label{sec:default-output}Default output}
-
-The standard \emph{header} (or initial fields displayed) include:
-
-\begin{verbatim}
-"%D %2c %8s %5T.%9t %5p %2a %3d "
-\end{verbatim}
-
-Breaking this down:
-
-\begin{description}
- \item[\%D] Displays the event's device major/minor as: \%3d,\%-3d.
- \item[\%2c] CPU ID (2-character field).
- \item[\%8s] Sequence number
- \item[\%5T.\%9t] 5-charcter field for the seconds portion of the
- time stamp and a 9-character field for the nanoseconds in the time stamp.
- \item[\%5p] 5-character field for the process ID.
- \item[\%2a] 2-character field for one of the actions.
- \item[\%3d] 3-character field for the RWBS data.
-\end{description}
-
-Seeing this in action:
-
-\begin{verbatim}
- 8,0 3 1 0.000000000 697 G W 223490 + 8 [kjournald]
-\end{verbatim}
-
-The header is the data in this line up to the 223490 (starting block).
-
-The default output for all event types includes this header.
-
-\paragraph{Default output per action}
-
-\begin{description}
- \item[C -- complete] 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 \emph{-t} option
- was specified, then the elapsed time is presented. In either case,
- it is followed by the error value for the completion.
-
- \item[D -- issued]
- \item[I -- inserted]
- \item[Q -- queued]
- \item[W -- bounced] 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 \emph{-t} 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).
-
- \item[B -- back merge]
- \item[F -- front merge]
- \item[G -- get request]
- \item[M -- front or back merge]
- \item[S -- sleep] 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).
-
- \item[P -- plug] The command associated with the event (surrounded by
- square brackets) is output.
-
- \item[U -- unplug]
- \item[T -- unplug due to timer] The command associated with the event
- (surrounded by square brackets) is output, followed by the number of
- requests outstanding.
-
- \item[X -- split] 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).
-
-\end{description}
-
-%------------------------------
-\newpage
-\newpage\section*{\label{sec:blktrace-kg}Appendix: blktrace Kernel Guide}
-
-The blktrace facility provides an efficient event transfer mechanism which
-supplies block IO layer state transition data via the relay
-filesystem. This section provides some details as to the interfaces
-blktrace utilizes in the kernel to effect this. It is good background data
-to help understand some of the outputs and command-line options above.
-
-\subsection{blktrace.h Definitions}
-Files which include $<linux/blktrace.h>$ are supplied with the following
-definitions:
-
-\subsubsection{Trace Action Specifiers}
-\begin{tabular}{|l|l|}\hline
- BLK\_TA\_QUEUE & (RQ) Command queued to request\_queue. \\
- & (BIO) Command queued by elevator. \\ \hline
- BLK\_TA\_BACKMERGE & Back merging elevator operation \\ \hline
- BLK\_TA\_FRONTMERGE & Front merging elevator operation \\ \hline
- BLK\_TA\_GETRQ & Free request retrieved. \\ \hline
- BLK\_TA\_SLEEPRQ & No requests available, device unplugged. \\ \hline
- BLK\_TA\_REQUEUE & Request requeued. \\ \hline
- BLK\_TA\_ISSUE & Command set to driver for request\_queue. \\ \hline
- BLK\_TA\_COMPLETE & Command completed by driver. \\ \hline
- BLK\_TA\_PLUG & Device is plugged \\ \hline
- BLK\_TA\_UNPLUG\_IO & Unplug device as IO is made available. \\ \hline
- BLK\_TA\_UNPLUG\_TIMER & Unplug device after timer expired. \\ \hline
- BLK\_TA\_INSERT & Insert request into queue. \\ \hline
- BLK\_TA\_SPLIT & BIO split into 2 or more requests. \\ \hline
- BLK\_TA\_BOUNCE & BIO was bounced \\ \hline
-\end{tabular}
-
-%..........................................
-\subsection{blktrace.h Routines}
-Files which include $<linux/blktrace.h>$ are supplied with the following
-kernel routine invocable interfaces:
-
-\begin{description}
- \item[blk\_add\_trace\_rq(struct request\_queue *q, struct request\_queue
- *rq, u32 what)]
- Adds a trace event describing the state change of the passed in
- request\_queue. The \emph{what} parameter describes the change in
- the request\_queue state, and is one of the request queue action
- specifiers -- BLK\_TA\_QUEUE, BLK\_TA\_REQUEUE, BLK\_TA\_ISSUE,
- or BLK\_TA\_COMPLETE.
-
- \item[blk\_add\_trace\_bio(struct request\_queue *q, struct bio *bio,
- u32 what)]
- Adds a trace event for the BIO passed in. The \emph{what} parameter
- describes the action being performed on the BIO, and is one of
- BLK\_TA\_BACKMERGE, BLK\_TA\_FRONTMERGE, or BLK\_TA\_QUEUE.
-
- \item[blk\_add\_trace\_generic(struct request\_queue *q, struct bio *bio,
- int rw, u32 what)]
- Adds a \emph{generic} trace event -- not one of the request queue
- or BIO traces. The \emph{what} parameter describes the action being
- performed on the BIO (if bio is non-NULL), and is one of
- BLK\_TA\_PLUG, BLK\_TA\_GETRQ or BLK\_TA\_SLEEPRQ.
-
- \item[blk\_add\_trace\_pdu\_int(struct request\_queue *q, u32 what,
- u32 pdu)]
- Adds a trace with some payload data -- in this case, an unsigned
- 32-bit entity (the \emph{pdu} parameter). The \emph{what} parameter
- describes the nature of the payload, and is one of
- BLK\_TA\_UNPLUG\_IO or BLK\_TA\_UNPLUG\_TIMER.
-
-\end{description}
-\end{document}
projects / blktrace.git / commitdiff