[PATCH] hwmon: Add sysfs interface for individual alarm files

Extend the sysfs interface of hardware monitoring chips, by adding
individual alarm and beep files. Contrary to the old aggregated "alarms"
and "beeps" files, individual files constitute a standard way to access
the status information, making it finally possible to implement a
chip-independant hardware monitoring chip access library (once all
drivers have been added this new interface, that is.)

If future drivers need more individual files, the interface will be
extended as needed at the same time these drivers are merged into the
kernel tree.

Signed-off-by: Jean Delvare <khali@linux-fr.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

1 files changed, 73 insertions, 25 deletions

diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface
index 2d16e1e4017..eeb912254db 100644
--- a/Documentation/hwmon/sysfs-interface
+++ b/Documentation/hwmon/sysfs-interface
@@ -252,9 +252,68 @@ curr[1-n]_input	Current input value
 		Read only.
 
 
-*********
-* Other *
-*********
+**********
+* Alarms *
+**********
+
+Each channel or limit may have an associated alarm file, containing a
+boolean value. 1 means than an alarm condition exists, 0 means no alarm.
+
+Usually a given chip will either use channel-related alarms, or
+limit-related alarms, not both. The driver should just reflect the hardware
+implementation.
+
+in[0-n]_alarm
+fan[1-n]_alarm
+temp[1-n]_alarm
+		Channel alarm
+		Boolean
+		Read-only
+
+OR
+
+in[0-n]_min_alarm
+in[0-n]_max_alarm
+fan[1-n]_min_alarm
+temp[1-n]_min_alarm
+temp[1-n]_max_alarm
+temp[1-n]_crit_alarm
+		Limit alarm
+		Boolean
+		Read-only
+
+Each input channel may have an associated fault file. This can be used
+to notify open diodes, unconnected fans etc. where the hardware
+supports it. When this boolean has value 1, the measurement for that
+channel should not be trusted.
+
+in[0-n]_input_fault
+fan[1-n]_input_fault
+temp[1-n]_input_fault
+		Input fault condition
+		Boolean
+		Read-only
+
+Some chips also offer the possibility to get beeped when an alarm occurs:
+
+beep_enable	Master beep enable
+		Boolean
+		Read/Write
+
+in[0-n]_beep
+fan[1-n]_beep
+temp[1-n]_beep
+		Channel beep
+		0 to disable.
+		1 to enable.
+		Read/write
+
+In theory, a chip could provide per-limit beep masking, but no such chip
+was seen so far.
+
+Old drivers provided a different, non-standard interface to alarms and
+beeps. These interface files are deprecated, but will be kept around
+for compatibility reasons:
 
 alarms		Alarm bitmask.
 		Read only.
@@ -265,33 +324,22 @@ alarms		Alarm bitmask.
 		if it is still valid.
 		Generally a direct representation of a chip's internal
 		alarm registers; there is no standard for the position
-		of individual bits.
+		of individual bits. For this reason, the use of this
+		interface file for new drivers is discouraged. Use
+		individual *_alarm and *_fault files instead.
 		Bits are defined in kernel/include/sensors.h.
 
-alarms_in	Alarm bitmask relative to in (voltage) channels
-		Read only
-		A '1' bit means an alarm, LSB corresponds to in0 and so on
-		Prefered to 'alarms' for newer chips
-
-alarms_fan	Alarm bitmask relative to fan channels
-		Read only
-		A '1' bit means an alarm, LSB corresponds to fan1 and so on
-		Prefered to 'alarms' for newer chips
-
-alarms_temp	Alarm bitmask relative to temp (temperature) channels
-		Read only
-		A '1' bit means an alarm, LSB corresponds to temp1 and so on
-		Prefered to 'alarms' for newer chips
-
-beep_enable	Beep/interrupt enable
-		0 to disable.
-		1 to enable.
-		Read/Write
-
 beep_mask	Bitmask for beep.
-		Same format as 'alarms' with the same bit locations.
+		Same format as 'alarms' with the same bit locations,
+		use discouraged for the same reason. Use individual
+		*_beep files instead.
 		Read/Write
 
+
+*********
+* Other *
+*********
+
 eeprom		Raw EEPROM data in binary form.
 		Read only.