Documentation/hwmon/lm93.rst

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