Documentation/hwmon/dme1737.rst

   1 Kernel driver dme1737
   2 =====================
   3
   4 Supported chips:
   5
   6   * SMSC DME1737 and compatibles (like Asus A8000)
   7
   8     Prefix: 'dme1737'
   9
  10     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
  11
  12     Datasheet: Provided by SMSC upon request and under NDA
  13
  14   * SMSC SCH3112, SCH3114, SCH3116
  15
  16     Prefix: 'sch311x'
  17
  18     Addresses scanned: none, address read from Super-I/O config space
  19
  20     Datasheet: Available on the Internet
  21
  22   * SMSC SCH5027
  23
  24     Prefix: 'sch5027'
  25
  26     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
  27
  28     Datasheet: Provided by SMSC upon request and under NDA
  29
  30   * SMSC SCH5127
  31
  32     Prefix: 'sch5127'
  33
  34     Addresses scanned: none, address read from Super-I/O config space
  35
  36     Datasheet: Provided by SMSC upon request and under NDA
  37
  38 Authors:
  39     Juerg Haefliger <juergh@gmail.com>
  40
  41
  42 Module Parameters
  43 -----------------
  44
  45 * force_start: bool
  46                         Enables the monitoring of voltage, fan and temp inputs
  47                         and PWM output control functions. Using this parameter
  48                         shouldn't be required since the BIOS usually takes care
  49                         of this.
  50
  51 * probe_all_addr: bool
  52                         Include non-standard LPC addresses 0x162e and 0x164e
  53                         when probing for ISA devices. This is required for the
  54                         following boards:
  55                         - VIA EPIA SN18000
  56
  57
  58 Description
  59 -----------
  60
  61 This driver implements support for the hardware monitoring capabilities of the
  62 SMSC DME1737 and Asus A8000 (which are the same), SMSC SCH5027, SCH311x,
  63 and SCH5127 Super-I/O chips. These chips feature monitoring of 3 temp sensors
  64 temp[1-3] (2 remote diodes and 1 internal), 8 voltages in[0-7] (7 external and
  65 1 internal) and up to 6 fan speeds fan[1-6]. Additionally, the chips implement
  66 up to 5 PWM outputs pwm[1-3,5-6] for controlling fan speeds both manually and
  67 automatically.
  68
  69 For the DME1737, A8000 and SCH5027, fan[1-2] and pwm[1-2] are always present.
  70 Fan[3-6] and pwm[3,5-6] are optional features and their availability depends on
  71 the configuration of the chip. The driver will detect which features are
  72 present during initialization and create the sysfs attributes accordingly.
  73
  74 For the SCH311x and SCH5127, fan[1-3] and pwm[1-3] are always present and
  75 fan[4-6] and pwm[5-6] don't exist.
  76
  77 The hardware monitoring features of the DME1737, A8000, and SCH5027 are only
  78 accessible via SMBus, while the SCH311x and SCH5127 only provide access via
  79 the ISA bus. The driver will therefore register itself as an I2C client driver
  80 if it detects a DME1737, A8000, or SCH5027 and as a platform driver if it
  81 detects a SCH311x or SCH5127 chip.
  82
  83
  84 Voltage Monitoring
  85 ------------------
  86
  87 The voltage inputs are sampled with 12-bit resolution and have internal
  88 scaling resistors. The values returned by the driver therefore reflect true
  89 millivolts and don't need scaling. The voltage inputs are mapped as follows
  90 (the last column indicates the input ranges):
  91
  92 DME1737, A8000::
  93
  94         in0: +5VTR      (+5V standby)           0V - 6.64V
  95         in1: Vccp       (processor core)        0V - 3V
  96         in2: VCC        (internal +3.3V)        0V - 4.38V
  97         in3: +5V                                0V - 6.64V
  98         in4: +12V                               0V - 16V
  99         in5: VTR        (+3.3V standby)         0V - 4.38V
 100         in6: Vbat       (+3.0V)                 0V - 4.38V
 101
 102 SCH311x::
 103
 104         in0: +2.5V                              0V - 3.32V
 105         in1: Vccp       (processor core)        0V - 2V
 106         in2: VCC        (internal +3.3V)        0V - 4.38V
 107         in3: +5V                                0V - 6.64V
 108         in4: +12V                               0V - 16V
 109         in5: VTR        (+3.3V standby)         0V - 4.38V
 110         in6: Vbat       (+3.0V)                 0V - 4.38V
 111
 112 SCH5027::
 113
 114         in0: +5VTR      (+5V standby)           0V - 6.64V
 115         in1: Vccp       (processor core)        0V - 3V
 116         in2: VCC        (internal +3.3V)        0V - 4.38V
 117         in3: V2_IN                              0V - 1.5V
 118         in4: V1_IN                              0V - 1.5V
 119         in5: VTR        (+3.3V standby)         0V - 4.38V
 120         in6: Vbat       (+3.0V)                 0V - 4.38V
 121
 122 SCH5127::
 123
 124         in0: +2.5                               0V - 3.32V
 125         in1: Vccp       (processor core)        0V - 3V
 126         in2: VCC        (internal +3.3V)        0V - 4.38V
 127         in3: V2_IN                              0V - 1.5V
 128         in4: V1_IN                              0V - 1.5V
 129         in5: VTR        (+3.3V standby)         0V - 4.38V
 130         in6: Vbat       (+3.0V)                 0V - 4.38V
 131         in7: Vtrip      (+1.5V)                 0V - 1.99V
 132
 133 Each voltage input has associated min and max limits which trigger an alarm
 134 when crossed.
 135
 136
 137 Temperature Monitoring
 138 ----------------------
 139
 140 Temperatures are measured with 12-bit resolution and reported in millidegree
 141 Celsius. The chip also features offsets for all 3 temperature inputs which -
 142 when programmed - get added to the input readings. The chip does all the
 143 scaling by itself and the driver therefore reports true temperatures that don't
 144 need any user-space adjustments. The temperature inputs are mapped as follows
 145 (the last column indicates the input ranges)::
 146
 147         temp1: Remote diode 1 (3904 type) temperature   -127C - +127C
 148         temp2: DME1737 internal temperature             -127C - +127C
 149         temp3: Remote diode 2 (3904 type) temperature   -127C - +127C
 150
 151 Each temperature input has associated min and max limits which trigger an alarm
 152 when crossed. Additionally, each temperature input has a fault attribute that
 153 returns 1 when a faulty diode or an unconnected input is detected and 0
 154 otherwise.
 155
 156
 157 Fan Monitoring
 158 --------------
 159
 160 Fan RPMs are measured with 16-bit resolution. The chip provides inputs for 6
 161 fan tachometers. All 6 inputs have an associated min limit which triggers an
 162 alarm when crossed. Fan inputs 1-4 provide type attributes that need to be set
 163 to the number of pulses per fan revolution that the connected tachometer
 164 generates. Supported values are 1, 2, and 4. Fan inputs 5-6 only support fans
 165 that generate 2 pulses per revolution. Fan inputs 5-6 also provide a max
 166 attribute that needs to be set to the maximum attainable RPM (fan at 100% duty-
 167 cycle) of the input. The chip adjusts the sampling rate based on this value.
 168
 169
 170 PWM Output Control
 171 ------------------
 172
 173 This chip features 5 PWM outputs. PWM outputs 1-3 are associated with fan
 174 inputs 1-3 and PWM outputs 5-6 are associated with fan inputs 5-6. PWM outputs
 175 1-3 can be configured to operate either in manual or automatic mode by setting
 176 the appropriate enable attribute accordingly. PWM outputs 5-6 can only operate
 177 in manual mode, their enable attributes are therefore read-only. When set to
 178 manual mode, the fan speed is set by writing the duty-cycle value to the
 179 appropriate PWM attribute. In automatic mode, the PWM attribute returns the
 180 current duty-cycle as set by the fan controller in the chip. All PWM outputs
 181 support the setting of the output frequency via the freq attribute.
 182
 183 In automatic mode, the chip supports the setting of the PWM ramp rate which
 184 defines how fast the PWM output is adjusting to changes of the associated
 185 temperature input. Associating PWM outputs to temperature inputs is done via
 186 temperature zones. The chip features 3 zones whose assignments to temperature
 187 inputs is static and determined during initialization. These assignments can
 188 be retrieved via the zone[1-3]_auto_channels_temp attributes. Each PWM output
 189 is assigned to one (or hottest of multiple) temperature zone(s) through the
 190 pwm[1-3]_auto_channels_zone attributes. Each PWM output has 3 distinct output
 191 duty-cycles: full, low, and min. Full is internally hard-wired to 255 (100%)
 192 and low and min can be programmed via pwm[1-3]_auto_point1_pwm and
 193 pwm[1-3]_auto_pwm_min, respectively. The thermal thresholds of the zones are
 194 programmed via zone[1-3]_auto_point[1-3]_temp and
 195 zone[1-3]_auto_point1_temp_hyst:
 196
 197         =============================== =======================================
 198         pwm[1-3]_auto_point2_pwm        full-speed duty-cycle (255, i.e., 100%)
 199         pwm[1-3]_auto_point1_pwm        low-speed duty-cycle
 200         pwm[1-3]_auto_pwm_min           min-speed duty-cycle
 201
 202         zone[1-3]_auto_point3_temp      full-speed temp (all outputs)
 203         zone[1-3]_auto_point2_temp      full-speed temp
 204         zone[1-3]_auto_point1_temp      low-speed temp
 205         zone[1-3]_auto_point1_temp_hyst min-speed temp
 206         =============================== =======================================
 207
 208 The chip adjusts the output duty-cycle linearly in the range of auto_point1_pwm
 209 to auto_point2_pwm if the temperature of the associated zone is between
 210 auto_point1_temp and auto_point2_temp. If the temperature drops below the
 211 auto_point1_temp_hyst value, the output duty-cycle is set to the auto_pwm_min
 212 value which only supports two values: 0 or auto_point1_pwm. That means that the
 213 fan either turns completely off or keeps spinning with the low-speed
 214 duty-cycle. If any of the temperatures rise above the auto_point3_temp value,
 215 all PWM outputs are set to 100% duty-cycle.
 216
 217 Following is another representation of how the chip sets the output duty-cycle
 218 based on the temperature of the associated thermal zone:
 219
 220         =============== =============== =================
 221         Temperature     Duty-Cycle      Duty-Cycle
 222                         Rising Temp     Falling Temp
 223         =============== =============== =================
 224         full-speed      full-speed      full-speed
 225
 226         -               < linearly      -
 227                         adjusted
 228                         duty-cycle >
 229
 230         low-speed       low-speed       low-speed
 231         -               min-speed       low-speed
 232         min-speed       min-speed       min-speed
 233         -               min-speed       min-speed
 234         =============== =============== =================
 235
 236
 237 Sysfs Attributes
 238 ----------------
 239
 240 Following is a list of all sysfs attributes that the driver provides, their
 241 permissions and a short description:
 242
 243 =============================== ======= =======================================
 244 Name                            Perm    Description
 245 =============================== ======= =======================================
 246 cpu0_vid                        RO      CPU core reference voltage in
 247                                         millivolts.
 248 vrm                             RW      Voltage regulator module version
 249                                         number.
 250
 251 in[0-7]_input                   RO      Measured voltage in millivolts.
 252 in[0-7]_min                     RW      Low limit for voltage input.
 253 in[0-7]_max                     RW      High limit for voltage input.
 254 in[0-7]_alarm                   RO      Voltage input alarm. Returns 1 if
 255                                         voltage input is or went outside the
 256                                         associated min-max range, 0 otherwise.
 257
 258 temp[1-3]_input                 RO      Measured temperature in millidegree
 259                                         Celsius.
 260 temp[1-3]_min                   RW      Low limit for temp input.
 261 temp[1-3]_max                   RW      High limit for temp input.
 262 temp[1-3]_offset                RW      Offset for temp input. This value will
 263                                         be added by the chip to the measured
 264                                         temperature.
 265 temp[1-3]_alarm                 RO      Alarm for temp input. Returns 1 if temp
 266                                         input is or went outside the associated
 267                                         min-max range, 0 otherwise.
 268 temp[1-3]_fault                 RO      Temp input fault. Returns 1 if the chip
 269                                         detects a faulty thermal diode or an
 270                                         unconnected temp input, 0 otherwise.
 271
 272 zone[1-3]_auto_channels_temp    RO      Temperature zone to temperature input
 273                                         mapping. This attribute is a bitfield
 274                                         and supports the following values:
 275
 276                                                 - 1: temp1
 277                                                 - 2: temp2
 278                                                 - 4: temp3
 279 zone[1-3]_auto_point1_temp_hyst RW      Auto PWM temp point1 hysteresis. The
 280                                         output of the corresponding PWM is set
 281                                         to the pwm_auto_min value if the temp
 282                                         falls below the auto_point1_temp_hyst
 283                                         value.
 284 zone[1-3]_auto_point[1-3]_temp  RW      Auto PWM temp points. Auto_point1 is
 285                                         the low-speed temp, auto_point2 is the
 286                                         full-speed temp, and auto_point3 is the
 287                                         temp at which all PWM outputs are set
 288                                         to full-speed (100% duty-cycle).
 289
 290 fan[1-6]_input                  RO      Measured fan speed in RPM.
 291 fan[1-6]_min                    RW      Low limit for fan input.
 292 fan[1-6]_alarm                  RO      Alarm for fan input. Returns 1 if fan
 293                                         input is or went below the associated
 294                                         min value, 0 otherwise.
 295 fan[1-4]_type                   RW      Type of attached fan. Expressed in
 296                                         number of pulses per revolution that
 297                                         the fan generates. Supported values are
 298                                         1, 2, and 4.
 299 fan[5-6]_max                    RW      Max attainable RPM at 100% duty-cycle.
 300                                         Required for chip to adjust the
 301                                         sampling rate accordingly.
 302
 303 pmw[1-3,5-6]                    RO/RW   Duty-cycle of PWM output. Supported
 304                                         values are 0-255 (0%-100%). Only
 305                                         writeable if the associated PWM is in
 306                                         manual mode.
 307 pwm[1-3]_enable                 RW      Enable of PWM outputs 1-3. Supported
 308                                         values are:
 309
 310                                                 - 0: turned off (output @ 100%)
 311                                                 - 1: manual mode
 312                                                 - 2: automatic mode
 313 pwm[5-6]_enable                 RO      Enable of PWM outputs 5-6. Always
 314                                         returns 1 since these 2 outputs are
 315                                         hard-wired to manual mode.
 316 pmw[1-3,5-6]_freq               RW      Frequency of PWM output. Supported
 317                                         values are in the range 11Hz-30000Hz
 318                                         (default is 25000Hz).
 319 pmw[1-3]_ramp_rate              RW      Ramp rate of PWM output. Determines how
 320                                         fast the PWM duty-cycle will change
 321                                         when the PWM is in automatic mode.
 322                                         Expressed in ms per PWM step. Supported
 323                                         values are in the range 0ms-206ms
 324                                         (default is 0, which means the duty-
 325                                         cycle changes instantly).
 326 pwm[1-3]_auto_channels_zone     RW      PWM output to temperature zone mapping.
 327                                         This attribute is a bitfield and
 328                                         supports the following values:
 329
 330                                                 - 1: zone1
 331                                                 - 2: zone2
 332                                                 - 4: zone3
 333                                                 - 6: highest of zone[2-3]
 334                                                 - 7: highest of zone[1-3]
 335 pwm[1-3]_auto_pwm_min           RW      Auto PWM min pwm. Minimum PWM duty-
 336                                         cycle. Supported values are 0 or
 337                                         auto_point1_pwm.
 338 pwm[1-3]_auto_point1_pwm        RW      Auto PWM pwm point. Auto_point1 is the
 339                                         low-speed duty-cycle.
 340 pwm[1-3]_auto_point2_pwm        RO      Auto PWM pwm point. Auto_point2 is the
 341                                         full-speed duty-cycle which is hard-
 342                                         wired to 255 (100% duty-cycle).
 343 =============================== ======= =======================================
 344
 345 Chip Differences
 346 ----------------
 347
 348 ======================= ======= ======= ======= =======
 349 Feature                 dme1737 sch311x sch5027 sch5127
 350 ======================= ======= ======= ======= =======
 351 temp[1-3]_offset        yes     yes
 352 vid                     yes
 353 zone3                   yes     yes     yes
 354 zone[1-3]_hyst          yes     yes
 355 pwm min/off             yes     yes
 356 fan3                    opt     yes     opt     yes
 357 pwm3                    opt     yes     opt     yes
 358 fan4                    opt             opt
 359 fan5                    opt             opt
 360 pwm5                    opt             opt
 361 fan6                    opt             opt
 362 pwm6                    opt             opt
 363 in7                                             yes
 364 ======================= ======= ======= ======= =======