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;
Message-ID: <7c0d3614-f501-d398-e023-5754e2ec9528@os.amperecomputing.com>
Date:   Thu, 6 Oct 2022 14:47:36 +0700
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:102.0)
 Gecko/20100101 Thunderbird/102.3.0
Subject: Re: [PATCH v9 2/9] docs: hwmon: (smpro-hwmon) Add documentation
Content-Language: en-CA
To:     Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     macro@orcam.me.uk, Lee Jones <lee@kernel.org>,
        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>,
        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>,
        Phong Vo <phong@os.amperecomputing.com>,
        thang@os.amperecomputing.com
References: <20220929094321.770125-1-quan@os.amperecomputing.com>
 <20220929094321.770125-3-quan@os.amperecomputing.com>
 <Yzg5GM97kM6/Hw82@debian.me>
From:   Quan Nguyen <quan@os.amperecomputing.com>
In-Reply-To: <Yzg5GM97kM6/Hw82@debian.me>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?SVlKSFQ4NWwwWmM3UWRQdGh0aFQvQXI0Sk5QN09VRVFaZUxLN2lVMW9qQmxS?=
 =?utf-8?B?NkJIWDFHNXdpWEZLRW1Ta29JMS9iNUJIK3BoR3BaSms1cEwxWEw3LzNhLzMr?=
 =?utf-8?B?S1Y0ZldWR0w3aHY3dDBGamNBeklIUjlHY28wMGhMbFM1a3REeFJSTWxvRjRp?=
 =?utf-8?B?cS9Bek5yZ25NeENyaGY1UFZDL0c3Z0dzYjBxRXBDRTBBdjBIQmkxajlqUUFZ?=
 =?utf-8?B?S2VadFNjUitBbXdmMXJyYTNPeC9RWEdoMjBBU1U1bmdFN2VPcEZQdVdMSU5L?=
 =?utf-8?B?RFIwby9QVTN1RDY5clhkQ1hkOTB0NnhyR0pCR3l3NTE5VGhaeWltQUdvMzZ5?=
 =?utf-8?B?SG12WGthRkMwTHd2Mnc0WjJqc2lvOGhLZmgrb3lxdVVrdys0RTZxZ0Iwcmpr?=
 =?utf-8?B?WnhENGkwSllVek1Bc1B0alRiczNaSWJia3E5dG1HQkxSNWVMTkRjc3RJdHJx?=
 =?utf-8?B?bWNtcWtXZlBBM2ZudDZYM01Bdks5MHBwL1RVWC84NGgzcjdCTDU1Z2EvRVNh?=
 =?utf-8?B?ZzRMSFZ2S1drankzTXg1V0Z1ajk4VmFvczZLVnI3bEd2c3dBZGQvMWNIell6?=
 =?utf-8?B?MWx4OGtEa2Y3WHY4b2p6Q3o0Vy9qYkFYdHI5NDB0VFFmUnNWZEo2eTYxZGQv?=
 =?utf-8?B?YW9zcFo1TllDMjZhbHRmbkVOZzFqYnNNcW9NUjJQSHJLRmJsa3pxQU9USVZX?=
 =?utf-8?B?NTlySkgxQm5uOERJblFzdytFV3d0NGYrb2lPdEdEVTFHV1FjRVJGVE9hdk1t?=
 =?utf-8?B?eUtTZ2lZTnlCQ1R1NWcvNktXcFhibUFmdnZXYitqUThmTDdhUFBBZWR4cjlB?=
 =?utf-8?B?WlRUc3dkRC83T0JBMSs4OTg0MDRaNmFSdktKODYxMnJxU2VGcDE1cGo4TGxm?=
 =?utf-8?B?WGFwdnVKRW1nMVRBc2g0a0J1VlQrdUlpc1VoaWU0K3dDSVdXQ0Z3MTNyR1dE?=
 =?utf-8?B?cXhLUHNybmxXOWtWRHVBNmg3RDIwTUtOR1ZZSFNGd1VPeXlHRTRmOVJsdlVv?=
 =?utf-8?B?L3NxNVk5ekpsOCtTaW5mUW04emwyRXNGUGFmRTF3UDdFazgyLytOeDZ3M1VP?=
 =?utf-8?B?WlRBaXhwZkg4UjFiL3UrZnRyN2VLTXFOTDdwY3pvYnhzMVlYZmRtTlFlZHNF?=
 =?utf-8?B?aHRIZ1dsOTFhaGxySHY3QkdhbStKbFUvTGJrUWowdjBHeEh2YjhXcWNTdVV3?=
 =?utf-8?B?QlJvSlpyK09Ld1lKOUpqRXBRTjhOZ3Z2WmxJWlBqNzdxK2hWSnNHTG95bTc5?=
 =?utf-8?B?RGQ5MW5oMVBMUlNrcUluVFhkREN2R2k1Z3ZxMTNFRHFUWVVlNHlrNjVxU01G?=
 =?utf-8?B?ak5lK2lkc0ViSUpuVDlMVGk1aVRDN1JqU0U5QzhrUERtOGpoRkVOdmcydE1u?=
 =?utf-8?B?RTl3blJ2aGR0V0F5Z203L2JVUWJEcUVuTDhSMkd5MFNjUkFPcjV2WkhTc0tX?=
 =?utf-8?B?aVZnenJJallYdHVrUTRjenBIdDNJa3BJM0Z6T3Y5K3dOUHV0R2d6UGxDMm5z?=
 =?utf-8?B?bUhZUlRaUnJiVWJMeVJFNEZsNHNxMnV1ZC9XakVaZk1IMHhnY1J5U2RWclpj?=
 =?utf-8?B?cjB5ek1HbFUxeFZtU0dvOFBQK3hVcGtGMDJLNDJiNHp3M3ZNOTlUalNlT0Y1?=
 =?utf-8?B?SmRqL3hsRHBBait0dDVkeVQ5REJadFczbkcySWc0eGU1WWNFaldOdWV6aHRM?=
 =?utf-8?B?MzJqVzgvSUlHQ3BJUm80M2FCeEZiWkpTU0Z4dHh6TDRPOUw3ZGZmazl4N2F5?=
 =?utf-8?B?WlZZRklDbGJmZXFiU3JTZHcxdnhBRVVzYnp3a2tRNXpOVm81OG5YNk1TaGFj?=
 =?utf-8?B?QzRLOCtJT1d2RWx6QVVwM0Qvb3Nic0l1Q1dEekpnRkNzZ2lmczBXK08zRVVZ?=
 =?utf-8?B?MFhUeUJvWHRQYVA3RElhclVQQmp1RTltNEJzWC9KbktxSGtVcnd3MmNLeVBz?=
 =?utf-8?B?OGJVZ0FqRG5wOHJ5Q0hqcUE3VXlLdVBrNlZkZDF0akJYZktGMVBvU21Zczgy?=
 =?utf-8?B?akJOY1VkZWp3dmhvcHhVQjY3M2xkSW1NSm9PSmlucE44TkhaZENLWlVMd21F?=
 =?utf-8?B?RExKYlpobnRpWngvVkZUMWZDeDcyWTNQeHphZUJwcnJEektla2FoVUFnekhR?=
 =?utf-8?B?ZUxlWGUxSjlsTDU5blhBV1NJZTBFdkNBY3lNMTNxb0FrUG43aWlOSDJ2dmlY?=
 =?utf-8?Q?odWtFQ9Z4HWXxPinVKwx10I=3D?=
X-OriginatorOrg: os.amperecomputing.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 96fca50a-84f2-418c-20a4-08daa76f105a
X-MS-Exchange-CrossTenant-AuthSource: SJ0PR01MB7282.prod.exchangelabs.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 06 Oct 2022 07:47:48.7489
 (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: qYpP7632uCVbUQ/X1UbsbVspKeO6WUauDJc5rODxtUXqN0rVE+njfo1TB1qyV5v6cmeylzRHYs9/wzZVbBLO8TNIVVz6RNWnExFw+z3Pfec=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY5PR01MB5796
X-Spam-Status: No, score=-3.4 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,NICE_REPLY_A,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


On 01/10/2022 19:56, Bagas Sanjaya wrote:
> On Thu, Sep 29, 2022 at 04:43:14PM +0700, Quan Nguyen wrote:
>> 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
>   
> The documentation above can be improved (both grammar and formatting):
> 
> ---- >8 ----
> 
> diff --git a/Documentation/hwmon/smpro-hwmon.rst b/Documentation/hwmon/smpro-hwmon.rst
> index 3a9b14dacf8975..fb7b3665735bba 100644
> --- a/Documentation/hwmon/smpro-hwmon.rst
> +++ b/Documentation/hwmon/smpro-hwmon.rst
> @@ -7,39 +7,39 @@ Supported chips:
>   
>     * Ampere(R) Altra(R)
>   
> -    Prefix: 'smpro'
> +    Prefix: ``smpro``
>   
> -    Reference: Altra SoC BMC Interface Specification
> +    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:
> +The smpro-hwmon driver supports hardware monitoring for Ampere(R) Altra(R)
> +SoCs based on the SMpro co-processor (SMpro).  The following sensor metrics
> +are supported by the driver:
>   
>     * temperature
>     * voltage
>     * current
>     * power
>   
> -The SMpro interface provides the registers to query the various sensors and
> +The 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.
> +The 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.
> +* ``<sensor_type><idx>_label`` reports the sensor label.
> +* ``<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.
> +The sysfs files are allocated in the SMpro rootfs folder, with one root
> +directory for each instance.
>   
> -When the SoC is turned off, the driver will fail to read registers
> -and return -ENXIO.
> +When the SoC is turned off, the driver will fail to read registers and
> +return ``-ENXIO``.
>   
>   Sysfs entries
>   -------------
> @@ -48,48 +48,49 @@ 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
> -============    =============   ======  ===============================================
> +  ============    =============  ======  ===============================================
> +  Name            Unit           Perm    Description
> +  ============    =============  ======  ===============================================
> +  temp1_input     millicelsius   RO      SoC temperature
> +  temp2_input     millicelsius   RO      Max temperature reported among SoC VRDs
> +  temp2_crit      millicelsius   RO      SoC VRD HOT Threshold temperature
> +  temp3_input     millicelsius   RO      Max temperature reported among DIMM VRDs
> +  temp4_input     millicelsius   RO      Max temperature reported among Core VRDs
> +  temp5_input     millicelsius   RO      Temperature of DIMM0 on CH0
> +  temp5_crit      millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp6_input     millicelsius   RO      Temperature of DIMM0 on CH1
> +  temp6_crit      millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp7_input     millicelsius   RO      Temperature of DIMM0 on CH2
> +  temp7_crit      millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp8_input     millicelsius   RO      Temperature of DIMM0 on CH3
> +  temp8_crit      millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp9_input     millicelsius   RO      Temperature of DIMM0 on CH4
> +  temp9_crit      millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp10_input    millicelsius   RO      Temperature of DIMM0 on CH5
> +  temp10_crit     millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp11_input    millicelsius   RO      Temperature of DIMM0 on CH6
> +  temp11_crit     millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp12_input    millicelsius   RO      Temperature of DIMM0 on CH7
> +  temp12_crit     millicelsius   RO      MEM HOT Threshold for all DIMMs
> +  temp13_input    millicelsius   RO      Max temperature reported among RCA VRDs
> +  in0_input       millivolts     RO      Core voltage
> +  in1_input       millivolts     RO      SoC voltage
> +  in2_input       millivolts     RO      DIMM VRD1 voltage
> +  in3_input       millivolts     RO      DIMM VRD2 voltage
> +  in4_input       millivolts     RO      RCA VRD voltage
> +  cur1_input      milliamperes   RO      Core VRD current
> +  cur2_input      milliamperes   RO      SoC VRD current
> +  cur3_input      milliamperes   RO      DIMM VRD1 current
> +  cur4_input      milliamperes   RO      DIMM VRD2 current
> +  cur5_input      milliamperes   RO      RCA VRD current
> +  power1_input    microwatts     RO      Core VRD power
> +  power2_input    microwatts     RO      SoC VRD power
> +  power3_input    microwatts     RO      DIMM VRD1 power
> +  power4_input    microwatts     RO      DIMM VRD2 power
> +  power5_input    microwatts     RO      RCA VRD power
> +  ============    =============  ======  ===============================================
>   
> -Example::
> +  Example::
>   
>       # cat in0_input
>       830
> 

Thank you Bagas, will apply in next version.
- Quan