Skip to contentSkip to conversation

ABI: sysfs-class-hwmon: document existing attributes

PATCH Applied Javier Carrasco 2 participants 9 messages Nov 17, 2023 – Nov 18, 2023 Hardware monitoring

lore
Share & tools
lore
#0 lore raw

cover ABI: sysfs-class-hwmon: document existing attributes

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.

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

Signature · 1 line
Javier Carrasco <[email protected]>
#1 lore raw

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

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.

---
 Documentation/ABI/testing/sysfs-class-hwmon | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)
Documentation/ABI/testing/sysfs-class-hwmon +8 -9
index 638f4c6d4ec7..b998a42add95 100644
@@ -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.
Signature · 1 line
2.39.2
maintainer Applied
#2 lore raw

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

Quoted 9 lines · 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.

Applied.

Thanks,
Guenter

Quoted 39 lines
---
 Documentation/ABI/testing/sysfs-class-hwmon | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)
Documentation/ABI/testing/sysfs-class-hwmon +8 -9
index 638f4c6d4ec7..b998a42add95 100644
@@ -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.
#3 lore raw

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

In reply to 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.

---
 Documentation/ABI/testing/sysfs-class-hwmon | 69 +++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
Documentation/ABI/testing/sysfs-class-hwmon +69 -0
index b998a42add95..dccbcdc2dad8 100644
@@ -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.
Signature · 1 line
2.39.2
maintainer Applied
#4 lore raw

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

Quoted 12 lines · 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

Quoted 4 lines

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

Applied.

Thanks,
Guenter

#5 lore raw

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

In reply to 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")
---
 Documentation/ABI/testing/sysfs-class-hwmon | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)
Documentation/ABI/testing/sysfs-class-hwmon +1 -6
index dccbcdc2dad8..3d5e6142ef0c 100644
@@ -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:
Signature · 1 line
2.39.2
maintainer Applied
#6 lore raw

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

Quoted 20 lines · 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

Quoted 4 lines

Fix the attribute description and make it read-only.

Fixes 365b5d63a505 ("ABI: sysfs-class-hwmon: add a description for tempY_crit_alarm")

Applied.

Thanks,
Guenter

#7 lore raw

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

In reply to 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.

---
 Documentation/ABI/testing/sysfs-class-hwmon | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
Documentation/ABI/testing/sysfs-class-hwmon +27 -0
index 3d5e6142ef0c..3dac923c9b0e 100644
@@ -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.
Signature · 1 line
2.39.2
maintainer Applied
#8 lore raw

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

Quoted 8 lines · 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.

Applied.

Thanks,
Guenter