[PATCH 0/4] ABI: sysfs-class-hwmon: document existing attributes

[PATCH 0/4] ABI: sysfs-class-hwmon: document existing attributes

[Javier Carrasco]

This series documents all humidity attributes that are used in the hwmon
subsystem and still do not have an entry in sysfs-class-hwmon.

Additionally, tempY_crit_alarm has been fixed to show proper access
rights according to its usage in the hwmon subsystem.

Three missing temperature alarms (tempY_emergency_alarm,
tempY_max_alarm and tempY_min_alarm) have been documented as well.

Note that there are no new additions, only existing attributes have
been documented.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
---
Javier Carrasco (4):
      ABI: sysfs-class-hwmon: rearrange humidity attributes alphabetically
      ABI: sysfs-class-hwmon: document missing humidity attributes
      ABI: sysfs-class-hwmon: fix tempY_crit_alarm access rights
      ABI: sysfs-class-hwmon: document emergency/max/min temperature alarms

 Documentation/ABI/testing/sysfs-class-hwmon | 110 +++++++++++++++++++++++++---
 1 file changed, 100 insertions(+), 10 deletions(-)
---
base-commit: b85ea95d086471afb4ad062012a4d73cd328fa86
change-id: 20231116-hwmon_abi-e6f803337fcf

Best regards,
-- 
Javier Carrasco <javier.carrasco.cruz@gmail.com>

[PATCH 1/4] ABI: sysfs-class-hwmon: rearrange humidity attributes alphabetically

[Javier Carrasco]

Preliminary step to add the missing humidity attributes in the ABI
documentation.

Adding new elements alphabetically is a common practice that has been
loosely followed in the sysfs-class-hwmon documentation. Since most of
the humidity attributes must be added to the file, a single attribute
needs to be rearranged to reinforce alphabetical order.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
---
 Documentation/ABI/testing/sysfs-class-hwmon | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
index 638f4c6d4ec7..b998a42add95 100644
--- a/Documentation/ABI/testing/sysfs-class-hwmon
+++ b/Documentation/ABI/testing/sysfs-class-hwmon
@@ -887,15 +887,6 @@ Description:
 
 		RW
 
-What:		/sys/class/hwmon/hwmonX/humidityY_input
-Description:
-		Humidity
-
-		Unit: milli-percent (per cent mille, pcm)
-
-		RO
-
-
 What:		/sys/class/hwmon/hwmonX/humidityY_enable
 Description:
 		Enable or disable the sensors
@@ -908,6 +899,14 @@ Description:
 
 		RW
 
+What:		/sys/class/hwmon/hwmonX/humidityY_input
+Description:
+		Humidity
+
+		Unit: milli-percent (per cent mille, pcm)
+
+		RO
+
 What:		/sys/class/hwmon/hwmonX/humidityY_rated_min
 Description:
 		Minimum rated humidity.

-- 
2.39.2

[PATCH 2/4] ABI: sysfs-class-hwmon: document missing humidity attributes

[Javier Carrasco]

All these attributes already exist and are used by the hwmon subsystem,
but they still must be documented.

The missing attributes are the following:
- humidityY_alarm
- humidityY_fault
- humidityY_label
- humidityY_max
- humidityY_max_hyst
- humidityY_min
- humidityY_min_hyst

Add the missing humidity attributes to the ABI documentation according
to their current usage and access rights in the hwmon subsystem.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
---
 Documentation/ABI/testing/sysfs-class-hwmon | 69 +++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
index b998a42add95..dccbcdc2dad8 100644
--- a/Documentation/ABI/testing/sysfs-class-hwmon
+++ b/Documentation/ABI/testing/sysfs-class-hwmon
@@ -887,6 +887,15 @@ Description:
 
 		RW
 
+What:		/sys/class/hwmon/hwmonX/humidityY_alarm
+Description:
+		Humidity limit detection
+
+		- 0: OK
+		- 1: Humidity limit has been reached
+
+		RO
+
 What:		/sys/class/hwmon/hwmonX/humidityY_enable
 Description:
 		Enable or disable the sensors
@@ -899,6 +908,15 @@ Description:
 
 		RW
 
+What:		/sys/class/hwmon/hwmonX/humidityY_fault
+Description:
+		Reports a humidity sensor failure.
+
+		- 1: Failed
+		- 0: Ok
+
+		RO
+
 What:		/sys/class/hwmon/hwmonX/humidityY_input
 Description:
 		Humidity
@@ -907,6 +925,57 @@ Description:
 
 		RO
 
+What:		/sys/class/hwmon/hwmonX/humidityY_label
+Description:
+		Suggested humidity channel label.
+
+		Text string
+
+		Should only be created if the driver has hints about what
+		this humidity channel is being used for, and user-space
+		doesn't. In all other cases, the label is provided by
+		user-space.
+
+		RO
+
+What:		/sys/class/hwmon/hwmonX/humidityY_max
+Description:
+		Humidity max value.
+
+		Unit: milli-percent (per cent mille, pcm)
+
+		RW
+
+What:		/sys/class/hwmon/hwmonX/humidityY_max_hyst
+Description:
+		Humidity hysteresis value for max limit.
+
+		Unit: milli-percent (per cent mille, pcm)
+
+		Must be reported as an absolute humidity, NOT a delta
+		from the max value.
+
+		RW
+
+What:		/sys/class/hwmon/hwmonX/humidityY_min
+Description:
+		Humidity min value.
+
+		Unit: milli-percent (per cent mille, pcm)
+
+		RW
+
+What:		/sys/class/hwmon/hwmonX/humidityY_min_hyst
+Description:
+		Humidity hysteresis value for min limit.
+
+		Unit: milli-percent (per cent mille, pcm)
+
+		Must be reported as an absolute humidity, NOT a delta
+		from the min value.
+
+		RW
+
 What:		/sys/class/hwmon/hwmonX/humidityY_rated_min
 Description:
 		Minimum rated humidity.

-- 
2.39.2

[PATCH 3/4] ABI: sysfs-class-hwmon: fix tempY_crit_alarm access rights

[Javier Carrasco]

This attribute is defined as read-only by all drivers that support it.

It seems that the access rights and description for this attribute were
copied from the intrusionY_alarm, which has indeed RW rights and must be
cleared by the user.

These are the modules that currently use this attribute:
- adt7x10
- i5500_temp
- jc42
- lm83
- lm90
- lm95245
- max31760
- max6621
- mc34vr500
- tmp401
- tmp464
- tmp513

Fix the attribute description and make it read-only.

Fixes: 365b5d63a505 ("ABI: sysfs-class-hwmon: add a description for tempY_crit_alarm")
Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
---
 Documentation/ABI/testing/sysfs-class-hwmon | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
index dccbcdc2dad8..3d5e6142ef0c 100644
--- a/Documentation/ABI/testing/sysfs-class-hwmon
+++ b/Documentation/ABI/testing/sysfs-class-hwmon
@@ -434,12 +434,7 @@ Description:
 		- 0: OK
 		- 1: temperature has reached tempY_crit
 
-		RW
-
-		Contrary to regular alarm flags which clear themselves
-		automatically when read, this one sticks until cleared by
-		the user. This is done by writing 0 to the file. Writing
-		other values is unsupported.
+		RO
 
 What:		/sys/class/hwmon/hwmonX/tempY_crit_hyst
 Description:

-- 
2.39.2

[PATCH 4/4] ABI: sysfs-class-hwmon: document emergency/max/min temperature alarms

[Javier Carrasco]

These attributes are widely used in the hwmon subsystem, but they still
must be documented.

Add tempY_emergency_alarm, tempY_max_alarm and tempY_min_alarm to the
ABI documentation according to their current usage and access rights in
the hwmon subsystem.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
---
 Documentation/ABI/testing/sysfs-class-hwmon | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
index 3d5e6142ef0c..3dac923c9b0e 100644
--- a/Documentation/ABI/testing/sysfs-class-hwmon
+++ b/Documentation/ABI/testing/sysfs-class-hwmon
@@ -381,6 +381,15 @@ Description:
 
 		RW
 
+What:		/sys/class/hwmon/hwmonX/tempY_max_alarm
+Description:
+		Maximum temperature alarm flag.
+
+		- 0: OK
+		- 1: temperature has reached tempY_max
+
+		RO
+
 What:		/sys/class/hwmon/hwmonX/tempY_min
 Description:
 		Temperature min value.
@@ -389,6 +398,15 @@ Description:
 
 		RW
 
+What:		/sys/class/hwmon/hwmonX/tempY_min_alarm
+Description:
+		Minimum temperature alarm flag.
+
+		- 0: OK
+		- 1: temperature has reached tempY_min
+
+		RO
+
 What:		/sys/class/hwmon/hwmonX/tempY_max_hyst
 Description:
 		Temperature hysteresis value for max limit.
@@ -457,6 +475,15 @@ Description:
 
 		RW
 
+What:		/sys/class/hwmon/hwmonX/tempY_emergency_alarm
+Description:
+		Emergency high temperature alarm flag.
+
+		- 0: OK
+		- 1: temperature has reached tempY_emergency
+
+		RO
+
 What:		/sys/class/hwmon/hwmonX/tempY_emergency_hyst
 Description:
 		Temperature hysteresis value for emergency limit.

-- 
2.39.2

Re: [PATCH 1/4] ABI: sysfs-class-hwmon: rearrange humidity attributes alphabetically

[Guenter Roeck]

On Fri, Nov 17, 2023 at 07:40:34AM +0100, Javier Carrasco wrote:
> Preliminary step to add the missing humidity attributes in the ABI
> documentation.
> 
> Adding new elements alphabetically is a common practice that has been
> loosely followed in the sysfs-class-hwmon documentation. Since most of
> the humidity attributes must be added to the file, a single attribute
> needs to be rearranged to reinforce alphabetical order.
> 
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>

Applied.

Thanks,
Guenter

> ---
>  Documentation/ABI/testing/sysfs-class-hwmon | 17 ++++++++---------
>  1 file changed, 8 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
> index 638f4c6d4ec7..b998a42add95 100644
> --- a/Documentation/ABI/testing/sysfs-class-hwmon
> +++ b/Documentation/ABI/testing/sysfs-class-hwmon
> @@ -887,15 +887,6 @@ Description:
>  
>  		RW
>  
> -What:		/sys/class/hwmon/hwmonX/humidityY_input
> -Description:
> -		Humidity
> -
> -		Unit: milli-percent (per cent mille, pcm)
> -
> -		RO
> -
> -
>  What:		/sys/class/hwmon/hwmonX/humidityY_enable
>  Description:
>  		Enable or disable the sensors
> @@ -908,6 +899,14 @@ Description:
>  
>  		RW
>  
> +What:		/sys/class/hwmon/hwmonX/humidityY_input
> +Description:
> +		Humidity
> +
> +		Unit: milli-percent (per cent mille, pcm)
> +
> +		RO
> +
>  What:		/sys/class/hwmon/hwmonX/humidityY_rated_min
>  Description:
>  		Minimum rated humidity.

Re: [PATCH 2/4] ABI: sysfs-class-hwmon: document missing humidity attributes

[Guenter Roeck]

On Fri, Nov 17, 2023 at 07:40:35AM +0100, Javier Carrasco wrote:
> All these attributes already exist and are used by the hwmon subsystem,
> but they still must be documented.
> 
> The missing attributes are the following:
> - humidityY_alarm
> - humidityY_fault
> - humidityY_label
> - humidityY_max
> - humidityY_max_hyst
> - humidityY_min
> - humidityY_min_hyst
> 
> Add the missing humidity attributes to the ABI documentation according
> to their current usage and access rights in the hwmon subsystem.
> 
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>

Applied.

Thanks,
Guenter

Re: [PATCH 3/4] ABI: sysfs-class-hwmon: fix tempY_crit_alarm access rights

[Guenter Roeck]

On Fri, Nov 17, 2023 at 07:40:36AM +0100, Javier Carrasco wrote:
> This attribute is defined as read-only by all drivers that support it.
> 
> It seems that the access rights and description for this attribute were
> copied from the intrusionY_alarm, which has indeed RW rights and must be
> cleared by the user.
> 
> These are the modules that currently use this attribute:
> - adt7x10
> - i5500_temp
> - jc42
> - lm83
> - lm90
> - lm95245
> - max31760
> - max6621
> - mc34vr500
> - tmp401
> - tmp464
> - tmp513
> 
> Fix the attribute description and make it read-only.
> 
> Fixes: 365b5d63a505 ("ABI: sysfs-class-hwmon: add a description for tempY_crit_alarm")
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>

Applied.

Thanks,
Guenter

Re: [PATCH 4/4] ABI: sysfs-class-hwmon: document emergency/max/min temperature alarms

[Guenter Roeck]

On Fri, Nov 17, 2023 at 07:40:37AM +0100, Javier Carrasco wrote:
> These attributes are widely used in the hwmon subsystem, but they still
> must be documented.
> 
> Add tempY_emergency_alarm, tempY_max_alarm and tempY_min_alarm to the
> ABI documentation according to their current usage and access rights in
> the hwmon subsystem.
> 
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>

Applied.

Thanks,
Guenter