diff --git a/doc/developers/applications b/doc/developers/applications new file mode 100644 index 00000000..291601d0 --- /dev/null +++ b/doc/developers/applications @@ -0,0 +1,105 @@ +How to write applications which use our 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. + +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) /proc access to the chip device driver + 4) libsensors library + + +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. + 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 prog/detect/i2cdetect.c 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. + + This method does not use a chip device driver at all. + 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 prog/detect/i2cdetect.c, + prog/dump/i2cdump.c, and prog/dump/i2cset.c. + + +3. /proc access +--------------- + Chip drivers using the i2c-proc module create subdirectories in + /proc/sys/dev/sensors which can be accessed directly by applications. + Naming and content standards for the entries in these subdirectories + is documented in the file doc/developers/proc. Note that these + standards are only loosely followed. + + If a new driver adheres to these standards then an application may + be able to support new devices on-the-fly. + + /proc access provides a method to read and write sensor values + for any driver using i2c-proc, including ISA chip drivers. + + This method also works well for shell and perl scripts + written to access a specific device. Note that i2c-proc is + standard in the kernel as of kernel 2.4.13. + + Note that most drivers provide only raw sensor readings via /proc; + many readings must be scaled or adjusted, and these adjustments + must often be changed by the user. An application using /proc 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. + + For examples of programs using /proc accesses, see + prog/eeprom/decode-dimms.pl, prog/matorb/displayit.pl, + prog/maxilife/writelcd.sh, prog/rrd/sens_update_rrd. + Also search freshmeat for sensors applications. + + +4. 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. + + Unfortunately there is no 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. + + Note that libsensors falls under the GPL, not the LGPL. + In more human language, that means it is FORBIDDEN to link any application + to the library, even to the shared version, if the application itself + 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.