1.\" $NetBSD: dbcool.4,v 1.3 2008/10/06 01:35:35 pgoyette Exp $ 2.\" 3.\" Copyright (c) 2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Goyette. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 5, 2008 31.Dt DBCOOL 4 32.Os 33.Sh NAME 34.Nm dbcool , 35.Nm adm1027 , 36.Nm adm1030 , 37.Nm adt7463 , 38.Nm adt7466 , 39.Nm adt7467 , 40.Nm adt7468 , 41.Nm adt7473 , 42.Nm adt7475 , 43.Nm adt7476 , 44.Nm adt7490 45.Nd dbCool(tm) family of environmental monitors and fan controllers 46.Sh SYNOPSIS 47.Cd "dbcool* at ki2c?" 48.Cd "dbcool* at iic? addr 0x2e" 49.Sh DESCRIPTION 50The 51.Nm 52driver provides support for the 53.Tn Analog Devices 54dbCool environmental monitor chips to be used with the 55.Xr envsys 4 56API. 57.Pp 58These chips support up to fourteen sensors. 59Not all of the following sensors are supported on all chips. 60.Bl -column "Sensor" "Units" "Typical" -offset indent 61.It Sy "Sensor" Ta Sy "Units" Ta Sy "Typical Use" 62.It Li "l_temp" Ta "uK" Ta "local chip temperature" 63.It Li "r1_temp" Ta "uK" Ta "CPU temperature" 64.It Li "r2_temp" Ta "uK" Ta "GPU temperature" 65.It Li "Vccp" Ta "uV DC" Ta "CPU Vcore" 66.It Li "Vcc" Ta "uV DC" Ta "Chip's supply voltage" 67.It Li "2.5V" Ta "uV DC" Ta "2.5V supply" 68.It Li "5V" Ta "uV DC" Ta "5V supply" 69.It Li "12V" Ta "uV DC" Ta "12V supply" 70.It Li "Vtt" Ta "uV DC" Ta "PECI ref. voltage (2.25V ref, ADT7490 only)" 71.It Li "Imon" Ta "uV DC" Ta "Current monitor (2.25V ref, ADT7490 only)" 72.It Li "AIN1" Ta "uV DC" Ta "Analog In (2.25V ref, ADT7466 only)" 73.It Li "AIN2" Ta "uV DC" Ta "Analog In (2.25V ref, ADT7466 only)" 74.It Li "fan1" Ta "RPM" Ta "Chassis Fan" 75.It Li "fan2" Ta "RPM" Ta "Chassis Fan" 76.It Li "fan3" Ta "RPM" Ta "Chassis Fan" 77.It Li "fan4" Ta "RPM" Ta "Chassis Fan" 78.El 79.Pp 80Each temperature and voltage sensor has a 81programmable high- and low-limit; fan sensors have only a low-limit. 82The user can set the threshold values using 83.Xr sysctl 8 84.Bd -literal -offset indent 85hw.dbcool0.l_temp.low_lim = 35 degrees C 86hw.dbcool0.l_temp.hi_lim = 75 degrees C 87hw.dbcool0.fan1.low_lim = 300 RPM 88hw.dbcool0.Vcc.low_lim = 2250 milliVolts 89hw.dbcool0.Vcc.hi_lim = 2750 milliVolts 90.Ed 91.Pp 92Temperature sensors also have 93.Em Tmin , 94.Em Trange , 95.Em Thyst , 96and 97.Em Ttherm 98.Xr sysctl 8 99variables; these values are used by the fan speed controllers. 100.Pp 101All 102.Xr sysctl 8 103variables associated with temperature sensors are in units of degC, since 104this is the unit which is programmed into the device registers. 105Limit values for voltage sensors are in millivolts. 106The low limit value for fan sensors is measured in RPM; due to 107the manner in which fan speed is measured, the lowest possible 108value for a fan limit is 83 RPM. 109.Pp 110All members of the dbCool family support Pulse-Width Modulated (PWM) 111fan speed control based on temperature thresholds - the fan will spin up 112when one or more thermal sensors exceeds its configured 113.Em Tmin 114value. 115The fan will go faster as the temperature rises, and will slow down 116as the temperature falls. 117If the temperature exceeds the sensor's 118.Em Ttherm 119value, the THERM signal will be asserted, and if enabled the fan will 120run at full speed. 121The fan will be turned off when the sensor(s) that triggered it 122reports a temperature which is at least 123.Em Thyst 124degrees below its 125.Em Tmin 126threshold. 127.Pp 128Each fan controller is programmable using the following 129.Xr sysctl 8 130variables. 131.Bd -literal -offset indent 132hw.dbcool0.fan_ctl_0.behavior 133hw.dbcool0.fan_ctl_0.min_duty 134hw.dbcool0.fan_ctl_0.max_duty 135hw.dbcool0.fan_ctl_0.cur_duty 136.Ed 137.Pp 138The 139.Em behavior 140variable controls the selection of temperature sensors associated with 141the fan controller. 142When the associated temperature sensor reaches its 143.Em Tmin 144value, the fan controller starts the fan at its minimum duty cycle; 145when the associated temperature sensor reaches its 146.Em Ttherm 147value and asserts the THERM signal (or if an external THERM signal is 148asserted), the fan controller sets the fan speed to a 100% duty cycle. 149Between these two settings, each temperature sensor is used to calculate 150a duty cycle linearly based on the slope defined by the temperature sensor's 151.Em range 152variable. 153When the associated temperature falls at least 154.Em Thyst 155degress below its 156.Em Tmin 157value, the fan controller will turn off the fan. 158(On the ADM1030, the 159value for 160.Em Thyst 161is fixed at 5 degrees C.) 162.Pp 163Valid values for the 164.Em behavior 165variable are: 166.Bd -literal -offset indent 167local (not available on ADM1030) 168remote1 169remote2 (not available on ADM1030) 170local+remote2 (not available on ADM1030) 171all-temps 172full-speed (not available on ADM1030) 173manual 174disabled 175.Ed 176.Pp 177When the 178.Em behavior 179variable is set to 180.Dq manual , 181the 182.Em cur-duty 183variable becomes user-writeable and can be set to any value between 0 and 184100 inclusive to control the fan's duty cycle manually. 185In all other 186.Em behavior 187modes, the 188.Em cur-duty 189variable is read-only and updates are ignored. 190.Pp 191The 192.Em min-duty 193and 194.Em max-duty 195variables define the range over which the fan controller will manage the 196fan's duty cycle. 197On the ADM1030, these values are not separately controllable. 198The 199.Em max-duty 200is fixed at 100%, and the 201.Em cur-duty 202variable is used to specify the minimum duty cycle when the fan 203controller is running in automatic mode. 204.Pp 205Note that the duty-cycle value does not directly correspond to the fan's 206speed. 207That is, a 33% duty cycle does not mean that the fan runs at 33% 208of its maximum speed; in actuality, a 33% duty cycle drives the 209fan at a speed close to 50% of its maximum. 210Fan speed correlates approximately to the square root of the duty 211cycle. 212.Sh EXAMPLES 213The 214.Xr envstat 8 215utility can be used to determine the sensors supported: 216.Bd -literal -offset indent 217 Current CritMax CritMin CritCap Unit 218 l_temp: 44.250 degC 219r1_temp: 41.250 degC 220r2_temp: N/A 221 Vccp: 0.002 V 222 Vcc: 3.351 V 223 fan1: N/A 224 fan2: N/A 225 fan3: N/A 226 fan4: N/A 227.Ed 228.Pp 229Using this information, the following commands in 230.Pa /etc/envsys.conf 231will set appropriate limits for CPU temperature and chip supply 232voltage, and powerd will be notified if the limits are exceeded: 233.Bd -literal -offset indent 234dbcool0 { 235 sensor1 { 236 warning-max = 60C; 237 critical-max = 65C; 238 } 239 sensor4 { 240 critical-min = 3.1; 241 warning-min = 3.2; 242 critical-max = 3.5; 243 } 244} 245.Ed 246.Pp 247Alternatively, set the following commands in 248.Pa /etc/sysctl.conf 249to perform limit checking in the hardware: 250.Bd -literal -offset indent 251hw.dbcool0.r1_temp.hi_lim = 65 252hw.dbcool0.Vcc.low_lim = 3200000 253hw.dbcool0.Vcc.hi_lim = 3500000 254.Ed 255.Sh SEE ALSO 256.Xr envsys 4 , 257.Xr envstat 8 , 258.Xr powerd 8 , 259.Xr sysctl 8 260.Sh HISTORY 261The 262.Nm 263device appeared in 264.Nx 5.0 . 265.Sh BUGS 266Although the sensor limit registers can be programmed, there is currently 267no use of the dbCool chips' ability to generate an SMBus interrupt when the 268limits are exceeded. 269Limit checking is only performed when the sensor values are polled 270and refreshed. 271.Pp 272The ADT7466 chip, although officially a member of the dbCool family, is 273programmed quite differently. 274The fan controllers on this chip are not currently implemented. 275.Pp 276The PECI (Processor Environment Control Interface) temperature sensors 277and the associated PWM behavior modes on the ADT7490 are not currently 278supported. 279