mirror of
https://github.com/lm-sensors/lm-sensors
synced 2025-09-08 18:25:14 +00:00
e554056734
git-svn-id: http://lm-sensors.org/svn/lm-sensors/trunk@2142 7894878c-1315-0410-8ee3-d5d059ff63e0
160 lines
6.7 KiB
Plaintext
160 lines
6.7 KiB
Plaintext
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 kernel/include/i2c-dev.h
|
|
3A) /proc access to the chip device driver
|
|
3B) sysfs access to the chip device driver
|
|
4) libsensors library
|
|
5) sensors program
|
|
|
|
|
|
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.
|
|
However it does require the i2c-dev module.
|
|
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 kernel/include/i2c-dev.h,
|
|
and in doc/dev-interface in the i2c package or
|
|
Documentation/i2c/dev-interface in the linux kernel sources.
|
|
Note that these used to be defined in <linux/i2c-dev.h> in the kernel
|
|
source tree. However, userspace applications are not supposed to
|
|
include kernel headers, so the inline functions were removed from
|
|
the kernel file in recent kernels. Use the header file in this package
|
|
instead.
|
|
|
|
This method does not use a chip device driver at all.
|
|
However it does require the i2c-dev module.
|
|
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.
|
|
|
|
|
|
3A. /proc access (2.4 kernels)
|
|
-----------------------------
|
|
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 may not be strictly 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,
|
|
prog/pwm/fancontrol, and prog/pwm/pwmconfig.
|
|
Also search freshmeat for sensors applications.
|
|
|
|
|
|
3B. sysfs access (2.6 kernels)
|
|
------------------------------
|
|
Chip drivers using the i2c-sensor module create subdirectories in
|
|
the sysfs filesystem (usually /sys) which can be accessed
|
|
directly by applications.
|
|
Naming and content standards for the entries in these subdirectories
|
|
is documented in the file Documentation/i2c/sysfs-interface in the
|
|
2.6 kernel source tree. Note that these standards may not be
|
|
strictly followed.
|
|
|
|
If a new driver adheres to these standards then an application may
|
|
be able to support new devices on-the-fly.
|
|
|
|
sysfs access provides a method to read and write sensor values
|
|
for any driver using i2c-sensor, including ISA chip drivers.
|
|
|
|
This method may also works well for shell and perl scripts
|
|
written to access a specific device. Note that sysfs is
|
|
standard in 2.6 kernels.
|
|
|
|
Note that most drivers provide only raw sensor readings via /sys;
|
|
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 an examples of a program using /sys accesses, see gkrellm.
|
|
See also lib/proc.c and prog/dump/i2cbusses.c for examples.
|
|
The sysfsutils package may also be helpful.
|
|
Also search freshmeat for sensors and sysfs 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.
|
|
The libsensors library supports both 2.4 and 2.6 kernels.
|
|
|
|
Unfortunately there is little 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.
|
|
|
|
For an examples of a program using libsensors accesses, see
|
|
prog/sensors/sensors. Also search freshmeat for sensors applications.
|
|
|
|
5. sensors program
|
|
------------------
|
|
The 'sensors' program is a text-based application that uses libsensors.
|
|
The output is fairly standardized; therefore this output could be
|
|
used by other applications.
|
|
One simple method is 'sensors|grep ALARM'.
|