root/lm-sensors/trunk/doc/developers/applications @ 2142

Revision 2142, 6.7 KB (checked in by mds, 10 years ago)

2.6 update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1How to write applications which use our drivers
2-----------------------------------------------
3
4You have several choices in accessing sensor devices using the
5drivers in our package. This document will briefly
6describe these methods, their advantages and disadvantages,
7and provide examples.
8
9From 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 kernel/include/i2c-dev.h
14        3A) /proc access to the chip device driver
15        3B) sysfs access to the chip device driver
16        4) libsensors library
17        5) sensors program
18
19
20Details:
21
221. Direct /dev access using ioctls
23----------------------------------
24   Character device access to the i2c bus driver via ioctls on a /dev
25   device. This device could be i2cx, i2c-x, or i2c/x, where x is an
26   integer. The ioctls are defined in doc/dev-interface in the
27   i2c package or Documentation/i2c/dev-interface in the linux kernel
28   sources.
29
30   This method does not use a chip device driver at all.
31   However it does require the i2c-dev module.
32   The driver must set an individual chip address on the bus via
33   an ioctl, so it must use locking if multiple devices on the
34   bus are being accessed. No access is provided for non-i2c
35   busses such as ISA.
36
37   For good examples, see prog/detect/i2cdetect.c and
38   prog/detect/sensors-detect.
39
40
412. Direct /dev access using inline functions
42--------------------------------------------
43   I2C bus access inline functions as defined in kernel/include/i2c-dev.h,
44   and in doc/dev-interface in the i2c package or
45   Documentation/i2c/dev-interface in the linux kernel sources.
46   Note that these used to be defined in <linux/i2c-dev.h> in the kernel
47   source tree. However, userspace applications are not supposed to     
48   include kernel headers, so the inline functions were removed from
49   the kernel file in recent kernels. Use the header file in this package
50   instead.
51
52   This method does not use a chip device driver at all.
53   However it does require the i2c-dev module.
54   The driver must set an individual chip address on the bus via
55   an ioctl, so it must use locking if multiple devices on the
56   bus are being accessed. No access is provided for non-i2c
57   busses such as ISA.
58
59   For good examples, see prog/detect/i2cdetect.c,
60   prog/dump/i2cdump.c, and prog/dump/i2cset.c.
61
62
633A. /proc access (2.4 kernels)
64-----------------------------
65   Chip drivers using the i2c-proc module create subdirectories in
66   /proc/sys/dev/sensors which can be accessed directly by applications.
67   Naming and content standards for the entries in these subdirectories
68   is documented in the file doc/developers/proc. Note that these
69   standards may not be strictly followed.
70
71   If a new driver adheres to these standards then an application may
72   be able to support new devices on-the-fly.
73
74   /proc access provides a method to read and write sensor values
75   for any driver using i2c-proc, including ISA chip drivers.
76
77   This method also works well for shell and perl scripts
78   written to access a specific device. Note that i2c-proc is
79   standard in the kernel as of kernel 2.4.13.
80
81   Note that most drivers provide only raw sensor readings via /proc;
82   many readings must be scaled or adjusted, and these adjustments
83   must often be changed by the user. An application using /proc must
84   generally provide adjustment facilities and the requirements
85   of the adjustments can be quite complex. If you need adjustment
86   facilities, consider the libsensors library, below.
87
88   For examples of programs using /proc accesses, see
89   prog/eeprom/decode-dimms.pl, prog/matorb/displayit.pl,
90   prog/maxilife/writelcd.sh, prog/rrd/sens_update_rrd,
91   prog/pwm/fancontrol, and prog/pwm/pwmconfig.
92   Also search freshmeat for sensors applications.
93
94
953B. sysfs access (2.6 kernels)
96------------------------------
97   Chip drivers using the i2c-sensor module create subdirectories in
98   the sysfs filesystem (usually /sys) which can be accessed
99   directly by applications.
100   Naming and content standards for the entries in these subdirectories
101   is documented in the file Documentation/i2c/sysfs-interface in the
102   2.6 kernel source tree. Note that these standards may not be
103   strictly followed.
104
105   If a new driver adheres to these standards then an application may
106   be able to support new devices on-the-fly.
107
108   sysfs access provides a method to read and write sensor values
109   for any driver using i2c-sensor, including ISA chip drivers.
110
111   This method may also works well for shell and perl scripts
112   written to access a specific device. Note that sysfs is
113   standard in 2.6 kernels.
114
115   Note that most drivers provide only raw sensor readings via /sys;
116   many readings must be scaled or adjusted, and these adjustments
117   must often be changed by the user. An application using /proc must
118   generally provide adjustment facilities and the requirements
119   of the adjustments can be quite complex. If you need adjustment
120   facilities, consider the libsensors library, below.
121
122   For an examples of a program using /sys accesses, see gkrellm.
123   See also lib/proc.c and prog/dump/i2cbusses.c for examples.
124   The sysfsutils package may also be helpful.
125   Also search freshmeat for sensors and sysfs applications.
126
127
1284. libsensors library
129---------------------
130   The libsensors library provides standardized access to all chip drivers.
131   It also provides a translation layer with settings in /etc/sensors.conf
132   so that your application sees adjusted (scaled) values using settings
133   provided by the user. Other facilities are sensor renaming, limit setting,
134   and ignoring individual sensors.
135   The libsensors library supports both 2.4 and 2.6 kernels.
136
137   Unfortunately there is little documentation for libsensors. See the
138   'sensors' application in prog/sensors for an example. The source
139   for libsensors is in the lib/ directory. Another example
140   is in prog/sensord. Also search freshmeat for sensors applications.
141
142   One other limitation of libsensors is that it is relatively
143   cumbersome to add support for new devices.
144
145   Note that libsensors falls under the GPL, not the LGPL.
146   In more human language, that means it is FORBIDDEN to link any application
147   to the library, even to the shared version, if the application itself
148   does not fall under the GPL. This may or may not be changed in the future.
149   Contact us if you wish to discuss your application.
150
151   For an examples of a program using libsensors accesses, see
152   prog/sensors/sensors. Also search freshmeat for sensors applications.
153
1545. sensors program
155------------------
156   The 'sensors' program is a text-based application that uses libsensors.
157   The output is fairly standardized; therefore this output could be
158   used by other applications.
159   One simple method is 'sensors|grep ALARM'.
Note: See TracBrowser for help on using the browser.