| blob | 50deefba6d0ebb8c674bf102ba8977bfa913a82c |
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
50 The
51 .Nm
52 driver provides support for the
53 .Tn Analog Devices
54 dbCool environmental monitor chips to be used with the
55 .Xr envsys 4
56 API.
57 .Pp
58 These chips support up to fourteen sensors.
59 Not 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
80 Each temperature and voltage sensor has a
81 programmable high- and low-limit; fan sensors have only a low-limit.
82 The user can set the threshold values using
83 .Xr sysctl 8
84 .Bd -literal -offset indent
85 hw.dbcool0.l_temp.low_lim = 35 degrees C
86 hw.dbcool0.l_temp.hi_lim = 75 degrees C
87 hw.dbcool0.fan1.low_lim = 300 RPM
88 hw.dbcool0.Vcc.low_lim = 2250 milliVolts
89 hw.dbcool0.Vcc.hi_lim = 2750 milliVolts
90 .Ed
91 .Pp
92 Temperature sensors also have
93 .Em Tmin ,
94 .Em Trange ,
95 .Em Thyst ,
96 and
97 .Em Ttherm
98 .Xr sysctl 8
99 variables; these values are used by the fan speed controllers.
100 .Pp
101 All
102 .Xr sysctl 8
103 variables associated with temperature sensors are in units of degC, since
104 this is the unit which is programmed into the device registers.
105 Limit values for voltage sensors are in millivolts.
106 The low limit value for fan sensors is measured in RPM; due to
107 the manner in which fan speed is measured, the lowest possible
108 value for a fan limit is 83 RPM.
109 .Pp
110 All members of the dbCool family support Pulse-Width Modulated (PWM)
111 fan speed control based on temperature thresholds - the fan will spin up
112 when one or more thermal sensors exceeds its configured
113 .Em Tmin
114 value.
115 The fan will go faster as the temperature rises, and will slow down
116 as the temperature falls.
117 If the temperature exceeds the sensor's
118 .Em Ttherm
119 value, the THERM signal will be asserted, and if enabled the fan will
120 run at full speed.
121 The fan will be turned off when the sensor(s) that triggered it
122 reports a temperature which is at least
123 .Em Thyst
124 degrees below its
125 .Em Tmin
126 threshold.
127 .Pp
128 Each fan controller is programmable using the following
129 .Xr sysctl 8
130 variables.
131 .Bd -literal -offset indent
132 hw.dbcool0.fan_ctl_0.behavior
133 hw.dbcool0.fan_ctl_0.min_duty
134 hw.dbcool0.fan_ctl_0.max_duty
135 hw.dbcool0.fan_ctl_0.cur_duty
136 .Ed
137 .Pp
138 The
139 .Em behavior
140 variable controls the selection of temperature sensors associated with
141 the fan controller.
142 When the associated temperature sensor reaches its
143 .Em Tmin
144 value, the fan controller starts the fan at its minimum duty cycle;
145 when the associated temperature sensor reaches its
146 .Em Ttherm
147 value and asserts the THERM signal (or if an external THERM signal is
148 asserted), the fan controller sets the fan speed to a 100% duty cycle.
149 Between these two settings, each temperature sensor is used to calculate
150 a duty cycle linearly based on the slope defined by the temperature sensor's
151 .Em range
152 variable.
153 When the associated temperature falls at least
154 .Em Thyst
155 degress below its
156 .Em Tmin
157 value, the fan controller will turn off the fan.
158 (On the ADM1030, the
159 value for
160 .Em Thyst
161 is fixed at 5 degrees C.)
162 .Pp
163 Valid values for the
164 .Em behavior
165 variable are:
166 .Bd -literal -offset indent
167 local (not available on ADM1030)
168 remote1
169 remote2 (not available on ADM1030)
170 local+remote2 (not available on ADM1030)
171 all-temps
172 full-speed (not available on ADM1030)
173 manual
174 disabled
175 .Ed
176 .Pp
177 When the
178 .Em behavior
179 variable is set to
180 .Dq manual ,
181 the
182 .Em cur-duty
183 variable becomes user-writable and can be set to any value between 0 and
184 100 inclusive to control the fan's duty cycle manually.
185 In all other
186 .Em behavior
187 modes, the
188 .Em cur-duty
189 variable is read-only and updates are ignored.
190 .Pp
191 The
192 .Em min-duty
193 and
194 .Em max-duty
195 variables define the range over which the fan controller will manage the
196 fan's duty cycle.
197 On the ADM1030, these values are not separately controllable.
198 The
199 .Em max-duty
200 is fixed at 100%, and the
201 .Em cur-duty
202 variable is used to specify the minimum duty cycle when the fan
203 controller is running in automatic mode.
204 .Pp
205 Note that the duty-cycle value does not directly correspond to the fan's
206 speed.
207 That is, a 33% duty cycle does not mean that the fan runs at 33%
208 of its maximum speed; in actuality, a 33% duty cycle drives the
209 fan at a speed close to 50% of its maximum.
210 Fan speed correlates approximately to the square root of the duty
211 cycle.
212 .Sh EXAMPLES
213 The
214 .Xr envstat 8
215 utility 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
219 r1_temp: 41.250 degC
220 r2_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
229 Using this information, the following commands in
230 .Pa /etc/envsys.conf
231 will set appropriate limits for CPU temperature and chip supply
232 voltage, and powerd will be notified if the limits are exceeded:
233 .Bd -literal -offset indent
234 dbcool0 {
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
247 Alternatively, set the following commands in
248 .Pa /etc/sysctl.conf
249 to perform limit checking in the hardware:
250 .Bd -literal -offset indent
251 hw.dbcool0.r1_temp.hi_lim = 65
252 hw.dbcool0.Vcc.low_lim = 3200000
253 hw.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
261 The
262 .Nm
263 device appeared in
264 .Nx 5.0 .
265 .Sh BUGS
266 Although the sensor limit registers can be programmed, there is currently
267 no use of the dbCool chips' ability to generate an SMBus interrupt when the
268 limits are exceeded.
269 Limit checking is only performed when the sensor values are polled
270 and refreshed.
271 .Pp
272 The ADT7466 chip, although officially a member of the dbCool family, is
273 programmed quite differently.
274 The fan controllers on this chip are not currently implemented.
275 .Pp
276 The PECI (Processor Environment Control Interface) temperature sensors
277 and the associated PWM behavior modes on the ADT7490 are not currently
278 supported.