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