diff --git a/CHANGES b/CHANGES index e5ce9aa0..7a88ebc0 100644 --- a/CHANGES +++ b/CHANGES @@ -2,6 +2,7 @@ lm-sensors CHANGES file ----------------------- SVN + documentation: Update the application writing guidelines Makefile: No warnings about ld configuration for staged installations sensors-detect: Drop PCA9540 detection diff --git a/doc/developers/applications b/doc/developers/applications index d928dd53..6cbfd731 100644 --- a/doc/developers/applications +++ b/doc/developers/applications @@ -1,113 +1,53 @@ -How to write applications which use our drivers ------------------------------------------------ +How to write applications which use the hwmon drivers +===================================================== -You have several choices in accessing sensor devices using the -drivers in our package. This document will briefly -describe these methods, their advantages and disadvantages, -and provide examples. +You have several choices in accessing sensor devices using the hwmon drivers. +This document will briefly describe these methods, their advantages and +disadvantages, and provide examples. From lowest-level to the highest-level, the access methods are: - 1) Character device access to the i2c bus driver - via /dev/i2c-x - 2) I2C bus access functions as defined in - 3) sysfs access to the chip device driver - 4) libsensors library - 5) sensors program + 1. sysfs access + 2. libsensors library + 3. sensors program Details: -1. Direct /dev access using ioctls ----------------------------------- - Character device access to the i2c bus driver via ioctls on a /dev - device. This device could be i2cx, i2c-x, or i2c/x, where x is an - integer. The ioctls are defined in doc/dev-interface in the - i2c package or Documentation/i2c/dev-interface in the linux kernel - sources. - - This method does not use a chip device driver at all. - However it does require the i2c-dev module. - The driver must set an individual chip address on the bus via - an ioctl, so it must use locking if multiple devices on the - bus are being accessed. No access is provided for non-i2c - busses such as ISA. - - For good examples, see i2cdetect.c (in the i2c-tools package) and - prog/detect/sensors-detect. - - -2. Direct /dev access using inline functions --------------------------------------------- - I2C bus access inline functions as defined in , - and in doc/dev-interface in the i2c package or - Documentation/i2c/dev-interface in the linux kernel sources. - Note that these used to be defined in in the kernel - source tree. However, userspace applications are not supposed to - include kernel headers, so the inline functions were removed from - the kernel file in recent kernels. Use the header file from the - i2c-tools package instead. - - This method does not use a chip device driver at all. - However it does require the i2c-dev module. - The driver must set an individual chip address on the bus via - an ioctl, so it must use locking if multiple devices on the - bus are being accessed. No access is provided for non-i2c - busses such as ISA. - - For good examples, see i2cdetect.c, i2cdump.c, and i2cset.c (all in the - i2c-tools package). - - -3. sysfs access +1. sysfs access --------------- - Chip drivers using the i2c-sensor module create subdirectories in - the sysfs filesystem (usually /sys) which can be accessed - directly by applications. + Hwmon drivers create subdirectories in the sysfs filesystem (usually /sys) + which can be accessed directly by applications. Naming and content standards for the entries in these subdirectories - is documented in the file Documentation/i2c/sysfs-interface in the - 2.6 kernel source tree. Note that these standards may not be - strictly followed. - - If a new driver adheres to these standards then an application may - be able to support new devices on-the-fly. - - sysfs access provides a method to read and write sensor values - for any driver, including ISA chip drivers. - - This method may also works well for shell and perl scripts - written to access a specific device. Note that sysfs is - standard in 2.6 kernels. + are documented in the file Documentation/hwmon/sysfs-interface in the 2.6 + kernel source tree. sysfs is the lowest-level access to sensor values. Note that most drivers provide only raw sensor readings via /sys; many readings must be scaled or adjusted, and these adjustments must often be changed by the user. An application using /sys must generally provide adjustment facilities and the requirements - of the adjustments can be quite complex. If you need adjustment - facilities, consider the libsensors library, below. + of the adjustments can be quite complex. For this reason, this + approach isn't recommended. Instead, consider the libsensors library, + which offers a higher-level interface on top of sysfs (see below.) - For an examples of a program using /sys accesses, see gkrellm. - See also lib/proc.c and i2cbusses.c (in the i2c-tools package) for - examples. The sysfsutils package may also be helpful. - Also search freshmeat for sensors and sysfs applications. + Still, this method may work well for shell and perl scripts written to + access a specific device. + For an example of a program using /sys accesses, see gkrellm (though + recent versions use libsensors instead.) See also lib/sysfs.c. -4. libsensors library +2. libsensors library --------------------- The libsensors library provides standardized access to all chip drivers. It also provides a translation layer with settings in /etc/sensors.conf so that your application sees adjusted (scaled) values using settings - provided by the user. Other facilities are sensor renaming, limit setting, - and ignoring individual sensors. - The libsensors library supports both 2.4 and 2.6 kernels. + provided by the user. Other facilities are sensor labelling, limit setting, + and ignoring individual sensors. This is the recommended way to access + the sensor chips. - Unfortunately there is little documentation for libsensors. See the - 'sensors' application in prog/sensors for an example. The source - for libsensors is in the lib/ directory. Another example - is in prog/sensord. Also search freshmeat for sensors applications. - - One other limitation of libsensors is that it is relatively - cumbersome to add support for new devices. + The library API is documented in the libsensors(3) manual page. The + configuration file format is documented in the sensors.conf(5) manual + page. Note that libsensors falls under the GPL, not the LGPL. In more human language, that means it is FORBIDDEN to link any application @@ -115,12 +55,16 @@ Details: does not fall under the GPL. This may or may not be changed in the future. Contact us if you wish to discuss your application. - For an examples of a program using libsensors accesses, see - prog/sensors/sensors. Also search freshmeat for sensors applications. + For examples of programs using libsensors accesses, see prog/sensors and + prog/sensord. -5. sensors program +3. sensors program ------------------ The 'sensors' program is a text-based application that uses libsensors. The output is fairly standardized; therefore this output could be used by other applications. One simple method is 'sensors|grep ALARM'. + Note though that there is no guarantee that the output format won't change + in the future, so be careful. We might improve the command-line interface + of 'sensors' someday to make it more convenient for external programs to + use it as a back-end.