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