Documentation/hwmon/dme1737

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