NAME
pmc.perf – measurements using the MPERF/APERF/IRPERF frequency counters
LIBRARY
library “libpmc”
SYNOPSIS
#include <pmc.h>
DESCRIPTION
AMD/Intel processors that implement the EffFreq (“Effective Frequency Interface”) feature report two fixed-counters machine specific registers, MPERF (“Max Performance Frequency Clock Count”) and APERF (“Actual Performance Frequency Clock Count”), that together allow the average effective CPU frequency over an interval to be computed. MPERF is incremented by hardware at the P0 frequency. The APERF register increments in proportion to the actual number of core clock cycles. Both registers only increment while the core is in C0. The ratio of APERF to MPERF scaled by the processor's nominal frequency, yields the average effective frequency.
AMD processors additionally provide a third fixed-counter machine specific register, IRPERF (“Instructions Retired Performance Count”), which increments by one for each instruction retired by the core. Unlike MPERF and APERF, IRPERF is an AMD-only facility and is not available on Intel processors.
The PMC_CLASS_PERF class exposes these MSRs as read-only 64-bit counters that may only be allocated in system-wide counting mode (PMC_MODE_SC.) All counters expose the unmodified contents of the underlying MSRs.
It reflects the free-running count of the underlying MSR since the processor was last reset, and continues to accumulate across allocate/release cycles.
PMC Features
AMD/Intel PERF supports the following capabilities.
| Capability | Support |
| PMC_CAP_CASCADE | No |
| PMC_CAP_EDGE | No |
| PMC_CAP_INTERRUPT | No |
| PMC_CAP_INVERT | No |
| PMC_CAP_PRECISE | No |
| PMC_CAP_READ | Yes |
| PMC_CAP_SYSTEM | No |
| PMC_CAP_TAGGING | No |
| PMC_CAP_THRESHOLD | No |
| PMC_CAP_USER | No |
| PMC_CAP_WRITE | No |
By default AMD/Intel PERF enables the read flag.
PERF events do not support further event qualifiers.
Event Specifiers
The following event names are supported:
- perf-mperf, mperf
-
The Max Performance Frequency Clock Count MSR of the core the counter is bound to.
- perf-aperf, aperf
-
The Actual Performance Frequency Clock Count MSR of the core the counter is bound to.
- perf-irperf, irperf
-
The Instructions Retired Performance Count MSR of the core the counter is bound to. This event is only available on AMD processors; it is not supported on Intel processors. See Availability below for the full set of conditions that must hold for this event to be present.
Counter Scope
MPERF, APERF, and IRPERF are per-core registers: each core has its own independent set of MSRs, and a PMC of this class always reads the value local to the CPU it is bound to. Readings from different cores must not be combined or averaged without accounting for each core's independent P-state history.
Availability
Availability of the PMC_CLASS_PERF class depends on both of the following being true:
-
The processor advertises EffFreq (“Effective Frequency Interface”) support in CPUID 6 leaf 0000_0006H bit 0 ECX.
-
The kernel verified, at boot time, that the MSRs actually increment. Some virtualized environments advertise the CPUID bit without functional MSR support.
If either condition does not hold, the PMC_CLASS_PERF class is not registered and does not appear in the output of pmccontrol(8) or pmcstat(8).
The perf-irperf event is further restricted to AMD processors that advertise support for the IRPERF MSR in CPUID 8000_0008H bit 1 EBX. On processors that do not advertise this bit, including all Intel processors, the perf-irperf event specifier is not available even though the rest of the PMC_CLASS_PERF class may be present.
Due to erratum #1054 (“Instructions Retired Performance Counter May Be Inaccurate”), IRPERF is additionally left disabled on affected AMD Zen 1 parts (Family 17h, Models below 30h), even though those processors advertise CPUID support for the MSR. It is enabled only for Zen 1 Family 17h Model 30h and later, and for all subsequent microarchitectures.
As with MPERF and APERF, the kernel also verifies, at boot time, that the IRPERF MSR is actually incrementing before enabling it; some virtualized environments advertise CPUID and erratum-safe family/model information without functional MSR support behind it.
If IRPERF is unavailable for any of the reasons above, the rest of the PMC_CLASS_PERF class (MPERF and APERF) is still registered normally; only the perf-irperf event specifier is absent.
EXAMPLES
Sample all three counters on CPU 0 for five seconds:
pmcstat -c 0 -s perf-mperf -s perf-aperf -s perf-irperf -w 5
SEE ALSO
pmc(3), pmc.tsc(3), pmc_allocate(3), pmc_read(3), pmclog(3), hwpmc(4), pmcstat(8)
HISTORY
The PMC_CLASS_PERF class first appeared in FreeBSD 16.0.
AUTHORS
AMD/Intel PERF support and this manual page were written by Anderson Nascimento ⟨[email protected]⟩ and sponsored by AMD, Inc.