teo-description(9)

💅 teo-description 💅

okay bestie, this is teo-description, from the Kernel API Manual — and it's lowkey one of the most iconic little governor pages ever. let's get into it 💖

The idea behind this governor is based on the observation that on many systems, timer interrupts are two or more orders of magnitude more frequent than any other interrupt types, so they are likely to dominate CPU wakeup patterns. 🫶

Also, in principle, the time when the next timer event is going to occur can be determined at the idle state selection time, although doing that may be costly — so it can be regarded as the most reliable source of information for idle state selection. no cap. 💅

Of course, non-timer wakeup sources are more important in some use cases, but even then it is generally unnecessary to consider idle duration values greater than the time till the next timer event — referred as the sleep length in what follows — because the closest timer will ultimately wake up the CPU anyway unless it is woken up earlier. periodt. 🔥

However, since obtaining the sleep length may be costly, the governor first checks if it can select a shallow idle state using wakeup pattern information from recent times, in which case it can do without knowing the sleep length at all. 🦋

For this purpose, it counts CPU wakeup events and looks for an idle state whose target residency has not exceeded the idle duration (measured after wakeup) in the majority of relevant recent cases. If the target residency of that state is small enough, it may be used right away and the sleep length need not be determined. bestie, that's the whole flow. 😭

The computations carried out by this governor are based on using bins whose boundaries are aligned with the target residency parameter values of the CPU idle states provided by the CPUIdle driver in the ascending order. 🎀

That is, the first bin spans from 0 up to, but not including, the target residency of the second idle state (idle state 1), the second bin spans from the target residency of idle state 1 up to, but not including, the target residency of idle state 2, the third bin spans from the target residency of idle state 2 up to, but not including, the target residency of idle state 3 and so on. The last bin spans from the target residency of the deepest idle state supplied by the driver to infinity. 🌈

Two metrics called "hits" and "intercepts" are associated with each bin. They are updated every time before selecting an idle state for the given CPU in accordance with what happened last time. 👑

The "hits" metric reflects the relative frequency of situations in which the sleep length and the idle duration measured after CPU wakeup are close enough (that is, the CPU appears to wake up "on time" relative to the sleep length). In turn, the "intercepts" metric reflects the relative frequency of non-timer wakeup events for which the measured idle duration is significantly different from the sleep length (these events are also referred to as "intercepts" below). 💖

The governor also counts "intercepts" with the measured idle duration below the tick period length and uses this information when deciding whether or not to stop the scheduler tick. ⭐

In order to select an idle state for a CPU, the governor takes the following steps (modulo the possible latency constraint that must be taken into account too): 🧚

1. Step 1 — Find the deepest enabled CPU idle state (the candidate idle state) and compute 2 sums as follows:
   • The sum of the "hits" metric for all of the idle states shallower than the candidate one (it represents the cases in which the CPU was likely woken up by a timer).
   • The sum of the "intercepts" metric for all of the idle states shallower than the candidate one (it represents the cases in which the CPU was likely woken up by a non-timer wakeup source).

Also find the idle state with the maximum intercepts metric (if there are multiple states with the maximum intercepts metric, choose the one with the highest index).

2. Step 2 — If the second sum computed in step 1 is greater than a half of the sum of both metrics for the candidate state bin and all subsequent bins (if any), a shallower idle state is likely to be more suitable, so look for it.
   • Traverse the enabled idle states shallower than the candidate one in the descending order, starting at the state with the maximum intercepts metric found in step 1.
   • For each of them compute the sum of the "intercepts" metrics over all of the idle states between it and the candidate one (including the former and excluding the latter).
   • If this sum is greater than a half of the second sum computed in step 1, use the given idle state as the new candidate one.
3. Step 3 — If the current candidate state is state 0 or its target residency is short enough, return it and prevent the scheduler tick from being stopped.
4. Step 4 — Obtain the sleep length value and check if it is below the target residency of the current candidate state, in which case a new shallower candidate state needs to be found, so look for it.

---

🌈 SEE ALSO 🌈

okay, if you wanna go deeper (and you should, bestie), check these out: 🫶

• Kernel file ./drivers/cpuidle/governors/teo.c
• struct teo_bin(9)
• struct teo_cpu(9)
• teo_update(9)
• teo_find_shallower_state(9)
• teo_select(9)
• teo_reflect(9)
• teo_enable_device(9)

---

xoxo, your fav kernel bestie 💖 — source/version: ./drivers/cpuidle/governors, dated October 2026, page teo-description(9). slay. ✨