Merge branch 'master' of ssh://axboe@router.home.kernel.dk/data/git/blktrace

[blktrace.git] / doc / blktrace.tex

diff --git a/doc/blktrace.tex b/doc/blktrace.tex
index fa18faec7566338026d25b1618cc69ecab532444..0ebbdd302f471076c02c1513ff44b7dafc38cfc3 100644 (file)
--- a/doc/blktrace.tex
+++ b/doc/blktrace.tex
@@ -66,7 +66,7 @@ As noted above, the kernel patch along with the blktrace and blkparse utilities
 \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
+% git checkout
 \end{verbatim}
 
 \subsection{\label{sec:patching}Patching and configuring the Linux kernel}
@@ -181,6 +181,40 @@ Total (8,0):
 Events (8,0): 89 entries, 0 skips
 \end{verbatim}
 
+A \emph{btrace} script is included in the distribution to ease live
+tracing of devices. The above could also be accomplished by issuing:
+
+\begin{verbatim}
+% btrace /dev/sda
+\end{verbatim}
+
+By default, \emph{btrace} runs the trace in quiet mode so it will not
+include statistics when you break the run. Add the \emph{-S} option to
+get that dumped as well.
+
+\subsection{\label{sec:pc-blktrace}blktrace -- SCSI commands}
+
+The previous section showed typical file system io actions, but blktrace
+can also show SCSI commands going in and out of the queue as submitted
+by applications using the SCSI Generic (\emph{sg}) interface.
+
+\begin{verbatim}
+% btrace /dev/cdrom
+[...]
+  3,0    0       25     0.004884107 13528  G   R 0 + 0 [inquiry]
+  3,0    0       26     0.004890361 13528  I   R 56 (12 00 00 00 38 ..) [inquiry]
+  3,0    0       27     0.004891223 13528  P   R [inquiry]
+  3,0    0       28     0.004893250 13528  D   R 56 (12 00 00 00 38 ..) [inquiry]
+  3,0    0       29     0.005344910     0  C   R (12 00 00 00 38 ..) [0]
+\end{verbatim}
+
+Here we see a program issuing an INQUIRY command to the CDROM device.
+The program requested a read of 56 bytes of data, the CDB is included
+in parenthesis after the data length. The completion event shows shows
+that the command completed successfully. Tracing SCSI commands can be
+very useful for debugging problems with programs talking directly to the
+device. An example of that would be \emph{cdrecord} burning.
+
 \subsection{\label{sec:blktrace-post}blktrace -- post-processing}
 
 Another way to run blktrace is to have blktrace save data away for later
@@ -527,6 +561,10 @@ Short              & Long                       & Description \\ \hline\hline
   normal boundary conditions. dm is notably bad at this and will clone
   lots of io.
 
+  \item[A -- remap] For stacked devices, incoming io is remapped to device
+  below it in the io stack. The remap action details what exactly is
+  being remapped to what.
+
 \end{description}
 
 \subsection{\label{sec:blkparse-format}Output Description and Formatting}
@@ -578,6 +616,7 @@ The following table shows the various actions which may be output.
 
 \begin{tabular}{|l|l|}\hline
 Act & Description \\ \hline\hline
+A & IO was remapped to a different device \\ \hline
 B & IO back merged with request on queue \\ \hline
 C & IO completion \\ \hline
 D & IO issued to driver \\ \hline
@@ -672,6 +711,9 @@ The default output for all event types includes this header.
   sector (separated by a slash (/) is output, followed by the command
   associated with the event (surrounded by square brackets).
 
+  \item[A -- remap] Sector and length is output, along with the original
+  device and sector offset.
+
 \end{description}
 
 %------------------------------
@@ -705,6 +747,7 @@ definitions:
   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
+  BLK\_TA\_REMAP & BIO was remapped \\ \hline
 \end{tabular}
 
 %..........................................
@@ -741,5 +784,11 @@ kernel routine invocable interfaces:
        describes the nature of the payload, and is one of
        BLK\_TA\_UNPLUG\_IO or BLK\_TA\_UNPLUG\_TIMER.
 
+  \item[blk\_add\_trace\_remap(struct request\_queue *q, struct bio  *bio,
+                                               dev\_t dev, sector\_t sector)]
+       Adds a trace with a remap event. \emph{dev} and \emph{sector} denote
+       the original device this \emph{bio} was mapped from.
+
+
 \end{description}
 \end{document}