Documentation/hwmon/it87.rst

   1 Kernel driver it87
   2 ==================
   3
   4 Supported chips:
   5
   6   * IT8603E/IT8623E
   7
   8     Prefix: 'it8603'
   9
  10     Addresses scanned: from Super I/O config space (8 I/O ports)
  11
  12     Datasheet: Not publicly available
  13
  14   * IT8620E
  15
  16     Prefix: 'it8620'
  17
  18     Addresses scanned: from Super I/O config space (8 I/O ports)
  19
  20   * IT8628E
  21
  22     Prefix: 'it8628'
  23
  24     Addresses scanned: from Super I/O config space (8 I/O ports)
  25
  26     Datasheet: Not publicly available
  27
  28   * IT8705F
  29
  30     Prefix: 'it87'
  31
  32     Addresses scanned: from Super I/O config space (8 I/O ports)
  33
  34     Datasheet: Once publicly available at the ITE website, but no longer
  35
  36   * IT8712F
  37
  38     Prefix: 'it8712'
  39
  40     Addresses scanned: from Super I/O config space (8 I/O ports)
  41
  42     Datasheet: Once publicly available at the ITE website, but no longer
  43
  44   * IT8716F/IT8726F
  45
  46     Prefix: 'it8716'
  47
  48     Addresses scanned: from Super I/O config space (8 I/O ports)
  49
  50     Datasheet: Once publicly available at the ITE website, but no longer
  51
  52   * IT8718F
  53
  54     Prefix: 'it8718'
  55
  56     Addresses scanned: from Super I/O config space (8 I/O ports)
  57
  58     Datasheet: Once publicly available at the ITE website, but no longer
  59
  60   * IT8720F
  61
  62     Prefix: 'it8720'
  63
  64     Addresses scanned: from Super I/O config space (8 I/O ports)
  65
  66     Datasheet: Not publicly available
  67
  68   * IT8721F/IT8758E
  69
  70     Prefix: 'it8721'
  71
  72     Addresses scanned: from Super I/O config space (8 I/O ports)
  73
  74     Datasheet: Not publicly available
  75
  76   * IT8728F
  77
  78     Prefix: 'it8728'
  79
  80     Addresses scanned: from Super I/O config space (8 I/O ports)
  81
  82     Datasheet: Not publicly available
  83
  84   * IT8732F
  85
  86     Prefix: 'it8732'
  87
  88     Addresses scanned: from Super I/O config space (8 I/O ports)
  89
  90     Datasheet: Not publicly available
  91
  92   * IT8771E
  93
  94     Prefix: 'it8771'
  95
  96     Addresses scanned: from Super I/O config space (8 I/O ports)
  97
  98     Datasheet: Not publicly available
  99
 100   * IT8772E
 101
 102     Prefix: 'it8772'
 103
 104     Addresses scanned: from Super I/O config space (8 I/O ports)
 105
 106     Datasheet: Not publicly available
 107
 108   * IT8781F
 109
 110     Prefix: 'it8781'
 111
 112     Addresses scanned: from Super I/O config space (8 I/O ports)
 113
 114     Datasheet: Not publicly available
 115
 116   * IT8782F
 117
 118     Prefix: 'it8782'
 119
 120     Addresses scanned: from Super I/O config space (8 I/O ports)
 121
 122     Datasheet: Not publicly available
 123
 124   * IT8783E/F
 125
 126     Prefix: 'it8783'
 127
 128     Addresses scanned: from Super I/O config space (8 I/O ports)
 129
 130     Datasheet: Not publicly available
 131
 132   * IT8786E
 133
 134     Prefix: 'it8786'
 135
 136     Addresses scanned: from Super I/O config space (8 I/O ports)
 137
 138     Datasheet: Not publicly available
 139
 140   * IT8790E
 141
 142     Prefix: 'it8790'
 143
 144     Addresses scanned: from Super I/O config space (8 I/O ports)
 145
 146     Datasheet: Not publicly available
 147
 148   * SiS950   [clone of IT8705F]
 149
 150     Prefix: 'it87'
 151
 152     Addresses scanned: from Super I/O config space (8 I/O ports)
 153
 154     Datasheet: No longer be available
 155
 156
 157 Authors:
 158     - Christophe Gauthron
 159     - Jean Delvare <jdelvare@suse.de>
 160
 161
 162 Module Parameters
 163 -----------------
 164
 165 * update_vbat: int
 166     0 if vbat should report power on value, 1 if vbat should be updated after
 167     each read. Default is 0. On some boards the battery voltage is provided
 168     by either the battery or the onboard power supply. Only the first reading
 169     at power on will be the actual battery voltage (which the chip does
 170     automatically). On other boards the battery voltage is always fed to
 171     the chip so can be read at any time. Excessive reading may decrease
 172     battery life but no information is given in the datasheet.
 173
 174 * fix_pwm_polarity int
 175     Force PWM polarity to active high (DANGEROUS). Some chips are
 176     misconfigured by BIOS - PWM values would be inverted. This option tries
 177     to fix this. Please contact your BIOS manufacturer and ask him for fix.
 178
 179
 180 Hardware Interfaces
 181 -------------------
 182
 183 All the chips supported by this driver are LPC Super-I/O chips, accessed
 184 through the LPC bus (ISA-like I/O ports). The IT8712F additionally has an
 185 SMBus interface to the hardware monitoring functions. This driver no
 186 longer supports this interface though, as it is slower and less reliable
 187 than the ISA access, and was only available on a small number of
 188 motherboard models.
 189
 190
 191 Description
 192 -----------
 193
 194 This driver implements support for the IT8603E, IT8620E, IT8623E, IT8628E,
 195 IT8705F, IT8712F, IT8716F, IT8718F, IT8720F, IT8721F, IT8726F, IT8728F, IT8732F,
 196 IT8758E, IT8771E, IT8772E, IT8781F, IT8782F, IT8783E/F, IT8786E, IT8790E, and
 197 SiS950 chips.
 198
 199 These chips are 'Super I/O chips', supporting floppy disks, infrared ports,
 200 joysticks and other miscellaneous stuff. For hardware monitoring, they
 201 include an 'environment controller' with 3 temperature sensors, 3 fan
 202 rotation speed sensors, 8 voltage sensors, associated alarms, and chassis
 203 intrusion detection.
 204
 205 The IT8712F and IT8716F additionally feature VID inputs, used to report
 206 the Vcore voltage of the processor. The early IT8712F have 5 VID pins,
 207 the IT8716F and late IT8712F have 6. They are shared with other functions
 208 though, so the functionality may not be available on a given system.
 209
 210 The IT8718F and IT8720F also features VID inputs (up to 8 pins) but the value
 211 is stored in the Super-I/O configuration space. Due to technical limitations,
 212 this value can currently only be read once at initialization time, so
 213 the driver won't notice and report changes in the VID value. The two
 214 upper VID bits share their pins with voltage inputs (in5 and in6) so you
 215 can't have both on a given board.
 216
 217 The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E and later IT8712F revisions
 218 have support for 2 additional fans. The additional fans are supported by the
 219 driver.
 220
 221 The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E, IT8732F, IT8781F, IT8782F,
 222 IT8783E/F, and late IT8712F and IT8705F also have optional 16-bit tachometer
 223 counters for fans 1 to 3. This is better (no more fan clock divider mess) but
 224 not compatible with the older chips and revisions. The 16-bit tachometer mode
 225 is enabled by the driver when one of the above chips is detected.
 226
 227 The IT8726F is just bit enhanced IT8716F with additional hardware
 228 for AMD power sequencing. Therefore the chip will appear as IT8716F
 229 to userspace applications.
 230
 231 The IT8728F, IT8771E, and IT8772E are considered compatible with the IT8721F,
 232 until a datasheet becomes available (hopefully.)
 233
 234 The IT8603E/IT8623E is a custom design, hardware monitoring part is similar to
 235 IT8728F. It only supports 3 fans, 16-bit fan mode, and the full speed mode
 236 of the fan is not supported (value 0 of pwmX_enable).
 237
 238 The IT8620E and IT8628E are custom designs, hardware monitoring part is similar
 239 to IT8728F. It only supports 16-bit fan mode. Both chips support up to 6 fans.
 240
 241 The IT8790E supports up to 3 fans. 16-bit fan mode is always enabled.
 242
 243 The IT8732F supports a closed-loop mode for fan control, but this is not
 244 currently implemented by the driver.
 245
 246 Temperatures are measured in degrees Celsius. An alarm is triggered once
 247 when the Overtemperature Shutdown limit is crossed.
 248
 249 Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
 250 triggered if the rotation speed has dropped below a programmable limit. When
 251 16-bit tachometer counters aren't used, fan readings can be divided by
 252 a programmable divider (1, 2, 4 or 8) to give the readings more range or
 253 accuracy. With a divider of 2, the lowest representable value is around
 254 2600 RPM. Not all RPM values can accurately be represented, so some rounding
 255 is done.
 256
 257 Voltage sensors (also known as IN sensors) report their values in volts. An
 258 alarm is triggered if the voltage has crossed a programmable minimum or
 259 maximum limit. Note that minimum in this case always means 'closest to
 260 zero'; this is important for negative voltage measurements. On most chips, all
 261 voltage inputs can measure voltages between 0 and 4.08 volts, with a resolution
 262 of 0.016 volt.  IT8603E, IT8721F/IT8758E and IT8728F can measure between 0 and
 263 3.06 volts, with a resolution of 0.012 volt.  IT8732F can measure between 0 and
 264 2.8 volts with a resolution of 0.0109 volt.  The battery voltage in8 does not
 265 have limit registers.
 266
 267 On the IT8603E, IT8620E, IT8628E, IT8721F/IT8758E, IT8732F, IT8781F, IT8782F,
 268 and IT8783E/F, some voltage inputs are internal and scaled inside the chip:
 269 * in3 (optional)
 270 * in7 (optional for IT8781F, IT8782F, and IT8783E/F)
 271 * in8 (always)
 272 * in9 (relevant for IT8603E only)
 273 The driver handles this transparently so user-space doesn't have to care.
 274
 275 The VID lines (IT8712F/IT8716F/IT8718F/IT8720F) encode the core voltage value:
 276 the voltage level your processor should work with. This is hardcoded by
 277 the mainboard and/or processor itself. It is a value in volts.
 278
 279 If an alarm triggers, it will remain triggered until the hardware register
 280 is read at least once. This means that the cause for the alarm may already
 281 have disappeared! Note that in the current implementation, all hardware
 282 registers are read whenever any data is read (unless it is less than 1.5
 283 seconds since the last update). This means that you can easily miss
 284 once-only alarms.
 285
 286 Out-of-limit readings can also result in beeping, if the chip is properly
 287 wired and configured. Beeping can be enabled or disabled per sensor type
 288 (temperatures, voltages and fans.)
 289
 290 The IT87xx only updates its values each 1.5 seconds; reading it more often
 291 will do no harm, but will return 'old' values.
 292
 293 To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2,
 294 or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'.
 295 Give 0 for unused sensor. Any other value is invalid. To configure this at
 296 startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor;
 297 3 = thermal diode)
 298
 299
 300 Fan speed control
 301 -----------------
 302
 303 The fan speed control features are limited to manual PWM mode. Automatic
 304 "Smart Guardian" mode control handling is only implemented for older chips
 305 (see below.) However if you want to go for "manual mode" just write 1 to
 306 pwmN_enable.
 307
 308 If you are only able to control the fan speed with very small PWM values,
 309 try lowering the PWM base frequency (pwm1_freq). Depending on the fan,
 310 it may give you a somewhat greater control range. The same frequency is
 311 used to drive all fan outputs, which is why pwm2_freq and pwm3_freq are
 312 read-only.
 313
 314
 315 Automatic fan speed control (old interface)
 316 -------------------------------------------
 317
 318 The driver supports the old interface to automatic fan speed control
 319 which is implemented by IT8705F chips up to revision F and IT8712F
 320 chips up to revision G.
 321
 322 This interface implements 4 temperature vs. PWM output trip points.
 323 The PWM output of trip point 4 is always the maximum value (fan running
 324 at full speed) while the PWM output of the other 3 trip points can be
 325 freely chosen. The temperature of all 4 trip points can be freely chosen.
 326 Additionally, trip point 1 has an hysteresis temperature attached, to
 327 prevent fast switching between fan on and off.
 328
 329 The chip automatically computes the PWM output value based on the input
 330 temperature, based on this simple rule: if the temperature value is
 331 between trip point N and trip point N+1 then the PWM output value is
 332 the one of trip point N. The automatic control mode is less flexible
 333 than the manual control mode, but it reacts faster, is more robust and
 334 doesn't use CPU cycles.
 335
 336 Trip points must be set properly before switching to automatic fan speed
 337 control mode. The driver will perform basic integrity checks before
 338 actually switching to automatic control mode.
 339
 340
 341 Temperature offset attributes
 342 -----------------------------
 343
 344 The driver supports temp[1-3]_offset sysfs attributes to adjust the reported
 345 temperature for thermal diodes or diode-connected thermal transistors.
 346 If a temperature sensor is configured for thermistors, the attribute values
 347 are ignored. If the thermal sensor type is Intel PECI, the temperature offset
 348 must be programmed to the critical CPU temperature.