blob: f3b2ad2ceb01bb8e9c92aec835d1f4e1cbed78ff [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
Guenter Roeckc7bf71c2011-01-17 12:48:20 -08009 * National Semiconductor LM94
10 Prefix 'lm94'
11 Addresses scanned: I2C 0x2c-0x2e
12 Datasheet: http://www.national.com/ds.cgi/LM/LM94.pdf
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020013
Jean Delvare471c6062007-08-16 14:48:49 +020014Authors:
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020015 Mark M. Hoffman <mhoffman@lightlink.com>
16 Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com>
17 Adapted to 2.6.20 by Carsten Emde <ce@osadl.org>
Hans J. Kochf99e0e92010-11-18 12:27:34 -080018 Modified for mainline integration by Hans J. Koch <hjk@hansjkoch.de>
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020019
20Module Parameters
21-----------------
22
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020023* init: integer
24 Set to non-zero to force some initializations (default is 0).
25* disable_block: integer
26 A "0" allows SMBus block data transactions if the host supports them. A "1"
27 disables SMBus block data transactions. The default is 0.
28* vccp_limit_type: integer array (2)
29 Configures in7 and in8 limit type, where 0 means absolute and non-zero
30 means relative. "Relative" here refers to "Dynamic Vccp Monitoring using
31 VID" from the datasheet. It greatly simplifies the interface to allow
32 only one set of limits (absolute or relative) to be in operation at a
33 time (even though the hardware is capable of enabling both). There's
34 not a compelling use case for enabling both at once, anyway. The default
35 is "0,0".
36* vid_agtl: integer
37 A "0" configures the VID pins for V(ih) = 2.1V min, V(il) = 0.8V max.
38 A "1" configures the VID pins for V(ih) = 0.8V min, V(il) = 0.4V max.
39 (The latter setting is referred to as AGTL+ Compatible in the datasheet.)
40 I.e. this parameter controls the VID pin input thresholds; if your VID
41 inputs are not working, try changing this. The default value is "0".
42
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020043
44Hardware Description
45--------------------
46
47(from the datasheet)
48
Jean Delvare471c6062007-08-16 14:48:49 +020049The LM93 hardware monitor has a two wire digital interface compatible with
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020050SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote
51diode connected transistors as well as its own die and 16 power supply
52voltages. To set fan speed, the LM93 has two PWM outputs that are each
53controlled by up to four temperature zones. The fancontrol algorithm is lookup
54table based. The LM93 includes a digital filter that can be invoked to smooth
55temperature readings for better control of fan speed. The LM93 has four
56tachometer inputs to measure fan speed. Limit and status registers for all
57measured values are included. The LM93 builds upon the functionality of
Jean Delvare471c6062007-08-16 14:48:49 +020058previous motherboard management ASICs and uses some of the LM85's features
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020059(i.e. smart tachometer mode). It also adds measurement and control support
60for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual
61processor Xeon class motherboard with a minimum of external components.
62
Guenter Roeckc7bf71c2011-01-17 12:48:20 -080063LM94 is also supported in LM93 compatible mode. Extra sensors and features of
64LM94 are not supported.
65
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020066
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020067User Interface
68--------------
69
70#PROCHOT:
71
72The LM93 can monitor two #PROCHOT signals. The results are found in the
73sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max,
74and prochot2_max. prochot1_max and prochot2_max contain the user limits
75for #PROCHOT1 and #PROCHOT2, respectively. prochot1 and prochot2 contain
76the current readings for the most recent complete time interval. The
77value of prochot1_avg and prochot2_avg is something like a 2 period
78exponential moving average (but not quite - check the datasheet). Note
79that this third value is calculated by the chip itself. All values range
80from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%.
81
82The monitoring intervals for the two #PROCHOT signals is also configurable.
83These intervals can be found in the sysfs files prochot1_interval and
84prochot2_interval. The values in these files specify the intervals for
85#P1_PROCHOT and #P2_PROCHOT, respectively. Selecting a value not in this
86list will cause the driver to use the next largest interval. The available
Jean Delvare471c6062007-08-16 14:48:49 +020087intervals are (in seconds):
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020088
89#PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372
90
91It is possible to configure the LM93 to logically short the two #PROCHOT
92signals. I.e. when #P1_PROCHOT is asserted, the LM93 will automatically
93assert #P2_PROCHOT, and vice-versa. This mode is enabled by writing a
94non-zero integer to the sysfs file prochot_short.
95
96The LM93 can also override the #PROCHOT pins by driving a PWM signal onto
Jean Delvare471c6062007-08-16 14:48:49 +020097one or both of them. When overridden, the signal has a period of 3.56 ms,
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +020098a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and
99a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle).
100
101The sysfs files prochot1_override and prochot2_override contain boolean
Jean Delvare471c6062007-08-16 14:48:49 +0200102integers which enable or disable the override function for #P1_PROCHOT and
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +0200103#P2_PROCHOT, respectively. The sysfs file prochot_override_duty_cycle
104contains a value controlling the duty cycle for the PWM signal used when
105the override function is enabled. This value ranges from 0 to 15, with 0
106indicating minimum duty cycle and 15 indicating maximum.
107
108#VRD_HOT:
109
110The LM93 can monitor two #VRD_HOT signals. The results are found in the
111sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for
112which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These
113files are read-only.
114
115Smart Tach Mode:
116
117(from the datasheet)
118
119 If a fan is driven using a low-side drive PWM, the tachometer
120 output of the fan is corrupted. The LM93 includes smart tachometer
121 circuitry that allows an accurate tachometer reading to be
122 achieved despite the signal corruption. In smart tach mode all
123 four signals are measured within 4 seconds.
124
125Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
126the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero
127will disable the function for that fan. Note that Smart tach mode cannot be
128enabled if the PWM output frequency is 22500 Hz (see below).
129
130Manual PWM:
131
132The LM93 has a fixed or override mode for the two PWM outputs (although, there
133are still some conditions that will override even this mode - see section
13415.10.6 of the datasheet for details.) The sysfs files pwm1_override
135and pwm2_override are used to enable this mode; each is a boolean integer
136where 0 disables and 1 enables the manual control mode. The sysfs files pwm1
137and pwm2 are used to set the manual duty cycle; each is an integer (0-255)
138where 0 is 0% duty cycle, and 255 is 100%. Note that the duty cycle values
139are constrained by the hardware. Selecting a value which is not available
140will cause the driver to use the next largest value. Also note: when manual
141PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty
142cycle chosen by the h/w.
143
144PWM Output Frequency:
145
146The LM93 supports several different frequencies for the PWM output channels.
147The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The
148frequency values are constrained by the hardware. Selecting a value which is
149not available will cause the driver to use the next largest value. Also note
150that this parameter has implications for the Smart Tach Mode (see above).
151
Jean Delvare471c6062007-08-16 14:48:49 +0200152PWM Output Frequencies (in Hz): 12, 36, 48, 60, 72, 84, 96, 22500 (default)
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +0200153
154Automatic PWM:
155
156The LM93 is capable of complex automatic fan control, with many different
157points of configuration. To start, each PWM output can be bound to any
158combination of eight control sources. The final PWM is the largest of all
159individual control sources to which the PWM output is bound.
160
161The eight control sources are: temp1-temp4 (aka "zones" in the datasheet),
162#PROCHOT 1 & 2, and #VRDHOT 1 & 2. The bindings are expressed as a bitmask
163in the sysfs files pwm<n>_auto_channels, where a "1" enables the binding, and
Jean Delvare471c6062007-08-16 14:48:49 +0200164a "0" disables it. The h/w default is 0x0f (all temperatures bound).
Hans-Jürgen Koche46957e2007-07-05 17:58:29 +0200165
166 0x01 - Temp 1
167 0x02 - Temp 2
168 0x04 - Temp 3
169 0x08 - Temp 4
170 0x10 - #PROCHOT 1
171 0x20 - #PROCHOT 2
172 0x40 - #VRDHOT 1
173 0x80 - #VRDHOT 2
174
175The function y = f(x) takes a source temperature x to a PWM output y. This
176function of the LM93 is derived from a base temperature and a table of 12
177temperature offsets. The base temperature is expressed in degrees C in the
178sysfs files temp<n>_auto_base. The offsets are expressed in cumulative
179degrees C, with the value of offset <i> for temperature value <n> being
180contained in the file temp<n>_auto_offset<i>. E.g. if the base temperature
181is 40C:
182
183 offset # temp<n>_auto_offset<i> range pwm
184 1 0 - 25.00%
185 2 0 - 28.57%
186 3 1 40C - 41C 32.14%
187 4 1 41C - 42C 35.71%
188 5 2 42C - 44C 39.29%
189 6 2 44C - 46C 42.86%
190 7 2 48C - 50C 46.43%
191 8 2 50C - 52C 50.00%
192 9 2 52C - 54C 53.57%
193 10 2 54C - 56C 57.14%
194 11 2 56C - 58C 71.43%
195 12 2 58C - 60C 85.71%
196 > 60C 100.00%
197
198Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments.
199
200There is an independent base temperature for each temperature channel. Note,
201however, there are only two tables of offsets: one each for temp[12] and
202temp[34]. Therefore, any change to e.g. temp1_auto_offset<i> will also
203affect temp2_auto_offset<i>.
204
205The LM93 can also apply hysteresis to the offset table, to prevent unwanted
206oscillation between two steps in the offsets table. These values are found in
207the sysfs files temp<n>_auto_offset_hyst. The value in this file has the
208same representation as in temp<n>_auto_offset<i>.
209
210If a temperature reading falls below the base value for that channel, the LM93
211will use the minimum PWM value. These values are found in the sysfs files
212temp<n>_auto_pwm_min. Note, there are only two minimums: one each for temp[12]
213and temp[34]. Therefore, any change to e.g. temp1_auto_pwm_min will also
214affect temp2_auto_pwm_min.
215
216PWM Spin-Up Cycle:
217
218A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to
219some value > 0%. The LM93 supports a minimum duty cycle during spin-up. These
220values are found in the sysfs files pwm<n>_auto_spinup_min. The value in this
221file has the same representation as other PWM duty cycle values. The
222duration of the spin-up cycle is also configurable. These values are found in
223the sysfs files pwm<n>_auto_spinup_time. The value in this file is
224the spin-up time in seconds. The available spin-up times are constrained by
225the hardware. Selecting a value which is not available will cause the driver
226to use the next largest value.
227
228Spin-up Durations: 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0,
229 2.0, 4.0
230
231#PROCHOT and #VRDHOT PWM Ramping:
232
233If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output
234channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete
235steps. The duration of each step is configurable. There are two files, with
236one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp.
237The available ramp times are constrained by the hardware. Selecting a value
238which is not available will cause the driver to use the next largest value.
239
240Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals
241
242Fan Boost:
243
244For each temperature channel, there is a boost temperature: if the channel
245exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%.
246This limit is expressed in degrees C in the sysfs files temp<n>_auto_boost.
247There is also a hysteresis temperature for this function: after the boost
248limit is reached, the temperature channel must drop below this value before
249the boost function is disabled. This temperature is also expressed in degrees
250C in the sysfs files temp<n>_auto_boost_hyst.
251
252GPIO Pins:
253
254The LM93 can monitor the logic level of four dedicated GPIO pins as well as the
255four tach input pins. GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively.
256All eight GPIOs are read by reading the bitmask in the sysfs file gpio. The
257LSB is GPIO0, and the MSB is GPIO7.
258
259
260LM93 Unique sysfs Files
261-----------------------
262
263 file description
264 -------------------------------------------------------------
265
266 prochot<n> current #PROCHOT %
267
268 prochot<n>_avg moving average #PROCHOT %
269
270 prochot<n>_max limit #PROCHOT %
271
272 prochot_short enable or disable logical #PROCHOT pin short
273
274 prochot<n>_override force #PROCHOT assertion as PWM
275
276 prochot_override_duty_cycle
277 duty cycle for the PWM signal used when
278 #PROCHOT is overridden
279
280 prochot<n>_interval #PROCHOT PWM sampling interval
281
282 vrdhot<n> 0 means negated, 1 means asserted
283
284 fan<n>_smart_tach enable or disable smart tach mode
285
286 pwm<n>_auto_channels select control sources for PWM outputs
287
288 pwm<n>_auto_spinup_min minimum duty cycle during spin-up
289
290 pwm<n>_auto_spinup_time duration of spin-up
291
292 pwm_auto_prochot_ramp ramp time per step when #PROCHOT asserted
293
294 pwm_auto_vrdhot_ramp ramp time per step when #VRDHOT asserted
295
296 temp<n>_auto_base temperature channel base
297
298 temp<n>_auto_offset[1-12]
299 temperature channel offsets
300
301 temp<n>_auto_offset_hyst
302 temperature channel offset hysteresis
303
304 temp<n>_auto_boost temperature channel boost (PWMs to 100%) limit
305
306 temp<n>_auto_boost_hyst temperature channel boost hysteresis
307
308 gpio input state of 8 GPIO pins; read-only
309