.\"                                      Hey, EMACS: -*- nroff -*-
.TH HWLATDETECT 8 "May  12, 2009"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
hwlatdetect \- program to control the kernel hardware latency detection module
.SH SYNOPSIS
.B hwlatdetect
.RI "[ \-\-duration=<time> ] [\-\-threshold=<usecs> ] \
[\-\-window=<time interval> ] [\-\-width=<time interval> ] [\-\-report=<path> ] \
[\-\-cleanup ] [\-\-debug ] [\-\-quiet ] [--watch]

.\" .SH DESCRIPTION
.\" This manual page documents briefly the
.\" .B hwlatdetect commands.
.\" .PP
.\" \fI<whatever>\fP escape sequences to invoke bold face and italics, respectively.
.\" \fBhwlatdetect\fP is a program that...
.SH DESCRIPTION
\fBhwlatdetect\fP is a program that controls the kernel hardware
latency detector module (hwlat_detector.ko). The module is a special
purpose kernel module that is used to detect large system latencies
induced by the behavior of certain underlying hardware or firmware,
independent of Linux itself. The code was developed originally to
detect SMIs (System Management Interrupts) on x86 systems, however
there is nothing x86 specific about this patchset. It was originally
written for use by the "RT" patch since the Real Time kernel is highly
latency sensitive. 

SMIs are usually not serviced by the Linux kernel, which typically does not
even know that they are occurring. SMIs are instead are set up by BIOS code
and are serviced by BIOS code, usually for "critical" events such as
management of thermal sensors and fans. Sometimes though, SMIs are used for
other tasks and those tasks can spend an inordinate amount of time in the
handler (sometimes measured in milliseconds). Obviously this is a problem if
you are trying to keep event service latencies down in the microsecond range.

The hardware latency detector module works by hogging all of the cpus
for configurable amounts of time (by calling stop_machine()), polling
the CPU Time Stamp Counter for some period, then looking for gaps in
the TSC data. Any gap indicates a time when the polling was
interrupted and since the machine is stopped and interrupts turned off
the only thing that could do that would be an SMI. 

The hwlatdetector script manages the mounting/unmounting of the
debugfs as well as the loading/unloading of the hwlat_detector
module. If the debugfs is already mounted then hwlatdetector will not
unmount it after a run. Likewise, if the hwlat_detector module is
already loaded, it will not be unloaded after a run. 

.SH OPTIONS
.TP
.B \-\-duration=<time>{s,m,d}
Run the detector logic in for the specified duration. The duration is
a base 10 integer number that defaults to a value in seconds. An
optional suffix may be specified to indicate minutes, hours or days.

.TP
.B \-\-threshold=<microsecond value>
Specify the TSC gap used to detect an SMI. Any gap value greater than
<threshold> is considered to be the result of an SMI occurring. 

.TP
.B \-\-window=<time value>{us,ms,s,m,d}
specify the size of the sample window. Converted to microseconds when
passed to the kernel module.

.TP
.B \-\-width=<time value>{us,ms,s,m,d}
The amount of time within the sample window where the detector is
actually sampling. Must be less than the \-\-window value.
.TP
.B \-\-report=FILENAME
Specify the output filename of the detector report. Default
behavior is to print to standard output
.TP
.B \-\-cleanup
Force unload of hwlat_detector.ko and unmounting of debugfs filesystem.
.TP
.B \-\-debug
Turn on debug prints
.TP
.B \-\-quiet
Turn off all information prints
.TP
.B \-\-watch
print sample data to stdout as it arrives

.\" .SH SEE ALSO
.\" .BR bar (1),
.\" .BR baz (1).
.\" .br
.\" The programs are documented fully by
.\" .IR "The Rise and Fall of a Fooish Bar" ,
.\" available via the Info system.
.SH AUTHOR
.B hwlatdetect
was written by Clark Williams <williams@redhat.com>
.br
.B hwlat_detector.ko
was written by Jon Masters <jcm@redhat.com>