X86_ENERGY_PERF_POLICY(8)

💖 x86_energy_perf_policy(8) — like, the whole vibe 💖

okay bestie, sit down, hydrate, and let me tell you about x86_energy_perf_policy from the System Manager's Manual, section 8. it's the little tool that decides whether your CPU is in its study era or its nap era. and yes, it's giving main character energy. 🦋

---

✨ NAME ✨

x86_energy_perf_policy — Manage Energy vs. Performance Policy

---

🌸 SYNOPSIS 🌸

x86_energy_perf_policy [ options ] [ scope ] [field  value]
scope: --cpu cpu-list | --pkg pkg-list
cpu-list, pkg-list: # | #,# | #-# | all
field: --all | --epb | --hwp-epp | --hwp-min | --hwp-max | --hwp-desired
other: (--force | --hwp-enable | --turbo-enable)  value)
soc-slider: --soc-slider-balance # | --soc-slider-offset # | --platform-profile <name>
value: # | default | performance | balance-performance | balance-power | power

---

🎀 DESCRIPTION 🎀

so x86_energy_perf_policy displays and updates energy-performance policy settings that are specific to Intel Architecture Processors. 💅

it summarizes the settings that live in standard Linux interfaces (eg. cpufreq), and it also decodes the underlying Model Specific Register (MSRs). and like… yes, it can manage energy-performance policy using only MSR access, but it prefers the standard Linux kernel interfaces whenever those are available. it's polite like that. 🫶

---

🧚 BACKGROUND 🧚

the policy in MSR_IA32_ENERGY_PERF_BIAS (EPB) can affect a whole range of hardware decisions — like how aggressively the hardware enters and exits CPU idle states (C-states) and Processor Performance States (P-states). 🔥

heads up bestie: this policy hint does not replace explicit OS C-state and P-state selection. it just tells the hardware how aggressively to implement those selections. periodt.

plus, it lets the OS influence energy/performance trade-offs in places where there's no software interface at all — like in the opportunistic "turbo-mode" P-state range. 👑

and here's the tea: MSR_IA32_ENERGY_PERF_BIAS is defined per CPU, but some implementations share a single MSR among all CPUs in each processor package. on those systems, a write to EPB on one processor will be visible — and will have an effect — on all CPUs in the same processor package. no cap. 😭

Hardware P-States (HWP) are basically an expansion of hardware P-state control, going from just the opportunistic turbo-mode P-state range to the entire range of available P-states. on Broadwell Xeon, the initial HWP implementation, EPB influenced HWP. that influence was removed in subsequent generations, where it got moved to the Energy_Performance_Preference (EPP) field in a pair of dedicated MSRs — MSR_IA32_HWP_REQUEST and MSR_IA32_HWP_REQUEST_PKG. glow-up honestly. ✨

EPP is the most commonly managed knob in HWP mode, but MSR_IA32_HWP_REQUEST also lets the user specify minimum-frequency for Quality-of-Service, and maximum-frequency for power-capping. MSR_IA32_HWP_REQUEST is defined per-CPU.

MSR_IA32_HWP_REQUEST_PKG has the same capability as MSR_IA32_HWP_REQUEST, but it can simultaneously set the default policy for all CPUs within a package. a bit in per-CPU MSR_IA32_HWP_REQUEST indicates whether it is over-ruled-by or exempt-from MSR_IA32_HWP_REQUEST_PKG.

MSR_HWP_CAPABILITIES shows the default values for the fields in MSR_IA32_HWP_REQUEST. it gets displayed when no values are being written. 🎀

⭐ SCOPE OPTIONS ⭐

• -c, --cpu — operate on the MSR_IA32_HWP_REQUEST for each CPU in a CPU-list. the CPU-list may be comma-separated CPU numbers, with a dash for range, or the string "all". eg. '--cpu 1,4,6-8' or '--cpu all'. when --cpu is used, --hwp-use-pkg becomes available, which specifies whether the per-cpu MSR_IA32_HWP_REQUEST should be over-ruled by MSR_IA32_HWP_REQUEST_PKG (1), or exempt from MSR_IA32_HWP_REQUEST_PKG (0). 🦋
• -p, --pkg — operate on the MSR_IA32_HWP_REQUEST_PKG for each package in the package-list. the list is a string of individual package numbers separated by commas, and/or ranges of package numbers separated by a dash, or the string "all". for example '--pkg 1,3' or '--pkg all'. 💜

🌈 VALUE OPTIONS 🌈

• normal | default — set a policy with a normal balance between performance and energy efficiency. the processor will tolerate minor performance compromise for potentially significant energy savings. this is a reasonable default for most desktops and servers. "default" is a synonym for "normal". 🍓
• performance — set a policy for maximum performance, accepting no performance sacrifice for the benefit of energy efficiency. it's in its grind era. 🔥
• balance-performance — set a policy with a high priority on performance, but allowing some performance loss to benefit energy efficiency.
• balance-power — set a policy where the performance and power are balanced. this is the default.
• power — set a policy where the processor can accept a measurable performance impact to maximize energy efficiency. nap queen. 😴

the following table shows the mapping from the value strings above to actual MSR values. this mapping is defined in the Linux-kernel header, msr-index.h.

VALUE STRING        EPB  EPP
performance         0    0
balance-performance 4    128
normal, default          6    128
balance-power       8    192
power               15   255

for MSR_IA32_HWP_REQUEST performance fields (--hwp-min, --hwp-max, --hwp-desired), the value option is in units of 100 MHz, eg. 12 signifies 1200 MHz. 🤯

💅 FIELD OPTIONS 💅

• -a, --all value-string — sets all EPB and EPP and HWP limit fields to the value associated with the value-string. in addition, enables turbo-mode and HWP-mode, if they were previously disabled. thus "--all normal" will set a system without cpufreq into a well known configuration. iconic. 👑
• -B, --epb — set EPB per-core or per-package. see value strings in the table above. ⭐
• -d, --debug debug — increases verbosity. by default x86_energy_perf_policy is silent for updates, and verbose for read-only mode. 🙈
• -P, --hwp-epp — set HWP.EPP per-core or per-package. see value strings in the table above. 💜
• -m, --hwp-min — request HWP to not go below the specified core/bus ratio. the "default" is the value found in IA32_HWP_CAPABILITIES.min.
• -M, --hwp-max — request HWP not exceed a the specified core/bus ratio. the "default" is the value found in IA32_HWP_CAPABILITIES.max.
• -D, --hwp-desired — request HWP 'desired' frequency. the "normal" setting is 0, which corresponds to 'full autonomous' HWP control. non-zero performance values request a specific performance level on this processor, specified in multiples of 100 MHz.
• -w, --hwp-window — specify integer number of microsec in the sliding window that HWP uses to maintain average frequency. this parameter is meaningful only when the "desired" field above is non-zero. default is 0, allowing the HW to choose. 🎀

🦋 SOC SLIDER OPTIONS 🦋

note bestie: the Platform Profile Name must be "SoC Slider", and the Platform Profile must be "balanced" for the --soc-slider-balance and --soc-slider-offset options to take effect. iykyk.

• --soc-slider-balance # — write numeric value to the SoC Slider. values range from 0 to 6. lower values result in higher performance, and higher values improve energy efficiency. actual values are model specific. 🌸
• --soc-slider-offset # — write the numeric value to the Soc Slider Offset. the slider offset is the maximum value that software allows the SoC to autonomously add to the SoC Slider to improve energy efficiency. the value 0 prohibits the SoC from autonomously changing the slider. 🛑
• --platform-profile <name> — set the platform profile to <name>. available choices are in platform-profile-0/choices. the Soc Slider driver currently supports "low-power", "balanced", and "performance". ✨

🌟 OTHER OPTIONS 🌟

• -f, --force — writes the specified values without bounds checking. (bold. reckless. we love that for you, but be careful fr fr. 😭)
• -U, --hwp-use-pkg (0 | 1) — when used in conjunction with --cpu, indicates whether the per-CPU MSR_IA32_HWP_REQUEST should be overruled (1) or exempt (0) from per-Package MSR_IA32_HWP_REQUEST_PKG settings. the default is exempt. 🫶
• -H, --hwp-enable — enable HardWare-P-state (HWP) mode. once enabled, system RESET is required to disable HWP mode. 💀 that's not a vibe, that's a commitment.
• -t, --turbo-enable — enable (1) or disable (0) turbo mode. 🔥
• -v, --version — print version and exit.

if no request to change policy is made, the default behavior is to read and display the current system state, including the default capabilities. it's just observing. main character behavior. 👑

---

🚨 WARNING 🚨

this utility writes directly to Model Specific Registers. there is no locking or coordination should this utility be used to modify HWP limit fields at the same time that intel_pstate's sysfs attributes access the same MSRs. 💀

also, note that --hwp-desired and --hwp-window are considered experimental. future versions of Linux reserve the right to access these fields internally — potentially conflicting with user-space access. so like… don't build your whole personality on them, bestie. 😭

---

🔥 EXAMPLE 🔥

# sudo x86_energy_perf_policy
cpu0: EPB 6
cpu0: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu0: HWP_CAP: low 1 eff 8 guar 27 high 35
cpu1: EPB 6
cpu1: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu1: HWP_CAP: low 1 eff 8 guar 27 high 35
cpu2: EPB 6
cpu2: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu2: HWP_CAP: low 1 eff 8 guar 27 high 35
cpu3: EPB 6
cpu3: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu3: HWP_CAP: low 1 eff 8 guar 27 high 35

look at all those little guys reporting in. so organized. so slay. 💖

---

📝 NOTES 📝

x86_energy_perf_policy runs only as root. sorry babe, you need the keys to the kingdom. 🔑

---

📂 FILES 📂

• EPB: /sys/devices/system/cpu/cpu*/power/energy_perf_bias
• EPP: /sys/devices/system/cpu/cpu*/cpufreq/energy_performance_preference
• MSR: /dev/cpu/*/msr
• Platform Profile Name: /sys/class/platform-profile/platform-profile-0/name
• Platform Profile: /sys/class/platform-profile/platform-profile-0/profile
• SOC Slider Balanced: /sys/module/processor_thermal_soc_slider/parameters/slider_balance
• SOC Slider Balanced Offset: /sys/module/processor_thermal_soc_slider/parameters/slider_offset

---

👀 SEE ALSO 👀

• msr(4)
• Intel(R) 64 and IA-32 Architectures Software Developer's Manual

---

🫶 AUTHORS 🫶

Len Brown — the icon who made all this possible. 💜

---

okay that's the whole page bestie, X86_ENERGY_PERF_POLICY(8) from the System Manager's Manual, section 8, and we are obsessed. go forth, tune your CPU, and remember: with great MSR access comes great responsibility. mwah. 💅✨🎀🦋🌸