| 1 | How to write applications which use our drivers |
|---|
| 2 | ----------------------------------------------- |
|---|
| 3 | |
|---|
| 4 | You have several choices in accessing sensor devices using the |
|---|
| 5 | drivers in our package. This document will briefly |
|---|
| 6 | describe these methods, their advantages and disadvantages, |
|---|
| 7 | and provide examples. |
|---|
| 8 | |
|---|
| 9 | From lowest-level to the highest-level, the access methods are: |
|---|
| 10 | |
|---|
| 11 | 1) Character device access to the i2c bus driver |
|---|
| 12 | via /dev/i2c-x |
|---|
| 13 | 2) I2C bus access functions as defined in <linux/i2c-dev.h> |
|---|
| 14 | 3) /proc access to the chip device driver |
|---|
| 15 | 4) libsensors library |
|---|
| 16 | |
|---|
| 17 | |
|---|
| 18 | Details: |
|---|
| 19 | |
|---|
| 20 | 1. Direct /dev access using ioctls |
|---|
| 21 | ---------------------------------- |
|---|
| 22 | Character device access to the i2c bus driver via ioctls on a /dev |
|---|
| 23 | device. This device could be i2cx, i2c-x, or i2c/x, where x is an |
|---|
| 24 | integer. The ioctls are defined in doc/dev-interface in the |
|---|
| 25 | i2c package or Documentation/i2c/dev-interface in the linux kernel |
|---|
| 26 | sources. |
|---|
| 27 | |
|---|
| 28 | This method does not use a chip device driver at all. |
|---|
| 29 | The driver must set an individual chip address on the bus via |
|---|
| 30 | an ioctl, so it must use locking if multiple devices on the |
|---|
| 31 | bus are being accessed. No access is provided for non-i2c |
|---|
| 32 | busses such as ISA. |
|---|
| 33 | |
|---|
| 34 | For good examples, see prog/detect/i2cdetect.c and |
|---|
| 35 | prog/detect/sensors-detect. |
|---|
| 36 | |
|---|
| 37 | |
|---|
| 38 | 2. Direct /dev access using inline functions |
|---|
| 39 | -------------------------------------------- |
|---|
| 40 | I2C bus access inline functions as defined in <linux/i2c-dev.h> |
|---|
| 41 | and in doc/dev-interface in the i2c package or |
|---|
| 42 | Documentation/i2c/dev-interface in the linux kernel sources. |
|---|
| 43 | |
|---|
| 44 | This method does not use a chip device driver at all. |
|---|
| 45 | The driver must set an individual chip address on the bus via |
|---|
| 46 | an ioctl, so it must use locking if multiple devices on the |
|---|
| 47 | bus are being accessed. No access is provided for non-i2c |
|---|
| 48 | busses such as ISA. |
|---|
| 49 | |
|---|
| 50 | For good examples, see prog/detect/i2cdetect.c, |
|---|
| 51 | prog/dump/i2cdump.c, and prog/dump/i2cset.c. |
|---|
| 52 | |
|---|
| 53 | |
|---|
| 54 | 3. /proc access |
|---|
| 55 | --------------- |
|---|
| 56 | Chip drivers using the i2c-proc module create subdirectories in |
|---|
| 57 | /proc/sys/dev/sensors which can be accessed directly by applications. |
|---|
| 58 | Naming and content standards for the entries in these subdirectories |
|---|
| 59 | is documented in the file doc/developers/proc. Note that these |
|---|
| 60 | standards are only loosely followed. |
|---|
| 61 | |
|---|
| 62 | If a new driver adheres to these standards then an application may |
|---|
| 63 | be able to support new devices on-the-fly. |
|---|
| 64 | |
|---|
| 65 | /proc access provides a method to read and write sensor values |
|---|
| 66 | for any driver using i2c-proc, including ISA chip drivers. |
|---|
| 67 | |
|---|
| 68 | This method also works well for shell and perl scripts |
|---|
| 69 | written to access a specific device. Note that i2c-proc is |
|---|
| 70 | standard in the kernel as of kernel 2.4.13. |
|---|
| 71 | |
|---|
| 72 | Note that most drivers provide only raw sensor readings via /proc; |
|---|
| 73 | many readings must be scaled or adjusted, and these adjustments |
|---|
| 74 | must often be changed by the user. An application using /proc must |
|---|
| 75 | generally provide adjustment facilities and the requirements |
|---|
| 76 | of the adjustments can be quite complex. If you need adjustment |
|---|
| 77 | facilities, consider the libsensors library, below. |
|---|
| 78 | |
|---|
| 79 | For examples of programs using /proc accesses, see |
|---|
| 80 | prog/eeprom/decode-dimms.pl, prog/matorb/displayit.pl, |
|---|
| 81 | prog/maxilife/writelcd.sh, prog/rrd/sens_update_rrd. |
|---|
| 82 | Also search freshmeat for sensors applications. |
|---|
| 83 | |
|---|
| 84 | |
|---|
| 85 | 4. libsensors library |
|---|
| 86 | --------------------- |
|---|
| 87 | The libsensors library provides standardized access to all chip drivers. |
|---|
| 88 | It also provides a translation layer with settings in /etc/sensors.conf |
|---|
| 89 | so that your application sees adjusted (scaled) values using settings |
|---|
| 90 | provided by the user. Other facilities are sensor renaming, limit setting, |
|---|
| 91 | and ignoring individual sensors. |
|---|
| 92 | |
|---|
| 93 | Unfortunately there is no documentation for libsensors. See the |
|---|
| 94 | 'sensors' application in prog/sensors for an example. The source |
|---|
| 95 | for libsensors is in the lib/ directory. Another example |
|---|
| 96 | is in prog/sensord. Also search freshmeat for sensors applications. |
|---|
| 97 | |
|---|
| 98 | One other limitation of libsensors is that it is relatively |
|---|
| 99 | cumbersome to add support for new devices. |
|---|
| 100 | |
|---|
| 101 | Note that libsensors falls under the GPL, not the LGPL. |
|---|
| 102 | In more human language, that means it is FORBIDDEN to link any application |
|---|
| 103 | to the library, even to the shared version, if the application itself |
|---|
| 104 | does not fall under the GPL. This may or may not be changed in the future. |
|---|
| 105 | Contact us if you wish to discuss your application. |
|---|
