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

Kernel driver 'lm93.o'
======================

Status: In progress

Supported chips:
  * National Semiconductor LM93
    Prefix: 'lm93'
    Addresses scanned: I2C 0x2c-0x2e

Author:
        Mark M. Hoffman <mhoffman@lightlink.com>


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

(specific to LM93)
* init: integer
  Set to zero to disable some initializations (default is 1)
* disable_block: integer
  A "0" allows SMBus block data transactions if the host supports them.  A "1"
  disables SMBus block data transactions.  The default is 0.
* vccp_limit_type: integer array (2)
  Configures in7 and in8 limit type, where 0 means absolute and non-zero
  means relative.  "Relative" here refers to "Dynamic Vccp Monitoring using
  VID" from the datasheet.  It greatly simplifies the interface to allow
  only one set of limits (absolute or relative) to be in operation at a
  time (even though the hardware is capable of enabling both).  There's
  not a compelling use case for enabling both at once, anyway.  The default
  is "0,0".
* vid_agtl: integer
  A "0" configures the VID pins for V(ih) = 2.1V min, V(il) = 0.8V max.
  A "1" configures the VID pins for V(ih) = 0.8V min, V(il) = 0.4V max.
  (The latter setting is referred to as AGTL+ Compatible in the datasheet.)
  I.e. this parameter controls the VID pin input thresholds; if your VID
  inputs are not working, trying changing this.  The default value is "0".

(common among sensor drivers)
* force: short array (min = 1, max = 48)
  List of adapter,address pairs to assume to be present.  Autodetection
  of the target device will still be attempted.  Use one of the more
  specific force directives below if this doesn't detect the device.
* force_lm93: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a 'lm93' 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


Hardware Description
--------------------

(from the datasheet)

The LM93, hardware monitor, has a two wire digital interface compatible with
SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote
diode connected transistors as well as its own die and 16 power supply
voltages. To set fan speed, the LM93 has two PWM outputs that are each
controlled by up to four temperature zones. The fancontrol algorithm is lookup
table based. The LM93 includes a digital filter that can be invoked to smooth
temperature readings for better control of fan speed. The LM93 has four
tachometer inputs to measure fan speed. Limit and status registers for all
measured values are included. The LM93 builds upon the functionality of
previous motherboard management ASICs and uses some of the LM85's features
(i.e. smart tachometer mode). It also adds measurement and control support
for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual
processor Xeon class motherboard with a minimum of external components.


User Interface
--------------

#PROCHOT:

The LM93 can monitor two #PROCHOT signals.  The results are found in the
/proc files prochot1 and prochot2.  There are three values per file: the first
value is the user limit.  The second value is the current reading for the
most recent complete time interval.  The third value is something like a
2 period exponential moving average (but not quite - check the datasheet).
Note that this third value is calculated by the chip itself.  All values
range from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%.

The monitoring intervals for the two #PROCHOT signals is also configurable.
These intervals can be found in the /proc file prochot_interval.  There are
two values in this file: one each for #P1_PROCHOT and #P2_PROCHOT, res-
pectively.  Selecting a value not in this list will cause the driver to
use the next largest interval.  The available intervals are (in seconds):

#PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372

It is possible to configure the LM93 to logically short the two #PROCHOT
signals.  I.e. when #P1_PROCHOT is asserted, the LM93 will automatically
assert #P2_PROCHOT, and vice-versa.  This mode is enabled by writing a 
non-zero integer to the /proc file prochot_short.

The LM93 can also override the #PROCHOT pins by driving a PWM signal onto
one or both of them.  When overridden, the signal has a period of 3.56 ms,
a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and
a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle).

The /proc file prochot_override has three values.  The first two are boolean
integers which enable/disable the override funtion for #P1_PROCHOT and 
#P2_PROCHOT, the third value is 0-15 where 0 indicates minimum duty cycle
and 15 indicates maximum.

#VRD_HOT:

The LM93 can monitor two #VRD_HOT signals. The results are found in the
/proc files vrdhot1 and vrdhot2. There is one value per file: a boolean for
which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These
files are read-only.

Smart Tach Mode:

(from the datasheet)

        If a fan is driven using a low-side drive PWM, the tachometer
        output of the fan is corrupted. The LM93 includes smart tachometer
        circuitry that allows an accurate tachometer reading to be
        achieved despite the signal corruption.  In smart tach mode all
        four signals are measured within 4 seconds.

Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
the fan tachometer with a pwm) to the /proc file fan<n>_smart_tach.  A zero
will disable the function for that fan.  Note that Smart tach mode cannot be
enabled if the PWM output frequency is 22500 Hz (see below).

Manual PWM:

The LM93 has a fixed or override mode for the two PWM outputs (although, there
are still some conditions that will override even this mode - see section
15.10.6 of the datasheet for details.)  The /proc files pwm1 and pwm2 are
used to enable and control this mode.  The first value of the file is an 
integer (0-255) where 0 is 0% duty cycle, and 255 is 100%.  The second value
is a boolean integer where 0 disables and 1 enables the manual control mode.
Note that the duty cycle values are constrained by the hardware. Selecting
a value which is not available will cause the driver to use the next largest
value.  Also note: when manual PWM mode is disabled, the first value of the
/proc files indicates the current duty cycle chosen by the h/w.

PWM Output Frequency:

The LM93 supports several different frequencies for the PWM output channels.
The /proc files pwm1_freq and pwm2_freq are used to select the frequency. The
frequency values are constrained by the hardware.  Selecting a value which is
not available will cause the driver to use the next largest value.  Also note
that this parameter has implications for the Smart Tach Mode (see above).

PWM Output Frequencies: 12, 36, 48, 60, 72, 84, 96, 22500 Hz (h/w default)

Automatic PWM:

The LM93 is capable of complex automatic fan control, with many different
points of configuration.  To start, each PWM output can be bound to any 
combination of eight control sources.  The final PWM is the largest of all
individual control sources to which the PWM output is bound.

The eight control sources are: temp1-temp4 (aka "zones" in the datasheet),
#PROCHOT 1 & 2, and #VRDHOT 1 & 2.  The bindings are expressed as a bitmask
in the /proc files pwm<n>_auto_channels, where a "1" enables the binding, and
a "0" disables it. The h/w default is 0x0f (all temperatures bound).

        0x01 - Temp 1
        0x02 - Temp 2
        0x04 - Temp 3
        0x08 - Temp 4
        0x10 - #PROCHOT 1
        0x20 - #PROCHOT 2
        0x40 - #VRDHOT 1
        0x80 - #VRDHOT 2

The function y = f(x) takes a source temperature x to a PWM output y.  This
function of the LM93 is derived from a base temperature and a table of 12
temperature offsets.  The base temperature is expressed in degrees C in the
/proc files temp<n>_auto_base.  The offsets are expressed in cumulative
degrees C, with all 12 values in the files temp<n>_auto_offsets. E.g. if the
base temperature is 40C:

     offset #   temp<n>_auto_offsets    range           pwm
         1              0               -                25.00%
         2              0               -                28.57%
         3              1               40C - 41C        32.14%
         4              1               41C - 42C        35.71%
         5              2               42C - 44C        39.29%
         6              2               44C - 46C        42.86%
         7              2               48C - 50C        46.43%
         8              2               50C - 52C        50.00%
         9              2               52C - 54C        53.57%
        10              2               54C - 56C        57.14%
        11              2               56C - 58C        71.43%
        12              2               58C - 60C        85.71%
                                        > 60C           100.00%
        
Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments.

There is an independent base temperature for each temperature channel. Note,
however, there are only two tables of offsets: one each for temp[12] and
temp[34].  Therefore, any change to e.g. temp1_auto_offsets will also affect
temp2_auto_offsets.

The LM93 can also apply hysteresis to the offset table, to prevent unwanted
oscillation between two steps in the offsets table.  These values are found in
the /proc files temp<n>_auto_offset_hyst.  There is just one value; it has the
same representation as in temp<n>_auto_offsets.

If a temperature reading falls below the base value for that channel, the LM93
will use the minimum PWM value.  These values are found in the /proc files
temp<n>_auto_pwm_min.  Note, there are only two minimums: one each for temp[12]
and temp[34].  Therefore, any change to e.g. temp1_auto_pwm_min will also
affect temp2_auto_pwm_min.

PWM Spin-Up Cycle:

A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to
some value > 0%.  The LM93 supports a minimum duty cycle during spin-up.  These
values are found in the /proc files pwm<n>_auto_spinup_min. There is one value
per file; it has the same representation as other PWM duty cycle values. The
duration of the spin-up cycle is also configurable.  These values are  found in
the /proc files pwm<n>_auto_spinup_time. There is one value per file; it is
the spin-up time in seconds.  The available spin-up times are constrained by
the hardware.  Selecting a value which is not available will cause the driver
to use the next largest value.

Spin-up Durations: 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0, 2.0, 4.0

#PROCHOT and #VRDHOT PWM Ramping:

If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output
channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete
steps. The duration of each step is configurable. There are two files, with
one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp.
The available ramp times are constrained by the hardware.  Selecting a value
which is not available will cause the driver to use the next largest value.

Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals

Fan Boost:

For each temperature channel, there is a boost temperature: if the channel
exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%.
This limit is expressed in degrees C in the /proc files temp<n>_auto_boost.
There is also a hysteresis temperature for this function: after the boost
limit is reached, the temperature channel must drop below this value before
the boost function is disabled.  This temperature is also expressed in degrees
C in the /proc files temp<n>_auto_boost_hyst.

GPIO Pins:

The LM93 can monitor the logic level of four dedicated GPIO pins as well as the
four tach input pins.  GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively.
All eight GPIOs are read by reading the bitmask in the /proc file gpio.  The
LSB is GPIO0, and the MSB is GPIO7.


LM93 Unique /proc Files
-----------------------

        file                    description
        -------------------------------------------------------------

        prochot<n>              limit, current, and moving average #PROCHOT %

        prochot_short           enable or disable logical #PROCHOT pin short

        prochot_override        force #PROCHOT assertion as PWM

        prochot_interval        #PROCHOT PWM sampling interval

        vrdhot<n>               0 means negated, 1 means asserted

        fan<n>_smart_tach       enable or disable smart tach mode

        pwm<n>_auto_spinup_min  minimum duty cycle during spin-up

        pwm<n>_auto_spinup_time duration of spin-up

        pwm_auto_prochot_ramp   ramp time per step when #PROCHOT asserted

        pwm_auto_vrdhot_ramp    ramp time per step when #VRDHOT asserted

        temp<n>_auto_base       temperature channel base

        temp<n>_auto_offsets    temperature channel offsets

        temp<n>_auto_offset_hyst
                                temperature channel offset hysteresis

        temp<n>_auto_boost      temperature channel boost (PWMs to 100%) limit

        temp<n>_auto_boost_hyst temperature channel boost hysteresis

        gpio                    input state of 8 GPIO pins; read-only


Sample Configuration File
-------------------------

Here is a sample LM93 chip config for sensors.conf:

---------- cut here ----------
chip "lm93-*"

# VOLTAGE INPUTS

        # labels and scaling based on datasheet recommendations
        label in1       "+12V1"
        compute in1     @ * 12.945, @ / 12.945
        set in1_min     12 * 0.90
        set in1_max     12 * 1.10

        label in2       "+12V2"
        compute in2     @ * 12.945, @ / 12.945
        set in2_min     12 * 0.90
        set in2_max     12 * 1.10

        label in3       "+12V3"
        compute in3     @ * 12.945, @ / 12.945
        set in3_min     12 * 0.90
        set in3_max     12 * 1.10

        label in4       "FSB_Vtt"

        label in5       "3GIO"

        label in6       "ICH_Core"

        label in7       "Vccp1"

        label in8       "Vccp2"

        label in9       "+3.3V"
        set in9_min     3.3 * 0.90
        set in9_max     3.3 * 1.10

        label in10      "+5V"
        set in10_min    5.0 * 0.90
        set in10_max    5.0 * 1.10

        label in11      "SCSI_Core"

        label in12      "Mem_Core"

        label in13      "Mem_Vtt"

        label in14      "Gbit_Core"

        # Assuming R1/R2 = 4.1143, and 3.3V reference
        # -12V = (4.1143 + 1) * (@ - 3.3) + 3.3
        label in15      "-12V"
        compute in15 @ * 5.1143 - 13.57719, (@ + 13.57719) / 5.1143
        set in15_min    -12 * 0.90
        set in15_max    -12 * 1.10

        label in16      "+3.3VSB"
        set in16_min    3.3 * 0.90
        set in16_max    3.3 * 1.10

# TEMPERATURE INPUTS

        label temp1     "CPU1"
        label temp2     "CPU2"
        label temp3     "LM93"

# TACHOMETER INPUTS

        label fan1      "Fan1"
        set fan1_min    3000
        label fan2      "Fan2"
        set fan2_min    3000
        label fan3      "Fan3"
        set fan3_min    3000
        label fan4      "Fan4"
        set fan4_min    3000

# PWM OUTPUTS

        label pwm1      "CPU1"
        label pwm2      "CPU2"