0001 Kernel driver lm93
0002 ==================
0003
0004 Supported chips:
0005
0006 * National Semiconductor LM93
0007
0008 Prefix 'lm93'
0009
0010 Addresses scanned: I2C 0x2c-0x2e
0011
0012 Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf
0013
0014 * National Semiconductor LM94
0015
0016 Prefix 'lm94'
0017
0018 Addresses scanned: I2C 0x2c-0x2e
0019
0020 Datasheet: http://www.national.com/ds.cgi/LM/LM94.pdf
0021
0022
0023 Authors:
0024 - Mark M. Hoffman <mhoffman@lightlink.com>
0025 - Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com>
0026 - Adapted to 2.6.20 by Carsten Emde <ce@osadl.org>
0027 - Modified for mainline integration by Hans J. Koch <hjk@hansjkoch.de>
0028
0029 Module Parameters
0030 -----------------
0031
0032 * init: integer
0033 Set to non-zero to force some initializations (default is 0).
0034 * disable_block: integer
0035 A "0" allows SMBus block data transactions if the host supports them. A "1"
0036 disables SMBus block data transactions. The default is 0.
0037 * vccp_limit_type: integer array (2)
0038 Configures in7 and in8 limit type, where 0 means absolute and non-zero
0039 means relative. "Relative" here refers to "Dynamic Vccp Monitoring using
0040 VID" from the datasheet. It greatly simplifies the interface to allow
0041 only one set of limits (absolute or relative) to be in operation at a
0042 time (even though the hardware is capable of enabling both). There's
0043 not a compelling use case for enabling both at once, anyway. The default
0044 is "0,0".
0045 * vid_agtl: integer
0046 A "0" configures the VID pins for V(ih) = 2.1V min, V(il) = 0.8V max.
0047 A "1" configures the VID pins for V(ih) = 0.8V min, V(il) = 0.4V max.
0048 (The latter setting is referred to as AGTL+ Compatible in the datasheet.)
0049 I.e. this parameter controls the VID pin input thresholds; if your VID
0050 inputs are not working, try changing this. The default value is "0".
0051
0052
0053 Hardware Description
0054 --------------------
0055
0056 (from the datasheet)
0057
0058 The LM93 hardware monitor has a two wire digital interface compatible with
0059 SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote
0060 diode connected transistors as well as its own die and 16 power supply
0061 voltages. To set fan speed, the LM93 has two PWM outputs that are each
0062 controlled by up to four temperature zones. The fancontrol algorithm is lookup
0063 table based. The LM93 includes a digital filter that can be invoked to smooth
0064 temperature readings for better control of fan speed. The LM93 has four
0065 tachometer inputs to measure fan speed. Limit and status registers for all
0066 measured values are included. The LM93 builds upon the functionality of
0067 previous motherboard management ASICs and uses some of the LM85's features
0068 (i.e. smart tachometer mode). It also adds measurement and control support
0069 for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual
0070 processor Xeon class motherboard with a minimum of external components.
0071
0072 LM94 is also supported in LM93 compatible mode. Extra sensors and features of
0073 LM94 are not supported.
0074
0075
0076 User Interface
0077 --------------
0078
0079 #PROCHOT
0080 ^^^^^^^^
0081
0082 The LM93 can monitor two #PROCHOT signals. The results are found in the
0083 sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max,
0084 and prochot2_max. prochot1_max and prochot2_max contain the user limits
0085 for #PROCHOT1 and #PROCHOT2, respectively. prochot1 and prochot2 contain
0086 the current readings for the most recent complete time interval. The
0087 value of prochot1_avg and prochot2_avg is something like a 2 period
0088 exponential moving average (but not quite - check the datasheet). Note
0089 that this third value is calculated by the chip itself. All values range
0090 from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%.
0091
0092 The monitoring intervals for the two #PROCHOT signals is also configurable.
0093 These intervals can be found in the sysfs files prochot1_interval and
0094 prochot2_interval. The values in these files specify the intervals for
0095 #P1_PROCHOT and #P2_PROCHOT, respectively. Selecting a value not in this
0096 list will cause the driver to use the next largest interval. The available
0097 intervals are (in seconds):
0098
0099 #PROCHOT intervals:
0100 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372
0101
0102 It is possible to configure the LM93 to logically short the two #PROCHOT
0103 signals. I.e. when #P1_PROCHOT is asserted, the LM93 will automatically
0104 assert #P2_PROCHOT, and vice-versa. This mode is enabled by writing a
0105 non-zero integer to the sysfs file prochot_short.
0106
0107 The LM93 can also override the #PROCHOT pins by driving a PWM signal onto
0108 one or both of them. When overridden, the signal has a period of 3.56 ms,
0109 a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and
0110 a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle).
0111
0112 The sysfs files prochot1_override and prochot2_override contain boolean
0113 integers which enable or disable the override function for #P1_PROCHOT and
0114 #P2_PROCHOT, respectively. The sysfs file prochot_override_duty_cycle
0115 contains a value controlling the duty cycle for the PWM signal used when
0116 the override function is enabled. This value ranges from 0 to 15, with 0
0117 indicating minimum duty cycle and 15 indicating maximum.
0118
0119 #VRD_HOT
0120 ^^^^^^^^
0121
0122 The LM93 can monitor two #VRD_HOT signals. The results are found in the
0123 sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for
0124 which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These
0125 files are read-only.
0126
0127 Smart Tach Mode (from the datasheet)::
0128
0129 If a fan is driven using a low-side drive PWM, the tachometer
0130 output of the fan is corrupted. The LM93 includes smart tachometer
0131 circuitry that allows an accurate tachometer reading to be
0132 achieved despite the signal corruption. In smart tach mode all
0133 four signals are measured within 4 seconds.
0134
0135 Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
0136 fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero
0137 will disable the function for that fan. Note that Smart tach mode cannot be
0138 enabled if the PWM output frequency is 22500 Hz (see below).
0139
0140 Manual PWM
0141 ^^^^^^^^^^
0142
0143 The LM93 has a fixed or override mode for the two PWM outputs (although, there
0144 are still some conditions that will override even this mode - see section
0145 15.10.6 of the datasheet for details.) The sysfs files pwm1_override
0146 and pwm2_override are used to enable this mode; each is a boolean integer
0147 where 0 disables and 1 enables the manual control mode. The sysfs files pwm1
0148 and pwm2 are used to set the manual duty cycle; each is an integer (0-255)
0149 where 0 is 0% duty cycle, and 255 is 100%. Note that the duty cycle values
0150 are constrained by the hardware. Selecting a value which is not available
0151 will cause the driver to use the next largest value. Also note: when manual
0152 PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty
0153 cycle chosen by the h/w.
0154
0155 PWM Output Frequency
0156 ^^^^^^^^^^^^^^^^^^^^
0157
0158 The LM93 supports several different frequencies for the PWM output channels.
0159 The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The
0160 frequency values are constrained by the hardware. Selecting a value which is
0161 not available will cause the driver to use the next largest value. Also note
0162 that this parameter has implications for the Smart Tach Mode (see above).
0163
0164 PWM Output Frequencies (in Hz):
0165 12, 36, 48, 60, 72, 84, 96, 22500 (default)
0166
0167 Automatic PWM
0168 ^^^^^^^^^^^^^
0169
0170 The LM93 is capable of complex automatic fan control, with many different
0171 points of configuration. To start, each PWM output can be bound to any
0172 combination of eight control sources. The final PWM is the largest of all
0173 individual control sources to which the PWM output is bound.
0174
0175 The eight control sources are: temp1-temp4 (aka "zones" in the datasheet),
0176 #PROCHOT 1 & 2, and #VRDHOT 1 & 2. The bindings are expressed as a bitmask
0177 in the sysfs files pwm<n>_auto_channels, where a "1" enables the binding, and
0178 a "0" disables it. The h/w default is 0x0f (all temperatures bound).
0179
0180 ====== ===========
0181 0x01 Temp 1
0182 0x02 Temp 2
0183 0x04 Temp 3
0184 0x08 Temp 4
0185 0x10 #PROCHOT 1
0186 0x20 #PROCHOT 2
0187 0x40 #VRDHOT 1
0188 0x80 #VRDHOT 2
0189 ====== ===========
0190
0191 The function y = f(x) takes a source temperature x to a PWM output y. This
0192 function of the LM93 is derived from a base temperature and a table of 12
0193 temperature offsets. The base temperature is expressed in degrees C in the
0194 sysfs files temp<n>_auto_base. The offsets are expressed in cumulative
0195 degrees C, with the value of offset <i> for temperature value <n> being
0196 contained in the file temp<n>_auto_offset<i>. E.g. if the base temperature
0197 is 40C:
0198
0199 ========== ======================= =============== =======
0200 offset # temp<n>_auto_offset<i> range pwm
0201 ========== ======================= =============== =======
0202 1 0 - 25.00%
0203 2 0 - 28.57%
0204 3 1 40C - 41C 32.14%
0205 4 1 41C - 42C 35.71%
0206 5 2 42C - 44C 39.29%
0207 6 2 44C - 46C 42.86%
0208 7 2 48C - 50C 46.43%
0209 8 2 50C - 52C 50.00%
0210 9 2 52C - 54C 53.57%
0211 10 2 54C - 56C 57.14%
0212 11 2 56C - 58C 71.43%
0213 12 2 58C - 60C 85.71%
0214 - - > 60C 100.00%
0215 ========== ======================= =============== =======
0216
0217 Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments.
0218
0219 There is an independent base temperature for each temperature channel. Note,
0220 however, there are only two tables of offsets: one each for temp[12] and
0221 temp[34]. Therefore, any change to e.g. temp1_auto_offset<i> will also
0222 affect temp2_auto_offset<i>.
0223
0224 The LM93 can also apply hysteresis to the offset table, to prevent unwanted
0225 oscillation between two steps in the offsets table. These values are found in
0226 the sysfs files temp<n>_auto_offset_hyst. The value in this file has the
0227 same representation as in temp<n>_auto_offset<i>.
0228
0229 If a temperature reading falls below the base value for that channel, the LM93
0230 will use the minimum PWM value. These values are found in the sysfs files
0231 temp<n>_auto_pwm_min. Note, there are only two minimums: one each for temp[12]
0232 and temp[34]. Therefore, any change to e.g. temp1_auto_pwm_min will also
0233 affect temp2_auto_pwm_min.
0234
0235 PWM Spin-Up Cycle
0236 ^^^^^^^^^^^^^^^^^
0237
0238 A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to
0239 some value > 0%. The LM93 supports a minimum duty cycle during spin-up. These
0240 values are found in the sysfs files pwm<n>_auto_spinup_min. The value in this
0241 file has the same representation as other PWM duty cycle values. The
0242 duration of the spin-up cycle is also configurable. These values are found in
0243 the sysfs files pwm<n>_auto_spinup_time. The value in this file is
0244 the spin-up time in seconds. The available spin-up times are constrained by
0245 the hardware. Selecting a value which is not available will cause the driver
0246 to use the next largest value.
0247
0248 Spin-up Durations:
0249 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0, 2.0, 4.0
0250
0251 #PROCHOT and #VRDHOT PWM Ramping
0252 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0253
0254 If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output
0255 channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete
0256 steps. The duration of each step is configurable. There are two files, with
0257 one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp.
0258 The available ramp times are constrained by the hardware. Selecting a value
0259 which is not available will cause the driver to use the next largest value.
0260
0261 Ramp Times:
0262 0 (disabled, h/w default) to 0.75 in 0.05 second intervals
0263
0264 Fan Boost
0265 ^^^^^^^^^
0266
0267 For each temperature channel, there is a boost temperature: if the channel
0268 exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%.
0269 This limit is expressed in degrees C in the sysfs files temp<n>_auto_boost.
0270 There is also a hysteresis temperature for this function: after the boost
0271 limit is reached, the temperature channel must drop below this value before
0272 the boost function is disabled. This temperature is also expressed in degrees
0273 C in the sysfs files temp<n>_auto_boost_hyst.
0274
0275 GPIO Pins
0276 ^^^^^^^^^
0277
0278 The LM93 can monitor the logic level of four dedicated GPIO pins as well as the
0279 four tach input pins. GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively.
0280 All eight GPIOs are read by reading the bitmask in the sysfs file gpio. The
0281 LSB is GPIO0, and the MSB is GPIO7.
0282
0283
0284 LM93 Unique sysfs Files
0285 -----------------------
0286
0287 =========================== ===============================================
0288 file description
0289 =========================== ===============================================
0290 prochot<n> current #PROCHOT %
0291 prochot<n>_avg moving average #PROCHOT %
0292 prochot<n>_max limit #PROCHOT %
0293 prochot_short enable or disable logical #PROCHOT pin short
0294 prochot<n>_override force #PROCHOT assertion as PWM
0295 prochot_override_duty_cycle duty cycle for the PWM signal used when
0296 #PROCHOT is overridden
0297 prochot<n>_interval #PROCHOT PWM sampling interval
0298 vrdhot<n> 0 means negated, 1 means asserted
0299 fan<n>_smart_tach enable or disable smart tach mode
0300 pwm<n>_auto_channels select control sources for PWM outputs
0301 pwm<n>_auto_spinup_min minimum duty cycle during spin-up
0302 pwm<n>_auto_spinup_time duration of spin-up
0303 pwm_auto_prochot_ramp ramp time per step when #PROCHOT asserted
0304 pwm_auto_vrdhot_ramp ramp time per step when #VRDHOT asserted
0305 temp<n>_auto_base temperature channel base
0306 temp<n>_auto_offset[1-12] temperature channel offsets
0307 temp<n>_auto_offset_hyst temperature channel offset hysteresis
0308 temp<n>_auto_boost temperature channel boost (PWMs to 100%)
0309 limit
0310 temp<n>_auto_boost_hyst temperature channel boost hysteresis
0311 gpio input state of 8 GPIO pins; read-only
0312 =========================== ===============================================
