updated hwlatdetect.8 to reflect new options/behavior

1 files changed, 42 insertions, 21 deletions

diff --git a/src/hwlatdetect/hwlatdetect.8 b/src/hwlatdetect/hwlatdetect.8
index 0f1751e..c075cf3 100644
--- a/src/hwlatdetect/hwlatdetect.8
+++ b/src/hwlatdetect/hwlatdetect.8
@@ -13,11 +13,11 @@
 .\" .sp <n>    insert n+1 empty lines
 .\" for manpage-specific macros, see man(7)
 .SH NAME
-hwlatdetect \- program to control the kernel SMI detection module
+hwlatdetect \- program to control the kernel hardware latency detection module
 .SH SYNOPSIS
 .B hwlatdetect
 .RI "[ \-\-duration=<time> ] [\-\-threshold=<usecs> ] \
-[\-\-interval=<msecs> ] [\-\-sample_width=<msecs> ] [\-\-report=<path> ] \
+[\-\-window=<time interval> ] [\-\-width=<time interval> ] [\-\-report=<path> ] \
 [\-\-cleanup ] [\-\-debug ] [\-\-quiet ]
 
 .\" .SH DESCRIPTION
@@ -27,21 +27,40 @@ hwlatdetect \- program to control the kernel SMI detection module
 .\" \fI<whatever>\fP escape sequences to invode bold face and italics, respectively.
 .\" \fBhwlatdetect\fP is a program that...
 .SH DESCRIPTION
-\fBhwlatdetect\fP is a program that controls the SMI detector kernel
-module (smi_detector.ko), provided with a realtime Linux kernel. The
-module is used to detect the presence of System Management Interrupts
-(SMI) which in some cases cause unexplained latencies. SMIs are generally
-handled by BIOS code, not Linux kernel code and so cause unexpected
-gaps in time.
+\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. 
 
-The SMI kernel module runs a function that polls the TSC register
-under the \fBstop_machine()\fP kernel function, looking for gaps in
-time. Any gap that exceeds the specified input threshold is considered
-to be the result of an SMI.
+SMIs are usually not serviced by the Linux kernel, which typically does not
+even know that they are occuring. 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>[smhd]
+.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.
@@ -52,21 +71,21 @@ Specify the TSC gap used to detect an SMI. Any gap value greater than
 <theshold> is considered to be the result of an SMI occuring. 
 
 .TP
-.B \-\-interval=<millisecond value>
-specify the interval between sample windows in milliseconds
+.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 \-\-sample_width=<millisecond value>
-Specify the amount of time the kernel logic will run the detector
-function, as a millisecond value
-context switch tracing (used with \-b)
+.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 SMI detector report. Default
+Specify the output filename of the detector report. Default
 behavior is to print to standard output
 .TP
 .B \-\-cleanup
-Force unload of smi_detector.ko and unmounting of debugfs filesystem.
+Force unload of hwlat_detector.ko and unmounting of debugfs filesystem.
 .TP
 .B \-\-debug
 Turn on debug prints
@@ -83,3 +102,5 @@ Turn off all information prints
 .SH AUTHOR
 .B hwlatdetect
 .R was written by Clark Williams <williams@redhat.com>
+.B hwlat_detector.ko
+.R was written by Jon Masters <jcm@redhat.com>