Kernel driver `it87.o'
======================

Status: Complete, stable

Supported chips:
  * IT8705F
    Addresses scanned: I2C 0x28 - 0x2f (inclusive), ISA autodetected
    Datasheet: Publicly available at the ITE website
               http://www.ite.com.tw
  * IT8712F
    Addresses scanned: I2C 0x28 - 0x2f (inclusive), ISA autodetected
    Datasheet: Publicly available at the ITE website
               http://www.ite.com.tw
  * Sis950   [clone of IT8705F]
    Addresses scanned: ISA 0x290
    Datasheet: No longer publicly available

Author: Christophe Gauthron <chrisg@0-in.com>


Module Parameters
-----------------

* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* ignore: short array (min = 1, max = 48)
  List of adapter,address pairs not to scan
* ignore_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples not to scan
* probe: short array (min = 1, max = 48)
  List of adapter,address pairs to scan additionally
* probe_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples to scan additionally
* update_vbat: integer 0 if vbat should report power on value, 1 if
  vbat should be updated after each read.  Default is 0.
  On some boards the battery voltage is provided by either the battery or
  the onboard power supply. Only the first reading at power on will be
  the actual battery voltage (which the chip does automatically).  On other 
  boards the battery voltage is always fed to the chip so can be read at 
  any time.  Excessive reading may decrease battery life but no information 
  is given in the datasheet.
* reset: integer 1 if the registers of the chip should be reset at
  module load time, 0 to not reset the registers. Default is 0.


Description
-----------

This driver implements support for the IT8705F, IT8712F and SiS950 chips.

These chips are 'Super I/O chips', supporting floppy disks, infrared ports,
joysticks and other miscellaneous stuff. For hardware monitoring,
they include an 'environmnent controller' with 3 temperature sensors,
3 fan rotation speed sensors, 8 voltage sensors, and associated alarms.
The IT8712F additionally features VID inputs.

Temperatures are measured in degrees Celcius. An alarm is triggered once
when the Overtemperature Shutdown limit is crossed; it is triggered again
as soon as it drops below the Hysteresis value.

Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
triggered if the rotation speed has dropped below a programmable limit. Fan 
readings can be divided by a programmable divider (1, 2, 4 or 8) to give
the readings more range or accuracy. This is important because some Fans
report only one 'tick' each rotation, while others report two - making
all readings twice as high. Not all RPM values can accurately be represented,
so some rounding is done. With a divider of 2, the lowest representable
value is around 2600 RPM.

Voltage sensors (also known as IN sensors) report their values in volts.
An alarm is triggered if the voltage has crossed a programmable minimum 
or maximum limit. Note that minimum in this case always means 'closest to
zero'; this is important for negative voltage measurements. All voltage
inputs can measure voltages between 0 and 4.08 volts, with a resolution
of 0.016 volt.  The battery voltage in8 does not have limit registers.

The VID lines (IT8712F only) encode the core voltage value: the voltage level
your processor should work with. This is hardcoded by the mainboard and/or
processor itself. It is a value in volts.

If an alarm triggers, it will remain triggered until the hardware register
is read at least once. This means that the cause for the alarm may 
already have disappeared!  Note that in the current implementation, all
hardware registers are read whenever any data is read (unless it is less
than 1.5 seconds since the last update). This means that you can easily
miss once-only alarms.

The IT87xx only updates its values each 1.5 seconds; reading it more often
will do no harm, but will return 'old' values.

The sensor type can be set at runtime as of release 2.8.2.
To change sensor N to a thermistor, 'echo 2 > sensorN'
where N is 1, 2, or 3.
To change sensor N to a thermal diode, 'echo 3 > sensorN'.
Give 0 for unused sensor. Any other value is invalid.
To configure this at startup, put the following lines in the it87 section
of /etc/sensors.conf.
(2 = thermistor; 3 = thermal diode; 0 = unused)
	set sensor1 3
	set sensor2 3
	set sensor3 3

If you set a sensor to 0, you'll also want to ignore its value:
	ignore tempN

The fan speed control features can be enabled by setting the bits 0-2 of
the fan_ctl register to 1. (Note: bits 6-4 of this register must be set to
1 to enable the fan monitoring).
	0x40 : enable fan speed monitoring for fan3
	0x20 : enable fan speed monitoring for fan2
	0x10 : enable fan speed monitoring for fan1
	0x04 : enable fan smart guardian mode for fan3
	0x02 : enable fan smart guardian mode for fan2
	0x01 : enable fan smart guardian mode for fan1

If a fan's smart guardian bit is not set this fan is in on-off mode.
It can be switched on or off by setting/clearing the corresponding bit 0-2
of the second fan control register fan_on_off. This register has no effect if
a fan is in smart guardian mode.
	0x04 : fan3 is on
	0x02 : fan2 is on
	0x01 : fan1 is on

Bit 7 of the pwm[1-3] registers enables/disables the chip's automatic
temperature control mode for the specified fan. If Bit 7 is set the bits
1 and 0 encode the number of the temperature sensor used for this feature.
Possible register values are:
	0x00-0x7f direct power control for the fan speed
	0x80  automatic smart guardian mode use temperature sensor 1
	0x81  automatic smart guardian mode use temperature sensor 2
	0x82  automatic smart guardian mode use temperature sensor 3

In automatic smart guardian mode pwm values for low, medium and high speed
can be set in sg_pwm[1-3]. The temperature limits for fan off, low, medium,
hi speed and over temperature are set in sg_tl[1-3]. While the sensor's
temperature is between the low and medium speed value the fan will run in
low speed. When the sensor's temperature is between the medium and high speed
value the fan spins in medium speed. When the sensor's temperature is between
the high speed and over temperature value the fan spins in high speed.
If the sensor's temperature is higher than the over temperature limit the
fan will spin with the highest possible speed.

Example:
The preconfigured (BIOS set) values of the Shuttle XPC SN41G2 Barebone.
The MB uses temp2 to monitor the CPU temperature and fan3 as the fan for their
special ICE heatpipe cooling system.
	$ cat fan_ctl
	116
	$ cat tan_on_off
	215
	$ cat pwm3
	129
	$ cat sg_tl3
	16.0 16.0 48.0 54.0 58.0
	$ cat sg_pwm3
	3 4 9

Explanation:
	fan_ctl -> 116 = 0x74 = 01110100 : fan monitoring on for all fans,
		and fan3 is in smart guardian mode.
	fan_on_off -> 215 = 0xd7 =11010111 : all fans are on this setting is
		ignored for fan3 which is in smart guardian mode
	pwm3 -> 129 = 0x81 = 10000001 : fan3 is in automatic mode and uses
		temp2 for speed control
	sg_tl3 -> 16.0 16.0 48.0 54.0 58.0 : off, low, med, high, and
		over temperature limits of fan3
	sg_pwm3 -> 3 4 9 : pwm values for low, medium and high fan speed of fan3.



Chip features
-------------

Chip `it87`
          LABEL     LABEL CLASS   COMPUTE CLASS ACCESS MAGNITUDE
            in0            NONE            NONE      R     2
            in1            NONE            NONE      R     2
            in2            NONE            NONE      R     2
            in3            NONE            NONE      R     2
            in4            NONE            NONE      R     2
            in5            NONE            NONE      R     2
            in6            NONE            NONE      R     2
            in7            NONE            NONE      R     2
            in8            NONE            NONE      R     2
        in0_min             in0             in0      RW    2
        in1_min             in1             in1      RW    2
        in2_min             in2             in2      RW    2
        in3_min             in3             in3      RW    2
        in4_min             in4             in4      RW    2
        in5_min             in5             in5      RW    2
        in6_min             in6             in6      RW    2
        in7_min             in6             in6      RW    2
        in0_max             in0             in0      RW    2
        in1_max             in1             in1      RW    2
        in2_max             in2             in2      RW    2
        in3_max             in3             in3      RW    2
        in4_max             in4             in4      RW    2
        in5_max             in5             in5      RW    2
        in6_max             in6             in6      RW    2
        in7_max             in6             in6      RW    2
           fan1            NONE            NONE      R     0
           fan2            NONE            NONE      R     0
           fan3            NONE            NONE      R     0
       fan1_min            fan1            fan1      RW    0
       fan2_min            fan2            fan2      RW    0
       fan3_min            fan3            fan3      RW    0
          temp1            NONE            NONE      R     1
          temp2            NONE            NONE      R     1
          temp3            NONE            NONE      R     1
      temp1_low            temp            temp      RW    1
     temp1_over            temp            temp      RW    1
      temp2_low            temp            temp      RW    1
     temp2_over            temp            temp      RW    1
      temp3_low            temp            temp      RW    1
     temp3_over            temp            temp      RW    1
            vid            NONE            NONE      R     2
       fan1_div            fan1            NONE      RW    0
       fan2_div            fan2            NONE      RW    0
       fan3_div            fan3            NONE      R     0
     alarms_vin            NONE            NONE      R     0
     alarms_fan            NONE            NONE      R     0
    alarms_temp            NONE            NONE      R     0

          LABEL                           FEATURE SYMBOL     SYSCTL FILE:OFFSET
            in0                         SENSORS_IT87_IN0             in0:3
            in1                         SENSORS_IT87_IN1             in1:3
            in2                         SENSORS_IT87_IN2             in2:3
            in3                         SENSORS_IT87_IN3             in3:3
            in4                         SENSORS_IT87_IN4             in4:3
            in5                         SENSORS_IT87_IN5             in5:3
            in6                         SENSORS_IT87_IN6             in6:3
            in7                         SENSORS_IT87_IN7             in7:3
        in0_min                     SENSORS_IT87_IN0_MIN             in0:1
        in1_min                     SENSORS_IT87_IN1_MIN             in1:1
        in2_min                     SENSORS_IT87_IN2_MIN             in2:1
        in3_min                     SENSORS_IT87_IN3_MIN             in3:1
        in4_min                     SENSORS_IT87_IN4_MIN             in4:1
        in5_min                     SENSORS_IT87_IN5_MIN             in5:1
        in6_min                     SENSORS_IT87_IN6_MIN             in6:1
        in7_min                     SENSORS_IT87_IN7_MIN             in7:1
        in0_max                     SENSORS_IT87_IN0_MAX             in0:2
        in1_max                     SENSORS_IT87_IN1_MAX             in1:2
        in2_max                     SENSORS_IT87_IN2_MAX             in2:2
        in3_max                     SENSORS_IT87_IN3_MAX             in3:2
        in4_max                     SENSORS_IT87_IN4_MAX             in4:2
        in5_max                     SENSORS_IT87_IN5_MAX             in5:2
        in6_max                     SENSORS_IT87_IN6_MAX             in6:2
        in7_max                     SENSORS_IT87_IN7_MAX             in7:2
           fan1                        SENSORS_IT87_FAN1            fan1:2
           fan2                        SENSORS_IT87_FAN2            fan2:2
           fan3                        SENSORS_IT87_FAN3            fan3:2
       fan1_min                    SENSORS_IT87_FAN1_MIN            fan1:1
       fan2_min                    SENSORS_IT87_FAN2_MIN            fan2:1
       fan3_min                    SENSORS_IT87_FAN3_MIN            fan3:1
          temp1                       SENSORS_IT87_TEMP1           temp1:3
          temp2                       SENSORS_IT87_TEMP2           temp2:3
          temp3                       SENSORS_IT87_TEMP3           temp3:3
      temp1_low                   SENSORS_IT87_TEMP1_LOW           temp1:2
     temp1_over                  SENSORS_IT87_TEMP1_HIGH           temp1:1
      temp2_low                   SENSORS_IT87_TEMP2_LOW           temp2:2
     temp2_over                  SENSORS_IT87_TEMP2_HIGH           temp2:1
      temp3_low                   SENSORS_IT87_TEMP3_LOW           temp3:2
     temp3_over                  SENSORS_IT87_TEMP3_HIGH           temp3:1
            vid                         SENSORS_IT87_VID             vid:1
       fan1_div                    SENSORS_IT87_FAN1_DIV         fan_div:1
       fan2_div                    SENSORS_IT87_FAN2_DIV         fan_div:2
       fan3_div                    SENSORS_IT87_FAN3_DIV         fan_div:3
     alarms_fan                  SENSORS_IT87_ALARMS_FAN      alarms_fan:1
     alarms_vin                  SENSORS_IT87_ALARMS_VIN      alarms_vin:1
    alarms_temp                 SENSORS_IT87_ALARMS_TEMP     alarms_temp:1


