root/lm-sensors/branches/lm-sensors-2.10/doc/chips/adm1026

Kernel driver `adm1026.o'
======================

Status: In development

Supported chips:
  * Analog Devices ADM1026
    Prefix: 'adm1026'
    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

Author: Philip Pokorny <ppokorny@penguincomputing.com>
        for Penguin Computing


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

* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* force_adm1026: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  an `adm1026' 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

The following only apply to the first ADM1026 detected.  These are a
workaround for if your BIOS hasn't setup your chip.

* gpio_input: int array (min = 1, max = 17)
  List of GPIO pins (0-16) to program as inputs
* gpio_output: int array (min = 1, max = 17)
  List of GPIO pins (0-16) to program as outputs
* gpio_inverted: int array (min = 1, max = 17)
  List of GPIO pins (0-16) to program as inverted
* gpio_normal: int array (min = 1, max = 17)
  List of GPIO pins (0-16) to program as normal/non-inverted
* gpio_fan: int array (min = 1, max = 8)
  List of GPIO pins (0-7) to program as fan tachs


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

This driver implements support for the Analog Devices ADM1026.  Analog
Devices calls it a "complete thermal system management controller."  

The ADM1026 implements three (3) temperature sensors, 17 voltage
sensors, 16 general purpose digital I/O lines, eight (8) fan speed
sensors (8-bit), an analog output and a PWM output along with limit,
alarm and mask bits for all of the above.  There is even 8k bytes of
EEPROM memory on chip.

Temperatures are measured in degrees Celsius.  There are two external
sensor inputs and one internal sensor.  Each sensor has a high and low
limit.  If the limit is exceeded, an interrupt (#SMBALERT) can be
generated.  The interrupts can be masked.  In addition, there are
over-temp limits for each sensor.  If this limit is exceeded, the
#THERM output will be asserted.  The current temperature and limits
have a resolution of 1 degree.

Fan rotation speeds are reported in RPM (rotations per minute) but
measured in counts of a 22.5kHz internal clock.  Each fan has a high
limit which corresponds to a minimum fan speed.  If the limit is
exceeded, an interrupt can be generated.  Each fan can be programmed
to divide the reference clock by 1, 2, 4 or 8.  Not all RPM values can
accurately be represented, so some rounding is done. With a divider of
8, the slowest measureable speed of a one pulse per rev fan is 1323
RPM.  Two pulse per rev fans can be measured as slow as 661 RPM.

Voltage sensors (in0 to in16) 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.
Several inputs have integrated attenuators so they can measure higher
voltages directly.  3.3V, 5V, 12V, -12V and battery voltage all have
dedicated inputs.  There are several inputs scaled to 0-3V full-scale
range for SCSI terminator power.  The remaining inputs are not scaled
and have a 0-2.5V full-scale range.  A 2.5V or 1.82V reference voltage
is provided 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 ADM1026 measures continuously.  Analog inputs are measured about 4
times a second.  Fan speed measurement time depends on fan speed and
divisor.  It can take as long as 1.5 seconds to measure all fan
speeds.

The ADM1026 has the ability to automaticaly control fan speed based on
the temperature sensor inputs.  Both the PWM output and the DAC output
can be used to control fan speed.  Usually only one of these two
outputs will be used.  Write the minimum PWM or DAC value to the
appropriate control register.  Then set the low temperature limit in
the tmin values for each temperature sensor.  The range of control is
fixed at 20 degC, and the largest difference between current and tmin
of the temperature sensors sets the control output.  See the datasheet
for several example circuits for controlling fan speed with the PWM
and DAC outputs.  The fan speed sensors do not have PWM compensation,
so it is probably best to control the fan voltage from the power
lead rather than on the ground lead.

The datasheet shows an example application with VID signals attached
to GPIO lines.  Unfortunately, the chip may not be connected to the
VID lines in this way.  The driver assumes that the chips *is*
connected this way to get a vid voltage.  If the VID value is wrong or
not wired as shown in the example, then you will need to write the
correct VID value to the driver either based on the GPIO values or
setting it directly.  The value written to VID should be the *raw* VID
value (0 to 0x3f) or -1 (to restore the default value).  When read,
the vid interface returns the scaled voltage according to the VRM spec
selected.

Example sensors.conf
--------------------

Here is an example sensors.conf configuration section for the ADM1026.

--------- cut here ---------
chip "adm1026-*"

# Voltage inputs
   label in0   "V2.25_0"    # Scaled for "SCSI terminator"?
   label in1   "V2.25_1"    #   supply voltage?
   label in2   "V2.25_2"
   label in3   "V2.25_3"
   label in4   "V2.25_4"
   label in5   "V2.25_5"

   label in6   "V1.875_0"   # Unscaled inputs
   label in7   "V1.875_1"

# If temp3 is enabled, in8 and in9 are disabled.
#   label in8   "V1.875_2"
#   label in9   "V1.875_3"
   ignore in8
   ignore in9

# Dedicated voltage inputs
   label in10   "Vbat"
   label in11   "V3.3STBY"
   label in12   "V3.3MAIN"
   label in13   "V5"
   label in14   "Vccp"
   label in15   "V12"
   label in16   "V-12"

# Temperature inputs
   label temp1  "Board"
   label temp2  "CPU0"
   label temp3  "CPU1"

# Fan inputs
   label fan0   "CPU_Fan"
   label fan1   "Fan1"
   label fan2   "Fan2"
   label fan3   "Fan3"
   label fan4   "Fan4"
   label fan5   "Fan5"
   label fan6   "Fan6"
   label fan7   "Fan7"

# PWM Outputs
   label pwm   "PWM"

# Voltage scaling is done on-chip.  No 'compute' directive
#    should be necessary.  If in0-in9 have external scaling,
#    set it here.

#   compute in0  @ * 2.5,   @ / 2.5

# Adjust fans speeds for actual pulses per rev
#   compute fan0  @ / 2,  @ * 2    # 2 pulse per rev
#   compute fan1  @ / 3,  @ * 3    # 3 pulse per rev
#   compute fan2  @ / 4,  @ * 4    # 4 pulse per rev
#   compute fan3  @ / 8,  @ * 8    # 8 pulse per rev

# Set VRM version
   set vrm  9.1
#   set vid  1.580

# Set voltage limits
   set in10_min  3.0 * 0.95
   set in10_max  3.0 * 1.05
   set in11_min  3.3 * 0.95
   set in11_max  3.3 * 1.05
   set in12_min  3.3 * 0.95
   set in12_max  3.3 * 1.05
   set in13_min  5.0 * 0.95
   set in13_max  5.0 * 1.05
# Uncomment if VID is wired or set above
#   set in14_min  vid * 0.95
#   set in14_max  vid * 1.05
   set in15_min   12 * 0.95
   set in15_max   12 * 1.05
   set in16_min  -12 * 0.95
   set in16_max  -12 * 1.05

# Set Fan limits
   set fan0_min  7000
   set fan1_min  7000
   set fan2_min  7000
   set fan3_min  7000
   set fan4_min  3000
   set fan5_min  3000
   set fan6_min  3000
   set fan7_min  3000