NAME

       hwlatdetect - program to control the ftrace kernel hardware latency detection

SYNOPSIS

       hwlatdetect  [  --duration=<time>  ]  [--threshold=<usecs>  ]  [--window=<time interval> ] [--width=<time
       interval> ] [--hardlimit=<microsecond value> ] [--report=<path> ] [--debug ] [--quiet ] [--watch]

DESCRIPTION

       hwlatdetect   is   a   program   that   controls   the   ftrace   kernel   hardware   latency    detector
       (hwlatdetector).hwlatdetector 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
       it.  It was originally written for use by the "RT" patch set 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  ftrace  hardware  latency detector 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 interacting with the
       ftrace hwlatdetector If the debugfs is already mounted then hwlatdetector will not  unmount  it  after  a
       run.

OPTIONS

       --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.

       --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.

       --hardlimit=<microsecond value>
              The test is considered to fail if a value above the hardlimit occurs.  This affects the exit value
              of hwlatdetect

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

       --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.

       --report=FILENAME
              Specify the output filename of the detector report. Default  behavior  is  to  print  to  standard
              output

       --cpu-list=CPU-LIST
              Specify the CPUs for hwlat thread to move across.

       --debug
              Turn on debug prints

       --quiet
              Turn off all information prints

       --watch
              print sample data to stdout as it arrives

AUTHOR

       hwlatdetect was written by Clark Williams <williams@redhat.com>
       hwlat_detector.ko was written by Jon Masters <jcm@redhat.com>

                                                  May  12, 2009                                   HWLATDETECT(8)