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