blob: 4e4a1dc1d2da98713de94ffacf61f495e5115e17 [file] [log] [blame]
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +02001Kernel driver lm93
2==================
3
4Supported chips:
5 * National Semiconductor LM93
6 Prefix 'lm93'
7 Addresses scanned: I2C 0x2c-0x2e
8 Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf
9
10Author:
11 Mark M. Hoffman <mhoffman@lightlink.com>
12 Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com>
13 Adapted to 2.6.20 by Carsten Emde <ce@osadl.org>
14 Modified for mainline integration by Hans J. Koch <hjk@linutronix.de>
15
16Module Parameters
17-----------------
18
19(specific to LM93)
20* init: integer
21 Set to non-zero to force some initializations (default is 0).
22* disable_block: integer
23 A "0" allows SMBus block data transactions if the host supports them. A "1"
24 disables SMBus block data transactions. The default is 0.
25* vccp_limit_type: integer array (2)
26 Configures in7 and in8 limit type, where 0 means absolute and non-zero
27 means relative. "Relative" here refers to "Dynamic Vccp Monitoring using
28 VID" from the datasheet. It greatly simplifies the interface to allow
29 only one set of limits (absolute or relative) to be in operation at a
30 time (even though the hardware is capable of enabling both). There's
31 not a compelling use case for enabling both at once, anyway. The default
32 is "0,0".
33* vid_agtl: integer
34 A "0" configures the VID pins for V(ih) = 2.1V min, V(il) = 0.8V max.
35 A "1" configures the VID pins for V(ih) = 0.8V min, V(il) = 0.4V max.
36 (The latter setting is referred to as AGTL+ Compatible in the datasheet.)
37 I.e. this parameter controls the VID pin input thresholds; if your VID
38 inputs are not working, try changing this. The default value is "0".
39
40(common among sensor drivers)
41* force: short array (min = 1, max = 48)
42 List of adapter,address pairs to assume to be present. Autodetection
43 of the target device will still be attempted. Use one of the more
44 specific force directives below if this doesn't detect the device.
45* force_lm93: short array (min = 1, max = 48)
46 List of adapter,address pairs which are unquestionably assumed to contain
47 a 'lm93' chip
48* ignore: short array (min = 1, max = 48)
49 List of adapter,address pairs not to scan
50* ignore_range: short array (min = 1, max = 48)
51 List of adapter,start-addr,end-addr triples not to scan
52* probe: short array (min = 1, max = 48)
53 List of adapter,address pairs to scan additionally
54* probe_range: short array (min = 1, max = 48)
55 List of adapter,start-addr,end-addr triples to scan additionally
56
57
58Hardware Description
59--------------------
60
61(from the datasheet)
62
63The LM93, hardware monitor, has a two wire digital interface compatible with
64SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote
65diode connected transistors as well as its own die and 16 power supply
66voltages. To set fan speed, the LM93 has two PWM outputs that are each
67controlled by up to four temperature zones. The fancontrol algorithm is lookup
68table based. The LM93 includes a digital filter that can be invoked to smooth
69temperature readings for better control of fan speed. The LM93 has four
70tachometer inputs to measure fan speed. Limit and status registers for all
71measured values are included. The LM93 builds upon the functionality of
72previous motherboard management ASICs and uses some of the LM85 s features
73(i.e. smart tachometer mode). It also adds measurement and control support
74for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual
75processor Xeon class motherboard with a minimum of external components.
76
77
78Driver Description
79------------------
80
81This driver implements support for the National Semiconductor LM93.
82
83
84User Interface
85--------------
86
87#PROCHOT:
88
89The LM93 can monitor two #PROCHOT signals. The results are found in the
90sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max,
91and prochot2_max. prochot1_max and prochot2_max contain the user limits
92for #PROCHOT1 and #PROCHOT2, respectively. prochot1 and prochot2 contain
93the current readings for the most recent complete time interval. The
94value of prochot1_avg and prochot2_avg is something like a 2 period
95exponential moving average (but not quite - check the datasheet). Note
96that this third value is calculated by the chip itself. All values range
97from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%.
98
99The monitoring intervals for the two #PROCHOT signals is also configurable.
100These intervals can be found in the sysfs files prochot1_interval and
101prochot2_interval. The values in these files specify the intervals for
102#P1_PROCHOT and #P2_PROCHOT, respectively. Selecting a value not in this
103list will cause the driver to use the next largest interval. The available
104intervals are:
105
106#PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372
107
108It is possible to configure the LM93 to logically short the two #PROCHOT
109signals. I.e. when #P1_PROCHOT is asserted, the LM93 will automatically
110assert #P2_PROCHOT, and vice-versa. This mode is enabled by writing a
111non-zero integer to the sysfs file prochot_short.
112
113The LM93 can also override the #PROCHOT pins by driving a PWM signal onto
114one or both of them. When overridden, the signal has a period of 3.56 mS,
115a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and
116a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle).
117
118The sysfs files prochot1_override and prochot2_override contain boolean
119intgers which enable or disable the override function for #P1_PROCHOT and
120#P2_PROCHOT, respectively. The sysfs file prochot_override_duty_cycle
121contains a value controlling the duty cycle for the PWM signal used when
122the override function is enabled. This value ranges from 0 to 15, with 0
123indicating minimum duty cycle and 15 indicating maximum.
124
125#VRD_HOT:
126
127The LM93 can monitor two #VRD_HOT signals. The results are found in the
128sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for
129which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These
130files are read-only.
131
132Smart Tach Mode:
133
134(from the datasheet)
135
136 If a fan is driven using a low-side drive PWM, the tachometer
137 output of the fan is corrupted. The LM93 includes smart tachometer
138 circuitry that allows an accurate tachometer reading to be
139 achieved despite the signal corruption. In smart tach mode all
140 four signals are measured within 4 seconds.
141
142Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
143the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero
144will disable the function for that fan. Note that Smart tach mode cannot be
145enabled if the PWM output frequency is 22500 Hz (see below).
146
147Manual PWM:
148
149The LM93 has a fixed or override mode for the two PWM outputs (although, there
150are still some conditions that will override even this mode - see section
15115.10.6 of the datasheet for details.) The sysfs files pwm1_override
152and pwm2_override are used to enable this mode; each is a boolean integer
153where 0 disables and 1 enables the manual control mode. The sysfs files pwm1
154and pwm2 are used to set the manual duty cycle; each is an integer (0-255)
155where 0 is 0% duty cycle, and 255 is 100%. Note that the duty cycle values
156are constrained by the hardware. Selecting a value which is not available
157will cause the driver to use the next largest value. Also note: when manual
158PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty
159cycle chosen by the h/w.
160
161PWM Output Frequency:
162
163The LM93 supports several different frequencies for the PWM output channels.
164The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The
165frequency values are constrained by the hardware. Selecting a value which is
166not available will cause the driver to use the next largest value. Also note
167that this parameter has implications for the Smart Tach Mode (see above).
168
169PWM Output Frequencies: 12, 36, 48, 60, 72, 84, 96, 22500 (h/w default)
170
171Automatic PWM:
172
173The LM93 is capable of complex automatic fan control, with many different
174points of configuration. To start, each PWM output can be bound to any
175combination of eight control sources. The final PWM is the largest of all
176individual control sources to which the PWM output is bound.
177
178The eight control sources are: temp1-temp4 (aka "zones" in the datasheet),
179#PROCHOT 1 & 2, and #VRDHOT 1 & 2. The bindings are expressed as a bitmask
180in the sysfs files pwm<n>_auto_channels, where a "1" enables the binding, and
181 a "0" disables it. The h/w default is 0x0f (all temperatures bound).
182
183 0x01 - Temp 1
184 0x02 - Temp 2
185 0x04 - Temp 3
186 0x08 - Temp 4
187 0x10 - #PROCHOT 1
188 0x20 - #PROCHOT 2
189 0x40 - #VRDHOT 1
190 0x80 - #VRDHOT 2
191
192The function y = f(x) takes a source temperature x to a PWM output y. This
193function of the LM93 is derived from a base temperature and a table of 12
194temperature offsets. The base temperature is expressed in degrees C in the
195sysfs files temp<n>_auto_base. The offsets are expressed in cumulative
196degrees C, with the value of offset <i> for temperature value <n> being
197contained in the file temp<n>_auto_offset<i>. E.g. if the base temperature
198is 40C:
199
200 offset # temp<n>_auto_offset<i> range pwm
201 1 0 - 25.00%
202 2 0 - 28.57%
203 3 1 40C - 41C 32.14%
204 4 1 41C - 42C 35.71%
205 5 2 42C - 44C 39.29%
206 6 2 44C - 46C 42.86%
207 7 2 48C - 50C 46.43%
208 8 2 50C - 52C 50.00%
209 9 2 52C - 54C 53.57%
210 10 2 54C - 56C 57.14%
211 11 2 56C - 58C 71.43%
212 12 2 58C - 60C 85.71%
213 > 60C 100.00%
214
215Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments.
216
217There is an independent base temperature for each temperature channel. Note,
218however, there are only two tables of offsets: one each for temp[12] and
219temp[34]. Therefore, any change to e.g. temp1_auto_offset<i> will also
220affect temp2_auto_offset<i>.
221
222The LM93 can also apply hysteresis to the offset table, to prevent unwanted
223oscillation between two steps in the offsets table. These values are found in
224the sysfs files temp<n>_auto_offset_hyst. The value in this file has the
225same representation as in temp<n>_auto_offset<i>.
226
227If a temperature reading falls below the base value for that channel, the LM93
228will use the minimum PWM value. These values are found in the sysfs files
229temp<n>_auto_pwm_min. Note, there are only two minimums: one each for temp[12]
230and temp[34]. Therefore, any change to e.g. temp1_auto_pwm_min will also
231affect temp2_auto_pwm_min.
232
233PWM Spin-Up Cycle:
234
235A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to
236some value > 0%. The LM93 supports a minimum duty cycle during spin-up. These
237values are found in the sysfs files pwm<n>_auto_spinup_min. The value in this
238file has the same representation as other PWM duty cycle values. The
239duration of the spin-up cycle is also configurable. These values are found in
240the sysfs files pwm<n>_auto_spinup_time. The value in this file is
241the spin-up time in seconds. The available spin-up times are constrained by
242the hardware. Selecting a value which is not available will cause the driver
243to use the next largest value.
244
245Spin-up Durations: 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0,
246 2.0, 4.0
247
248#PROCHOT and #VRDHOT PWM Ramping:
249
250If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output
251channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete
252steps. The duration of each step is configurable. There are two files, with
253one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp.
254The available ramp times are constrained by the hardware. Selecting a value
255which is not available will cause the driver to use the next largest value.
256
257Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals
258
259Fan Boost:
260
261For each temperature channel, there is a boost temperature: if the channel
262exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%.
263This limit is expressed in degrees C in the sysfs files temp<n>_auto_boost.
264There is also a hysteresis temperature for this function: after the boost
265limit is reached, the temperature channel must drop below this value before
266the boost function is disabled. This temperature is also expressed in degrees
267C in the sysfs files temp<n>_auto_boost_hyst.
268
269GPIO Pins:
270
271The LM93 can monitor the logic level of four dedicated GPIO pins as well as the
272four tach input pins. GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively.
273All eight GPIOs are read by reading the bitmask in the sysfs file gpio. The
274LSB is GPIO0, and the MSB is GPIO7.
275
276
277LM93 Unique sysfs Files
278-----------------------
279
280 file description
281 -------------------------------------------------------------
282
283 prochot<n> current #PROCHOT %
284
285 prochot<n>_avg moving average #PROCHOT %
286
287 prochot<n>_max limit #PROCHOT %
288
289 prochot_short enable or disable logical #PROCHOT pin short
290
291 prochot<n>_override force #PROCHOT assertion as PWM
292
293 prochot_override_duty_cycle
294 duty cycle for the PWM signal used when
295 #PROCHOT is overridden
296
297 prochot<n>_interval #PROCHOT PWM sampling interval
298
299 vrdhot<n> 0 means negated, 1 means asserted
300
301 fan<n>_smart_tach enable or disable smart tach mode
302
303 pwm<n>_auto_channels select control sources for PWM outputs
304
305 pwm<n>_auto_spinup_min minimum duty cycle during spin-up
306
307 pwm<n>_auto_spinup_time duration of spin-up
308
309 pwm_auto_prochot_ramp ramp time per step when #PROCHOT asserted
310
311 pwm_auto_vrdhot_ramp ramp time per step when #VRDHOT asserted
312
313 temp<n>_auto_base temperature channel base
314
315 temp<n>_auto_offset[1-12]
316 temperature channel offsets
317
318 temp<n>_auto_offset_hyst
319 temperature channel offset hysteresis
320
321 temp<n>_auto_boost temperature channel boost (PWMs to 100%) limit
322
323 temp<n>_auto_boost_hyst temperature channel boost hysteresis
324
325 gpio input state of 8 GPIO pins; read-only
326
327
328Sample Configuration File
329-------------------------
330
331Here is a sample LM93 chip config for sensors.conf:
332
333---------- cut here ----------
334chip "lm93-*"
335
336# VOLTAGE INPUTS
337
338 # labels and scaling based on datasheet recommendations
339 label in1 "+12V1"
340 compute in1 @ * 12.945, @ / 12.945
341 set in1_min 12 * 0.90
342 set in1_max 12 * 1.10
343
344 label in2 "+12V2"
345 compute in2 @ * 12.945, @ / 12.945
346 set in2_min 12 * 0.90
347 set in2_max 12 * 1.10
348
349 label in3 "+12V3"
350 compute in3 @ * 12.945, @ / 12.945
351 set in3_min 12 * 0.90
352 set in3_max 12 * 1.10
353
354 label in4 "FSB_Vtt"
355
356 label in5 "3GIO"
357
358 label in6 "ICH_Core"
359
360 label in7 "Vccp1"
361
362 label in8 "Vccp2"
363
364 label in9 "+3.3V"
365 set in9_min 3.3 * 0.90
366 set in9_max 3.3 * 1.10
367
368 label in10 "+5V"
369 set in10_min 5.0 * 0.90
370 set in10_max 5.0 * 1.10
371
372 label in11 "SCSI_Core"
373
374 label in12 "Mem_Core"
375
376 label in13 "Mem_Vtt"
377
378 label in14 "Gbit_Core"
379
380 # Assuming R1/R2 = 4.1143, and 3.3V reference
381 # -12V = (4.1143 + 1) * (@ - 3.3) + 3.3
382 label in15 "-12V"
383 compute in15 @ * 5.1143 - 13.57719, (@ + 13.57719) / 5.1143
384 set in15_min -12 * 0.90
385 set in15_max -12 * 1.10
386
387 label in16 "+3.3VSB"
388 set in16_min 3.3 * 0.90
389 set in16_max 3.3 * 1.10
390
391# TEMPERATURE INPUTS
392
393 label temp1 "CPU1"
394 label temp2 "CPU2"
395 label temp3 "LM93"
396
397# TACHOMETER INPUTS
398
399 label fan1 "Fan1"
400 set fan1_min 3000
401 label fan2 "Fan2"
402 set fan2_min 3000
403 label fan3 "Fan3"
404 set fan3_min 3000
405 label fan4 "Fan4"
406 set fan4_min 3000
407
408# PWM OUTPUTS
409
410 label pwm1 "CPU1"
411 label pwm2 "CPU2"
412