add brief guide for applications developers

git-svn-id: http://lm-sensors.org/svn/lm-sensors/trunk@1302 7894878c-1315-0410-8ee3-d5d059ff63e0

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 <linux/i2c-dev.h>
+	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 <linux/i2c-dev.h>
+   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.