Kernel driver `adm1021.o'
=========================

Status: Complete; tested for most devices.

Supported chips:
  * Analog Devices ADM1021
    Prefix `adm1021'
    Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e (inclusive)
    Datasheet: Publicly available at the Analog Devices website
  * Genesys Logic GL523SM
    Prefix `gl523sm'
    Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e (inclusive)
    Datasheet:
  * Intel Xeon Processor
    Prefix - any other - requires 'force' parameter - see MODPARMS file
    Addresses scanned: none
    Datasheet: Publicly available at Intel website
  * Maxim MAX1617
    Prefix `max1617'
    Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e (inclusive)
    Datasheet: Publicly available at the Maxim website
  * Maxim MAX1617A
    Prefix `max1617a'
    Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e (inclusive)
    Datasheet: Publicly available at the Maxim website
  * National Semiconductor LM84
    Prefix `lm84'
    Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e (inclusive)
    Datasheet: Publicly available at the National Semiconductor website
  * TI THMC10
    Prefix `thmc10'
    Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e (inclusive)
    Datasheet: Publicly available at the TI 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_adm1021: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `adm1021' chip
* force_max1617: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `max1617' chip
* force_max1617a: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `max1617a' 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
-----------

The chips supported by this driver are very similar. The Maxim MAX1617
is the oldest; it has the problem that it is not very well detectable.
The MAX1617A solves that.  The ADM1021 is a straight clone of the MAX1617A.
Ditto for the THMC10.
From here on, we will refer to all these chips as ADM1021-clones.

ADM1021-clones implement two temperature sensors. One of them is internal,
and measures the temperature of the chip itself; the other is external
and is realised in the form of a transistor-like device. A special alarm
indicates whether the remote sensor is connected.

Each sensor has its own low and high limits. When they are crossed, the 
corresponding alarm is set and remains on as long as the temperature stays 
out of range. Temperatures are measured in degrees Celcius. Measurements 
are possible between -65 and +127 degrees, with a resolution of one degree.

The ADM1021 reports a die code, which is a sort of revision code. This
can help us pinpoint problems; it is not very useful otherwise.

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!

This driver  only updates its values each 1.5 seconds; reading it more often
will do no harm, but will return 'old' values. It is possible to make 
ADM1021-clones do faster measurements, but there is really no good reason
for that.


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

Chip `adm1021'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
              temp               NONE               NONE     R     0
          temp_low               temp               temp     RW    0
         temp_over               temp               temp     RW    0
       remote_temp               NONE               NONE     R     0
   remote_temp_low        remote_temp        remote_temp     RW    0
  remote_temp_over        remote_temp        remote_temp     RW    0
            alarms               NONE               NONE     R     0
          die_code               NONE               NONE     R     0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
              temp                    SENSORS_ADM1021_TEMP               temp:3
          temp_low               SENSORS_ADM1021_TEMP_HYST               temp:2
         temp_over               SENSORS_ADM1021_TEMP_OVER               temp:1
       remote_temp             SENSORS_ADM1021_REMOTE_TEMP        remote_temp:3
   remote_temp_low        SENSORS_ADM1021_REMOTE_TEMP_HYST        remote_temp:2
  remote_temp_over        SENSORS_ADM1021_REMOTE_TEMP_OVER        remote_temp:1
            alarms                  SENSORS_ADM1021_ALARMS             alarms:1
          die_code                SENSORS_ADM1021_DIE_CODE           die_code:1


Chip `thmc10'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
              temp               NONE               NONE     R     0
          temp_low               temp               temp     RW    0
         temp_over               temp               temp     RW    0
       remote_temp               NONE               NONE     R     0
   remote_temp_low        remote_temp        remote_temp     RW    0
  remote_temp_over        remote_temp        remote_temp     RW    0
            alarms               NONE               NONE     R     0
          die_code               NONE               NONE     R     0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
              temp                    SENSORS_ADM1021_TEMP               temp:3
          temp_low               SENSORS_ADM1021_TEMP_HYST               temp:2
         temp_over               SENSORS_ADM1021_TEMP_OVER               temp:1
       remote_temp             SENSORS_ADM1021_REMOTE_TEMP        remote_temp:3
   remote_temp_low        SENSORS_ADM1021_REMOTE_TEMP_HYST        remote_temp:2
  remote_temp_over        SENSORS_ADM1021_REMOTE_TEMP_OVER        remote_temp:1
            alarms                  SENSORS_ADM1021_ALARMS             alarms:1
          die_code                SENSORS_ADM1021_DIE_CODE           die_code:1


Chip `max1617'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
              temp               NONE               NONE     R     0
          temp_low               temp               temp     RW    0
         temp_over               temp               temp     RW    0
       remote_temp               NONE               NONE     R     0
   remote_temp_low        remote_temp        remote_temp     RW    0
  remote_temp_over        remote_temp        remote_temp     RW    0
            alarms               NONE               NONE     R     0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
              temp                    SENSORS_MAX1617_TEMP               temp:3
          temp_low               SENSORS_MAX1617_TEMP_HYST               temp:2
         temp_over               SENSORS_MAX1617_TEMP_OVER               temp:1
       remote_temp             SENSORS_MAX1617_REMOTE_TEMP        remote_temp:3
   remote_temp_low        SENSORS_MAX1617_REMOTE_TEMP_HYST        remote_temp:2
  remote_temp_over        SENSORS_MAX1617_REMOTE_TEMP_OVER        remote_temp:1
            alarms                  SENSORS_MAX1617_ALARMS             alarms:1


Chip `max1617a'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
              temp               NONE               NONE     R     0
          temp_low               temp               temp     RW    0
         temp_over               temp               temp     RW    0
       remote_temp               NONE               NONE     R     0
   remote_temp_low        remote_temp        remote_temp     RW    0
  remote_temp_over        remote_temp        remote_temp     RW    0
            alarms               NONE               NONE     R     0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
              temp                   SENSORS_MAX1617A_TEMP               temp:3
          temp_low              SENSORS_MAX1617A_TEMP_HYST               temp:2
         temp_over              SENSORS_MAX1617A_TEMP_OVER               temp:1
       remote_temp            SENSORS_MAX1617A_REMOTE_TEMP        remote_temp:3
   remote_temp_low       SENSORS_MAX1617A_REMOTE_TEMP_HYST        remote_temp:2
  remote_temp_over       SENSORS_MAX1617A_REMOTE_TEMP_OVER        remote_temp:1
            alarms                 SENSORS_MAX1617A_ALARMS             alarms:1



Old Documentation (may be outdated)
-----------------------------------

This file documents the adm1021 directories for the Analog Devices ADM1021
and MAX1617 temperature sensor chip. Note that this last chip should be
fully compatible; it is not yet well-tested, though.

There will be one directory created for each detected ADM1021 chip. As
ADM1021 chips can only be on a SMBus, they will be called adm1021-i2c-?-??, with
the first question mark being the number of the i2c bus (see /proc/bus/i2c
for a list of them, if i2c-proc is loaded), and the SMBus (I2C) address
of the chip at the end. An ADM1021 is uniquely characterised with these
two numbers. Likewise, for each MAX1617 chip, a directory max1617-i2c-?-??
will be created.  /proc/sys/dev/sensors/chips contains the SYSCTL values for
all chip directories.

Within each ADM1021 or MAX1617  directory, you can find the following files:
* die_code (ADM1021_SYSCTL_DIE_CODE)
  Silicon die (mask) revision code.  This driver was written using a sample
  device of die code 3.  Normally this kind of information isn't reported
  in its own proc file, but for a device this simple I didn't think it
  would hurt.
* status (ADM1021_SYSCTL_STATUS)
  This is an intergral number composed of 8-bits, which indicate the
  different alarms and conversion status's of the chip.  Here is what
  each bit indicates:
    7 BUSY 1 When ADC Converting.
    6 LHIGH# 1 When Local High Temp Limit Tripped.
    5 LLOW# 1 When Local Low Temp Limit Tripped.
    4 RHIGH# 1 When Remote High Temp Limit Tripped.
    3 RLOW# 1 When Remote Low Temp Limit Tripped.
    2 OPEN# 1 When Remote Sensor Open-Circuit. (i.e., no connected remote 
            sensor)
    1-0 Reserved.
  Note: # - These flags stay high until the status register is read or they 
            are reset by POR.
* temp (ADM1021_SYSCTL_TEMP)
  A list of three numbers. The first number is the Overtemperature Shutdown
  value, the second number is Low limit value, and the third number is the
  current temperature. The first two values can be modified. Each value can
  be set and read to full-degree accuracy. All values are in degrees Celcius.
  An alarm is issued (usually to a connected ADM9240) when the temperature 
  gets higher then the Overtemperature Shutdown value; it stays on until
  the temperature falls back below the Overtemperature Shutdown value. 
  NOTE: This is different than the way most remote temperature sensors work
  (e.g. the LM75), they usually use the lower limit to clear the alarm set
  from initially going above the Overtemperature limit.  Instead, the
  ADM1021 acts much the way that voltage limits work on, say, the LM78 or
  ADM9240.  A disadvantage to this is that the alarm doesn't have a
  hysteresis (like a shmidt-trigger or thermostat) type of function for
  doing things like controlling over-heat fans and such.  Instead, the
  lower limit can be used to signal an alarm if (goodness forbid!) the
  computer gets too cold.
  If accessed through sysctl, this is a list of longs, each being the
  temperature times 10.
* remote_temp (ADM1021_SYSCTL_REMOTE_TEMP)
  Works exactly the same way as 'temp', but uses an external temperature
  probe for the sensing.  The temperature probe is of a silicon diode type
  and not of a thermal-resistive type.  A probe can easily be made from a
  common transister (see the ADM1021 for qualification specs) by shorting
  the base to the collector.  From the docs: "Transistors such as 2N3904,
  2N3906 or equivalents in SOT-23 package are suitable to use."

The data for each chip is updated each 1.5 seconds, but only if it is 
actually read.  And, any alarms triggered between reads which always be 
present in the next read just after the alarm was triggered (regardless if 
the alarm situation has been resolved or not).

This driver was written and is maintained by Philip Edelbrock
<phil@netroedge.com>.  Please send corrections/comments to him.  For
further technical information on this chip, please get the Acrobat PDF
documentation available from www.analog.com.  We'd also like to thank
Analog Devices for helping us with correspondance and free samples to make
this driver (and other Analog Devices drivers) possible.
