From: Naveen Krishna Chatradhi <nchatrad@amd.com>
To: linux-hwmon@vger.kernel.org
Cc: naveenkrishna.ch@gmail.com,
Naveen Krishna Chatradhi <nchatrad@amd.com>,
Guenter Roeck <linux@roeck-us.net>
Subject: [PATCH 2/3 v7] hwmon: (amd_energy) Add documentation
Date: Tue, 19 May 2020 21:20:10 +0530 [thread overview]
Message-ID: <20200519155011.56184-2-nchatrad@amd.com> (raw)
In-Reply-To: <20200519155011.56184-1-nchatrad@amd.com>
Document amd_energy driver with energy sensors supported by it.
Cc: Guenter Roeck <linux@roeck-us.net>
Signed-off-by: Naveen Krishna Chatradhi <nchatrad@amd.com>
---
Changes in v7:
1. Add a note explaining the siblings behavior
Documentation/hwmon/amd_energy.rst | 109 +++++++++++++++++++++++++++++
Documentation/hwmon/index.rst | 1 +
2 files changed, 110 insertions(+)
create mode 100644 Documentation/hwmon/amd_energy.rst
diff --git a/Documentation/hwmon/amd_energy.rst b/Documentation/hwmon/amd_energy.rst
new file mode 100644
index 000000000000..f8288edff664
--- /dev/null
+++ b/Documentation/hwmon/amd_energy.rst
@@ -0,0 +1,109 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Kernel driver amd_energy
+==========================
+
+Supported chips:
+
+* AMD Family 17h Processors
+
+ Prefix: 'amd_energy'
+
+ Addresses used: RAPL MSRs
+
+ Datasheets:
+
+ - Processor Programming Reference (PPR) for AMD Family 17h Model 01h, Revision B1 Processors
+
+ https://developer.amd.com/wp-content/resources/55570-B1_PUB.zip
+
+ - Preliminary Processor Programming Reference (PPR) for AMD Family 17h Model 31h, Revision B0 Processors
+
+ https://developer.amd.com/wp-content/resources/56176_ppr_Family_17h_Model_71h_B0_pub_Rev_3.06.zip
+
+Author: Naveen Krishna Chatradhi <nchatrad@amd.com>
+
+Description
+-----------
+
+The Energy driver exposes the energy counters that are
+reported via the Running Average Power Limit (RAPL)
+Model-specific Registers (MSRs) via the hardware monitor
+(HWMON) sysfs interface.
+
+1. Power, Energy and Time Units
+ MSR_RAPL_POWER_UNIT/ C001_0299:
+ shared with all cores in the socket
+
+2. Energy consumed by each Core
+ MSR_CORE_ENERGY_STATUS/ C001_029A:
+ 32-bitRO, Accumulator, core-level power reporting
+
+3. Energy consumed by Socket
+ MSR_PACKAGE_ENERGY_STATUS/ C001_029B:
+ 32-bitRO, Accumulator, socket-level power reporting,
+ shared with all cores in socket
+
+These registers are updated every 1ms and cleared on
+reset of the system.
+
+Note: If SMT is enabled, Linux enumerates all threads as cpus.
+Since, the energy status registers are accessed at core level,
+reading those registers from the sibling threads would result
+in duplicate values. Hence, energy counter entries are not
+populated for the siblings.
+
+Energy Caluclation
+------------------
+
+Energy information (in Joules) is based on the multiplier,
+1/2^ESU; where ESU is an unsigned integer read from
+MSR_RAPL_POWER_UNIT register. Default value is 10000b,
+indicating energy status unit is 15.3 micro-Joules increment.
+
+Reported values are scaled as per the formula
+
+scaled value = ((1/2^ESU) * (Raw value) * 1000000UL) in uJoules
+
+Users calculate power for a given domain by calculating
+ dEnergy/dTime for that domain.
+
+Energy accumulation
+--------------------------
+
+Current, Socket energy status register is 32bit, assuming a 240W
+2P system, the register would wrap around in
+
+ 2^32*15.3 e-6/240 * 2 = 547.60833024 secs to wrap(~9 mins)
+
+The Core energy register may wrap around after several days.
+
+To improve the wrap around time, a kernel thread is implemented
+to accumulate the socket energy counters and one core energy counter
+per run to a respective 64-bit counter. The kernel thread starts
+running during probe, wakes up every 100secs and stops running
+when driver is removed.
+
+A socket and core energy read would return the current register
+value added to the respective energy accumulator.
+
+Sysfs attributes
+----------------
+
+=============== ======== =====================================
+Attribute Label Description
+=============== ======== =====================================
+
+* For index N between [1] and [nr_cpus]
+
+=============== ======== ======================================
+energy[N]_input EcoreX Core Energy X = [0] to [nr_cpus - 1]
+ Measured input core energy
+=============== ======== ======================================
+
+* For N between [nr_cpus] and [nr_cpus + nr_socks]
+
+=============== ======== ======================================
+energy[N]_input EsocketX Socket Energy X = [0] to [nr_socks -1]
+ Measured input socket energy
+=============== ======== ======================================
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index 8ef62fd39787..fc4b89810e67 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -39,6 +39,7 @@ Hardware Monitoring Kernel Drivers
adt7470
adt7475
amc6821
+ amd_energy
asb100
asc7621
aspeed-pwm-tacho
--
2.17.1
next prev parent reply other threads:[~2020-05-19 15:50 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-19 15:50 [PATCH 1/3 v7] hwmon: Add amd_energy driver to report energy counters Naveen Krishna Chatradhi
2020-05-19 15:50 ` Naveen Krishna Chatradhi [this message]
2020-05-19 15:50 ` [PATCH 3/3 v7] MAINTAINERS: add entry for AMD energy driver Naveen Krishna Chatradhi
2020-05-22 13:26 ` [PATCH 1/3 v7] hwmon: Add amd_energy driver to report energy counters Guenter Roeck
2020-05-22 14:19 ` Naveen Krishna Ch
2020-05-26 22:37 ` Alexander Monakov
2020-05-27 3:03 ` Naveen Krishna Ch
2020-05-27 6:59 ` Alexander Monakov
2020-05-27 10:35 ` Naveen Krishna Ch
2020-05-27 13:28 ` Guenter Roeck
2020-05-27 14:08 ` Alexander Monakov
2020-05-27 14:42 ` Naveen Krishna Ch
2020-05-27 15:15 ` Guenter Roeck
2020-05-27 15:25 ` Alexander Monakov
2020-05-27 15:35 ` Guenter Roeck
2020-05-27 14:48 ` Guenter Roeck
2020-05-27 15:12 ` Alexander Monakov
2020-05-27 15:33 ` Guenter Roeck
2020-05-27 16:41 ` Alexander Monakov
2020-05-27 16:57 ` Guenter Roeck
2020-05-27 17:12 ` Alexander Monakov
2020-05-27 16:59 ` Alexander Monakov
2020-05-28 4:11 ` Naveen Krishna Ch
2020-06-10 20:21 ` Alexander Monakov
2020-06-16 14:46 ` Chatradhi, Naveen Krishna
2020-06-16 14:53 ` Guenter Roeck
2020-06-16 14:57 ` Naveen Krishna Ch
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200519155011.56184-2-nchatrad@amd.com \
--to=nchatrad@amd.com \
--cc=linux-hwmon@vger.kernel.org \
--cc=linux@roeck-us.net \
--cc=naveenkrishna.ch@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).