- Timestamp:
- 12/02/07 14:25:16 (5 years ago)
- Files:
-
- 1 modified
Legend:
- Unmodified
- Added
- Removed
-
lm-sensors/branches/lm-sensors-3.0.0/doc/developers/applications
r4498 r5056 1 How to write applications which use ourdrivers2 ----------------------------------------------- 1 How to write applications which use the hwmon drivers 2 ===================================================== 3 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. 4 You have several choices in accessing sensor devices using the hwmon drivers. 5 This document will briefly describe these methods, their advantages and 6 disadvantages, and provide examples. 8 7 9 8 From lowest-level to the highest-level, the access methods are: 10 9 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) sysfs access to the chip device driver 15 4) libsensors library 16 5) sensors program 10 1. sysfs access 11 2. libsensors library 12 3. sensors program 17 13 18 14 19 15 Details: 20 16 21 1. Direct /dev access using ioctls 22 ---------------------------------- 23 Character device access to the i2c bus driver via ioctls on a /dev 24 device. This device could be i2cx, i2c-x, or i2c/x, where x is an 25 integer. The ioctls are defined in doc/dev-interface in the 26 i2c package or Documentation/i2c/dev-interface in the linux kernel 27 sources. 28 29 This method does not use a chip device driver at all. 30 However it does require the i2c-dev module. 31 The driver must set an individual chip address on the bus via 32 an ioctl, so it must use locking if multiple devices on the 33 bus are being accessed. No access is provided for non-i2c 34 busses such as ISA. 35 36 For good examples, see i2cdetect.c (in the i2c-tools package) and 37 prog/detect/sensors-detect. 38 39 40 2. Direct /dev access using inline functions 41 -------------------------------------------- 42 I2C bus access inline functions as defined in <linux/i2c-dev.h>, 43 and in doc/dev-interface in the i2c package or 44 Documentation/i2c/dev-interface in the linux kernel sources. 45 Note that these used to be defined in <linux/i2c-dev.h> in the kernel 46 source tree. However, userspace applications are not supposed to 47 include kernel headers, so the inline functions were removed from 48 the kernel file in recent kernels. Use the header file from the 49 i2c-tools package instead. 50 51 This method does not use a chip device driver at all. 52 However it does require the i2c-dev module. 53 The driver must set an individual chip address on the bus via 54 an ioctl, so it must use locking if multiple devices on the 55 bus are being accessed. No access is provided for non-i2c 56 busses such as ISA. 57 58 For good examples, see i2cdetect.c, i2cdump.c, and i2cset.c (all in the 59 i2c-tools package). 60 61 62 3. sysfs access 17 1. sysfs access 63 18 --------------- 64 Chip drivers using the i2c-sensor module create subdirectories in 65 the sysfs filesystem (usually /sys) which can be accessed 66 directly by applications. 19 Hwmon drivers create subdirectories in the sysfs filesystem (usually /sys) 20 which can be accessed directly by applications. 67 21 Naming and content standards for the entries in these subdirectories 68 is documented in the file Documentation/i2c/sysfs-interface in the 69 2.6 kernel source tree. Note that these standards may not be 70 strictly followed. 71 72 If a new driver adheres to these standards then an application may 73 be able to support new devices on-the-fly. 74 75 sysfs access provides a method to read and write sensor values 76 for any driver, including ISA chip drivers. 77 78 This method may also works well for shell and perl scripts 79 written to access a specific device. Note that sysfs is 80 standard in 2.6 kernels. 22 are documented in the file Documentation/hwmon/sysfs-interface in the 2.6 23 kernel source tree. sysfs is the lowest-level access to sensor values. 81 24 82 25 Note that most drivers provide only raw sensor readings via /sys; … … 84 27 must often be changed by the user. An application using /sys must 85 28 generally provide adjustment facilities and the requirements 86 of the adjustments can be quite complex. If you need adjustment 87 facilities, consider the libsensors library, below. 29 of the adjustments can be quite complex. For this reason, this 30 approach isn't recommended. Instead, consider the libsensors library, 31 which offers a higher-level interface on top of sysfs (see below.) 88 32 89 For an examples of a program using /sys accesses, see gkrellm. 90 See also lib/proc.c and i2cbusses.c (in the i2c-tools package) for 91 examples. The sysfsutils package may also be helpful. 92 Also search freshmeat for sensors and sysfs applications. 33 Still, this method may work well for shell and perl scripts written to 34 access a specific device. 93 35 36 For an example of a program using /sys accesses, see gkrellm (though 37 recent versions use libsensors instead.) See also lib/sysfs.c. 94 38 95 4. libsensors library39 2. libsensors library 96 40 --------------------- 97 41 The libsensors library provides standardized access to all chip drivers. 98 42 It also provides a translation layer with settings in /etc/sensors.conf 99 43 so that your application sees adjusted (scaled) values using settings 100 provided by the user. Other facilities are sensor renaming, limit setting,101 and ignoring individual sensors. 102 The libsensors library supports both 2.4 and 2.6 kernels.44 provided by the user. Other facilities are sensor labelling, limit setting, 45 and ignoring individual sensors. This is the recommended way to access 46 the sensor chips. 103 47 104 Unfortunately there is little documentation for libsensors. See the 105 'sensors' application in prog/sensors for an example. The source 106 for libsensors is in the lib/ directory. Another example 107 is in prog/sensord. Also search freshmeat for sensors applications. 108 109 One other limitation of libsensors is that it is relatively 110 cumbersome to add support for new devices. 48 The library API is documented in the libsensors(3) manual page. The 49 configuration file format is documented in the sensors.conf(5) manual 50 page. 111 51 112 52 Note that libsensors falls under the GPL, not the LGPL. … … 116 56 Contact us if you wish to discuss your application. 117 57 118 For an examples of a program using libsensors accesses, see119 prog/sensor s/sensors. Also search freshmeat for sensors applications.58 For examples of programs using libsensors accesses, see prog/sensors and 59 prog/sensord. 120 60 121 5. sensors program61 3. sensors program 122 62 ------------------ 123 63 The 'sensors' program is a text-based application that uses libsensors. … … 125 65 used by other applications. 126 66 One simple method is 'sensors|grep ALARM'. 67 Note though that there is no guarantee that the output format won't change 68 in the future, so be careful. We might improve the command-line interface 69 of 'sensors' someday to make it more convenient for external programs to 70 use it as a back-end.
