bionic (8) hwlatdetect.8.gz

NAME

       hwlatdetect - program to control the kernel hardware latency detection module

SYNOPSIS

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

DESCRIPTION

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

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.

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

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

       --cleanup
              Force unload of hwlat_detector.ko and unmounting of debugfs filesystem.

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