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