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   * IT8792E/IT8795E
 149
 150     Prefix: 'it8792'
 151
 152     Addresses scanned: from Super I/O config space (8 I/O ports)
 153
 154     Datasheet: Not publicly available
 155
 156   * IT87952E
 157
 158     Prefix: 'it87952'
 159
 160     Addresses scanned: from Super I/O config space (8 I/O ports)
 161
 162     Datasheet: Not publicly available
 163
 164   * SiS950   [clone of IT8705F]
 165
 166     Prefix: 'it87'
 167
 168     Addresses scanned: from Super I/O config space (8 I/O ports)
 169
 170     Datasheet: No longer be available
 171
 172
 173 Authors:
 174     - Christophe Gauthron
 175     - Jean Delvare <jdelvare@suse.de>
 176
 177
 178 Module Parameters
 179 -----------------
 180
 181 * update_vbat bool
 182     0 if vbat should report power on value, 1 if vbat should be updated after
 183     each read. Default is 0. On some boards the battery voltage is provided
 184     by either the battery or the onboard power supply. Only the first reading
 185     at power on will be the actual battery voltage (which the chip does
 186     automatically). On other boards the battery voltage is always fed to
 187     the chip so can be read at any time. Excessive reading may decrease
 188     battery life but no information is given in the datasheet.
 189
 190 * fix_pwm_polarity bool
 191     Force PWM polarity to active high (DANGEROUS). Some chips are
 192     misconfigured by BIOS - PWM values would be inverted. This option tries
 193     to fix this. Please contact your BIOS manufacturer and ask him for fix.
 194
 195 * force_id short, short
 196
 197   Force multiple chip ID to specified value, separated by ','.
 198   For example "force_id=0x8689,0x8633".  A value of 0 is ignored
 199   for that chip.
 200   Note: A single force_id value (e.g. "force_id=0x8689") is used for
 201   all chips, to only set the first chip use "force_id=0x8689,0".
 202   Should only be used for testing.
 203
 204 * ignore_resource_conflict bool
 205
 206   Similar to acpi_enforce_resources=lax, but only affects this driver.
 207   ACPI resource conflicts are ignored if this parameter is provided and
 208   set to 1.
 209   Provided since there are reports that system-wide acpi_enfore_resources=lax
 210   can result in boot failures on some systems.
 211   Note: This is inherently risky since it means that both ACPI and this driver
 212   may access the chip at the same time. This can result in race conditions and,
 213   worst case, result in unexpected system reboots.
 214
 215
 216 Hardware Interfaces
 217 -------------------
 218
 219 All the chips supported by this driver are LPC Super-I/O chips, accessed
 220 through the LPC bus (ISA-like I/O ports). The IT8712F additionally has an
 221 SMBus interface to the hardware monitoring functions. This driver no
 222 longer supports this interface though, as it is slower and less reliable
 223 than the ISA access, and was only available on a small number of
 224 motherboard models.
 225
 226
 227 Description
 228 -----------
 229
 230 This driver implements support for the IT8603E, IT8620E, IT8623E, IT8628E,
 231 IT8705F, IT8712F, IT8716F, IT8718F, IT8720F, IT8721F, IT8726F, IT8728F, IT8732F,
 232 IT8758E, IT8771E, IT8772E, IT8781F, IT8782F, IT8783E/F, IT8786E, IT8790E,
 233 IT8792E/IT8795E, IT87952E and SiS950 chips.
 234
 235 These chips are 'Super I/O chips', supporting floppy disks, infrared ports,
 236 joysticks and other miscellaneous stuff. For hardware monitoring, they
 237 include an 'environment controller' with 3 temperature sensors, 3 fan
 238 rotation speed sensors, 8 voltage sensors, associated alarms, and chassis
 239 intrusion detection.
 240
 241 The IT8712F and IT8716F additionally feature VID inputs, used to report
 242 the Vcore voltage of the processor. The early IT8712F have 5 VID pins,
 243 the IT8716F and late IT8712F have 6. They are shared with other functions
 244 though, so the functionality may not be available on a given system.
 245
 246 The IT8718F and IT8720F also features VID inputs (up to 8 pins) but the value
 247 is stored in the Super-I/O configuration space. Due to technical limitations,
 248 this value can currently only be read once at initialization time, so
 249 the driver won't notice and report changes in the VID value. The two
 250 upper VID bits share their pins with voltage inputs (in5 and in6) so you
 251 can't have both on a given board.
 252
 253 The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E and later IT8712F revisions
 254 have support for 2 additional fans. The additional fans are supported by the
 255 driver.
 256
 257 The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E, IT8732F, IT8781F, IT8782F,
 258 IT8783E/F, and late IT8712F and IT8705F also have optional 16-bit tachometer
 259 counters for fans 1 to 3. This is better (no more fan clock divider mess) but
 260 not compatible with the older chips and revisions. The 16-bit tachometer mode
 261 is enabled by the driver when one of the above chips is detected.
 262
 263 The IT8726F is just bit enhanced IT8716F with additional hardware
 264 for AMD power sequencing. Therefore the chip will appear as IT8716F
 265 to userspace applications.
 266
 267 The IT8728F, IT8771E, and IT8772E are considered compatible with the IT8721F,
 268 until a datasheet becomes available (hopefully.)
 269
 270 The IT8603E/IT8623E is a custom design, hardware monitoring part is similar to
 271 IT8728F. It only supports 3 fans, 16-bit fan mode, and the full speed mode
 272 of the fan is not supported (value 0 of pwmX_enable).
 273
 274 The IT8620E and IT8628E are custom designs, hardware monitoring part is similar
 275 to IT8728F. It only supports 16-bit fan mode. Both chips support up to 6 fans.
 276
 277 The IT8790E, IT8792E/IT8795E and IT87952E support up to 3 fans. 16-bit fan
 278 mode is always enabled.
 279
 280 The IT8732F supports a closed-loop mode for fan control, but this is not
 281 currently implemented by the driver.
 282
 283 Temperatures are measured in degrees Celsius. An alarm is triggered once
 284 when the Overtemperature Shutdown limit is crossed.
 285
 286 Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
 287 triggered if the rotation speed has dropped below a programmable limit. When
 288 16-bit tachometer counters aren't used, fan readings can be divided by
 289 a programmable divider (1, 2, 4 or 8) to give the readings more range or
 290 accuracy. With a divider of 2, the lowest representable value is around
 291 2600 RPM. Not all RPM values can accurately be represented, so some rounding
 292 is done.
 293
 294 Voltage sensors (also known as IN sensors) report their values in volts. An
 295 alarm is triggered if the voltage has crossed a programmable minimum or
 296 maximum limit. Note that minimum in this case always means 'closest to
 297 zero'; this is important for negative voltage measurements. On most chips, all
 298 voltage inputs can measure voltages between 0 and 4.08 volts, with a resolution
 299 of 0.016 volt.  IT8603E, IT8721F/IT8758E and IT8728F can measure between 0 and
 300 3.06 volts, with a resolution of 0.012 volt.  IT8732F can measure between 0 and
 301 2.8 volts with a resolution of 0.0109 volt.  The battery voltage in8 does not
 302 have limit registers.
 303
 304 On the IT8603E, IT8620E, IT8628E, IT8721F/IT8758E, IT8732F, IT8781F, IT8782F,
 305 and IT8783E/F, some voltage inputs are internal and scaled inside the chip:
 306 * in3 (optional)
 307 * in7 (optional for IT8781F, IT8782F, and IT8783E/F)
 308 * in8 (always)
 309 * in9 (relevant for IT8603E only)
 310 The driver handles this transparently so user-space doesn't have to care.
 311
 312 The VID lines (IT8712F/IT8716F/IT8718F/IT8720F) encode the core voltage value:
 313 the voltage level your processor should work with. This is hardcoded by
 314 the mainboard and/or processor itself. It is a value in volts.
 315
 316 If an alarm triggers, it will remain triggered until the hardware register
 317 is read at least once. This means that the cause for the alarm may already
 318 have disappeared! Note that in the current implementation, all hardware
 319 registers are read whenever any data is read (unless it is less than 1.5
 320 seconds since the last update). This means that you can easily miss
 321 once-only alarms.
 322
 323 Out-of-limit readings can also result in beeping, if the chip is properly
 324 wired and configured. Beeping can be enabled or disabled per sensor type
 325 (temperatures, voltages and fans.)
 326
 327 The IT87xx only updates its values each 1.5 seconds; reading it more often
 328 will do no harm, but will return 'old' values.
 329
 330 To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2,
 331 or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'.
 332 Give 0 for unused sensor. Any other value is invalid. To configure this at
 333 startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor;
 334 3 = thermal diode)
 335
 336
 337 Fan speed control
 338 -----------------
 339
 340 The fan speed control features are limited to manual PWM mode. Automatic
 341 "Smart Guardian" mode control handling is only implemented for older chips
 342 (see below.) However if you want to go for "manual mode" just write 1 to
 343 pwmN_enable.
 344
 345 If you are only able to control the fan speed with very small PWM values,
 346 try lowering the PWM base frequency (pwm1_freq). Depending on the fan,
 347 it may give you a somewhat greater control range. The same frequency is
 348 used to drive all fan outputs, which is why pwm2_freq and pwm3_freq are
 349 read-only.
 350
 351
 352 Automatic fan speed control (old interface)
 353 -------------------------------------------
 354
 355 The driver supports the old interface to automatic fan speed control
 356 which is implemented by IT8705F chips up to revision F and IT8712F
 357 chips up to revision G.
 358
 359 This interface implements 4 temperature vs. PWM output trip points.
 360 The PWM output of trip point 4 is always the maximum value (fan running
 361 at full speed) while the PWM output of the other 3 trip points can be
 362 freely chosen. The temperature of all 4 trip points can be freely chosen.
 363 Additionally, trip point 1 has an hysteresis temperature attached, to
 364 prevent fast switching between fan on and off.
 365
 366 The chip automatically computes the PWM output value based on the input
 367 temperature, based on this simple rule: if the temperature value is
 368 between trip point N and trip point N+1 then the PWM output value is
 369 the one of trip point N. The automatic control mode is less flexible
 370 than the manual control mode, but it reacts faster, is more robust and
 371 doesn't use CPU cycles.
 372
 373 Trip points must be set properly before switching to automatic fan speed
 374 control mode. The driver will perform basic integrity checks before
 375 actually switching to automatic control mode.
 376
 377
 378 Temperature offset attributes
 379 -----------------------------
 380
 381 The driver supports temp[1-3]_offset sysfs attributes to adjust the reported
 382 temperature for thermal diodes or diode-connected thermal transistors.
 383 If a temperature sensor is configured for thermistors, the attribute values
 384 are ignored. If the thermal sensor type is Intel PECI, the temperature offset
 385 must be programmed to the critical CPU temperature.