root/lm-sensors/trunk/doc/chips/lm87 @ 2325

Kernel driver `lm87.o'
======================

Status: Complete and somewhat tested

Supported chips:
  * National Semiconductors LM87
    Prefix `lm87'
    Addresses scanned: I2C 0x2c - 0x2f (inclusive)

Authors: Frodo Looijaard <frodol@dds.nl>,
      Philip Edelbrock <phil@netroedge.com>, 
      Mark Studebaker <mdsxyz123@yahoo.com>,
      and Stephen Rousset <stephen.rousset@rocketlogix.com>


Module Parameters
-----------------

* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* force_lm87: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `lm87' chip
* ignore: short array (min = 1, max = 48)
  List of adapter,address pairs not to scan
* ignore_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples not to scan
* probe: short array (min = 1, max = 48)
  List of adapter,address pairs to scan additionally
* probe_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples to scan additionally


Description
-----------

This driver implements support for the National Semiconductors LM87.

The LM87 implements up to three temperature sensors, up to two FAN
rotation speed sensors, up to seven voltage sensors, alarms, and some
miscellaneous stuff.

Temperatures are measured in degrees Celcius. Each input has a high
and low alarm settings.  A high limit produces an alarm when the value
goes above it, and an alarm is also produced when the value goes below
the low limit.

FAN rotation speeds are reported in RPM (rotations per minute). An alarm is
triggered if the rotation speed has dropped below a programmable limit. FAN 
readings can be divided by a programmable divider (1, 2, 4 or 8) to give
the readings more range or accuracy. This is important because some FANs
report only one 'tick' each rotation, while others report two - making
all readings twice as high. Not all RPM values can accurately be represented,
so some rounding is done. With a divider of 2, the lowest representable
value is around 2600 RPM.

Voltage sensors (also known as IN sensors) report their values in
volts. An alarm is triggered if the voltage has crossed a programmable
minimum or maximum limit. Note that minimum in this case always means
'closest to zero'; this is important for negative voltage
measurements.

If an alarm triggers, it will remain triggered until the hardware register
is read at least once. This means that the cause for the alarm may 
already have disappeared!  Note that in the current implementation, all
hardware registers are read whenever any data is read (unless it is less
than 2.0 seconds since the last update). This means that you can easily
miss once-only alarms.

The LM87 only updates its values each 1.0 seconds; reading it more
often will do no harm, but will return 'old' values.


Hardware Configurations
-----------------------

The LM87 has four pins which can serve one of two possible functions,
depending on the hardware configuration. These pins are:

Vccp2/D2-       (pin 17)
+2.5V(IN0)/D2+  (pin 18)
FAN1/AIN1       (pin 5)
FAN2/AIN2       (pin 6)

The most common configuration is to use the values shown here on the
left (Vccp2, 2.5V, FAN1, and FAN2).  However, for a third temperature
sensor, it is possible to do away with Vccp2 and 2.5V (IN0) for the
second external temp diode inputs.  Strangely, it seems that you can
monitor the core voltage of the second processor or its temperature,
but never both at the same time.  Also, either/both FAN1 and FAN2
inputs can be substituted for aux analog inputs AIN1 and/or AIN2,
respectively.

To adjust the driver for a hardware configuration other than the
default, simply uncomment the appropriate #defines in the
kernel/chips/lm87.c driver header, and then recompile/reinstall.  
Here is a copy (as of this writing) of the header:


--snip--
/* Chip configuration settings.  These should be set to reflect the
HARDWARE configuration of your chip.  By default (read: when all of
these are left commented out), this driver assumes that the
configuration is the same as National's defaults for the Channel Mode
register.

 Set to '1' the appropriate defines, as nessesary:

 - External temp sensors 2 (possible second CPU temp)
   This will disable the 2.5V and Vccp2 readings.
   Strangely, National decided that you can read the
   temperature of a second CPU or its core voltage,
   but not both!  Comment out if FAULT is reported.  */

/* #define LM87_EXT2 1 */

/* Aux analog input. When enabled, the Fan 1 reading 
   will be disabled */

/* #define LM87_AIN1 1 */

/* Aux analog input 2. When enabled, the Fan 2 reading 
   will be disabled */

/* #define LM87_AIN2 1 */

/* Internal Vcc is 5V instead of 3.3V */

/* #define LM87_5V_VCC 1 */

/* That's the end of the hardware config defines.  I would have made
   them insmod params, but it would be too much work. ;') */
--snip--

Please note: Only adjust the #defines to reflect your HARDWARE
configuration.  Otherwise some, if not all, the readings will be
wrong.  Simply enabling different driver configurations does not
provide the desired readings.  You must make hardware changes (which
is hard) if you really wish to get a different set of readings!!

If you may suspect that your configuration may be different than the
default, try enabling the different #defines.  If you get a 'FAULT'
when using D2, it is most likely that you don't have a second external
diode, so recomment-out the #define.  If you get strange readings for
some/all of the other values when enabling a AIN, then recomment-out
that #define.

Unfortunately, it's tough to 'detect' all hardware config's
automaticly.  And, I needed to resort to using #defines instead of
insmod params to make life easier on myself.