1.\" $NetBSD: dbcool.4,v 1.7 2010/03/01 03:15:16 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 February 26, 2010 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 fifteen 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.It Li "VID" Ta "(none)" Ta "CPU VID code (selected chips only)" 79.El 80.Pp 81Each temperature and voltage sensor has programmable hardware 82high- and low-limits; fan sensors have only a low-limit. 83These limits can be set using the 84.Xr envstat 8 85utility. 86Due to hardware limitations, the minimum permissible value for the fan 87speed low-limits is 83 RPM. 88.Pp 89Temperature sensors also have 90.Em Tmin , 91.Em Trange , 92.Em Thyst , 93and 94.Em Ttherm 95.Xr sysctl 8 96variables; these values are used by the fan speed controllers. 97Their values are in units of degC, since this is the unit which is 98programmed into the device registers. 99.Pp 100All members of the dbCool family support Pulse-Width Modulated (PWM) 101fan speed control based on temperature thresholds - the fan will spin up 102when its associated thermal sensor(s) exceeds its configured 103.Em Tmin 104value. 105The fan will go faster as the temperature rises, and will slow down 106as the temperature falls. 107If the temperature exceeds the sensor's 108.Em Ttherm 109value, the THERM signal will be asserted, and if enabled the fan will 110run at full speed. 111The fan will be turned off when the sensor(s) that triggered it 112reports a temperature which is at least 113.Em Thyst 114degrees below its 115.Em Tmin 116threshold. 117.Pp 118Each fan controller is programmable using the following 119.Xr sysctl 8 120variables. 121.Bd -literal -offset indent 122hw.dbcool0.fan_ctl_0.behavior 123hw.dbcool0.fan_ctl_0.min_duty 124hw.dbcool0.fan_ctl_0.max_duty 125hw.dbcool0.fan_ctl_0.cur_duty 126.Ed 127.Pp 128The 129.Em behavior 130variable controls the selection of temperature sensors associated with 131the fan controller. 132When the associated temperature sensor reaches its 133.Em Tmin 134value, the fan controller starts the fan at its minimum duty cycle; 135when the associated temperature sensor reaches its 136.Em Ttherm 137value and asserts the THERM signal (or if an external THERM signal is 138asserted), the fan controller sets the fan speed to a 100% duty cycle. 139Between these two settings, each temperature sensor is used to calculate 140a duty cycle linearly based on the slope defined by the temperature sensor's 141.Em range 142variable. 143When the associated temperature falls at least 144.Em Thyst 145degress below its 146.Em Tmin 147value, the fan controller will turn off the fan. 148(On the ADM1030, the 149value for 150.Em Thyst 151is fixed at 5 degC.) 152.Pp 153Valid values for the 154.Em behavior 155variable are: 156.Bd -literal -offset indent 157local (not available on ADM1030) 158remote1 159remote2 (not available on ADM1030) 160local+remote2 (not available on ADM1030) 161all-temps 162full-speed (not available on ADM1030) 163manual 164disabled 165.Ed 166.Pp 167When the 168.Em behavior 169variable is set to 170.Dq manual , 171the 172.Em cur-duty 173variable becomes user-writable and can be set to any value between 0 and 174100 inclusive to control the fan's duty cycle manually. 175In all other 176.Em behavior 177modes, the 178.Em cur-duty 179variable is read-only and updates are ignored. 180.Pp 181The 182.Em min-duty 183and 184.Em max-duty 185variables define the range over which the fan controller will manage the 186fan's duty cycle. 187On the ADM1030, these values are not separately controllable. 188The 189.Em max-duty 190is fixed at 100%, and the 191.Em cur-duty 192variable is used to specify the minimum duty cycle when the fan 193controller is running in automatic mode. 194.Pp 195Note that the duty-cycle value does not directly correspond to the fan's 196speed. 197That is, a 33% duty cycle does not mean that the fan runs at 33% 198of its maximum speed; in actuality, a 33% duty cycle drives the 199fan at a speed close to 50% of its maximum. 200Fan speed correlates approximately to the square root of the duty 201cycle. 202.Sh EXAMPLES 203The 204.Xr envstat 8 205utility can be used to determine the sensors supported: 206.Bd -literal -offset indent 207 Current CritMax WarnMax WarnMin CritMin Unit 208 l_temp: 44.250 degC 209r1_temp: 41.250 degC 210r2_temp: N/A 211 Vccp: 0.002 V 212 Vcc: 3.351 V 213 fan1: N/A 214 fan2: N/A 215 fan3: N/A 216 fan4: N/A 217.Ed 218.Pp 219Using this information, the following commands in 220.Pa /etc/envsys.conf 221will set appropriate limits for CPU temperature and chip supply 222voltage, and powerd will be notified if the limits are exceeded: 223.Bd -literal -offset indent 224dbcool0 { 225 sensor1 { 226 warning-max = 60C; 227 critical-max = 65C; 228 } 229 sensor4 { 230 critical-min = 3.1; 231 warning-min = 3.2; 232 critical-max = 3.5; 233 } 234} 235.Ed 236.Sh SEE ALSO 237.Xr envsys 4 , 238.Xr iic 4 , 239.Xr envstat 8 , 240.Xr powerd 8 , 241.Xr sysctl 8 242.Sh HISTORY 243The 244.Nm 245device appeared in 246.Nx 5.0 . 247.Sh BUGS 248Although the sensor limit registers can be programmed, there is currently 249no use of the dbCool chips' ability to generate an SMBus interrupt when the 250limits are exceeded. 251Limit checking and event generation are done in software, and are performed 252only when the sensor values are polled and refreshed. 253.Pp 254The ADT7466 chip, although officially a member of the dbCool family, is 255programmed quite differently. 256The fan controllers on this chip are not currently implemented. 257.Pp 258The PECI (Processor Environment Control Interface) temperature sensors 259and the associated PWM behavior modes on the ADT7490 are not currently 260supported. 261