1*3fdd05c6SAndre Silva.\" 2*3fdd05c6SAndre Silva.\" Copyright (c) 2026 Advanced Micro Devices, Inc. 3*3fdd05c6SAndre Silva.\" 4*3fdd05c6SAndre Silva.\" SPDX-License-Identifier: BSD-2-Clause 5*3fdd05c6SAndre Silva.\" 6*3fdd05c6SAndre Silva.Dd July 6, 2026 7*3fdd05c6SAndre Silva.Dt PMC.RAPL 3 8*3fdd05c6SAndre Silva.Os 9*3fdd05c6SAndre Silva.Sh NAME 10*3fdd05c6SAndre Silva.Nm pmc.rapl 11*3fdd05c6SAndre Silva.Nd measurements using RAPL energy counters 12*3fdd05c6SAndre Silva.Sh LIBRARY 13*3fdd05c6SAndre Silva.Lb libpmc 14*3fdd05c6SAndre Silva.Sh SYNOPSIS 15*3fdd05c6SAndre Silva.In pmc.h 16*3fdd05c6SAndre Silva.Sh DESCRIPTION 17*3fdd05c6SAndre Silva.Tn AMD 18*3fdd05c6SAndre Silvaand 19*3fdd05c6SAndre Silva.Tn Intel 20*3fdd05c6SAndre Silvaprocessors report cumulative energy consumption through the RAPL 21*3fdd05c6SAndre Silva(Running Average Power Limit) machine specific registers. 22*3fdd05c6SAndre SilvaThe 23*3fdd05c6SAndre Silva.Li PMC_CLASS_RAPL 24*3fdd05c6SAndre Silvaclass exposes these registers as read-only 64-bit counters that may 25*3fdd05c6SAndre Silvaonly be allocated in system-wide counting mode 26*3fdd05c6SAndre Silva.Pq Li PMC_MODE_SC . 27*3fdd05c6SAndre SilvaCounter values are cumulative energy in microjoules. 28*3fdd05c6SAndre SilvaThe kernel scales the raw hardware counts by the hardware energy unit, 29*3fdd05c6SAndre Silvaso no further conversion is required. 30*3fdd05c6SAndre Silva.Pp 31*3fdd05c6SAndre SilvaA counter's accumulator is not reset when a PMC is allocated or 32*3fdd05c6SAndre Silvareleased; it reflects energy consumed since the counters began 33*3fdd05c6SAndre Silvaaccumulating and is reset only when the 34*3fdd05c6SAndre Silva.Xr hwpmc 4 35*3fdd05c6SAndre Silvamodule is unloaded. 36*3fdd05c6SAndre SilvaAn individual reading is therefore meaningful only as a difference 37*3fdd05c6SAndre Silvabetween two samples. 38*3fdd05c6SAndre Silva.Pp 39*3fdd05c6SAndre SilvaThe hardware counters are 32 bits wide and wrap frequently under load. 40*3fdd05c6SAndre SilvaThe RAPL PMC class instead provides virtual 64-bit counters that are 41*3fdd05c6SAndre Silvaguaranteed to be monotonic, by periodically sampling the hardware 42*3fdd05c6SAndre Silvacounters while at least one RAPL PMC is allocated. 43*3fdd05c6SAndre Silva.Pp 44*3fdd05c6SAndre SilvaRAPL events do not support further event qualifiers. 45*3fdd05c6SAndre Silva.Ss Event Specifiers 46*3fdd05c6SAndre SilvaThe following event names are supported: 47*3fdd05c6SAndre Silva.Bl -tag -width indent 48*3fdd05c6SAndre Silva.It Li rapl-energy-pkg 49*3fdd05c6SAndre SilvaEnergy consumed by the processor package (socket) the counter is bound 50*3fdd05c6SAndre Silvato. 51*3fdd05c6SAndre Silva.It Li rapl-energy-cores 52*3fdd05c6SAndre SilvaOn 53*3fdd05c6SAndre Silva.Tn AMD 54*3fdd05c6SAndre Silvaprocessors, energy consumed by the physical core the counter is bound 55*3fdd05c6SAndre Silvato. 56*3fdd05c6SAndre SilvaOn 57*3fdd05c6SAndre Silva.Tn Intel 58*3fdd05c6SAndre Silvaprocessors, energy consumed by the PP0 (all cores) power plane of the 59*3fdd05c6SAndre Silvapackage, i.e. a package-scoped value. 60*3fdd05c6SAndre Silva.It Li rapl-energy-dram 61*3fdd05c6SAndre SilvaEnergy consumed by the DRAM domain of the package. 62*3fdd05c6SAndre SilvaPresent only on 63*3fdd05c6SAndre Silva.Tn Intel 64*3fdd05c6SAndre Silvaprocessors that implement the DRAM domain, typically server parts. 65*3fdd05c6SAndre Silva.El 66*3fdd05c6SAndre Silva.Ss Counter Scope 67*3fdd05c6SAndre SilvaRAPL counters measure package or core power domains, not individual 68*3fdd05c6SAndre SilvaCPUs: every CPU of a domain reads the same underlying counter. 69*3fdd05c6SAndre SilvaConsumers should bind one PMC per domain and must not sum readings 70*3fdd05c6SAndre Silvafrom CPUs that share a domain. 71*3fdd05c6SAndre Silva.Pp 72*3fdd05c6SAndre SilvaThe class advertises the 73*3fdd05c6SAndre Silva.Li PMC_CAP_DOMWIDE 74*3fdd05c6SAndre Silvacapability, which makes 75*3fdd05c6SAndre Silva.Xr pmcstat 8 76*3fdd05c6SAndre Silvaallocate one counter per NUMA domain instead of one per CPU. 77*3fdd05c6SAndre SilvaNUMA domains follow the firmware memory policy and need not match 78*3fdd05c6SAndre Silvapackages, in either direction: 79*3fdd05c6SAndre Silva.Bl -bullet 80*3fdd05c6SAndre Silva.It 81*3fdd05c6SAndre SilvaWith several NUMA domains per package (for example 82*3fdd05c6SAndre Silva.Tn AMD 83*3fdd05c6SAndre SilvaNPS2/NPS4 or 84*3fdd05c6SAndre Silva.Tn Intel 85*3fdd05c6SAndre SilvaSub-NUMA Clustering), 86*3fdd05c6SAndre Silva.Xr pmcstat 8 87*3fdd05c6SAndre Silvaallocates one counter per domain, so package-scoped counters within 88*3fdd05c6SAndre Silvaone package alias each other: each reading is correct on its own, 89*3fdd05c6SAndre Silvabut they must not be summed. 90*3fdd05c6SAndre Silva.It 91*3fdd05c6SAndre SilvaWith a single NUMA domain spanning several packages (for example 92*3fdd05c6SAndre Silva.Tn AMD 93*3fdd05c6SAndre SilvaNPS0 memory interleaving, NUMA disabled in firmware, or a kernel 94*3fdd05c6SAndre Silvabuilt without NUMA support), 95*3fdd05c6SAndre Silva.Xr pmcstat 8 96*3fdd05c6SAndre Silvaallocates only one counter, on the first configured CPU, and the 97*3fdd05c6SAndre Silvaremaining packages are silently not measured. 98*3fdd05c6SAndre Silva.El 99*3fdd05c6SAndre Silva.Pp 100*3fdd05c6SAndre SilvaFor explicit placement, allocate one system-scope PMC per package 101*3fdd05c6SAndre Silvawith 102*3fdd05c6SAndre Silva.Xr pmc_allocate 3 , 103*3fdd05c6SAndre Silvaor give 104*3fdd05c6SAndre Silva.Xr pmcstat 8 105*3fdd05c6SAndre Silvaone 106*3fdd05c6SAndre Silva.Fl c Ar cpu 107*3fdd05c6SAndre Silvaand 108*3fdd05c6SAndre Silva.Fl s Ar event 109*3fdd05c6SAndre Silvapair per package, for example on a two-socket system whose second 110*3fdd05c6SAndre Silvapackage starts at CPU 64: 111*3fdd05c6SAndre Silva.Dl pmcstat -c 0 -s rapl-energy-pkg -c 64 -s rapl-energy-pkg 112*3fdd05c6SAndre SilvaA single 113*3fdd05c6SAndre Silva.Fl c 114*3fdd05c6SAndre Silvalist naming several CPUs does not achieve this: for 115*3fdd05c6SAndre Silva.Li PMC_CAP_DOMWIDE 116*3fdd05c6SAndre Silvacounters 117*3fdd05c6SAndre Silva.Xr pmcstat 8 118*3fdd05c6SAndre Silvahonors only the first CPU of the list. 119*3fdd05c6SAndre Silva.Ss Privilege 120*3fdd05c6SAndre SilvaAllocating a RAPL PMC always requires the 121*3fdd05c6SAndre Silva.Li PRIV_PMC_SYSTEM 122*3fdd05c6SAndre Silvaprivilege, regardless of the 123*3fdd05c6SAndre Silva.Va security.bsd.unprivileged_syspmcs 124*3fdd05c6SAndre Silvasysctl: fine-grained energy readings form a power side channel 125*3fdd05c6SAndre Silva(PLATYPUS, CVE-2020-8694 and CVE-2020-12912). 126*3fdd05c6SAndre SilvaUnprivileged allocation requests fail with 127*3fdd05c6SAndre Silva.Er EPERM . 128*3fdd05c6SAndre Silva.Sh SEE ALSO 129*3fdd05c6SAndre Silva.Xr pmc 3 , 130*3fdd05c6SAndre Silva.Xr pmc.tsc 3 , 131*3fdd05c6SAndre Silva.Xr pmc_allocate 3 , 132*3fdd05c6SAndre Silva.Xr pmc_read 3 , 133*3fdd05c6SAndre Silva.Xr pmclog 3 , 134*3fdd05c6SAndre Silva.Xr hwpmc 4 , 135*3fdd05c6SAndre Silva.Xr pmcstat 8 136*3fdd05c6SAndre Silva.Sh HISTORY 137*3fdd05c6SAndre SilvaThe RAPL PMC class first appeared in 138*3fdd05c6SAndre Silva.Fx 16.0 . 139