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 =============== ========  ======================================