TIMECOUNTERS(4)

💖 TIMECOUNTERS 💖

ok so bestie, welcome to timecounters(4) — it's a page from the Kernel Interfaces Manual, section 4, and it's literally all about how your kernel keeps track of time. sit down, grab a boba, we're doing this 🧋✨

✨ SYNOPSIS ✨

so the kernel uses a bunch of different time-related devices, right? like:

• real time clocks — these track real world time, mostly when the system is down 💀
• time counters — these do the tracking when the system is running 👑
• event timers — these generate interrupts at a specified time or periodically, to run different time-based events ⏰

and this whole page? it's about the second one. time counters. the main character. periodt 💅

🌸 DESCRIPTION 🌸

Time counters are the lowest level of time tracking in the kernel. no cap. they give you monotonically increasing timestamps with known width and update frequency. that's the vibe.

but bestie, listen — they can overflow, they can drift, etc. so in raw form they can only be used in very limited performance-critical places, like the process scheduler. it's giving "don't touch this unless you know what you're doing" 😭

more usable time gets created by scaling the values read from the selected time counter and combining it with some offset, regularly updated by tc_windup() on hardclock() invocation. iconic behaviour honestly.

Different platforms provide different kinds of timer hardware. and the whole goal of the time counters subsystem is to provide a unified way to access that hardware. slay 🦋

Each driver implementing time counters registers them with the subsystem. and you can literally see the list of present time counters via the kern.timecounter sysctl(8) variable:

kern.timecounter.choice: TSC-low(-100) HPET(950) i8254(0) ACPI-fast(900) dummy(-1000000)
kern.timecounter.tc.ACPI-fast.mask: 16777215
kern.timecounter.tc.ACPI-fast.counter: 13467909
kern.timecounter.tc.ACPI-fast.frequency: 3579545
kern.timecounter.tc.ACPI-fast.quality: 900
kern.timecounter.tc.i8254.mask: 65535
kern.timecounter.tc.i8254.counter: 62692
kern.timecounter.tc.i8254.frequency: 1193182
kern.timecounter.tc.i8254.quality: 0
kern.timecounter.tc.HPET.mask: 4294967295
kern.timecounter.tc.HPET.counter: 3013495652
kern.timecounter.tc.HPET.frequency: 14318180
kern.timecounter.tc.HPET.quality: 950
kern.timecounter.tc.TSC-low.mask: 4294967295
kern.timecounter.tc.TSC-low.counter: 4067509463
kern.timecounter.tc.TSC-low.frequency: 11458556
kern.timecounter.tc.TSC-low.quality: -100

🎀 the output nodes, explained 🎀

The output nodes are defined as follows:

• kern.timecounter.tc.X.mask — it's a bitmask, defining valid counter bits 🌈
• kern.timecounter.tc.X.counter — it's a present counter value ⭐
• kern.timecounter.tc.X.frequency — it's a counter update frequency 🔥
• kern.timecounter.tc.X.quality — it's an integral value, defining the quality of this time counter compared to others. a negative value means this time counter is broken and should not be used 💀

The time management code of the kernel automatically switches to a higher-quality time counter when it registers — unless the kern.timecounter.hardware sysctl has been used to choose a specific device. so like, it picks for you, but you can override it if you're feeling spicy 💅

⚠️ ok serious moment bestie: there is no way to unregister a time counter once it has registered with the kernel. none. zero. nope. If a dynamically loaded module contains a time counter you will not be able to unload that module, even if the time counter it contains is not the one currently in use. that's just how it is 🙈

🌈 SEE ALSO 🌈

• attimer(4)
• eventtimers(4)
• ffclock(4)
• hpet(4)

that's the whole page bestie, you ate it, go forth and understand your kernel's clock vibe ✨🫶

Debian — August 12, 2015 — TIMECOUNTERS(4) 💜