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 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@hansjkoch.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