LinuxCommandLibrary

cpufreq-aperf

Report CPU frequency performance counters

TLDR

Start calculating, defaulting to all CPU cores and 1 second refresh interval

$ sudo cpufreq-aperf
copy

Start calculating for CPU 1 only
$ sudo cpufreq-aperf [[-c|--cpu]] [1]
copy

Start calculating with a 3 second refresh interval for all CPU cores
$ sudo cpufreq-aperf [[-i|--interval]] [3]
copy

Calculate only once
$ sudo cpufreq-aperf [[-o|--once]]
copy

SYNOPSIS

cpufreq-aperf [OPTIONS] [duration_in_seconds]

PARAMETERS

duration_in_seconds
    The duration, in seconds, for which the command should monitor and collect performance data. If omitted, it defaults to 1 second.

-d, --debug
    Prints additional debug information during execution, which can be useful for troubleshooting.

-h, --help
    Displays a brief help message and exits.

-V, --version
    Prints the version information of the cpufreq-aperf utility and exits.

DESCRIPTION

The cpufreq-aperf command is a diagnostic tool designed to measure actual CPU frequency and core activity by utilizing the APERF (Actual Performance) and MPERF (Maximum Performance) Model Specific Registers (MSRs) available on modern x86 processors.
These MSRs provide a cumulative count of cycles that the CPU spent running at its current frequency (APERF) versus cycles that the CPU could have spent running at its maximum non-turbo frequency (MPERF). By sampling these counters over a period, cpufreq-aperf calculates the average operating frequency and the percentage of time the CPU was busy, effectively revealing how much of its potential performance a CPU core is actually delivering.
It's a valuable utility for verifying if CPU frequency scaling mechanisms are working as expected and for understanding performance bottlenecks related to CPU clock speeds. It is part of the cpufrequtils package.

CAVEATS

Requires root privileges to access MSRs.
Relies on the availability of APERF and MPERF MSRs, which are present on most modern Intel and AMD CPUs but may not be available on all architectures or older processors.
The output can be challenging to interpret without an understanding of MSRs and CPU frequency scaling concepts.
It measures core-level performance, not overall system performance.
It is part of the cpufrequtils package; ensure this package is installed.

UNDERSTANDING APERF AND MPERF MSRS

The command leverages two key Model Specific Registers (MSRs):
- APERF (Actual Performance Counter): Counts CPU cycles when the processor is not in a halted state (e.g., C0 state). This counter accumulates cycles at the actual operating frequency.
- MPERF (Maximum Performance Counter): Counts CPU cycles at the CPU's maximum non-turbo frequency (base frequency). This counter accumulates cycles as if the CPU were constantly running at its highest defined speed.
By comparing the difference in these counters over a time interval, cpufreq-aperf calculates the percentage of time the CPU was active and its average effective frequency relative to its maximum frequency.

OUTPUT INTERPRETATION

A typical output might look like:
CPU 0: 67% busy, actual freq: 2.1 GHz, max freq: 3.2 GHz (1 second avg)
- "X% busy": Represents (APERF_delta / MPERF_delta) * 100. This indicates the percentage of cycles the CPU spent executing instructions relative to the maximum possible cycles it could have executed at its base frequency.
- "actual freq": The average operating frequency of the CPU core over the measurement period. This is derived from (APERF_delta / measurement_duration).
- "max freq": The reported maximum non-turbo frequency of the CPU core, used as the reference for MPERF.

HISTORY

The cpufreq-aperf utility is part of the cpufrequtils package, a collection of tools designed for managing and inspecting the CPU frequency scaling capabilities of Linux systems. Its development emerged alongside the increasing sophistication of dynamic CPU frequency scaling (often known as SpeedStep, PowerNow!, or Cool'n'Quiet), necessitating tools to verify the actual operating frequencies and performance states of CPU cores. cpufreq-aperf specifically addresses the need to validate the proper functioning of the APERF and MPERF MSRs, which are crucial for accurate performance monitoring by the kernel and other utilities.

SEE ALSO

cpufreq-info(1), cpufreq-set(1), turbostat(8), perf(1), msr(4)

Copied to clipboard