1.\" 2.\" Copyright (c) 2026 Advanced Micro Devices, Inc. 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd August 5, 2026 7.Dt PMC.PERF 3 8.Os 9.Sh NAME 10.Nm pmc.perf 11.Nd measurements using the MPERF/APERF effective 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 41The 42.Dv PMC_CLASS_PERF 43class exposes these two MSRs as read-only 64-bit counters that may 44only be allocated in system-wide counting mode 45.Pq Dv PMC_MODE_SC. 46Both counters expose the unmodified contents of the underlying MSRs. 47.Pp 48It reflects the free-running count of the underlying MSR since the 49processor was last reset, and continues to accumulate across 50allocate/release cycles. 51.Ss PMC Features 52AMD/Intel PERF supports the following capabilities. 53.Bl -column "PMC_CAP_THRESHOLD" "Support" 54.It Sy Capability Ta Sy Support 55.It Dv PMC_CAP_CASCADE Ta \&No 56.It Dv PMC_CAP_EDGE Ta \&No 57.It Dv PMC_CAP_INTERRUPT Ta \&No 58.It Dv PMC_CAP_INVERT Ta \&No 59.It Dv PMC_CAP_PRECISE Ta \&No 60.It Dv PMC_CAP_READ Ta Yes 61.It Dv PMC_CAP_SYSTEM Ta \&No 62.It Dv PMC_CAP_TAGGING Ta \&No 63.It Dv PMC_CAP_THRESHOLD Ta \&No 64.It Dv PMC_CAP_USER Ta \&No 65.It Dv PMC_CAP_WRITE Ta \&No 66.El 67.Pp 68By default AMD/Intel PERF enables the read flag. 69.Pp 70PERF events do not support further event qualifiers. 71.Ss Event Specifiers 72The following event names are supported: 73.Bl -tag -width "perf-mperf / mperf" 74.It Cm perf-mperf , Cm mperf 75The Max Performance Frequency Clock Count 76MSR of the core the counter is bound to. 77.It Cm perf-aperf , Cm aperf 78The Actual Performance Frequency Clock Count 79MSR of the core the counter is bound to. 80.El 81.Ss Counter Scope 82.Va MPERF 83and 84.Va APERF 85are per-core registers: each core has its own independent pair of 86MSRs, and a PMC of this class always reads the value local to the 87CPU it is bound to. 88Readings from different cores must not be combined or averaged 89without accounting for each core's independent P-state history. 90.Ss Availability 91Availability of the 92.Dv PMC_CLASS_PERF 93class depends on both of the following being true: 94.Bl -enum 95.It 96The processor advertises EffFreq 97.Pq Dq Effective Frequency Interface 98support in CPUID 6 leaf 0000_0006H bit 0 ECX. 99.It 100The kernel verified, at boot time, that the MSRs actually increment. 101Some virtualized environments advertise the CPUID bit without 102functional MSR support. 103.El 104.Pp 105If either condition does not hold, the 106.Dv PMC_CLASS_PERF 107class is not registered and does not appear in the output of 108.Xr pmccontrol 8 109or 110.Xr pmcstat 8 . 111.Sh EXAMPLES 112Sample both counters on CPU 0 for five seconds: 113.Bd -literal -offset indent 114pmcstat -c 0 -s perf-mperf -s perf-aperf -w 5 115.Ed 116.Sh SEE ALSO 117.Xr pmc 3 , 118.Xr pmc.tsc 3 , 119.Xr pmc_allocate 3 , 120.Xr pmc_read 3 , 121.Xr pmclog 3 , 122.Xr hwpmc 4 , 123.Xr pmcstat 8 124.Sh HISTORY 125The 126.Dv PMC_CLASS_PERF 127class first appeared in 128.Fx 16.0 . 129.Sh AUTHORS 130AMD/Intel PERF support and this manual page were written by 131.An Anderson Nascimento Aq Mt anascime@amd.com 132and sponsored by AMD, Inc. 133