Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Quan Nguyen <quan@os.amperecomputing.com>
To:     macro@orcam.me.uk, Lee Jones <lee@kernel.org>,
        Bagas Sanjaya <bagasdotme@gmail.com>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Jean Delvare <jdelvare@suse.com>,
        Guenter Roeck <linux@roeck-us.net>,
        Jonathan Corbet <corbet@lwn.net>,
        Derek Kiernan <derek.kiernan@xilinx.com>,
        Dragan Cvetic <dragan.cvetic@xilinx.com>,
        Arnd Bergmann <arnd@arndb.de>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Quan Nguyen <quan@os.amperecomputing.com>,
        Thu Nguyen <thu@os.amperecomputing.com>,
        linux-kernel@vger.kernel.org, devicetree@vger.kernel.org,
        linux-hwmon@vger.kernel.org, linux-doc@vger.kernel.org,
        OpenBMC Maillist <openbmc@lists.ozlabs.org>,
        Open Source Submission <patches@amperecomputing.com>
Cc:     Phong Vo <phong@os.amperecomputing.com>,
        thang@os.amperecomputing.com
Subject: [PATCH v9 2/9] docs: hwmon: (smpro-hwmon) Add documentation
Date:   Thu, 29 Sep 2022 16:43:14 +0700
Message-Id: <20220929094321.770125-3-quan@os.amperecomputing.com>
In-Reply-To: <20220929094321.770125-1-quan@os.amperecomputing.com>
References: <20220929094321.770125-1-quan@os.amperecomputing.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?7XIjIfqp30VcRWAL5EfHOSFbigqRqX4m4f9FL0eJ8qiWIWeT6k3Bu/i/7SCF?=
 =?us-ascii?Q?huHlrv1oJ1xzWTCN9jN3jbghcNdxBuQcqzI6bkfjvUbrzckHWXOMEu0gIXFl?=
 =?us-ascii?Q?9FSyPrlZdhZwqDWoGE+enAMnMioAa4MgjpIfXyerJfuccK4ML7ol+BSgHFUJ?=
 =?us-ascii?Q?At8iQu0+75qTohIsBPzspJOjlpjy2XYrEYInOK+GQ9Q6UKRAC0+imdVa/2P1?=
 =?us-ascii?Q?wbmfbYW2UAyyT3aM3k3zkuTSCtDxOsNpf7w09Q92m94pc9xMzAz8aU84oQcG?=
 =?us-ascii?Q?apsFR5F3HsJ668iIot9aEJozgObScKhofWU3aHLxQE98DkfiOa7ykSlvoyDT?=
 =?us-ascii?Q?hRrx1rQBlUd2WN5eHN9SGtGDUVnGAt8jHJZijgnQV+cJMLjjQucBhJy+79nb?=
 =?us-ascii?Q?vhLvuqmhN3wdSI0HmfwP1R2zvpKHXIFl7NefQ5sQ8Qn2hkSyrQhO1mtQNptN?=
 =?us-ascii?Q?aRt849RCOFVz5LObeM0tVMDkclmkaXH4WZgVIK6F/4Cr5PSIHKU9rpRVXyaC?=
 =?us-ascii?Q?G3l5FWMH0YUxhPvx5zJMF5r0nMQgPqorY5SzwBhtMHkkfz+YQrGKdTtx6YY/?=
 =?us-ascii?Q?8KO8Fuw4WyCfSp5aC3yNT9zJOwDjR2nDl72+NlH+bZqfU8rFDCCbmdixdoZi?=
 =?us-ascii?Q?byPO5z4cyl87694o9u45/lEa4zGrnLPS1PWZ3Y4sHkoDVItJHEgU/N4DbyD0?=
 =?us-ascii?Q?jah4C/jv0ZPC7o2Yqce0bL0GP5V+sagWyRNhRlXB3HOWcqCtxDE7tzpaWQre?=
 =?us-ascii?Q?65SXnG2BYanfRWBQPjy3OFO6IuYNuExEObgOBSboRpUkUtjrCGctaqD/yAus?=
 =?us-ascii?Q?9ywEfToueZUrwrOVXBbUsYw8yNPREJp7UNcNOsVBpoadLBCn/yZqVXUsA30Y?=
 =?us-ascii?Q?EYeI1f0uOorQhUkBknwp1RFRTHRP56Oi88VzVmzzgcpzoLKmzKb9SU6TEN0H?=
 =?us-ascii?Q?K77CpAcjGjnGB853I+U4AIeLmPCAzt/yn1GgZJgPSyXGd2tXyQO5L+148zsz?=
 =?us-ascii?Q?fczAqSSu3az6/qMLqzw9fUdjmPkwsBEWzpYuGBVdrSjsCSL6+S33smJ9eN2S?=
 =?us-ascii?Q?NaVAJVI95PtnaN+0ZoSArxTPKEf9gKTxp5sf5GbabTQ/r1URasHsVo7gUiWj?=
 =?us-ascii?Q?foryLFC3nuGVAldtgh9RJxKo8XTsjjXgusW3KutxoqZ/4V9tSKNhwTkbXQI1?=
 =?us-ascii?Q?l7oK/rJUmQk9kHNG5o9UbpDkiTZz6GE5IM4fmvRtJDxTSl4/D4TnV9LtXZMJ?=
 =?us-ascii?Q?l0KrlBSmi9BcrLqGOGrphKGLy3zBGNJPXGxgBmyYp0/d5V18Nr16Z9lZzC03?=
 =?us-ascii?Q?deA/fdptdtrAanACj/bRIgygt1wac3Yd7Mxv0C6lfXIJhX+1LaYESNyAoCUO?=
 =?us-ascii?Q?XRq14w7jpKEMwxU10z0npqJgsBpRx4A1zNp+/vIH7d6P0VmGdPdamXIRuGpO?=
 =?us-ascii?Q?HJI7lrYOz9f4PXBx5IR/baZKycw4tkSiTrjjghyFDQqLLSGkOUB+sg8u2dCe?=
 =?us-ascii?Q?sGlymi5jI3k11hbLqSagFHq5lxg18oVEU5B4Pda9cIksn8A23+8jtNfTbLq5?=
 =?us-ascii?Q?FY/ml47Es+GldpDepjm9p76lRr3g1JvVZzISEVuUXnRqbdF4s1ONMfo1na7n?=
 =?us-ascii?Q?ZAODBuULNnrl7Mf+hAF3Rog=3D?=
X-OriginatorOrg: os.amperecomputing.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 3f1e272d-10e0-40db-9156-08daa1ff2010
X-MS-Exchange-CrossTenant-AuthSource: SJ0PR01MB7282.prod.exchangelabs.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 29 Sep 2022 09:43:55.8828
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 3bc2b170-fd94-476d-b0ce-4229bdc904a7
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 6O+wfA6iVvzIKlj7KxQJf6f8y9r5WXH5GLyyf2Q/JawOfT8++Ujgyk4uGFpWyM3AwSOZk5TX2XcurYLcLrERmz/N4g+gxaRT6EapjFOA6ZI=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR01MB5503
X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,
        SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Add documentation for the Ampere(R)'s Altra(R) SMpro hwmon driver.

Signed-off-by: Thu Nguyen <thu@os.amperecomputing.com>
Signed-off-by: Quan Nguyen <quan@os.amperecomputing.com>
Reviewed-by: Guenter Roeck <linux@roeck-us.net>
---
Changes in v9:
  + Update SPDX license                                [Greg]

Changes from v3=>v8:
  + None

Changes in v2:
  + Removed "virtual" sensors [Guenter]
  + Fixed typo "mili" to "milli", "nanoWatt" to "microWatt" [Guenter]
  + Reported SOC_TDP as "Socket TDP" using max attributes [Guenter]
  + Clarified "highest" meaning in documentation [Guenter]
  + Reported MEM HOT Threshold for all DIMMs as temp*_crit [Guenter]
  + Removed Socket TDP sensor [Quan]
  + Included sensor type and channel in labels [Quan]

 Documentation/hwmon/index.rst       |   1 +
 Documentation/hwmon/smpro-hwmon.rst | 101 ++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100644 Documentation/hwmon/smpro-hwmon.rst

diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index c1d11cf13eef..ddff3c5713d7 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -187,6 +187,7 @@ Hardware Monitoring Kernel Drivers
    sis5595
    sl28cpld
    smm665
+   smpro-hwmon
    smsc47b397
    smsc47m192
    smsc47m1
diff --git a/Documentation/hwmon/smpro-hwmon.rst b/Documentation/hwmon/smpro-hwmon.rst
new file mode 100644
index 000000000000..3a9b14dacf89
--- /dev/null
+++ b/Documentation/hwmon/smpro-hwmon.rst
@@ -0,0 +1,101 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Kernel driver Ampere(R)'s Altra(R) SMpro hwmon
+==============================================
+
+Supported chips:
+
+  * Ampere(R) Altra(R)
+
+    Prefix: 'smpro'
+
+    Reference: Altra SoC BMC Interface Specification
+
+Author: Thu Nguyen <thu@os.amperecomputing.com>
+
+Description
+-----------
+This driver supports hardware monitoring for Ampere(R) Altra(R) SoC's based on the
+SMpro co-processor (SMpro).
+The following sensor types are supported by the driver:
+
+  * temperature
+  * voltage
+  * current
+  * power
+
+The SMpro interface provides the registers to query the various sensors and
+their values which are then exported to userspace by this driver.
+
+Usage Notes
+-----------
+
+SMpro hwmon driver creates at least two sysfs files for each sensor.
+
+* File ``<sensor_type><idx>_label`` reports the sensor label.
+* File ``<sensor_type><idx>_input`` returns the sensor value.
+
+The sysfs files are allocated in the SMpro root fs folder.
+There is one root folder for each SMpro instance.
+
+When the SoC is turned off, the driver will fail to read registers
+and return -ENXIO.
+
+Sysfs entries
+-------------
+
+The following sysfs files are supported:
+
+* Ampere(R) Altra(R):
+
+============    =============   ======  ===============================================
+Name            Unit            Perm    Description
+temp1_input     milli Celsius   RO      SoC temperature
+temp2_input     milli Celsius   RO      Max temperature reported among SoC VRDs
+temp2_crit      milli Celsius   RO      SoC VRD HOT Threshold temperature
+temp3_input     milli Celsius   RO      Max temperature reported among DIMM VRDs
+temp4_input     milli Celsius   RO      Max temperature reported among Core VRDs
+temp5_input     milli Celsius   RO      Temperature of DIMM0 on CH0
+temp5_crit      milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp6_input     milli Celsius   RO      Temperature of DIMM0 on CH1
+temp6_crit      milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp7_input     milli Celsius   RO      Temperature of DIMM0 on CH2
+temp7_crit      milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp8_input     milli Celsius   RO      Temperature of DIMM0 on CH3
+temp8_crit      milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp9_input     milli Celsius   RO      Temperature of DIMM0 on CH4
+temp9_crit      milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp10_input    milli Celsius   RO      Temperature of DIMM0 on CH5
+temp10_crit     milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp11_input    milli Celsius   RO      Temperature of DIMM0 on CH6
+temp11_crit     milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp12_input    milli Celsius   RO      Temperature of DIMM0 on CH7
+temp12_crit     milli Celsius   RO      MEM HOT Threshold for all DIMMs
+temp13_input    milli Celsius   RO      Max temperature reported among RCA VRDs
+in0_input       milli Volts     RO      Core voltage
+in1_input       milli Volts     RO      SoC voltage
+in2_input       milli Volts     RO      DIMM VRD1 voltage
+in3_input       milli Volts     RO      DIMM VRD2 voltage
+in4_input       milli Volts     RO      RCA VRD voltage
+cur1_input      milli Amperes   RO      Core VRD current
+cur2_input      milli Amperes   RO      SoC VRD current
+cur3_input      milli Amperes   RO      DIMM VRD1 current
+cur4_input      milli Amperes   RO      DIMM VRD2 current
+cur5_input      milli Amperes   RO      RCA VRD current
+power1_input    micro Watts     RO      Core VRD power
+power2_input    micro Watts     RO      SoC VRD power
+power3_input    micro Watts     RO      DIMM VRD1 power
+power4_input    micro Watts     RO      DIMM VRD2 power
+power5_input    micro Watts     RO      RCA VRD power
+============    =============   ======  ===============================================
+
+Example::
+
+    # cat in0_input
+    830
+    # cat temp1_input
+    37000
+    # cat curr1_input
+    9000
+    # cat power5_input
+    19500000
-- 
2.35.1