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