Changeset 5056

Show
Ignore:
Timestamp:
12/02/07 14:25:16 (7 years ago)
Author:
khali
Message:

Update the application writing guidelines:
* 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.

Location:
lm-sensors/branches/lm-sensors-3.0.0
Files:
2 modified

Legend:

Unmodified
Added
Removed
  • lm-sensors/branches/lm-sensors-3.0.0/CHANGES

    r5048 r5056  
    33 
    44SVN 
     5  documentation: Update the application writing guidelines 
    56  Makefile: No warnings about ld configuration for staged installations 
    67  sensors-detect: Drop PCA9540 detection 
  • lm-sensors/branches/lm-sensors-3.0.0/doc/developers/applications

    r4498 r5056  
    1 How to write applications which use our drivers 
    2 ----------------------------------------------- 
     1How to write applications which use the hwmon drivers 
     2===================================================== 
    33 
    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. 
     4You have several choices in accessing sensor devices using the hwmon drivers. 
     5This document will briefly describe these methods, their advantages and 
     6disadvantages, and provide examples. 
    87 
    98From lowest-level to the highest-level, the access methods are: 
    109 
    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 
    1713 
    1814 
    1915Details: 
    2016 
    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 
     171. sysfs access 
    6318--------------- 
    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. 
    6721   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. 
    8124 
    8225   Note that most drivers provide only raw sensor readings via /sys; 
     
    8427   must often be changed by the user. An application using /sys must 
    8528   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.) 
    8832 
    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. 
    9335 
     36   For an example of a program using /sys accesses, see gkrellm (though 
     37   recent versions use libsensors instead.) See also lib/sysfs.c. 
    9438 
    95 4. libsensors library 
     392. libsensors library 
    9640--------------------- 
    9741   The libsensors library provides standardized access to all chip drivers. 
    9842   It also provides a translation layer with settings in /etc/sensors.conf 
    9943   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. 
    10347 
    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. 
    11151 
    11252   Note that libsensors falls under the GPL, not the LGPL. 
     
    11656   Contact us if you wish to discuss your application. 
    11757 
    118    For an examples of a program using libsensors accesses, see 
    119    prog/sensors/sensors. Also search freshmeat for sensors applications. 
     58   For examples of programs using libsensors accesses, see prog/sensors and 
     59   prog/sensord. 
    12060 
    121 5. sensors program 
     613. sensors program 
    12262------------------ 
    12363   The 'sensors' program is a text-based application that uses libsensors. 
     
    12565   used by other applications. 
    12666   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.