EVENTTIMERS(4)

🌸 EVENTTIMERS — kernel event timers subsystem 💖

ok so bestie, welcome to eventtimers(4), the page about the kernel's event timer subsystem. it's giving clock girl summer ✨

✨ SYNOPSIS ✨

okay so here's the tea 🫖 the kernel uses a few different flavors of time-related devices, and you gotta know the difference or you'll be lost:

• real time clocks — these are the ones responsible for tracking real world time, mostly when the system is down. like, they keep the receipts while everyone's asleep 💤
• time counters — these are responsible for generation of monotonically increasing timestamps for precise uptime tracking purposes, when the system is running. monotonic, no cap 📈
• event timers — these are responsible for generating interrupts at specified time or periodically, to run different time-based events. the moment-makers, the schedulers, the ✨main characters✨

and this page? this page is about the last one. event timers. periodt. 💅

🎀 DESCRIPTION 🎀

the kernel uses time-based events for so many different purposes: scheduling, statistics, time keeping, profiling and many other things — all based on the callout(9) mechanism. it's a whole ecosystem fr fr 🦋

these purposes now grouped into three main callbacks:

• hardclock() — callout(9) and timekeeping events entry. called with frequency defined by hz variable, usually 1000Hz. she's the backbone, the moment you wake up and check the group chat 🔥
• statclock() — statistics and scheduler events entry. called with frequency about 128Hz. the girl who keeps the notes 📝
• profclock() — profiler events entry. when enabled, called with frequency about 8KHz. only shows up when you're doing the deep analysis, iykyk 👑

different platforms provide different kinds of timer hardware. the goal of the event timers subsystem is to provide a unified way to control that hardware, and to use it, supplying the kernel with all required time-based events. one interface to rule them all, lowkey iconic 🌈

each driver implementing event timers registers them at the subsystem. and you can see the list of present event timers, like this, via kern.eventtimer sysctl:

kern.eventtimer.choice: HPET(550) LAPIC(400) i8254(100) RTC(0)
kern.eventtimer.et.LAPIC.flags: 15
kern.eventtimer.et.LAPIC.frequency: 0
kern.eventtimer.et.LAPIC.quality: 400
kern.eventtimer.et.i8254.flags: 1
kern.eventtimer.et.i8254.frequency: 1193182
kern.eventtimer.et.i8254.quality: 100
kern.eventtimer.et.RTC.flags: 17
kern.eventtimer.et.RTC.frequency: 32768
kern.eventtimer.et.RTC.quality: 0
kern.eventtimer.et.HPET.flags: 7
kern.eventtimer.et.HPET.frequency: 14318180
kern.eventtimer.et.HPET.quality: 550

where, bestie:

• kern.eventtimer.et.X.flags is a bitmask, defining event timer capabilities:
  • 1 — periodic mode supported,
  • 2 — one-shot mode supported,
  • 4 — timer is per-CPU,
  • 8 — timer may stop when CPU goes to sleep state,
  • 16 — timer supports only power-of-2 divisors.
• kern.eventtimer.et.X.frequency is a timer base frequency,
• kern.eventtimer.et.X.quality is an integral value, defining how good is this timer, comparing to others. the vibe check score, basically ⭐

timers management code of the kernel chooses one timer from that list. current choice can be read and affected via kern.eventtimer.timer tunable/sysctl. and several other tunables/sysctls are affecting how exactly this timer is used:

• kern.eventtimer.periodic — allows to choose periodic and one-shot operation mode. in periodic mode, periodic interrupts from timer hardware are taken as the only source of time for time events. one-shot mode instead uses currently selected time counter to precisely schedule all needed events and programs event timer to generate interrupt exactly in specified time. default value depends of chosen timer capabilities, but one-shot mode is preferred, until other is forced by user or hardware. she has range, she has precision 💜
• kern.eventtimer.singlemul — in periodic mode specifies how much times higher timer frequency should be, to not strictly alias hardclock() and statclock() events. default values are 1, 2 or 4, depending on configured HZ value. no aliasing allowed, we're keeping them separated 🙈
• kern.eventtimer.idletick — makes each CPU to receive every timer interrupt independently of whether they busy or not. by default this options is disabled. if chosen timer is per-CPU and runs in periodic mode, this option has no effect - all interrupts are always generating.

⚠️ okay but real talk: by default kern.eventtimer.idletick is disabled. and if the chosen timer is per-CPU and runs in periodic mode, that option has no effect — all interrupts are always generating anyway. don't come for me, that's just the facts 💀

🌸 SEE ALSO 🌸

apic(4), atrtc(4), attimer(4), hpet(4), timecounters(4), eventtimers(9)

and that's the whole page bestie, you ate it up 🎀 this one came to you from Debian, dated March 13, 2012 — like, vintage but still serving 💖 go forth and schedule your interrupts, queen 👑💅