\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}
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
\end{tabular}
\newpage
+\subsection{\label{sec:blkparse-actions}Trace actions}
+
+\begin{description}
+ \item[C -- complete] 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.
+
+ \item[D -- issued] A request that previously resided on the block layer
+ queue or in the io scheduler has been sent to the driver.
+
+ \item[I -- inserted] A request is being sent to the io scheduler for
+ addition to the internal queue and later service by the driver. The
+ request is fully formed at this time.
+
+ \item[Q -- queued] This notes intent to queue io at the given location.
+ No real requests exists yet.
+
+ \item[W -- bounced] The data pages attached to this \emph{bio} are
+ not reachable by the hardware and must be bounced to a lower memory
+ location. This causes a big slowdown in io performance, since the data
+ must be copied to/from kernel buffers. Usually this can be fixed with
+ using better hardware - either a better io controller, or a platform
+ with an IOMMU.
+
+ \item[B -- back merge] A previously inserted request exists that ends
+ on the boundary of where this io begins, so the io scheduler can merge
+ them together.
+
+ \item[F -- front merge] Same as the back merge, except this io ends
+ where a previously inserted requests starts.
+
+ \item[M -- front or back merge] One of the above.
+
+ \item[G -- get request] To send any type of request to a block device,
+ a \emph{struct request} container must be allocated first.
+
+ \item[S -- sleep] No available request structures were available, so
+ the issuer has to wait for one to be freed.
+
+ \item[P -- plug] When io 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.
+
+ \item[U -- unplug] 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.
+
+ \item[T -- unplug due to timer] If nobody requests the io that was queued
+ after plugging the queue, Linux will automatically unplug it after a
+ defined period has passed.
+
+ \item[X -- split] On raid or device mapper setups, an incoming io 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 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}
The output from blkparse can be tailored for specific use - in particular,
\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
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}
%------------------------------
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}
%..........................................
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}
projects / blktrace.git / blobdiff