HWLATDETECT(8)

📦
version 2.11 · 3 versions
, in arch rolling, centos-stream 10, centos-stream 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu resolute, ubuntu stonking

💅 hwlatdetect(8) — bestie edition ✨

okay so this is the man page for hwlatdetect, living in the System Manager's Manual section 8. if you've ever been like "why is my box stuttering for no reason", this little icon is gonna be your new obsession 🫶

# SPDX-License-Identifier: GPL-2.0-only — yes ma'am, license line present and accounted for 💖

🌸 NAME 🌸

hwlatdetect — the program that controls the ftrace kernel hardware latency detection. it's giving "latency detector wrangler", no cap.

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

so hwlatdetect is the program that drives the ftrace kernel hardware latency detector, aka hwlatdetector. and what does that thing do? it hunts down big system latencies caused by how certain hardware or firmware underneath behaves — and it does this independently of Linux itself. like, Linux is just vibing, and the hardware is out here doing its own thing 🙈

the code was originally built to catch SMIs (System Management Interrupts) on x86 systems, but fr fr there is nothing x86 specific about it. it was originally written for use by the "RT" patch set, because the Real Time kernel is extremely latency sensitive — main character energy, cannot be late to anything 💅

now, SMIs are usually not serviced by the Linux kernel, which typically doesn't even know they're happening. nope. SMIs get set up by BIOS code and are serviced by BIOS code, usually for "critical" events like managing thermal sensors and fans. but sometimes SMIs get used for other tasks, and those tasks can spend an inordinate amount of time in the handler (sometimes measured in milliseconds 😭). obviously that's a whole problem if you're trying to keep event service latencies down in the microsecond range. like, girl. microseconds vs milliseconds is not the same vibe at all.

so how does the ftrace hardware latency detector actually work? it hogs all of the cpus for configurable amounts of time (by calling stop_machine()), polls the CPU Time Stamp Counter for some period, then looks for gaps in the TSC data. any gap = a time when the polling got interrupted. and since the machine is stopped and interrupts are turned off, the only thing that could possibly do that would be an SMI. periodt. 🔥

and the hwlatdetector script manages the mounting/unmounting of the debugfs as well as interacting with the ftrace hwlatdetector. quick note bestie: if the debugfs is already mounted, then hwlatdetector will not unmount it after a run. it's respectful like that ✨

🎀 OPTIONS 🎀

  • --duration=<time>{s,m,d} — runs the detector logic for the duration you specify. the duration is a base 10 integer, and it defaults to a value in seconds. you can slap on an optional suffix to say minutes, hours or days instead. so flexible, we love her 💖
  • --threshold=<microsecond value> — sets the TSC gap used to detect an SMI. any gap value greater than <threshold> gets considered to be the result of an SMI occurring. that's the whole point, bestie.
  • --hardlimit=<microsecond value> — the test is considered to fail if a value above the hardlimit occurs. and yes, this affects the exit value of hwlatdetect. so if you're scripting this, pay attention 👀
  • --window=<time value>{us,ms,s,m,d} — specifies the size of the sample window. it gets converted to microseconds when passed to the kernel.
  • --width=<time value>{us,ms,s,m,d} — how much time within the sample window the detector is actually sampling. and here's the rule: it must be less than the --window value. no exceptions, no negotiating 💅
  • --report=FILENAME — specify the output filename of the detector report. default behavior is to print to standard output, which is honestly fine most of the time.
  • --cpu-list=CPU-LIST — specify the CPUs for the hwlat thread to move across. yes she travels 🧚
  • --debug — turn on debug prints. chaotic but useful.
  • --quiet — turn off all information prints. shhh 🤫
  • --watch — print sample data to stdout as it arrives. live footage, we're watching it happen 🌈

👑 AUTHOR 👑

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

and that's the whole page, bestie! this one came from the System Manager's Manual, dated May 12, 2009 — shoutout to the HWLATDETECT(8) era, vintage but still slaying ⭐💜

📦 where this page comes from