Kernel driver `adm9240.o'
=========================

Status: Complete and tested

Supported chips:
  * Analog Devices ADM9240
    Prefix `adm9240'
    Addresses scanned: I2C 0x2c - 0x2f (inclusive)
    Datasheet: Publicly available at the Analog Devices website
  * Dallas Semiconductor DS1780
    Prefix `ds1780'
    Addresses scanned: I2C 0x2c - 0x2f (inclusive)
    Datasheet: Publicly available at the Dallas Semiconductor website
  * National Semiconductor LM81
    Prefix `lm81'
    Addresses scanned: I2C 0x2c - 0x2f (inclusive)
    Datasheet: Publicly available at the National Semiconductor website


Author: Frodo Looijaard <frodol@dds.nl> and Philip Edelbrock
        <phil@netroedge.com>


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

* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* force_adm9240: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `adm9240' chip
* force_ds1780: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `ds1780' chip
* force_lm81: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `lm81' 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 Analog Devices ADM9240,
Dallas Semiconductor DS1780, and National Semiconductor LM81 chips.
These chips appear to be completely
identical, except for the manufacturer IDs encoded in two registers, and
the speed with which they update their sensor readings.

The chips implement six voltage sensors, a temperature sensor,
two FAN rotation speed sensors, VID lines and some miscellaneous stuff.

Temperatures are measured in degrees Celcius. An alarm is triggered whenever
the temperature is above the hot limit, and will continue to be generated
until the temperature has dropped beneath the hysteresis limit. Measurements
are guaranteed between -40 and +125 degrees. The current temperature
has a resolution of 0.5 degrees, the limits of 1 degree.

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.
IMPORTANT: The current voltage measurement system is very probably broken.
Please report back to us if you have a ADM9240 or DS1780!

The VID lines encode the core voltage value: the voltage level your processor
should work with. This is hardcoded by the mainboard and/or processor itself.
It is a value in volts. When it is unconnected, you will often find the
value 3.50 V here.

The analog output can be programmed separatedly. It can take values
between 0 and 255. What it actually does is mainboard-dependent; it
might influence the FAN-speed. Please report to us whether this is
the case with your ADM9240.

In addition to the alarms described above, the CHAS alarm triggers
if your computer case is open. 

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 1.5 seconds since the last update). This means that you can easily
miss once-only alarms.

Thes ADM9240 only updates its values every 0.5 seconds; the DS1780 one
every 2 seconds; and the LM81 every 0.4 seconds.
Reading them more often will do no harm, but will return 
'old' values. (NB: theoretically, this could be done much faster for the
ADM9240, but there is no real reason to do so, and this way the SMBus use 
is kept within reasonable limits)


Chip Features
-------------

Chip `adm9240'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
              2.5V               NONE               NONE     R     2
             Vccp1               NONE               NONE     R     2
              3.3V               NONE               NONE     R     2
                5V               NONE               NONE     R     2
               12V               NONE               NONE     R     2
             Vccp2               NONE               NONE     R     2
          2.5V_min               2.5V               2.5V     RW    2
         Vccp1_min              Vccp1              Vccp1     RW    2
          3.3V_min               3.3V               3.3V     RW    2
            5V_min                 5V                 5V     RW    2
           12V_min                12V                12V     RW    2
         Vccp2_min              Vccp2              Vccp2     RW    2
          2.5V_max               2.5V               2.5V     RW    2
         Vccp1_max              Vccp1              Vccp1     RW    2
          3.3V_max               3.3V               3.3V     RW    2
            5V_max                 5V                 5V     RW    2
           12V_max                12V                12V     RW    2
         Vccp2_max              Vccp2              Vccp2     RW    2
              fan1               NONE               NONE     R     0
              fan2               NONE               NONE     R     0
          fan1_min               fan1               fan1     RW    0
          fan2_min               fan2               fan2     RW    0
              temp               NONE               NONE     R     1
         temp_hyst               temp               temp     RW    1
         temp_over               temp               temp     RW    1
               vid               NONE               NONE     R     2
          fan1_div               fan1               NONE     RW    0
          fan2_div               fan2               NONE     RW    0
            alarms               NONE               NONE     R     0
        analog_out               NONE               NONE     RW    0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
              2.5V                     SENSORS_ADM9240_IN0               2.5V:3
             Vccp1                     SENSORS_ADM9240_IN1              Vccp1:3
              3.3V                     SENSORS_ADM9240_IN2               3.3V:3
                5V                     SENSORS_ADM9240_IN3                 5V:3
               12V                     SENSORS_ADM9240_IN4                12V:3
             Vccp2                     SENSORS_ADM9240_IN5              Vccp2:3
          2.5V_min                 SENSORS_ADM9240_IN0_MIN               2.5V:1
         Vccp1_min                 SENSORS_ADM9240_IN1_MIN              Vccp1:1
          3.3V_min                 SENSORS_ADM9240_IN2_MIN               3.3V:1
            5V_min                 SENSORS_ADM9240_IN3_MIN                 5V:1
           12V_min                 SENSORS_ADM9240_IN4_MIN                12V:1
         Vccp2_min                 SENSORS_ADM9240_IN5_MIN              Vccp2:1
          2.5V_max                 SENSORS_ADM9240_IN0_MAX               2.5V:2
         Vccp1_max                 SENSORS_ADM9240_IN1_MAX              Vccp1:2
          3.3V_max                 SENSORS_ADM9240_IN2_MAX               3.3V:2
            5V_max                 SENSORS_ADM9240_IN3_MAX                 5V:2
           12V_max                 SENSORS_ADM9240_IN4_MAX                12V:2
         Vccp2_max                 SENSORS_ADM9240_IN5_MAX              Vccp2:2
              fan1                    SENSORS_ADM9240_FAN1               fan1:2
              fan2                    SENSORS_ADM9240_FAN2               fan2:2
          fan1_min                SENSORS_ADM9240_FAN1_MIN               fan1:1
          fan2_min                SENSORS_ADM9240_FAN2_MIN               fan2:1
              temp                    SENSORS_ADM9240_TEMP               temp:3
         temp_hyst               SENSORS_ADM9240_TEMP_HYST               temp:2
         temp_over               SENSORS_ADM9240_TEMP_OVER               temp:1
               vid                     SENSORS_ADM9240_VID                vid:1
          fan1_div                SENSORS_ADM9240_FAN1_DIV            fan_div:1
          fan2_div                SENSORS_ADM9240_FAN2_DIV            fan_div:2
            alarms                  SENSORS_ADM9240_ALARMS             alarms:1
        analog_out              SENSORS_ADM9240_ANALOG_OUT         analog_out:1


Chip `ds1780'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
              2.5V               NONE               NONE     R     2
             Vccp1               NONE               NONE     R     2
              3.3V               NONE               NONE     R     2
                5V               NONE               NONE     R     2
               12V               NONE               NONE     R     2
             Vccp2               NONE               NONE     R     2
          2.5V_min               2.5V               2.5V     RW    2
         Vccp1_min              Vccp1              Vccp1     RW    2
          3.3V_min               3.3V               3.3V     RW    2
            5V_min                 5V                 5V     RW    2
           12V_min                12V                12V     RW    2
         Vccp2_min              Vccp2              Vccp2     RW    2
          2.5V_max               2.5V               2.5V     RW    2
         Vccp1_max              Vccp1              Vccp1     RW    2
          3.3V_max               3.3V               3.3V     RW    2
            5V_max                 5V                 5V     RW    2
           12V_max                12V                12V     RW    2
         Vccp2_max              Vccp2              Vccp2     RW    2
              fan1               NONE               NONE     R     0
              fan2               NONE               NONE     R     0
          fan1_min               fan1               fan1     RW    0
          fan2_min               fan2               fan2     RW    0
              temp               NONE               NONE     R     1
         temp_hyst               temp               temp     RW    1
         temp_over               temp               temp     RW    1
               vid               NONE               NONE     R     2
          fan1_div               fan1               NONE     RW    0
          fan2_div               fan2               NONE     RW    0
            alarms               NONE               NONE     R     0
        analog_out               NONE               NONE     RW    0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
              2.5V                      SENSORS_DS1780_IN0               2.5V:3
             Vccp1                      SENSORS_DS1780_IN1              Vccp1:3
              3.3V                      SENSORS_DS1780_IN2               3.3V:3
                5V                      SENSORS_DS1780_IN3                 5V:3
               12V                      SENSORS_DS1780_IN4                12V:3
             Vccp2                      SENSORS_DS1780_IN5              Vccp2:3
          2.5V_min                  SENSORS_DS1780_IN0_MIN               2.5V:1
         Vccp1_min                  SENSORS_DS1780_IN1_MIN              Vccp1:1
          3.3V_min                  SENSORS_DS1780_IN2_MIN               3.3V:1
            5V_min                  SENSORS_DS1780_IN3_MIN                 5V:1
           12V_min                  SENSORS_DS1780_IN4_MIN                12V:1
         Vccp2_min                  SENSORS_DS1780_IN5_MIN              Vccp2:1
          2.5V_max                  SENSORS_DS1780_IN0_MAX               2.5V:2
         Vccp1_max                  SENSORS_DS1780_IN1_MAX              Vccp1:2
          3.3V_max                  SENSORS_DS1780_IN2_MAX               3.3V:2
            5V_max                  SENSORS_DS1780_IN3_MAX                 5V:2
           12V_max                  SENSORS_DS1780_IN4_MAX                12V:2
         Vccp2_max                  SENSORS_DS1780_IN5_MAX              Vccp2:2
              fan1                     SENSORS_DS1780_FAN1               fan1:2
              fan2                     SENSORS_DS1780_FAN2               fan2:2
          fan1_min                 SENSORS_DS1780_FAN1_MIN               fan1:1
          fan2_min                 SENSORS_DS1780_FAN2_MIN               fan2:1
              temp                     SENSORS_DS1780_TEMP               temp:3
         temp_hyst                SENSORS_DS1780_TEMP_HYST               temp:2
         temp_over                SENSORS_DS1780_TEMP_OVER               temp:1
               vid                      SENSORS_DS1780_VID                vid:1
          fan1_div                 SENSORS_DS1780_FAN1_DIV            fan_div:1
          fan2_div                 SENSORS_DS1780_FAN2_DIV            fan_div:2
            alarms                   SENSORS_DS1780_ALARMS             alarms:1
        analog_out               SENSORS_DS1780_ANALOG_OUT         analog_out:1


Chip `lm81'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
              2.5V               NONE               NONE     R     2
             Vccp1               NONE               NONE     R     2
              3.3V               NONE               NONE     R     2
                5V               NONE               NONE     R     2
               12V               NONE               NONE     R     2
             Vccp2               NONE               NONE     R     2
          2.5V_min               2.5V               2.5V     RW    2
         Vccp1_min              Vccp1              Vccp1     RW    2
          3.3V_min               3.3V               3.3V     RW    2
            5V_min                 5V                 5V     RW    2
           12V_min                12V                12V     RW    2
         Vccp2_min              Vccp2              Vccp2     RW    2
          2.5V_max               2.5V               2.5V     RW    2
         Vccp1_max              Vccp1              Vccp1     RW    2
          3.3V_max               3.3V               3.3V     RW    2
            5V_max                 5V                 5V     RW    2
           12V_max                12V                12V     RW    2
         Vccp2_max              Vccp2              Vccp2     RW    2
              fan1               NONE               NONE     R     0
              fan2               NONE               NONE     R     0
          fan1_min               fan1               fan1     RW    0
          fan2_min               fan2               fan2     RW    0
              temp               NONE               NONE     R     1
         temp_hyst               temp               temp     RW    1
         temp_over               temp               temp     RW    1
               vid               NONE               NONE     R     2
          fan1_div               fan1               NONE     RW    0
          fan2_div               fan2               NONE     RW    0
            alarms               NONE               NONE     R     0
        analog_out               NONE               NONE     RW    0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
              2.5V                     SENSORS_ADM9240_IN0               2.5V:3
             Vccp1                     SENSORS_ADM9240_IN1              Vccp1:3
              3.3V                     SENSORS_ADM9240_IN2               3.3V:3
                5V                     SENSORS_ADM9240_IN3                 5V:3
               12V                     SENSORS_ADM9240_IN4                12V:3
             Vccp2                     SENSORS_ADM9240_IN5              Vccp2:3
          2.5V_min                 SENSORS_ADM9240_IN0_MIN               2.5V:1
         Vccp1_min                 SENSORS_ADM9240_IN1_MIN              Vccp1:1
          3.3V_min                 SENSORS_ADM9240_IN2_MIN               3.3V:1
            5V_min                 SENSORS_ADM9240_IN3_MIN                 5V:1
           12V_min                 SENSORS_ADM9240_IN4_MIN                12V:1
         Vccp2_min                 SENSORS_ADM9240_IN5_MIN              Vccp2:1
          2.5V_max                 SENSORS_ADM9240_IN0_MAX               2.5V:2
         Vccp1_max                 SENSORS_ADM9240_IN1_MAX              Vccp1:2
          3.3V_max                 SENSORS_ADM9240_IN2_MAX               3.3V:2
            5V_max                 SENSORS_ADM9240_IN3_MAX                 5V:2
           12V_max                 SENSORS_ADM9240_IN4_MAX                12V:2
         Vccp2_max                 SENSORS_ADM9240_IN5_MAX              Vccp2:2
              fan1                    SENSORS_ADM9240_FAN1               fan1:2
              fan2                    SENSORS_ADM9240_FAN2               fan2:2
          fan1_min                SENSORS_ADM9240_FAN1_MIN               fan1:1
          fan2_min                SENSORS_ADM9240_FAN2_MIN               fan2:1
              temp                    SENSORS_ADM9240_TEMP               temp:3
         temp_hyst               SENSORS_ADM9240_TEMP_HYST               temp:2
         temp_over               SENSORS_ADM9240_TEMP_OVER               temp:1
               vid                     SENSORS_ADM9240_VID                vid:1
          fan1_div                SENSORS_ADM9240_FAN1_DIV            fan_div:1
          fan2_div                SENSORS_ADM9240_FAN2_DIV            fan_div:2
            alarms                  SENSORS_ADM9240_ALARMS             alarms:1
        analog_out              SENSORS_ADM9240_ANALOG_OUT         analog_out:1




Old Documentation
-----------------

Supports the Analog Devices ADM9240 and the Dallas Semiconductor DS1780.
These chips are apparently identical except for the manufacturer ID
register.
The proc directory will be adm9240-i2c-x-xx for the adm9240 and
ds1780-i2c-x-xx for the ds1780.

-----------------------------------------------------------------------

This file documents the adm9240 directories for the Analog Devices
ADM9240 hardware health monitoring chip found on some Intel mainboards
(and others?).

There will be one directory created for each detected ADM9240 chip.
Each chip must be on the SMBus. Directories are called things
like adm9240-i2c-1-2c. /proc/sys/dev/sensors/chips contains the SYSCTL
values for all chip directories.

Within each ADM9240 directory, you can find the following files:
* alarms (ADM9240_SYSCTL_ALARMS)
  A number which indicates which alarms are on. An alarm gets triggered when
  some limit has been crossed. This number is composed from a 16 bit
  value which is the combination of the Interrupt Status Register 1
  (low byte) and 2 (high byte).
  This file can not be written to.
  The number is the logical OR of the following components (bit #
  followed by a description):
  
0 +2.5 V_Error Read Only A "1" indicates a high or low limit has been exceeded.
1 VCCP_Error Read Only A "1" indicates a high or low limit has been exceeded.
2 +3.3 V_Error Read Only A "1" indicates a high or low limit has been exceeded.
3 +5 V_Error Read Only A "1" indicates a high or low limit has been exceeded.
4 Temp_Error Read Only A "1" indicates that a temperature interrupt has been set.
5 Reserved Read Only Undefined.
6 FAN1_Error Read Only A "1" indicates that a fan count limit has been exceeded.
7 FAN2_Error Read Only A "1" indicates that a fan count limit has been exceeded.
8 +12 V_Error Read Only A "1" indicates a high or low limit has been exceeded.
9 VCCP2_Error Read Only A "1" indicates a high or low limit has been exceeded.
10 Reserved Read Only Undefined.
11 Reserved Read Only Undefined.
12 Chassis_Error Read Only A "1" indicates chassis intrusion has gone high.
13 Reserved Read Only Undefined.
14 Reserved Read Only Undefined.
15 Reserved Read Only Undefined.

  If accessed through sysctl, this value is a long.
* fan[1-3] (ADM9240_SYSCTL_FAN[1-2])
  A list of two numbers. The first is the minimum fan rotation limit; the
  second is the current fan rotation speed. Both are in RPM (rotations per
  minute). An alarm is triggered if the rotation speed drops below the
  limit. The first value can be changed. Not all RPM values can accurately
  be represented, so some rounding is done.
  If accessed through sysctl, this is a list of longs.
* fan_div (LM78_SYSCTL_FAN_DIV)
  A list of two numbers, one for each fan. Each number can be either 1, 2,
  4 or 8. It is the internal scaling factor used for the FAN rotations. If
  you change this number, the FAN readings get more or less detailed, but
  the range in which they can be read too. Higher numbers give better 
  resolution, but less range. The first two numbers can be changed, the
  third not.
  If accessed through sysctl, this is a list of longs.
* 2.5V, Vccp1, 3.3V, 5V, 12V, and Vccp2 (ADM9240_SYSCTL_IN[0-5] in the
  order shown)
  A list of three numbers. The first is the minimum limit, the second is the
  maximum limit, and the third is the current value.  Note that
  minimum means 'closest to zero'; so if the normal value equals -10, a
  minimum could equal -9, and a maximum -11. Vccp1 and Vccp2 reflect core
  voltages; they are by default set from the vid values, or set to 2.80V
  if the vid lines seem to be unconnected. Not all voltage values
  can be accurately represented, so some rounding is done.
  The first two numbers can be changed, the third not.
  If accessed through sysctl, this is a list of longs, each being the voltage
  times 100.
* temp
  A list of three numbers. The first number is the Overtemperature Shutdown
  value; the second is the Hysteresis value and the third number is the
  current value. The first two values can be modified. All values are in
  degrees Celsius. An alarm is issued when the temperature first gets above
  the Overtemperature Shutdown value; no more alarms are issued until the
  temperature gets below the Hysteresis value, at which moment another alarm
  is issued, and the state is reset. A more useful behaviour can be found
  by setting the Hysteresis value to +127 degrees Celsius; in this case, 
  alarms are issued during all the time when the actual temperature is 
  above the Overtemperature Shutdown value.
  The first two numbers can be changed, the third not.
  If accessed through sysctl, this is a list of longs, each being the
  temperature in degrees Celsius times 10.
* vid
  The core voltage value (the voltage level your processor should work with),
  in volts. This is the value IN0 and IN1 are initialized to. If unconnected,
  it usually reads 3.50V.
  This number can not be changed.
  If accessed through sysctl, this is a long, being the voltage times 100.
* analog_out
   This is feature is specific to the ADM9240.  It is a DAC voltage
   control register for the Analog-Out pin.  Valid values are from 255
   to 0 (with 255 being the highest voltage, and 0 the lowest).  From
   the docs: "The ADM9240 has a single analog output from an unsigned
   8-bit DAC which produces 0 V - 1.25 V."

The data for each ADM9240 is updated each 1.5 seconds,
but only if it is actually read.

Note: Much of this documentation is copied from the LM78 documenation
(the device from which most featuers of the ADM9240 is modelled from).
The maintainer of the ADM9240 is Philip Edelbrock
<phil@netroedge.com>; please forward corrections, suggestions, etc.
to him.  For further technical information on this chip, I suggest
getting the Acrobat PDF documentation from www.analog.com.

Dallas documentation is at http://www.dalsemi.com.
