CPUFREQ(4)

💖 CPUFREQ 💖

okay bestie, welcome to cpufreq(4), from the Kernel Interfaces Manual — it's the CPU frequency control framework and it's literally the main character of power management, no cap. 🌈

---

🎀 NAME 🎀

cpufreq — CPU frequency control framework ✨

---

🌸 SYNOPSIS 🌸

device cpufreq

#include <sys/cpu.h>

int
cpufreq_levels(device_t dev, struct cf_level *levels, int *count);

int
cpufreq_set(device_t dev, const struct cf_level *level, int priority);

int
cpufreq_get(device_t dev, struct cf_level *level);

int
cpufreq_drv_settings(device_t dev, struct cf_setting *sets, int *count);

int
cpufreq_drv_type(device_t dev, int *type);

int
cpufreq_drv_set(device_t dev, const struct cf_setting *set);

int
cpufreq_drv_get(device_t dev, struct cf_setting *set);

---

🦋 DESCRIPTION 🦋

So the cpufreq driver is giving unified kernel + user interface for CPU frequency control drivers, and honestly? iconic. 💅 It takes multiple drivers that each offer different settings and smushes them together into one single interface of all possible levels — like a group chat for frequency settings, except everyone actually gets along.

You can reach this interface in two ways, bestie:

• directly via sysctl(8) 👑
• or by telling /etc/rc.d/power_profile that it should switch settings whenever the AC line state changes, via rc.conf(5) 🔌

---

⭐ SYSCTL VARIABLES ⭐

quick heads up before we dive in: these settings may be overridden by kernel drivers that are requesting alternate settings. And when that happens? the original values get restored once the condition has passed (think: the system has cooled down enough, she's fine now 🧊). And if a sysctl can't be set because of an override condition, it returns EPERM. rude but valid.

💀 IMPORTANT: the frequency cannot be changed if TSC is in use as the timecounter. Why? because the timecounter system needs a source with a constant rate, periodt. You can switch the timecounter source with the kern.timecounter.hardware sysctl, and the available modes live in the kern.timecounter.choice sysctl entry. go look, iykyk.

here's the whole roster 🫶:

• dev.cpu.%d.freq — current active CPU frequency, in MHz. the now-now.
• dev.cpu.%d.freq_levels — the levels currently available for the CPU, shown as frequency/power usage. values are in units of MHz and milliwatts. ✨
• dev.DEVICE.%d.freq_settings — the settings currently available for the driver, also frequency/power usage, also MHz and milliwatts. this one is super helpful for figuring out which settings are offered by which driver — debugging queen behavior 🐛👑
• debug.cpufreq.lowest — the lowest CPU frequency, in MHz, to offer to users. this setting is also reachable via a tunable with the same name. use it to disable those very low levels that may be unusable on some systems 🙈
• debug.cpufreq.verbose — print verbose messages. also accessible via a tunable with the same name. she's chatty 💬

---

🔥 SUPPORTED DRIVERS 🔥

absolute frequency control

these device drivers offer absolute frequency control through the cpufreq interface. usually only one of them can be active at a time, so no drama:

• acpi_perf — ACPI CPU performance states
• est — Intel Enhanced SpeedStep
• ichss — Intel SpeedStep for ICH
• powernow — AMD PowerNow! and Cool'n'Quiet for K7 and K8
• smist — Intel SMI-based SpeedStep for PIIX4

relative frequency control

these ones offer relative frequency control and have an additive effect (they stack, bestie, they're a team 💞):

• acpi_throttle — ACPI CPU throttling
• p4tcc — Pentium 4 Thermal Control Circuitry

---

💜 KERNEL INTERFACE 💜

kernel components can query and set CPU frequencies through the cpufreq kernel interface. the whole ritual goes like this:

1. obtain a cpufreq device
2. call cpufreq_levels() to get the currently available frequency levels
3. check the current level with cpufreq_get()
4. set a new one from the list with cpufreq_set()

each level may actually reference more than one cpufreq driver — but kernel components do not need to be aware of that, bless. the total_set element of struct cf_level gives you a summary of the frequency and power for that level. unknown or irrelevant values are set to CPUFREQ_VAL_UNKNOWN. 🫥

---

cpufreq_levels()

takes a cpufreq device and an empty array of levels. the count value should be set to the number of levels available, and once the function completes it'll be set to the actual number of levels returned. if there are more levels than count will allow? it should return E2BIG. too much, she said. 😭

cpufreq_get()

takes a pointer to space where a level can be stored. after a successful completion, the output is the current active level — and it's equal to one of the levels that cpufreq_levels() returned. matching, as she should. ✨

cpufreq_set()

takes a pointer to a level and attempts to activate it. the priority (i.e., CPUFREQ_PRIO_KERN) tells cpufreq whether to override previous settings while activating this level.

• if priority is higher than the current active level, that level gets saved and overridden with the new level 💾
• if a level is already saved, the new level is set without overwriting the older saved level
• if cpufreq_set() is called with a NULL level, the saved level gets restored 🫶
• if there's no saved level, cpufreq_set() returns ENXIO
• if priority is lower than the current active level's priority, this method returns EPERM

---

🌟 DRIVER INTERFACE 🌟

kernel drivers that offer hardware-specific CPU frequency control export their individual settings through the cpufreq driver interface. to do that, they implement these methods: cpufreq_drv_settings(), cpufreq_drv_type(), cpufreq_drv_set(), and cpufreq_drv_get(). on top of that, the driver must attach a device as a child of a CPU device so that the cpufreq framework can call these methods. no attaching, no calling, that's the rule 📎

---

cpufreq_drv_settings()

returns an array of currently available settings, each one of type struct cf_setting. the driver should set unknown or irrelevant values to CPUFREQ_VAL_UNKNOWN. all of the following elements for each setting should be returned:

struct cf_setting {
        int     freq;   /* CPU clock in MHz or 100ths of a percent. */
        int     volts;  /* Voltage in mV. */
        int     power;  /* Power consumed in mW. */
        int     lat;    /* Transition latency in us. */
        device_t dev;   /* Driver providing this setting. */
};

on entry to this method, count contains the number of settings that can be returned. on successful completion, the driver sets it to the actual number of settings returned. if the driver offers more settings than count will allow, it should return E2BIG. (again. she's overflowing. 💀)

cpufreq_drv_type()

indicates the type of settings the driver offers — either CPUFREQ_TYPE_ABSOLUTE or CPUFREQ_TYPE_RELATIVE. additionally, the driver may set the CPUFREQ_FLAG_INFO_ONLY flag if the settings it provides are information for other drivers only and cannot be passed to cpufreq_drv_set() to activate them. look, don't touch, got it 🙅‍♀️

cpufreq_drv_set()

takes a driver setting and makes it active. if the setting is invalid or not currently available, it should return EINVAL. bestie said no. 🚫

cpufreq_drv_get()

returns the currently-active driver setting. the struct cf_setting returned must be valid for passing to cpufreq_drv_set(), and that includes all elements being filled out correctly. if the driver cannot infer the current setting — even by estimating it with cpu_est_clockrate() — then it should set all elements to CPUFREQ_VAL_UNKNOWN. shrug emoji, we tried. 🤷‍♀️

---

🌈 SEE ALSO 🌈

acpi(4), est(4), timecounters(4), powerd(8), sysctl(8)

---

👑 AUTHORS 👑

• Nate Lawson
• Bruno Ducrot contributed the powernow driver. 🫡

---

💀 BUGS 💀

the tea, and it's lukewarm:

• the following drivers have not yet been converted to the cpufreq interface: longrun(4). girl is still stuck in the old era 😭
• notification of CPU and bus frequency changes is not implemented yet. she doesn't text back. 📵
• when multiple CPUs offer frequency control, they cannot be set to different levels and must all offer the same frequency settings. matching outfits only, no exceptions 👯‍♀️

---

and that's the whole page, bestie 🎀 this was the cpufreq(4) manual from Debian, dated March 3, 2006 — yes she's vintage and she still ate 💅 stay cool, stay clocked, and go touch some sysctl ✨🦋💖