Subversion Repositories test_project

Kernel driver lm93

==================

Supported chips:

  * National Semiconductor LM93

    Prefix 'lm93'

    Addresses scanned: I2C 0x2c-0x2e

    Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf

Authors:

        Mark M. Hoffman 

        Ported to 2.6 by Eric J. Bowersox 

        Adapted to 2.6.20 by Carsten Emde 

        Modified for mainline integration by Hans J. Koch 

Module Parameters

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

* init: integer

  Set to non-zero to force some initializations (default is 0).

* 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, try changing this.  The default value is "0".

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

sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max,

and prochot2_max.  prochot1_max and prochot2_max contain the user limits

for #PROCHOT1 and #PROCHOT2, respectively.  prochot1 and prochot2 contain

the current readings for the most recent complete time interval.  The

value of prochot1_avg and prochot2_avg 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 sysfs files prochot1_interval and

prochot2_interval.  The values in these files specify the intervals for

#P1_PROCHOT and #P2_PROCHOT, respectively.  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 sysfs 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 sysfs files prochot1_override and prochot2_override contain boolean

integers which enable or disable the override function for #P1_PROCHOT and

#P2_PROCHOT, respectively.  The sysfs file prochot_override_duty_cycle

contains a value controlling the duty cycle for the PWM signal used when

the override function is enabled.  This value ranges from 0 to 15, with 0

indicating minimum duty cycle and 15 indicating maximum.

#VRD_HOT:

The LM93 can monitor two #VRD_HOT signals. The results are found in the

sysfs 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 sysfs file fan_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 sysfs files pwm1_override

and pwm2_override are used to enable this mode; each is a boolean integer

where 0 disables and 1 enables the manual control mode.  The sysfs files pwm1

and pwm2 are used to set the manual duty cycle; each is an integer (0-255)

where 0 is 0% duty cycle, and 255 is 100%.  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 value of pwm1 and pwm2 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 sysfs 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 (in Hz): 12, 36, 48, 60, 72, 84, 96, 22500 (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 sysfs files pwm_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

sysfs files temp_auto_base.  The offsets are expressed in cumulative

degrees C, with the value of offset  for temperature value  being

contained in the file temp_auto_offset.  E.g. if the base temperature

is 40C:

     offset #   temp_auto_offset        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_offset will also

affect temp2_auto_offset.

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 sysfs files temp_auto_offset_hyst.  The value in this file has the

same representation as in temp_auto_offset.

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 sysfs files

temp_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 sysfs files pwm_auto_spinup_min. The value in this

file 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 sysfs files pwm_auto_spinup_time. The value in this file 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 sysfs files temp_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 sysfs files temp_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 sysfs file gpio.  The

LSB is GPIO0, and the MSB is GPIO7.

LM93 Unique sysfs Files

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

        file                    description

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

        prochot         current #PROCHOT %

        prochot_avg             moving average #PROCHOT %

        prochot_max             limit #PROCHOT %

        prochot_short           enable or disable logical #PROCHOT pin short

        prochot_override        force #PROCHOT assertion as PWM

        prochot_override_duty_cycle

                                duty cycle for the PWM signal used when

                                #PROCHOT is overridden

        prochot_interval        #PROCHOT PWM sampling interval

        vrdhot          0 means negated, 1 means asserted

        fan_smart_tach  enable or disable smart tach mode

        pwm_auto_channels       select control sources for PWM outputs

        pwm_auto_spinup_min     minimum duty cycle during spin-up

        pwm_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_auto_base  temperature channel base

        temp_auto_offset[1-12]

                                temperature channel offsets

        temp_auto_offset_hyst

                                temperature channel offset hysteresis

        temp_auto_boost temperature channel boost (PWMs to 100%) limit

        temp_auto_boost_hyst    temperature channel boost hysteresis

        gpio                    input state of 8 GPIO pins; read-only