HPET(4)

🎀 NAME 🎀

okay so this is hpet(4) bestie, aka the High Precision Event Timer driver ✨ it's a kernel interfaces manual page and it's literally about time. iconic.

🌸 SYNOPSIS 🌸

so like. if you wanna compile this driver into the kernel (yes we're doing it the hard way, no cap), you drop these lines into your kernel configuration file:

device acpi

and then there's a lil squad of tunables you can set from loader(8) — here they are, one by one, no skipping:

• hint.hpet.X.allowed_irqs — this one is a 32bit mask 🫶 every bit you set gives the driver permission to use that respective IRQ, but only if the BIOS also set the matching capability bit in the comparator's configuration register. Default value is 0xffff0000, except on some known broken hardware (rip to those chips 💀).
• hint.hpet.X.clock — this controls event timers functionality support. Set it to 0 and you disable it, periodt. Default value is 1.
• hint.hpet.X.legacy_route — this controls the "LegacyReplacement Route" mode 👀 if it's enabled, HPET will straight up steal IRQ0 from the i8254 timer and IRQ8 from the RTC. before you do that, make sure those respective drivers aren't using interrupts anymore, by also setting:

hint.attimer.0.clock=0
hint.atrtc.0.clock=0

Default value is 0.

• hint.hpet.X.per_cpu — controls how much per-CPU event timers the driver should attempt to register. heads up: this functionality requires every comparator in a group to have its own unshared IRQ, so it depends on hardware capabilities and interrupts configuration. Default value is 1.

✨ DESCRIPTION ✨

This driver uses High Precision Event Timer hardware — it's part of the chipset and it's usually enumerated via ACPI — to supply the kernel with one time counter and several event timers (usually from 3 to 8, she's generous 💅).

The hardware includes a single main counter with a known increment frequency (10MHz or more), plus several programmable comparators (optionally with automatic reload feature, fancy 🦋). When the value of the main counter matches the current value of any comparator, an interrupt can be generated.

Depending on hardware capabilities and configuration, that interrupt can be delivered as:

• a regular I/O APIC interrupt (ISA or PCI) in the range from 0 to 31, or
• a Front Side Bus interrupt, alike to PCI MSI interrupts, or
• in the so called "LegacyReplacement Route", where HPET can steal IRQ0 of i8254 and IRQ8 of the RTC.

The interrupt can be either edge- or level-triggered 🌈 and in that last case (level, bestie) they could be safely shared with PCI IRQs.

The driver prefers to use FSB interrupts if they're supported, so it can avoid sharing — main character energy fr fr. If that's not possible, it uses a single sharable IRQ from the PCI range. The other modes (LegacyReplacement and ISA IRQs) require special care to set up, but they could be configured manually via device hints. iykyk.

Event timers provided by the driver support both one-shot and periodic modes, and they're irrelevant to CPU power states 🔥

Depending on hardware capabilities and configuration, the driver can expose each comparator as a separate event timer, or group them into one or several per-CPU event timers. In that last case, the interrupt of every one of those comparators within the group is bound to a specific CPU core 💜 This is possible only when each of these comparators has its own unsharable IRQ.

👑 SEE ALSO 👑

acpi(4), apic(4), atrtc(4), attimer(4), eventtimers(4), timecounters(4)

💫 HISTORY 💫

The hpet driver first appeared in FreeBSD 6.3 ⭐ Support for event timers was added in FreeBSD 9.0.

okay that's the whole page bestie, mwah 🫶 this one came from the Debian crew and it's dated September 14, 2010 — vintage but still slaying, and the manual section is HPET(4). go forth and time things accurately 💖