DBCOOL(4)               NetBSD Kernel Interfaces Manual              DBCOOL(4)

NAME
     dbcool, adm1027, adm1030, adt7463, adt7466, adt7467, adt7468, adt7473,
     adt7475, adt7476, adt7490 -- dbCool(tm) family of environmental monitors
     and fan controllers

SYNOPSIS
     dbcool* at ki2c?
     dbcool* at iic? addr 0x2e

DESCRIPTION
     The dbcool driver provides support for the Analog Devices dbCool environ-
     mental monitor chips to be used with the envsys(4) API.

     These chips support up to fourteen sensors.  Not all of the following
     sensors are supported on all chips.

           Sensor    Units    Typical Use
           l_temp    uK       local chip temperature
           r1_temp   uK       CPU temperature
           r2_temp   uK       GPU temperature
           Vccp      uV DC    CPU Vcore
           Vcc       uV DC    Chip's supply voltage
           2.5V      uV DC    2.5V supply
           5V        uV DC    5V supply
           12V       uV DC    12V supply
           Vtt       uV DC    PECI ref. voltage (2.25V ref, ADT7490 only)
           Imon      uV DC    Current monitor (2.25V ref, ADT7490 only)
           AIN1      uV DC    Analog In (2.25V ref, ADT7466 only)
           AIN2      uV DC    Analog In (2.25V ref, ADT7466 only)
           fan1      RPM      Chassis Fan
           fan2      RPM      Chassis Fan
           fan3      RPM      Chassis Fan
           fan4      RPM      Chassis Fan

     Each temperature and voltage sensor has a programmable high- and low-
     limit; fan sensors have only a low-limit.  The user can set the threshold
     values using sysctl(8)

           hw.dbcool0.l_temp.low_lim = 35         degrees C
           hw.dbcool0.l_temp.hi_lim = 75          degrees C
           hw.dbcool0.fan1.low_lim = 300          RPM
           hw.dbcool0.Vcc.low_lim = 2250          milliVolts
           hw.dbcool0.Vcc.hi_lim = 2750           milliVolts

     Temperature sensors also have Tmin, Trange, Thyst, and Ttherm sysctl(8)
     variables; these values are used by the fan speed controllers.

     All sysctl(8) variables associated with temperature sensors are in units
     of degC, since this is the unit which is programmed into the device reg-
     isters.  Limit values for voltage sensors are in millivolts.  The low
     limit value for fan sensors is measured in RPM; due to the manner in
     which fan speed is measured, the lowest possible value for a fan limit is
     83 RPM.

     All members of the dbCool family support Pulse-Width Modulated (PWM) fan
     speed control based on temperature thresholds - the fan will spin up when
     one or more thermal sensors exceeds its configured Tmin value.  The fan
     will go faster as the temperature rises, and will slow down as the tem-
     perature falls.  If the temperature exceeds the sensor's Ttherm value,
     the THERM signal will be asserted, and if enabled the fan will run at
     full speed.  The fan will be turned off when the sensor(s) that triggered
     it reports a temperature which is at least Thyst degrees below its Tmin
     threshold.

     Each fan controller is programmable using the following sysctl(8) vari-
     ables.

           hw.dbcool0.fan_ctl_0.behavior
           hw.dbcool0.fan_ctl_0.min_duty
           hw.dbcool0.fan_ctl_0.max_duty
           hw.dbcool0.fan_ctl_0.cur_duty

     The behavior variable controls the selection of temperature sensors asso-
     ciated with the fan controller.  When the associated temperature sensor
     reaches its Tmin value, the fan controller starts the fan at its minimum
     duty cycle; when the associated temperature sensor reaches its Ttherm
     value and asserts the THERM signal (or if an external THERM signal is
     asserted), the fan controller sets the fan speed to a 100% duty cycle.
     Between these two settings, each temperature sensor is used to calculate
     a duty cycle linearly based on the slope defined by the temperature sen-
     sor's range variable.  When the associated temperature falls at least
     Thyst degress below its Tmin value, the fan controller will turn off the
     fan.  (On the ADM1030, the value for Thyst is fixed at 5 degrees C.)

     Valid values for the behavior variable are:

           local           (not available on ADM1030)
           remote1
           remote2         (not available on ADM1030)
           local+remote2   (not available on ADM1030)
           all-temps
           full-speed      (not available on ADM1030)
           manual
           disabled

     When the behavior variable is set to ``manual'', the cur-duty variable
     becomes user-writeable and can be set to any value between 0 and 100
     inclusive to control the fan's duty cycle manually.  In all other
     behavior modes, the cur-duty variable is read-only and updates are
     ignored.

     The min-duty and max-duty variables define the range over which the fan
     controller will manage the fan's duty cycle.  On the ADM1030, these val-
     ues are not separately controllable.  The max-duty is fixed at 100%, and
     the cur-duty variable is used to specify the minimum duty cycle when the
     fan controller is running in automatic mode.

     Note that the duty-cycle value does not directly correspond to the fan's
     speed.  That is, a 33% duty cycle does not mean that the fan runs at 33%
     of its maximum speed; in actuality, a 33% duty cycle drives the fan at a
     speed close to 50% of its maximum.  Fan speed correlates approximately to
     the square root of the duty cycle.

EXAMPLES
     The envstat(8) utility can be used to determine the sensors supported:

                       Current  CritMax  CritMin  CritCap     Unit
            l_temp:     44.250                                degC
           r1_temp:     41.250                                degC
           r2_temp:        N/A
              Vccp:      0.002                                   V
               Vcc:      3.351                                   V
              fan1:        N/A
              fan2:        N/A
              fan3:        N/A
              fan4:        N/A

     Using this information, the following commands in /etc/envsys.conf will
     set appropriate limits for CPU temperature and chip supply voltage, and
     powerd will be notified if the limits are exceeded:

           dbcool0 {
                   sensor1 {
                           warning-max  = 60C;
                           critical-max = 65C;
                   }
                   sensor4 {
                           critical-min = 3.1;
                           warning-min =  3.2;
                           critical-max = 3.5;
                   }
           }

     Alternatively, set the following commands in /etc/sysctl.conf to perform
     limit checking in the hardware:

           hw.dbcool0.r1_temp.hi_lim = 65
           hw.dbcool0.Vcc.low_lim = 3200000
           hw.dbcool0.Vcc.hi_lim = 3500000

SEE ALSO
     envsys(4), envstat(8), powerd(8), sysctl(8)

HISTORY
     The dbcool device appeared in NetBSD 5.0.

BUGS
     Although the sensor limit registers can be programmed, there is currently
     no use of the dbCool chips' ability to generate an SMBus interrupt when
     the limits are exceeded.  Limit checking is only performed when the sen-
     sor values are polled and refreshed.

     The ADT7466 chip, although officially a member of the dbCool family, is
     programmed quite differently.  The fan controllers on this chip are not
     currently implemented.

     The PECI (Processor Environment Control Interface) temperature sensors
     and the associated PWM behavior modes on the ADT7490 are not currently
     supported.

NetBSD 5.0_STABLE               October 5, 2008              NetBSD 5.0_STABLE
