freebsd/lib/libpmc/pmc.perf.3

.\"
.\" Copyright (c) 2026 Advanced Micro Devices, Inc.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.Dd October 13, 2026
.Dt PMC.PERF 3 amd64
.Os
.Sh NAME
.Nm pmc.perf
.Nd measurements using the MPERF/APERF/IRPERF frequency counters
.Sh LIBRARY
.Lb libpmc
.Sh SYNOPSIS
.In pmc.h
.Sh DESCRIPTION
AMD/Intel processors that implement the EffFreq
.Pq Dq Effective Frequency Interface
feature report two fixed-counters machine specific registers,
.Va MPERF
.Pq Dq Max Performance Frequency Clock Count
and
.Va APERF
.Pq Dq Actual Performance Frequency Clock Count ,
that together allow the average effective CPU frequency over an
interval to be computed.
.Va MPERF
is incremented by hardware at the P0 frequency.
The
.Va 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
.Va APERF
to
.Va MPERF
scaled by the processor's nominal frequency, yields the
average effective frequency.
.Pp
AMD processors additionally provide a third fixed-counter machine
specific register,
.Va IRPERF
.Pq Dq Instructions Retired Performance Count ,
which increments by one for each instruction retired by the core.
Unlike
.Va MPERF
and
.Va APERF ,
.Va IRPERF
is an AMD-only facility and is not available on Intel processors.
.Pp
The
.Dv PMC_CLASS_PERF
class exposes these MSRs as read-only 64-bit counters that may
only be allocated in system-wide counting mode
.Pq Dv PMC_MODE_SC.
All counters expose the unmodified contents of the underlying MSRs.
.Pp
It reflects the free-running count of the underlying MSR since the
processor was last reset, and continues to accumulate across
allocate/release cycles.
.Ss PMC Features
AMD/Intel PERF supports the following capabilities.
.Bl -column "PMC_CAP_THRESHOLD" "Support"
.It Sy Capability Ta Sy Support
.It Dv PMC_CAP_CASCADE Ta \&No
.It Dv PMC_CAP_EDGE Ta \&No
.It Dv PMC_CAP_INTERRUPT Ta \&No
.It Dv PMC_CAP_INVERT Ta \&No
.It Dv PMC_CAP_PRECISE Ta \&No
.It Dv PMC_CAP_READ Ta Yes
.It Dv PMC_CAP_SYSTEM Ta \&No
.It Dv PMC_CAP_TAGGING Ta \&No
.It Dv PMC_CAP_THRESHOLD Ta \&No
.It Dv PMC_CAP_USER Ta \&No
.It Dv PMC_CAP_WRITE Ta \&No
.El
.Pp
By default AMD/Intel PERF enables the read flag.
.Pp
PERF events do not support further event qualifiers.
.Ss Event Specifiers
The following event names are supported:
.Bl -tag -width "perf-irperf / irperf"
.It Cm perf-mperf , Cm mperf
The Max Performance Frequency Clock Count
MSR of the core the counter is bound to.
.It Cm perf-aperf , Cm aperf
The Actual Performance Frequency Clock Count
MSR of the core the counter is bound to.
.It Cm perf-irperf , Cm 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
.Sx Availability
below for the full set of conditions that must hold for this
event to be present.
.El
.Ss Counter Scope
.Va MPERF ,
.Va APERF ,
and
.Va 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.
.Ss Availability
Availability of the
.Dv PMC_CLASS_PERF
class depends on both of the following being true:
.Bl -enum
.It
The processor advertises EffFreq
.Pq Dq Effective Frequency Interface
support in CPUID 6 leaf 0000_0006H bit 0 ECX.
.It
The kernel verified, at boot time, that the MSRs actually increment.
Some virtualized environments advertise the CPUID bit without
functional MSR support.
.El
.Pp
If either condition does not hold, the
.Dv PMC_CLASS_PERF
class is not registered and does not appear in the output of
.Xr pmccontrol 8
or
.Xr pmcstat 8 .
.Pp
The
.Cm 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
.Cm perf-irperf
event specifier is not available even though the rest of the
.Dv PMC_CLASS_PERF
class may be present.
.Pp
Due to erratum #1054
.Pq Dq Instructions Retired Performance Counter May Be Inaccurate ,
IRPERF is additionally left disabled on affected AMD Zen 1 parts
.Pq 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.
.Pp
As with
.Va MPERF
and
.Va 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.
.Pp
If IRPERF is unavailable for any of the reasons above, the rest of
the
.Dv PMC_CLASS_PERF
class
.Pq Va MPERF No and Va APERF
is still registered normally; only the
.Cm perf-irperf
event specifier is absent.
.Sh EXAMPLES
Sample all three counters on CPU 0 for five seconds:
.Bd -literal -offset indent
pmcstat -c 0 -s perf-mperf -s perf-aperf -s perf-irperf -w 5
.Ed
.Sh SEE ALSO
.Xr pmc 3 ,
.Xr pmc.tsc 3 ,
.Xr pmc_allocate 3 ,
.Xr pmc_read 3 ,
.Xr pmclog 3 ,
.Xr hwpmc 4 ,
.Xr pmcstat 8
.Sh HISTORY
The
.Dv PMC_CLASS_PERF
class first appeared in
.Fx 16.0 .
.Sh AUTHORS
AMD/Intel PERF support and this manual page were written by
.An Anderson Nascimento Aq Mt [email protected]
and sponsored by AMD, Inc.