1HWLATDETECT(8) System Manager's Manual HWLATDETECT(8)
2# SPDX-License-Identifier: GPL-2.0-only
6
8 hwlatdetect - program to control the ftrace kernel hardware latency de‐
9 tection
10
12 hwlatdetect [ --duration=<time> ] [--threshold=<usecs> ] [--win‐
13 dow=<time interval> ] [--width=<time interval> ] [--hardlimit=<mi‐
14 crosecond value> ] [--report=<path> ] [--debug ] [--quiet ] [--watch]
15
18 hwlatdetect is a program that controls the ftrace kernel hardware la‐
19 tency detector (hwlatdetector).hwlatdetector is used to detect large
20 system latencies induced by the behavior of certain underlying hardware
21 or firmware, independent of Linux itself. The code was developed orig‐
22 inally to detect SMIs (System Management Interrupts) on x86 systems,
23 however there is nothing x86 specific about it. It was originally
24 written for use by the "RT" patch set since the Real Time kernel is
25 highly latency sensitive.
26 SMIs are usually not serviced by the Linux kernel, which typically does
28 not even know that they are occurring. SMIs are instead are set up by
29 BIOS code and are serviced by BIOS code, usually for "critical" events
30 such as management of thermal sensors and fans. Sometimes though, SMIs
31 are used for other tasks and those tasks can spend an inordinate amount
32 of time in the handler (sometimes measured in milliseconds). Obviously
33 this is a problem if you are trying to keep event service latencies
34 down in the microsecond range.
35 The ftrace hardware latency detector works by hogging all of the cpus
37 for configurable amounts of time (by calling stop_machine()), polling
38 the CPU Time Stamp Counter for some period, then looking for gaps in
39 the TSC data. Any gap indicates a time when the polling was interrupted
40 and since the machine is stopped and interrupts turned off the only
41 thing that could do that would be an SMI.
42 The hwlatdetector script manages the mounting/unmounting of the debugfs
44 as well as interacting with the ftrace hwlatdetector If the debugfs is
45 already mounted then hwlatdetector will not unmount it after a run.
46
49 --duration=<time>{s,m,d}
50 Run the detector logic in for the specified duration. The dura‐
51 tion is a base 10 integer number that defaults to a value in
52 seconds. An optional suffix may be specified to indicate min‐
53 utes, hours or days.
54 --threshold=<microsecond value>
57 Specify the TSC gap used to detect an SMI. Any gap value greater
58 than <threshold> is considered to be the result of an SMI occur‐
59 ring.
60 --hardlimit=<microsecond value>
63 The test is considered to fail if a value above the hardlimit
64 occurs. This affects the exit value of hwlatdetect
65 --window=<time value>{us,ms,s,m,d}
68 specify the size of the sample window. Converted to microseconds
69 when passed to the kernel.
70 --width=<time value>{us,ms,s,m,d}
73 The amount of time within the sample window where the detector
74 is actually sampling. Must be less than the --window value.
75 --report=FILENAME
77 Specify the output filename of the detector report. Default be‐
78 havior is to print to standard output
79 --cpu-list=CPU-LIST
81 Specify the CPUs for hwlat thread to move across.
82 --debug
84 Turn on debug prints
85 --quiet
87 Turn off all information prints
88 --watch
90 print sample data to stdout as it arrives
91
94 hwlatdetect was written by Clark Williams <williams@redhat.com>
95 hwlat_detector.ko was written by Jon Masters <jcm@redhat.com>
96 May 12, 2009 HWLATDETECT(8)