Merge master.kernel.org:/pub/scm/linux/kernel/git/torvalds/linux-2.6
[linux-2.6] / Documentation / hwmon / lm93
1 Kernel driver lm93
2 ==================
3
4 Supported 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
10 Author:
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
16 Module 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
58 Hardware Description
59 --------------------
60
61 (from the datasheet)
62
63 The LM93, hardware monitor, has a two wire digital interface compatible with
64 SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote
65 diode connected transistors as well as its own die and 16 power supply
66 voltages. To set fan speed, the LM93 has two PWM outputs that are each
67 controlled by up to four temperature zones. The fancontrol algorithm is lookup
68 table based. The LM93 includes a digital filter that can be invoked to smooth
69 temperature readings for better control of fan speed. The LM93 has four
70 tachometer inputs to measure fan speed. Limit and status registers for all
71 measured values are included. The LM93 builds upon the functionality of
72 previous motherboard management ASICs and uses some of the LM85 s features
73 (i.e. smart tachometer mode). It also adds measurement and control support
74 for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual
75 processor Xeon class motherboard with a minimum of external components.
76
77
78 Driver Description
79 ------------------
80
81 This driver implements support for the National Semiconductor LM93.
82
83
84 User Interface
85 --------------
86
87 #PROCHOT:
88
89 The LM93 can monitor two #PROCHOT signals.  The results are found in the
90 sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max,
91 and prochot2_max.  prochot1_max and prochot2_max contain the user limits
92 for #PROCHOT1 and #PROCHOT2, respectively.  prochot1 and prochot2 contain
93 the current readings for the most recent complete time interval.  The
94 value of prochot1_avg and prochot2_avg is something like a 2 period
95 exponential moving average (but not quite - check the datasheet). Note
96 that this third value is calculated by the chip itself.  All values range
97 from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%.
98
99 The monitoring intervals for the two #PROCHOT signals is also configurable.
100 These intervals can be found in the sysfs files prochot1_interval and
101 prochot2_interval.  The values in these files specify the intervals for
102 #P1_PROCHOT and #P2_PROCHOT, respectively.  Selecting a value not in this
103 list will cause the driver to use the next largest interval.  The available
104 intervals are:
105
106 #PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372
107
108 It is possible to configure the LM93 to logically short the two #PROCHOT
109 signals.  I.e. when #P1_PROCHOT is asserted, the LM93 will automatically
110 assert #P2_PROCHOT, and vice-versa.  This mode is enabled by writing a
111 non-zero integer to the sysfs file prochot_short.
112
113 The LM93 can also override the #PROCHOT pins by driving a PWM signal onto
114 one or both of them.  When overridden, the signal has a period of 3.56 mS,
115 a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and
116 a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle).
117
118 The sysfs files prochot1_override and prochot2_override contain boolean
119 intgers which enable or disable the override function for #P1_PROCHOT and
120 #P2_PROCHOT, respectively.  The sysfs file prochot_override_duty_cycle
121 contains a value controlling the duty cycle for the PWM signal used when
122 the override function is enabled.  This value ranges from 0 to 15, with 0
123 indicating minimum duty cycle and 15 indicating maximum.
124
125 #VRD_HOT:
126
127 The LM93 can monitor two #VRD_HOT signals. The results are found in the
128 sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for
129 which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These
130 files are read-only.
131
132 Smart 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
142 Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
143 the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach.  A zero
144 will disable the function for that fan.  Note that Smart tach mode cannot be
145 enabled if the PWM output frequency is 22500 Hz (see below).
146
147 Manual PWM:
148
149 The LM93 has a fixed or override mode for the two PWM outputs (although, there
150 are still some conditions that will override even this mode - see section
151 15.10.6 of the datasheet for details.)  The sysfs files pwm1_override
152 and pwm2_override are used to enable this mode; each is a boolean integer
153 where 0 disables and 1 enables the manual control mode.  The sysfs files pwm1
154 and pwm2 are used to set the manual duty cycle; each is an integer (0-255)
155 where 0 is 0% duty cycle, and 255 is 100%.  Note that the duty cycle values
156 are constrained by the hardware. Selecting a value which is not available
157 will cause the driver to use the next largest value.  Also note: when manual
158 PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty
159 cycle chosen by the h/w.
160
161 PWM Output Frequency:
162
163 The LM93 supports several different frequencies for the PWM output channels.
164 The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The
165 frequency values are constrained by the hardware.  Selecting a value which is
166 not available will cause the driver to use the next largest value.  Also note
167 that this parameter has implications for the Smart Tach Mode (see above).
168
169 PWM Output Frequencies: 12, 36, 48, 60, 72, 84, 96, 22500 (h/w default)
170
171 Automatic PWM:
172
173 The LM93 is capable of complex automatic fan control, with many different
174 points of configuration.  To start, each PWM output can be bound to any
175 combination of eight control sources.  The final PWM is the largest of all
176 individual control sources to which the PWM output is bound.
177
178 The 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
180 in 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
192 The function y = f(x) takes a source temperature x to a PWM output y.  This
193 function of the LM93 is derived from a base temperature and a table of 12
194 temperature offsets.  The base temperature is expressed in degrees C in the
195 sysfs files temp<n>_auto_base.  The offsets are expressed in cumulative
196 degrees C, with the value of offset <i> for temperature value <n> being
197 contained in the file temp<n>_auto_offset<i>.  E.g. if the base temperature
198 is 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
215 Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments.
216
217 There is an independent base temperature for each temperature channel. Note,
218 however, there are only two tables of offsets: one each for temp[12] and
219 temp[34].  Therefore, any change to e.g. temp1_auto_offset<i> will also
220 affect temp2_auto_offset<i>.
221
222 The LM93 can also apply hysteresis to the offset table, to prevent unwanted
223 oscillation between two steps in the offsets table.  These values are found in
224 the sysfs files temp<n>_auto_offset_hyst.  The value in this file has the
225 same representation as in temp<n>_auto_offset<i>.
226
227 If a temperature reading falls below the base value for that channel, the LM93
228 will use the minimum PWM value.  These values are found in the sysfs files
229 temp<n>_auto_pwm_min.  Note, there are only two minimums: one each for temp[12]
230 and temp[34].  Therefore, any change to e.g. temp1_auto_pwm_min will also
231 affect temp2_auto_pwm_min.
232
233 PWM Spin-Up Cycle:
234
235 A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to
236 some value > 0%.  The LM93 supports a minimum duty cycle during spin-up.  These
237 values are found in the sysfs files pwm<n>_auto_spinup_min. The value in this
238 file has the same representation as other PWM duty cycle values. The
239 duration of the spin-up cycle is also configurable.  These values are found in
240 the sysfs files pwm<n>_auto_spinup_time. The value in this file is
241 the spin-up time in seconds.  The available spin-up times are constrained by
242 the hardware.  Selecting a value which is not available will cause the driver
243 to use the next largest value.
244
245 Spin-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
250 If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output
251 channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete
252 steps. The duration of each step is configurable. There are two files, with
253 one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp.
254 The available ramp times are constrained by the hardware.  Selecting a value
255 which is not available will cause the driver to use the next largest value.
256
257 Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals
258
259 Fan Boost:
260
261 For each temperature channel, there is a boost temperature: if the channel
262 exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%.
263 This limit is expressed in degrees C in the sysfs files temp<n>_auto_boost.
264 There is also a hysteresis temperature for this function: after the boost
265 limit is reached, the temperature channel must drop below this value before
266 the boost function is disabled.  This temperature is also expressed in degrees
267 C in the sysfs files temp<n>_auto_boost_hyst.
268
269 GPIO Pins:
270
271 The LM93 can monitor the logic level of four dedicated GPIO pins as well as the
272 four tach input pins.  GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively.
273 All eight GPIOs are read by reading the bitmask in the sysfs file gpio.  The
274 LSB is GPIO0, and the MSB is GPIO7.
275
276
277 LM93 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
328 Sample Configuration File
329 -------------------------
330
331 Here is a sample LM93 chip config for sensors.conf:
332
333 ---------- cut here ----------
334 chip "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