Merge remote-tracking branch 'stable/linux-5.10.y' into rpi-5.10.y
[platform/kernel/linux-rpi.git] / Documentation / hwmon / amd_energy.rst
1 .. SPDX-License-Identifier: GPL-2.0
2
3 Kernel driver amd_energy
4 ==========================
5
6 Supported chips:
7
8 * AMD Family 17h Processors
9
10   Prefix: 'amd_energy'
11
12   Addresses used:  RAPL MSRs
13
14   Datasheets:
15
16   - Processor Programming Reference (PPR) for AMD Family 17h Model 01h, Revision B1 Processors
17
18         https://developer.amd.com/wp-content/resources/55570-B1_PUB.zip
19
20   - Preliminary Processor Programming Reference (PPR) for AMD Family 17h Model 31h, Revision B0 Processors
21
22         https://developer.amd.com/wp-content/resources/56176_ppr_Family_17h_Model_71h_B0_pub_Rev_3.06.zip
23
24 Author: Naveen Krishna Chatradhi <nchatrad@amd.com>
25
26 Description
27 -----------
28
29 The Energy driver exposes the energy counters that are
30 reported via the Running Average Power Limit (RAPL)
31 Model-specific Registers (MSRs) via the hardware monitor
32 (HWMON) sysfs interface.
33
34 1. Power, Energy and Time Units
35    MSR_RAPL_POWER_UNIT/ C001_0299:
36    shared with all cores in the socket
37
38 2. Energy consumed by each Core
39    MSR_CORE_ENERGY_STATUS/ C001_029A:
40    32-bitRO, Accumulator, core-level power reporting
41
42 3. Energy consumed by Socket
43    MSR_PACKAGE_ENERGY_STATUS/ C001_029B:
44    32-bitRO, Accumulator, socket-level power reporting,
45    shared with all cores in socket
46
47 These registers are updated every 1ms and cleared on
48 reset of the system.
49
50 Note: If SMT is enabled, Linux enumerates all threads as cpus.
51 Since, the energy status registers are accessed at core level,
52 reading those registers from the sibling threads would result
53 in duplicate values. Hence, energy counter entries are not
54 populated for the siblings.
55
56 Energy Caluclation
57 ------------------
58
59 Energy information (in Joules) is based on the multiplier,
60 1/2^ESU; where ESU is an unsigned integer read from
61 MSR_RAPL_POWER_UNIT register. Default value is 10000b,
62 indicating energy status unit is 15.3 micro-Joules increment.
63
64 Reported values are scaled as per the formula
65
66 scaled value = ((1/2^ESU) * (Raw value) * 1000000UL) in uJoules
67
68 Users calculate power for a given domain by calculating
69         dEnergy/dTime for that domain.
70
71 Energy accumulation
72 --------------------------
73
74 Current, Socket energy status register is 32bit, assuming a 240W
75 2P system, the register would wrap around in
76
77         2^32*15.3 e-6/240 * 2 = 547.60833024 secs to wrap(~9 mins)
78
79 The Core energy register may wrap around after several days.
80
81 To improve the wrap around time, a kernel thread is implemented
82 to accumulate the socket energy counters and one core energy counter
83 per run to a respective 64-bit counter. The kernel thread starts
84 running during probe, wakes up every 100secs and stops running
85 when driver is removed.
86
87 Frequency of the accumulator thread is set during the probe
88 based on the chosen energy unit resolution. For example
89 A. fine grain (1.625 micro J)
90 B. course grain (0.125 milli J)
91
92 A socket and core energy read would return the current register
93 value added to the respective energy accumulator.
94
95 Sysfs attributes
96 ----------------
97
98 =============== ========  =====================================
99 Attribute       Label     Description
100 =============== ========  =====================================
101
102 * For index N between [1] and [nr_cpus]
103
104 =============== ========  ======================================
105 energy[N]_input EcoreX    Core Energy   X = [0] to [nr_cpus - 1]
106                           Measured input core energy
107 =============== ========  ======================================
108
109 * For N between [nr_cpus] and [nr_cpus + nr_socks]
110
111 =============== ========  ======================================
112 energy[N]_input EsocketX  Socket Energy X = [0] to [nr_socks -1]
113                           Measured input socket energy
114 =============== ========  ======================================