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.