1.\" 2.\" Copyright (c) 2026 Advanced Micro Devices, Inc. 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd October 13, 2026 7.Dt PMC.PERF 3 8.Os 9.Sh NAME 10.Nm pmc.perf 11.Nd measurements using the MPERF/APERF/IRPERF frequency counters 12.Sh LIBRARY 13.Lb libpmc 14.Sh SYNOPSIS 15.In pmc.h 16.Sh DESCRIPTION 17AMD/Intel processors that implement the EffFreq 18.Pq Dq Effective Frequency Interface 19feature report two fixed-counters machine specific registers, 20.Va MPERF 21.Pq Dq Max Performance Frequency Clock Count 22and 23.Va APERF 24.Pq Dq Actual Performance Frequency Clock Count , 25that together allow the average effective CPU frequency over an 26interval to be computed. 27.Va MPERF 28is incremented by hardware at the P0 frequency. 29The 30.Va APERF 31register increments in proportion to the actual number of core 32clock cycles. 33Both registers only increment while the core is in C0. 34The ratio of 35.Va APERF 36to 37.Va MPERF 38scaled by the processor's nominal frequency, yields the 39average effective frequency. 40.Pp 41AMD processors additionally provide a third fixed-counter machine 42specific register, 43.Va IRPERF 44.Pq Dq Instructions Retired Performance Count , 45which increments by one for each instruction retired by the core. 46Unlike 47.Va MPERF 48and 49.Va APERF , 50.Va IRPERF 51is an AMD-only facility and is not available on Intel processors. 52.Pp 53The 54.Dv PMC_CLASS_PERF 55class exposes these MSRs as read-only 64-bit counters that may 56only be allocated in system-wide counting mode 57.Pq Dv PMC_MODE_SC. 58All counters expose the unmodified contents of the underlying MSRs. 59.Pp 60It reflects the free-running count of the underlying MSR since the 61processor was last reset, and continues to accumulate across 62allocate/release cycles. 63.Ss PMC Features 64AMD/Intel PERF supports the following capabilities. 65.Bl -column "PMC_CAP_THRESHOLD" "Support" 66.It Sy Capability Ta Sy Support 67.It Dv PMC_CAP_CASCADE Ta \&No 68.It Dv PMC_CAP_EDGE Ta \&No 69.It Dv PMC_CAP_INTERRUPT Ta \&No 70.It Dv PMC_CAP_INVERT Ta \&No 71.It Dv PMC_CAP_PRECISE Ta \&No 72.It Dv PMC_CAP_READ Ta Yes 73.It Dv PMC_CAP_SYSTEM Ta \&No 74.It Dv PMC_CAP_TAGGING Ta \&No 75.It Dv PMC_CAP_THRESHOLD Ta \&No 76.It Dv PMC_CAP_USER Ta \&No 77.It Dv PMC_CAP_WRITE Ta \&No 78.El 79.Pp 80By default AMD/Intel PERF enables the read flag. 81.Pp 82PERF events do not support further event qualifiers. 83.Ss Event Specifiers 84The following event names are supported: 85.Bl -tag -width "perf-irperf / irperf" 86.It Cm perf-mperf , Cm mperf 87The Max Performance Frequency Clock Count 88MSR of the core the counter is bound to. 89.It Cm perf-aperf , Cm aperf 90The Actual Performance Frequency Clock Count 91MSR of the core the counter is bound to. 92.It Cm perf-irperf , Cm irperf 93The Instructions Retired Performance Count 94MSR of the core the counter is bound to. 95This event is only available on AMD processors; it is not 96supported on Intel processors. 97See 98.Sx Availability 99below for the full set of conditions that must hold for this 100event to be present. 101.El 102.Ss Counter Scope 103.Va MPERF , 104.Va APERF , 105and 106.Va IRPERF 107are per-core registers: each core has its own independent set of 108MSRs, and a PMC of this class always reads the value local to the 109CPU it is bound to. 110Readings from different cores must not be combined or averaged 111without accounting for each core's independent P-state history. 112.Ss Availability 113Availability of the 114.Dv PMC_CLASS_PERF 115class depends on both of the following being true: 116.Bl -enum 117.It 118The processor advertises EffFreq 119.Pq Dq Effective Frequency Interface 120support in CPUID 6 leaf 0000_0006H bit 0 ECX. 121.It 122The kernel verified, at boot time, that the MSRs actually increment. 123Some virtualized environments advertise the CPUID bit without 124functional MSR support. 125.El 126.Pp 127If either condition does not hold, the 128.Dv PMC_CLASS_PERF 129class is not registered and does not appear in the output of 130.Xr pmccontrol 8 131or 132.Xr pmcstat 8 . 133.Pp 134The 135.Cm perf-irperf 136event is further restricted to AMD processors that advertise 137support for the IRPERF MSR in CPUID 8000_0008H bit 1 EBX. 138On processors that do not advertise this bit, including all 139Intel processors, the 140.Cm perf-irperf 141event specifier is not available even though the rest of the 142.Dv PMC_CLASS_PERF 143class may be present. 144.Pp 145Due to erratum #1054 146.Pq Dq Instructions Retired Performance Counter May Be Inaccurate , 147IRPERF is additionally left disabled on affected AMD Zen 1 parts 148.Pq Family 17h, Models below 30h , 149even though those processors advertise CPUID support for the MSR. 150It is enabled only for Zen 1 Family 17h Model 30h and later, and for 151all subsequent microarchitectures. 152.Pp 153As with 154.Va MPERF 155and 156.Va APERF , 157the kernel also verifies, at boot time, that the IRPERF MSR is 158actually incrementing before enabling it; some virtualized 159environments advertise CPUID and erratum-safe family/model 160information without functional MSR support behind it. 161.Pp 162If IRPERF is unavailable for any of the reasons above, the rest of 163the 164.Dv PMC_CLASS_PERF 165class 166.Pq Va MPERF No and Va APERF 167is still registered normally; only the 168.Cm perf-irperf 169event specifier is absent. 170.Sh EXAMPLES 171Sample all three counters on CPU 0 for five seconds: 172.Bd -literal -offset indent 173pmcstat -c 0 -s perf-mperf -s perf-aperf -s perf-irperf -w 5 174.Ed 175.Sh SEE ALSO 176.Xr pmc 3 , 177.Xr pmc.tsc 3 , 178.Xr pmc_allocate 3 , 179.Xr pmc_read 3 , 180.Xr pmclog 3 , 181.Xr hwpmc 4 , 182.Xr pmcstat 8 183.Sh HISTORY 184The 185.Dv PMC_CLASS_PERF 186class first appeared in 187.Fx 16.0 . 188.Sh AUTHORS 189AMD/Intel PERF support and this manual page were written by 190.An Anderson Nascimento Aq Mt anascime@amd.com 191and sponsored by AMD, Inc. 192