CPUPOWER-MONITOR(1)

✨ CPUPOWER-MONITOR(1) ✨

cpupower Manual 🎀 manual page, section 1

💖 NAME 💖

cpupower-monitor — Report processor frequency and idle statistics ✨

🧚 SYNOPSIS 🧚

cpupower monitor -l

cpupower monitor [-c][-m <mon1>,[<mon2>,...]]  [-i seconds]
cpupower monitor [-c][-m <mon1>,[<mon2>,...]]  command

📖 DESCRIPTION 📖

okay so cpupower-monitor is literally your processor's stat diary 📓 It reports topology, frequency, and idle power state stats. You can either hand it a command, which gets forked and then spills its stats when it finishes, or have it print stats periodically. Iconic. 💅

It's giving independent counters 🦋 Processor sleep states and frequency get tracked by a bunch of separate counters. Some come from kernel statistics and some are read straight out of hardware registers. Run -l first to see which ones your system supports, bestie 🫶

✨ Options ✨

• -l — Lists every monitor on your system, with extra details for each one 📋
  • The name in quotation marks, which is what you pass to -m 🏷️
  • How many counters the monitor supports, shown in brackets 🔢
  • How many seconds the counters might overflow after, because of implementation limits ⏳
  • The name and description of each counter, plus which processor hierarchy levels it covers, shown in square brackets 🗺️
    • [T] → Thread
    • [C] → Core
    • [P] → Processor Package (Socket)
    • [M] → Machine/Platform wide counter
• -m <mon1>,<mon2>,... — Only show specific monitors. Use the monitor strings you got from -l 🎯
• -i seconds — Sets the measure interval ⏱️
• -c — Schedules the process on every core before measuring starts and again when it ends 🏃‍♀️💨 This might be needed for the Idle_Stats monitor when no other MSR based monitor (which has to run on the core being measured) is running in parallel. It wakes the processors up from deeper sleep states so the kernel can re-account its cpuidle (C-state) info before the cpuidle timings get read from sysfs. Super specific, but it matters 🙈
• command — Measures the idle and frequency characteristics of any command or workload 🏋️‍♀️ The executable gets forked, and once it exits, you get the stats gathered since it was forked 🎉

🌈 MONITOR DESCRIPTIONS 🌈

🔥 Idle_Stats 🔥

This shows stats from the cpuidle kernel subsystem. The values come from /sys/devices/system/cpu/cpu*/cpuidle/state*/. The kernel updates them every time an idle state is entered or left, so things can be a little inaccurate when cores sit in an idle state at the very start or end of a measurement. Worst case? One core stays idle for the whole measure time and the kernel never updates its idle state usage time. Then you'd see a residency of 0 percent when it was really 100. Kinda tragic 😭

💜 Mperf 💜

The name comes from the aperf/mperf (average and maximum) MSR registers it uses, which show up on recent X86 processors. It shows the average frequency, boost frequencies included 🚀 Since mperf stops ticking in every idle state on all recent hardware, it's also used to show C0 (processor is active) and Cx (processor is in any sleep state) times. These counters don't have the inaccuracy problems that Idle_Stats can have ✨ Heads up: it may work poorly on Linux-2.6.20 through 2.6.29, because the acpi-cpufreq kernel frequency driver periodically cleared the aperf/mperf registers in those kernels 💀

🧊 Nehalem SandyBridge HaswellExtended 🧊

These are Intel Core and Package sleep state counters 💎 Threads (hyperthreaded cores) might not be able to enter deeper core states while their sibling is busy. The deepest package sleep states can actually show up as machine/platform wide sleep states, and they can only be entered when every core is idle. For more details, check the Intel manuals listed in the References section 📚

The monitors are named after the CPU family where each sleep state capability first showed up, so they might not match your exact CPU name. For example, an IvyBridge processor has sleep state capabilities that first arrived in the Nehalem and SandyBridge families. So on an IvyBridge chip, you'll get both the Nehalem and SandyBridge sleep state monitors 🫠 HaswellExtended covers extra package sleep state capabilities that only exist in a specific Haswell (family 0x45), and probably in other future processors too 🔮

🌸 Fam_12h Fam_14h 🌸

These are sleep state counters for AMD laptop and desktop processors (families 12h and 14h) 💻 The registers are accessed over PCI, so you can still read them while cores are offlined 🙌

There's one special counter, NBP1 (North Bridge P1) 👑 It's always 0 or 1, depending on whether the North Bridge P1 power state got entered at least once during the measure time. Entering NBP1 also depends on graphics power management, so this counter can help you check whether the graphics driver's power management is working as expected 🎨

🍓 EXAMPLES 🍓

Running cpupower monitor -l might show something like this:

cpupower monitor -l" may show:
    Monitor "Mperf" (3 states) - Might overflow after 922000000 s

          ...

       Monitor "Idle_Stats" (3 states) - Might overflow after 4294967295 s

          ...

Here's a cute one: monitor the scp command and show both the Mperf and Idle_Stats state counter stats, just with the order swapped 🔄

cpupower monitor -m "Idle_Stats,Mperf" scp /tmp/test /nfs/tmp

⚠️ Careful, bestie! The typical trick to max out one CPU with cat /dev/zero >/dev/null does NOT work as expected, because the measured output gets redirected to /dev/null 💀 cpupower monitor cat /dev/zero >/dev/null A workaround is to put that line into its own tiny shell script. Hit CTRL-c to terminate the command and get the measure output displayed 🙏

📚 REFERENCES 📚

• "BIOS and Kernel Developer's Guide (BKDG) for AMD Family 14h Processors" — https://support.amd.com/us/Processor_TechDocs/43170.pdf 📄
• "What Is Intel® Turbo Boost Technology?" — https://www.intel.com/content/www/us/en/gaming/resources/turbo-boost.html ⚡
• "Power Management - Technology Overview" — https://cdrdv2.intel.com/v1/dl/getContent/637748 🔋
• "Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide" — https://www.intel.com/products/processor/manuals 📘

🗂️ FILES 🗂️

• /dev/cpu/*/msr
• /sys/devices/system/cpu/cpu*/cpuidle/state*/.

🔗 SEE ALSO 🔗

powertop(8), msr(4), vmstat(8) 💜

👩‍💻 AUTHORS 👩‍💻

Written by Thomas Renninger <trenn@suse.de> 🫶

Nehalem and SandyBridge monitors and command passing are based on turbostat.8 from Len Brown <len.brown@intel.com> 🌟

---

That's the whole tea, bestie! 🌈 This page is part of the cpupower Manual, last revised 22/02/2011, and it's got CPUPOWER-MONITOR(1) energy all the way through 💖✨