[lm-sensors] [PATCH] hwmon: Update the sysfs interface documentation

[lm-sensors] [PATCH] hwmon: Update the sysfs interface documentation

[Jean Delvare]

* Document the name attribute.
* Document the *_label attributes.
* Drop "typical usage" lists, they no longer match the reality.
* Drop non hardware-monitoring related entries.

Signed-off-by: Jean Delvare <khali@linux-fr.org>
---
 Documentation/hwmon/sysfs-interface |   75 +++++++++++++++++++----------------
 1 file changed, 41 insertions(+), 34 deletions(-)

--- linux-2.6.23-rc3.orig/Documentation/hwmon/sysfs-interface	2007-08-19 12:04:41.000000000 +0200
+++ linux-2.6.23-rc3/Documentation/hwmon/sysfs-interface	2007-08-20 16:41:06.000000000 +0200
@@ -78,8 +78,21 @@ RW	read/write value
 Read/write values may be read-only for some chips, depending on the
 hardware implementation.
 
-All entries are optional, and should only be created in a given driver
-if the chip has the feature.
+All entries (except name) are optional, and should only be created in a
+given driver if the chip has the feature.
+
+
+********
+* Name *
+********
+
+name		The chip name.
+		This should be a short, lowercase string, not containing
+		spaces nor dashes, representing the chip name. This is
+		the only mandatory attribute.
+		I2C devices get this attribute created automatically.
+		RO
+
 
 ************
 * Voltages *
@@ -104,18 +117,17 @@ in[0-*]_input	Voltage input value.
 		by the chip driver, and must be done by the application.
 		However, some drivers (notably lm87 and via686a)
 		do scale, because of internal resistors built into a chip.
-		These drivers will output the actual voltage.
-
-		Typical usage:
-			in0_*	CPU #1 voltage (not scaled)
-			in1_*	CPU #2 voltage (not scaled)
-			in2_*	3.3V nominal (not scaled)
-			in3_*	5.0V nominal (scaled)
-			in4_*	12.0V nominal (scaled)
-			in5_*	-12.0V nominal (scaled)
-			in6_*	-5.0V nominal (scaled)
-			in7_*	varies
-			in8_*	varies
+		These drivers will output the actual voltage. Rule of
+		thumb: drivers should report the voltage values at their
+		pins.
+
+in[0-*]_label	Suggested voltage channel label.
+		Text string
+		Should only be created if the driver has hints about what
+		this voltage channel is being used for, and user-space
+		doesn't. In all other cases, the label is provided by
+		user-space.
+		RO
 
 cpu[0-*]_vid	CPU core reference voltage.
 		Unit: millivolt
@@ -159,6 +171,13 @@ fan[1-*]_target
 		Only makes sense if the chip supports closed-loop fan speed
 		control based on the measured fan speed.
 
+fan[1-*]_label	Suggested fan channel label.
+		Text string
+		Should only be created if the driver has hints about what
+		this fan channel is being used for, and user-space doesn't.
+		In all other cases, the label is provided by user-space.
+		RO
+
 Also see the Alarms section for status flags associated with fans.
 
 
@@ -260,18 +279,19 @@ temp[1-*]_crit_hyst
 		from the critical value.
 		RW
 
-temp[1-4]_offset
+temp[1-*]_offset
 		Temperature offset which is added to the temperature reading
 		by the chip.
 		Unit: millidegree Celsius
 		Read/Write value.
 
-		If there are multiple temperature sensors, temp1_* is
-		generally the sensor inside the chip itself,
-		reported as "motherboard temperature".  temp2_* to
-		temp4_* are generally sensors external to the chip
-		itself, for example the thermal diode inside the CPU or
-		a thermistor nearby.
+temp[1-*]_label	Suggested temperature channel label.
+		Text string
+		Should only be created if the driver has hints about what
+		this temperature channel is being used for, and user-space
+		doesn't. In all other cases, the label is provided by
+		user-space.
+		RO
 
 Some chips measure temperature using external thermistors and an ADC, and
 report the temperature measurement as a voltage. Converting this voltage
@@ -391,16 +411,3 @@ beep_mask	Bitmask for beep.
 		use discouraged for the same reason. Use individual
 		*_beep files instead.
 		RW
-
-
-*********
-* Other *
-*********
-
-eeprom		Raw EEPROM data in binary form.
-		RO
-
-pec		Enable or disable PEC (SMBus only)
-		0: disable
-		1: enable
-		RW


-- 
Jean Delvare

_______________________________________________
lm-sensors mailing list
lm-sensors@lm-sensors.org
http://lists.lm-sensors.org/mailman/listinfo/lm-sensors

Re: [lm-sensors] [PATCH] hwmon: Update the sysfs interface

[Hans de Goede]

Jean Delvare wrote:
> * Document the name attribute.
> * Document the *_label attributes.
> * Drop "typical usage" lists, they no longer match the reality.
> * Drop non hardware-monitoring related entries.
> 
> Signed-off-by: Jean Delvare <khali@linux-fr.org>

Looks good to me"
Acked-by: Hans de Goede <j.w.r.degoede@hhs.nl>

Regards,

Hans

> ---
>  Documentation/hwmon/sysfs-interface |   75 +++++++++++++++++++----------------
>  1 file changed, 41 insertions(+), 34 deletions(-)
> 
> --- linux-2.6.23-rc3.orig/Documentation/hwmon/sysfs-interface	2007-08-19 12:04:41.000000000 +0200
> +++ linux-2.6.23-rc3/Documentation/hwmon/sysfs-interface	2007-08-20 16:41:06.000000000 +0200
> @@ -78,8 +78,21 @@ RW	read/write value
>  Read/write values may be read-only for some chips, depending on the
>  hardware implementation.
>  
> -All entries are optional, and should only be created in a given driver
> -if the chip has the feature.
> +All entries (except name) are optional, and should only be created in a
> +given driver if the chip has the feature.
> +
> +
> +********
> +* Name *
> +********
> +
> +name		The chip name.
> +		This should be a short, lowercase string, not containing
> +		spaces nor dashes, representing the chip name. This is
> +		the only mandatory attribute.
> +		I2C devices get this attribute created automatically.
> +		RO
> +
>  
>  ************
>  * Voltages *
> @@ -104,18 +117,17 @@ in[0-*]_input	Voltage input value.
>  		by the chip driver, and must be done by the application.
>  		However, some drivers (notably lm87 and via686a)
>  		do scale, because of internal resistors built into a chip.
> -		These drivers will output the actual voltage.
> -
> -		Typical usage:
> -			in0_*	CPU #1 voltage (not scaled)
> -			in1_*	CPU #2 voltage (not scaled)
> -			in2_*	3.3V nominal (not scaled)
> -			in3_*	5.0V nominal (scaled)
> -			in4_*	12.0V nominal (scaled)
> -			in5_*	-12.0V nominal (scaled)
> -			in6_*	-5.0V nominal (scaled)
> -			in7_*	varies
> -			in8_*	varies
> +		These drivers will output the actual voltage. Rule of
> +		thumb: drivers should report the voltage values at their
> +		pins.
> +
> +in[0-*]_label	Suggested voltage channel label.
> +		Text string
> +		Should only be created if the driver has hints about what
> +		this voltage channel is being used for, and user-space
> +		doesn't. In all other cases, the label is provided by
> +		user-space.
> +		RO
>  
>  cpu[0-*]_vid	CPU core reference voltage.
>  		Unit: millivolt
> @@ -159,6 +171,13 @@ fan[1-*]_target
>  		Only makes sense if the chip supports closed-loop fan speed
>  		control based on the measured fan speed.
>  
> +fan[1-*]_label	Suggested fan channel label.
> +		Text string
> +		Should only be created if the driver has hints about what
> +		this fan channel is being used for, and user-space doesn't.
> +		In all other cases, the label is provided by user-space.
> +		RO
> +
>  Also see the Alarms section for status flags associated with fans.
>  
>  
> @@ -260,18 +279,19 @@ temp[1-*]_crit_hyst
>  		from the critical value.
>  		RW
>  
> -temp[1-4]_offset
> +temp[1-*]_offset
>  		Temperature offset which is added to the temperature reading
>  		by the chip.
>  		Unit: millidegree Celsius
>  		Read/Write value.
>  
> -		If there are multiple temperature sensors, temp1_* is
> -		generally the sensor inside the chip itself,
> -		reported as "motherboard temperature".  temp2_* to
> -		temp4_* are generally sensors external to the chip
> -		itself, for example the thermal diode inside the CPU or
> -		a thermistor nearby.
> +temp[1-*]_label	Suggested temperature channel label.
> +		Text string
> +		Should only be created if the driver has hints about what
> +		this temperature channel is being used for, and user-space
> +		doesn't. In all other cases, the label is provided by
> +		user-space.
> +		RO
>  
>  Some chips measure temperature using external thermistors and an ADC, and
>  report the temperature measurement as a voltage. Converting this voltage
> @@ -391,16 +411,3 @@ beep_mask	Bitmask for beep.
>  		use discouraged for the same reason. Use individual
>  		*_beep files instead.
>  		RW
> -
> -
> -*********
> -* Other *
> -*********
> -
> -eeprom		Raw EEPROM data in binary form.
> -		RO
> -
> -pec		Enable or disable PEC (SMBus only)
> -		0: disable
> -		1: enable
> -		RW
> 
> 


_______________________________________________
lm-sensors mailing list
lm-sensors@lm-sensors.org
http://lists.lm-sensors.org/mailman/listinfo/lm-sensors

Re: [lm-sensors] [PATCH] hwmon: Update the sysfs interface

[Mark M. Hoffman]

* Hans de Goede <j.w.r.degoede@hhs.nl> [2007-08-20 22:51:07 +0200]:
> Jean Delvare wrote:
> >* Document the name attribute.
> >* Document the *_label attributes.
> >* Drop "typical usage" lists, they no longer match the reality.
> >* Drop non hardware-monitoring related entries.
> >
> >Signed-off-by: Jean Delvare <khali@linux-fr.org>
> 
> Looks good to me"
> Acked-by: Hans de Goede <j.w.r.degoede@hhs.nl>

Applied to hwmon-2.6.git/testing, with one small change...

> >+		These drivers will output the actual voltage. Rule of
> >+		thumb: drivers should report the voltage values at their
> >+		pins.

Drivers don't have pins, chips do.  Also, quote pins so as to include pads,
balls, etc... whatever the actual external connection might be.

+               These drivers will output the actual voltage. Rule of
+               thumb: drivers should report the voltage values at the
+               "pins" of the chip.

Thanks,

-- 
Mark M. Hoffman
mhoffman@lightlink.com


_______________________________________________
lm-sensors mailing list
lm-sensors@lm-sensors.org
http://lists.lm-sensors.org/mailman/listinfo/lm-sensors

Re: [lm-sensors] [PATCH] hwmon: Update the sysfs interface

[Jean Delvare]

On Sun, 26 Aug 2007 14:50:41 -0400, Mark M. Hoffman wrote:
> * Hans de Goede <j.w.r.degoede@hhs.nl> [2007-08-20 22:51:07 +0200]:
> > Jean Delvare wrote:
> > >* Document the name attribute.
> > >* Document the *_label attributes.
> > >* Drop "typical usage" lists, they no longer match the reality.
> > >* Drop non hardware-monitoring related entries.
> > >
> > >Signed-off-by: Jean Delvare <khali@linux-fr.org>
> > 
> > Looks good to me"
> > Acked-by: Hans de Goede <j.w.r.degoede@hhs.nl>
> 
> Applied to hwmon-2.6.git/testing, with one small change...
> 
> > >+		These drivers will output the actual voltage. Rule of
> > >+		thumb: drivers should report the voltage values at their
> > >+		pins.
> 
> Drivers don't have pins, chips do.  Also, quote pins so as to include pads,
> balls, etc... whatever the actual external connection might be.
> 
> +               These drivers will output the actual voltage. Rule of
> +               thumb: drivers should report the voltage values at the
> +               "pins" of the chip.

Good catch, thanks for the fix.

-- 
Jean Delvare

_______________________________________________
lm-sensors mailing list
lm-sensors@lm-sensors.org
http://lists.lm-sensors.org/mailman/listinfo/lm-sensors

[lm-sensors] [PATCH] hwmon: Update the sysfs interface documentation

[Jean Delvare]

* Document the characteristics of libsensors 3.0.0 and 3.0.1.
* The sysfs interface is no longer subject to changes.

Signed-off-by: Jean Delvare <khali@linux-fr.org>
---
 Documentation/hwmon/sysfs-interface |   33 +++++++++++++--------------------
 1 file changed, 13 insertions(+), 20 deletions(-)

--- linux-2.6.25-rc2.orig/Documentation/hwmon/sysfs-interface	2008-01-25 10:26:47.000000000 +0100
+++ linux-2.6.25-rc2/Documentation/hwmon/sysfs-interface	2008-02-23 10:47:34.000000000 +0100
@@ -2,17 +2,12 @@ Naming and data format standards for sys
 ------------------------------------------------
 
 The libsensors library offers an interface to the raw sensors data
-through the sysfs interface. See libsensors documentation and source for
-further information. As of writing this document, libsensors
-(from lm_sensors 2.8.3) is heavily chip-dependent. Adding or updating
-support for any given chip requires modifying the library's code.
-This is because libsensors was written for the procfs interface
-older kernel modules were using, which wasn't standardized enough.
-Recent versions of libsensors (from lm_sensors 2.8.2 and later) have
-support for the sysfs interface, though.
-
-The new sysfs interface was designed to be as chip-independent as
-possible.
+through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
+completely chip-independent. It assumes that all the kernel drivers
+implement the standard sysfs interface described in this document.
+This makes adding or updating support for any given chip very easy, as
+libsensors, and applications using it, do not need to be modified.
+This is a major improvement compared to lm-sensors 2.
 
 Note that motherboards vary widely in the connections to sensor chips.
 There is no standard that ensures, for example, that the second
@@ -35,19 +30,17 @@ access this data in a simple and consist
 will have to implement conversion, labeling and hiding of inputs. For
 this reason, it is still not recommended to bypass the library.
 
-If you are developing a userspace application please send us feedback on
-this standard.
-
-Note that this standard isn't completely established yet, so it is subject
-to changes. If you are writing a new hardware monitoring driver those
-features can't seem to fit in this interface, please contact us with your
-extension proposal. Keep in mind that backward compatibility must be
-preserved.
-
 Each chip gets its own directory in the sysfs /sys/devices tree.  To
 find all sensor chips, it is easier to follow the device symlinks from
 /sys/class/hwmon/hwmon*.
 
+Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
+in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
+in the hwmon "class" device directory are also supported. Complex drivers
+(e.g. drivers for multifunction chips) may want to use this possibility to
+avoid namespace pollution. The only drawback will be that older versions of
+libsensors won't support the driver in question.
+
 All sysfs values are fixed point numbers.
 
 There is only one value per file, unlike the older /proc specification.


-- 
Jean Delvare

_______________________________________________
lm-sensors mailing list
lm-sensors@lm-sensors.org
http://lists.lm-sensors.org/mailman/listinfo/lm-sensors

Re: [lm-sensors] [PATCH] hwmon: Update the sysfs interface

[Juerg Haefliger]

Looks good.

Acked-by: Juerg Haefliger <juergh at gmail.com>


> * Document the characteristics of libsensors 3.0.0 and 3.0.1.
>  * The sysfs interface is no longer subject to changes.
>
>  Signed-off-by: Jean Delvare <khali at linux-fr.org>
>  ---
>   Documentation/hwmon/sysfs-interface |   33 +++++++++++++--------------------
>   1 file changed, 13 insertions(+), 20 deletions(-)
>
>  --- linux-2.6.25-rc2.orig/Documentation/hwmon/sysfs-interface   2008-01-25
>  10:26:47.000000000 +0100
>  +++ linux-2.6.25-rc2/Documentation/hwmon/sysfs-interface        2008-02-23
>  10:47:34.000000000 +0100
>  @@ -2,17 +2,12 @@ Naming and data format standards for sys
>   ------------------------------------------------
>
>   The libsensors library offers an interface to the raw sensors data
>  -through the sysfs interface. See libsensors documentation and source for
>  -further information. As of writing this document, libsensors
>  -(from lm_sensors 2.8.3) is heavily chip-dependent. Adding or updating
>  -support for any given chip requires modifying the library's code.
>  -This is because libsensors was written for the procfs interface
>  -older kernel modules were using, which wasn't standardized enough.
>  -Recent versions of libsensors (from lm_sensors 2.8.2 and later) have
>  -support for the sysfs interface, though.
>  -
>  -The new sysfs interface was designed to be as chip-independent as
>  -possible.
>  +through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
>  +completely chip-independent. It assumes that all the kernel drivers
>  +implement the standard sysfs interface described in this document.
>  +This makes adding or updating support for any given chip very easy, as
>  +libsensors, and applications using it, do not need to be modified.
>  +This is a major improvement compared to lm-sensors 2.
>
>   Note that motherboards vary widely in the connections to sensor chips.
>   There is no standard that ensures, for example, that the second
>  @@ -35,19 +30,17 @@ access this data in a simple and consist
>   will have to implement conversion, labeling and hiding of inputs. For
>   this reason, it is still not recommended to bypass the library.
>
>  -If you are developing a userspace application please send us feedback on
>  -this standard.
>  -
>  -Note that this standard isn't completely established yet, so it is subject
>  -to changes. If you are writing a new hardware monitoring driver those
>  -features can't seem to fit in this interface, please contact us with your
>  -extension proposal. Keep in mind that backward compatibility must be
>  -preserved.
>  -
>   Each chip gets its own directory in the sysfs /sys/devices tree.  To
>   find all sensor chips, it is easier to follow the device symlinks from
>   /sys/class/hwmon/hwmon*.
>
>  +Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
>  +in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
>  +in the hwmon "class" device directory are also supported. Complex drivers
>  +(e.g. drivers for multifunction chips) may want to use this possibility to
>  +avoid namespace pollution. The only drawback will be that older versions of
>  +libsensors won't support the driver in question.
>  +
>   All sysfs values are fixed point numbers.
>
>   There is only one value per file, unlike the older /proc specification.
>
>
>  --
>  Jean Delvare
>

_______________________________________________
lm-sensors mailing list
lm-sensors@lm-sensors.org
http://lists.lm-sensors.org/mailman/listinfo/lm-sensors

Re: [lm-sensors] [PATCH] hwmon: Update the sysfs interface

[Mark M. Hoffman]

Hi:

* Juerg Haefliger <juergh@gmail.com> [2008-04-09 10:16:50 -0700]:
> Looks good.
> 
> Acked-by: Juerg Haefliger <juergh at gmail.com>
> 
> 
> > * Document the characteristics of libsensors 3.0.0 and 3.0.1.
> >  * The sysfs interface is no longer subject to changes.
> >
> >  Signed-off-by: Jean Delvare <khali at linux-fr.org>
> >  ---
> >   Documentation/hwmon/sysfs-interface |   33 +++++++++++++--------------------
> >   1 file changed, 13 insertions(+), 20 deletions(-)

Applied to hwmon-2.6.git/testing, thanks.

-- 
Mark M. Hoffman
mhoffman@lightlink.com


_______________________________________________
lm-sensors mailing list
lm-sensors@lm-sensors.org
http://lists.lm-sensors.org/mailman/listinfo/lm-sensors