wt/lm-sensors
1
0 Fork 0
mirror of https://github.com/lm-sensors/lm-sensors.git synced 2026-11-13 17:00:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update the application writing guidelines:

Browse Source 
* The drivers are no longer in this package.
* Drop all references to i2c, these aren't related to sensors per se and
belong elsewhere.
* Random updates, fix broken references, clarify some parts.
* Add references to the relevant manual pages.
* Drop references to freshmeat, they don't really help.


git-svn-id: http://lm-sensors.org/svn/lm-sensors/branches/lm-sensors-3.0.0@5056 7894878c-1315-0410-8ee3-d5d059ff63e0
This commit is contained in:
Jean Delvare committed 2007-12-02 13:25:16 +00:00
1 parent 1e8dab35c9
commit da141f4699
2 files changed
+35 -90
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CHANGES
+1
View File
@@ -2,6 +2,7 @@ lm-sensors CHANGES file
-----------------------
SVN
documentation: Update the application writing guidelines
Makefile: No warnings about ld configuration for staged installations
sensors-detect: Drop PCA9540 detection
doc/developers/applications
+34 -90
View File
@@ -1,113 +1,53 @@
How to write applications which use our drivers
-----------------------------------------------
How to write applications which use the hwmon 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.
You have several choices in accessing sensor devices using the hwmon drivers.
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) sysfs access to the chip device driver
4) libsensors library
5) sensors program
1. sysfs access
2. libsensors library
3. 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 i2cdetect.c (in the i2c-tools package) 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.
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 from the
i2c-tools 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 i2cdetect.c, i2cdump.c, and i2cset.c (all in the
i2c-tools package).
3. sysfs access
1. sysfs access
---------------
Chip drivers using the i2c-sensor module create subdirectories in
the sysfs filesystem (usually /sys) which can be accessed
directly by applications.
Hwmon drivers 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, 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.
are documented in the file Documentation/hwmon/sysfs-interface in the 2.6
kernel source tree. sysfs is the lowest-level access to sensor values.
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 /sys 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.
of the adjustments can be quite complex. For this reason, this
approach isn't recommended. Instead, consider the libsensors library,
which offers a higher-level interface on top of sysfs (see below.)
For an examples of a program using /sys accesses, see gkrellm.
See also lib/proc.c and i2cbusses.c (in the i2c-tools package) for
examples. The sysfsutils package may also be helpful.
Also search freshmeat for sensors and sysfs applications.
Still, this method may work well for shell and perl scripts written to
access a specific device.
For an example of a program using /sys accesses, see gkrellm (though
recent versions use libsensors instead.) See also lib/sysfs.c.
4. libsensors library
2. 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.
provided by the user. Other facilities are sensor labelling, limit setting,
and ignoring individual sensors. This is the recommended way to access
the sensor chips.
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.
The library API is documented in the libsensors(3) manual page. The
configuration file format is documented in the sensors.conf(5) manual
page.
Note that libsensors falls under the GPL, not the LGPL.
In more human language, that means it is FORBIDDEN to link any application
@@ -115,12 +55,16 @@ Details:
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.
For examples of programs using libsensors accesses, see prog/sensors and
prog/sensord.
5. sensors program
3. 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'.
Note though that there is no guarantee that the output format won't change
in the future, so be careful. We might improve the command-line interface
of 'sensors' someday to make it more convenient for external programs to
use it as a back-end.