aboutsummaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorAnderson Nascimento <anascime@amd.com>2026-09-03 17:51:38 +0000
committerMitchell Horne <mhorne@FreeBSD.org>2026-09-09 14:42:58 +0000
commit5369f8e73eff4772b133284012cb810e50d7c018 (patch)
tree681fbfb87dc75737d1a1aabd23836fdbd39484ec /lib
parentb60c5233770cdbec77596c81e031cf874267efd4 (diff)
hwpmc: add MPERF/APERF MSR support for AMD/Intel CPUs
Add support for reading the MPERF (MSR 0xE7) and APERF (MSR 0xE8) model-specific registers on AMD/Intel CPUs through hwpmc(4). These counters track maximum and actual performance frequency respectively, and are used to compute effective CPU frequency scaling independent of the nominal TSC rate. The name of the class was chosen as PERF because later support for other PERF MSRs can be added to the same class. Extend libpmc(3) to expose the AMD/Intel MPERF/APERF counters added to hwpmc(4) in the companion kernel change, so userland consumers (pmcstat(8), etc.) can allocate and read these events by name. Document the new PERF class and its MPERF/APERF counters in a new pmc.perf.3 manual page, describing their semantics and how to read them via pmc(3) and pmcstat(8). Bump PMC_VERSION_MINOR. Signed-off-by: Anderson Nascimento <anascime@amd.com> Reviewed by: Ali Mashtizadeh <ali@mashtizadeh.com>, mhorne Reviewed by: ziaee (manpages) Sponsored by: AMD Differential Revision: https://reviews.freebsd.org/D58647
Diffstat (limited to 'lib')
-rw-r--r--lib/libpmc/Makefile1
-rw-r--r--lib/libpmc/libpmc.c31
-rw-r--r--lib/libpmc/pmc.38
-rw-r--r--lib/libpmc/pmc.perf.3132
4 files changed, 172 insertions, 0 deletions
diff --git a/lib/libpmc/Makefile b/lib/libpmc/Makefile
index d86191cc35cb..1540e9c8417c 100644
--- a/lib/libpmc/Makefile
+++ b/lib/libpmc/Makefile
@@ -77,6 +77,7 @@ MAN+= pmc.iaf.3
MAN+= pmc.ibs.3
MAN+= pmc.ivybridge.3
MAN+= pmc.ivybridgexeon.3
+MAN+= pmc.perf.3
MAN+= pmc.rapl.3
MAN+= pmc.sandybridge.3
MAN+= pmc.sandybridgeuc.3
diff --git a/lib/libpmc/libpmc.c b/lib/libpmc/libpmc.c
index 5fc4630540fc..41a75ac694de 100644
--- a/lib/libpmc/libpmc.c
+++ b/lib/libpmc/libpmc.c
@@ -60,6 +60,8 @@ static int tsc_allocate_pmc(enum pmc_event _pe, char *_ctrspec,
struct pmc_op_pmcallocate *_pmc_config);
static int rapl_allocate_pmc(enum pmc_event _pe, char *_ctrspec,
struct pmc_op_pmcallocate *_pmc_config);
+static int perf_allocate_pmc(enum pmc_event _pe, char *_ctrspec,
+ struct pmc_op_pmcallocate *_pmc_config);
#endif
#if defined(__arm__)
static int armv7_allocate_pmc(enum pmc_event _pe, char *_ctrspec,
@@ -139,6 +141,7 @@ struct pmc_class_descr {
PMC_CLASSDEP_TABLE(iaf, IAF);
PMC_CLASSDEP_TABLE(k8, K8);
PMC_CLASSDEP_TABLE(ibs, IBS);
+PMC_CLASSDEP_TABLE(perf, PERF);
PMC_CLASSDEP_TABLE(armv7, ARMV7);
PMC_CLASSDEP_TABLE(armv8, ARMV8);
PMC_CLASSDEP_TABLE(cmn600_pmu, CMN600_PMU);
@@ -216,6 +219,7 @@ PMC_CLASS_TABLE_DESC(k8, K8, k8, k8);
PMC_CLASS_TABLE_DESC(ibs, IBS, ibs, ibs);
PMC_CLASS_TABLE_DESC(tsc, TSC, tsc, tsc);
PMC_CLASS_TABLE_DESC(rapl, RAPL, rapl, rapl);
+PMC_CLASS_TABLE_DESC(perf, PERF, perf, perf);
#endif
#if defined(__arm__)
PMC_CLASS_TABLE_DESC(cortex_a8, ARMV7, cortex_a8, armv7);
@@ -903,6 +907,22 @@ rapl_allocate_pmc(enum pmc_event pe, char *ctrspec,
return (0);
}
+
+static int
+perf_allocate_pmc(enum pmc_event pe, char *ctrspec,
+ struct pmc_op_pmcallocate *pmc_config)
+{
+ if (pe < PMC_EV_PERF_FIRST || pe > PMC_EV_PERF_LAST)
+ return (-1);
+
+ /* PERF events must be unqualified. */
+ if (ctrspec != NULL && *ctrspec != '\0')
+ return (-1);
+
+ pmc_config->pm_caps |= PMC_CAP_READ;
+
+ return (0);
+}
#endif
static struct pmc_event_alias generic_aliases[] = {
@@ -1463,6 +1483,10 @@ pmc_event_names_of_class(enum pmc_class cl, const char ***eventnames,
ev = rapl_event_table;
count = PMC_EVENT_TABLE_SIZE(rapl);
break;
+ case PMC_CLASS_PERF:
+ ev = perf_event_table;
+ count = PMC_EVENT_TABLE_SIZE(perf);
+ break;
case PMC_CLASS_K8:
ev = k8_event_table;
count = PMC_EVENT_TABLE_SIZE(k8);
@@ -1675,6 +1699,10 @@ pmc_init(void)
pmc_class_table[n++] = &rapl_class_table_descr;
break;
+ case PMC_CLASS_PERF:
+ pmc_class_table[n++] = &perf_class_table_descr;
+ break;
+
case PMC_CLASS_K8:
pmc_class_table[n++] = &k8_class_table_descr;
break;
@@ -1950,6 +1978,9 @@ _pmc_name_of_event(enum pmc_event pe, enum pmc_cputype cpu)
} else if (pe >= PMC_EV_RAPL_FIRST && pe <= PMC_EV_RAPL_LAST) {
ev = rapl_event_table;
evfence = rapl_event_table + PMC_EVENT_TABLE_SIZE(rapl);
+ } else if (pe >= PMC_EV_PERF_FIRST && pe <= PMC_EV_PERF_LAST) {
+ ev = perf_event_table;
+ evfence = perf_event_table + PMC_EVENT_TABLE_SIZE(perf);
} else if ((int)pe >= PMC_EV_SOFT_FIRST && (int)pe <= PMC_EV_SOFT_LAST) {
ev = soft_event_table;
evfence = soft_event_table + soft_event_info.pm_nevent;
diff --git a/lib/libpmc/pmc.3 b/lib/libpmc/pmc.3
index b04c2d39cf69..bb051b87ec13 100644
--- a/lib/libpmc/pmc.3
+++ b/lib/libpmc/pmc.3
@@ -233,6 +233,12 @@ Family 10h and above.
Programmable hardware counters present in
.Tn "AMD Athlon64"
CPUs.
+.It Li PMC_CLASS_PERF
+MPERF and APERF counters present in
+.Tn AMD
+and
+.Tn Intel
+CPUs.
.It Li PMC_CLASS_RAPL
RAPL energy counters present in
.Tn AMD
@@ -505,6 +511,7 @@ following manual pages:
.It Li PMC_CLASS_IBS Ta Xr pmc.ibs 3
.It Li PMC_CLASS_K8 Ta Xr pmc.amd 3
.It Li PMC_CLASS_RAPL Ta Xr pmc.rapl 3
+.It Li PMC_CLASS_PERF Ta Xr pmc.perf 3
.It Li PMC_CLASS_TSC Ta Xr pmc.tsc 3
.El
.Ss Event Name Aliases
@@ -558,6 +565,7 @@ Doing otherwise is unsupported.
.Xr pmc.ibs 3 ,
.Xr pmc.ivybridge 3 ,
.Xr pmc.ivybridgexeon 3 ,
+.Xr pmc.perf 3 ,
.Xr pmc.rapl 3 ,
.Xr pmc.sandybridge 3 ,
.Xr pmc.sandybridgeuc 3 ,
diff --git a/lib/libpmc/pmc.perf.3 b/lib/libpmc/pmc.perf.3
new file mode 100644
index 000000000000..2404abd53555
--- /dev/null
+++ b/lib/libpmc/pmc.perf.3
@@ -0,0 +1,132 @@
+.\"
+.\" Copyright (c) 2026 Advanced Micro Devices, Inc.
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd August 5, 2026
+.Dt PMC.PERF 3
+.Os
+.Sh NAME
+.Nm pmc.perf
+.Nd measurements using the MPERF/APERF effective 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
+The
+.Dv PMC_CLASS_PERF
+class exposes these two MSRs as read-only 64-bit counters that may
+only be allocated in system-wide counting mode
+.Pq Dv PMC_MODE_SC.
+Both 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-mperf / mperf"
+.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.
+.El
+.Ss Counter Scope
+.Va MPERF
+and
+.Va APERF
+are per-core registers: each core has its own independent pair 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 .
+.Sh EXAMPLES
+Sample both counters on CPU 0 for five seconds:
+.Bd -literal -offset indent
+pmcstat -c 0 -s perf-mperf -s perf-aperf -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 anascime@amd.com
+and sponsored by AMD, Inc.