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