Page MenuHomeFreeBSD
Files F169214896

D58649.diff
No OneTemporary
Actions

D58649.diff
View Options

diff --git a/lib/libpmc/Makefile b/lib/libpmc/Makefile
--- a/lib/libpmc/Makefile
+++ b/lib/libpmc/Makefile
@@ -77,6 +77,7 @@
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/pmc.3 b/lib/libpmc/pmc.3
--- a/lib/libpmc/pmc.3
+++ b/lib/libpmc/pmc.3
@@ -233,6 +233,10 @@
Programmable hardware counters present in
.Tn "AMD Athlon64"
CPUs.
+.It Li PMC_CLASS_PERF
+MPERF and APERF counters present in
+.Tn AMD
+CPUs.
.It Li PMC_CLASS_RAPL
RAPL energy counters present in
.Tn AMD
@@ -505,6 +509,7 @@
.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 +563,7 @@
.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
--- /dev/null
+++ b/lib/libpmc/pmc.perf.3
@@ -0,0 +1,140 @@
+.\" Copyright (c) 2026 Advanced Micro Devices, Inc.
+.\" All rights reserved.
+.\"
+.Dd August 5, 2026
+.Dt PMC.PERF 3
+.Os FreeBSD 16.0
+.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 processors that implement the EffFreq
+.Pq Qq Effective Frequency Interface
+feature report two fixed-counters machine specific registers,
+.Va MPERF
+.Pq Qq Max Performance Frequency Clock Count
+and
+.Va APERF
+.Pq Qq 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 an
+.Va APERF
+delta to the corresponding
+.Va MPERF
+delta, scaled by the processor's nominal frequency, yields the
+average effective frequency over that interval.
+.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 .
+Counter values are the raw, unscaled contents of the underlying MSR.
+No conversion to frequency or any other unit is performed by the
+kernel; callers wanting an effective frequency must sample both
+counters at two points in time and compute the ratio of deltas
+themselves.
+.Pp
+A counter's value is not reset when a PMC is allocated or released;
+it reflects the free-running count of the underlying MSR since the
+processor was last reset, and continues to accumulate across
+allocate/release cycles.
+An individual reading is therefore only meaningful as a difference
+between two samples taken while a PMC of this class is allocated.
+.Ss PMC Features
+AMD 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 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
+.Va MPERF
+MSR of the core the counter is bound to.
+.It Cm perf-aperf , Cm aperf
+The
+.Va APERF
+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 Qq 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, and the MSRs may also be read-only on such
+hosts.
+.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 PERF support and this manual page were written by
+.An Anderson Nascimento Aq Mt anscime@amd.com
+and sponsored by AMD, Inc.

File Metadata

Mime Type
text/plain
Expires
Tue, Sep 1, 9:29 PM (10 h, 30 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
37856763
Default Alt Text
D58649.diff (5 KB)

Event Timeline