Documentation/hwmon/vt1211

   1 Kernel driver vt1211
   2 ====================
   3
   4 Supported chips:
   5   * VIA VT1211
   6     Prefix: 'vt1211'
   7     Addresses scanned: none, address read from Super-I/O config space
   8     Datasheet: Provided by VIA upon request and under NDA
   9
  10 Authors: Juerg Haefliger <juergh@gmail.com>
  11
  12 This driver is based on the driver for kernel 2.4 by Mark D. Studebaker and
  13 its port to kernel 2.6 by Lars Ekman.
  14
  15 Thanks to Joseph Chan and Fiona Gatt from VIA for providing documentation and
  16 technical support.
  17
  18
  19 Description
  20 -----------
  21
  22 The VIA VT1211 Super-I/O chip includes complete hardware monitoring
  23 capabilities. It monitors 2 dedicated temperature sensor inputs (temp1 and
  24 temp2), 1 dedicated voltage (in5) and 2 fans. Additionally, the chip
  25 implements 5 universal input channels (UCH1-5) that can be individually
  26 programmed to either monitor a voltage or a temperature.
  27
  28 This chip also provides manual and automatic control of fan speeds (according
  29 to the datasheet). The driver only supports automatic control since the manual
  30 mode doesn't seem to work as advertised in the datasheet. In fact I couldn't
  31 get manual mode to work at all! Be aware that automatic mode hasn't been
  32 tested very well (due to the fact that my EPIA M10000 doesn't have the fans
  33 connected to the PWM outputs of the VT1211 :-().
  34
  35 The following table shows the relationship between the vt1211 inputs and the
  36 sysfs nodes.
  37
  38 Sensor          Voltage Mode   Temp Mode   Default Use (from the datasheet)
  39 ------          ------------   ---------   --------------------------------
  40 Reading 1                      temp1       Intel thermal diode
  41 Reading 3                      temp2       Internal thermal diode
  42 UCH1/Reading2   in0            temp3       NTC type thermistor
  43 UCH2            in1            temp4       +2.5V
  44 UCH3            in2            temp5       VccP (processor core)
  45 UCH4            in3            temp6       +5V
  46 UCH5            in4            temp7       +12V
  47 +3.3V           in5                        Internal VCC (+3.3V)
  48
  49
  50 Voltage Monitoring
  51 ------------------
  52
  53 Voltages are sampled by an 8-bit ADC with a LSB of ~10mV. The supported input
  54 range is thus from 0 to 2.60V. Voltage values outside of this range need
  55 external scaling resistors. This external scaling needs to be compensated for
  56 via compute lines in sensors.conf, like:
  57
  58 compute inx @*(1+R1/R2), @/(1+R1/R2)
  59
  60 The board level scaling resistors according to VIA's recommendation are as
  61 follows. And this is of course totally dependent on the actual board
  62 implementation :-) You will have to find documentation for your own
  63 motherboard and edit sensors.conf accordingly.
  64
  65                                       Expected
  66 Voltage       R1     R2     Divider   Raw Value
  67 -----------------------------------------------
  68 +2.5V         2K     10K    1.2       2083 mV
  69 VccP          ---    ---    1.0       1400 mV (1)
  70 +5V           14K    10K    2.4       2083 mV
  71 +12V          47K    10K    5.7       2105 mV
  72 +3.3V (int)   2K     3.4K   1.588     3300 mV (2)
  73 +3.3V (ext)   6.8K   10K    1.68      1964 mV
  74
  75 (1) Depending on the CPU (1.4V is for a VIA C3 Nehemiah).
  76 (2) R1 and R2 for 3.3V (int) are internal to the VT1211 chip and the driver
  77     performs the scaling and returns the properly scaled voltage value.
  78
  79 Each measured voltage has an associated low and high limit which triggers an
  80 alarm when crossed.
  81
  82
  83 Temperature Monitoring
  84 ----------------------
  85
  86 Temperatures are reported in millidegree Celsius. Each measured temperature
  87 has a high limit which triggers an alarm if crossed. There is an associated
  88 hysteresis value with each temperature below which the temperature has to drop
  89 before the alarm is cleared (this is only true for interrupt mode 0). The
  90 interrupt mode can be forced to 0 in case the BIOS doesn't do it
  91 automatically. For that, the parameter int_mode=0 needs to be supplied when
  92 loading the driver module. Be aware that overriding BIOS defaults might cause
  93 some unwanted side effects!
  94
  95 All temperature channels except temp2 are external. Temp2 is the VT1211
  96 internal thermal diode and the driver does all the scaling for temp2 and
  97 returns the temperature in millidegree Celsius. For the external channels
  98 temp1 and temp3-temp7, scaling depends on the board implementation and needs
  99 to be performed in userspace via sensors.conf.
 100
 101 Temp1 is an Intel-type thermal diode which requires the following formula to
 102 convert between sysfs readings and real temperatures:
 103
 104 compute temp1 (@-Offset)/Gain, (@*Gain)+Offset
 105
 106 According to the VIA VT1211 BIOS porting guide, the following gain and offset
 107 values should be used:
 108
 109 Diode Type      Offset   Gain
 110 ----------      ------   ----
 111 Intel CPU       88.638   0.9528
 112                 65.000   0.9686   *)
 113 VIA C3 Ezra     83.869   0.9528
 114 VIA C3 Ezra-T   73.869   0.9528
 115
 116 *) This is the formula from the lm_sensors 2.10.0 sensors.conf file. I don't
 117 know where it comes from or how it was derived, it's just listed here for
 118 completeness.
 119
 120 Temp3-temp7 support NTC thermistors. For these channels, the driver returns
 121 the voltages as seen at the individual pins of UCH1-UCH5. The voltage at the
 122 pin (Vpin) is formed by a voltage divider made of the thermistor (Rth) and a
 123 scaling resistor (Rs):
 124
 125 Vpin = 2200 * Rth / (Rs + Rth)   (2200 is the ADC max limit of 2200 mV)
 126
 127 The equation for the thermistor is as follows (google it if you want to know
 128 more about it):
 129
 130 Rth = Ro * exp(B * (1 / T - 1 / To))   (To is 298.15K (25C) and Ro is the
 131                                         nominal resistance at 25C)
 132
 133 Mingling the above two equations and assuming Rs = Ro and B = 3435 yields the
 134 following formula for sensors.conf:
 135
 136 compute tempx 1 / (1 / 298.15 - (` (2200 / @ - 1)) / 3435) - 273.15,
 137               2200 / (1 + (^ (3435 / 298.15 - 3435 / (273.15 + @))))
 138
 139
 140 Fan Speed Control
 141 -----------------
 142
 143 The VT1211 provides 2 programmable PWM outputs to control the speeds of 2
 144 fans. Writing a 2 to any of the two pwm[1-2]_enable sysfs nodes will put the
 145 PWM controller in automatic mode. There is only a single controller that
 146 controls both PWM outputs but each PWM output can be individually enabled and
 147 disabled.
 148
 149 Each PWM has 4 associated distinct output duty-cycles: full, high, low and
 150 off. Full and off are internally hard-wired to 255 (100%) and 0 (0%),
 151 respectively. High and low can be programmed via
 152 pwm[1-2]_auto_point[2-3]_pwm. Each PWM output can be associated with a
 153 different thermal input but - and here's the weird part - only one set of
 154 thermal thresholds exist that controls both PWMs output duty-cycles. The
 155 thermal thresholds are accessible via pwm[1-2]_auto_point[1-4]_temp. Note
 156 that even though there are 2 sets of 4 auto points each, they map to the same
 157 registers in the VT1211 and programming one set is sufficient (actually only
 158 the first set pwm1_auto_point[1-4]_temp is writable, the second set is
 159 read-only).
 160
 161 PWM Auto Point             PWM Output Duty-Cycle
 162 ------------------------------------------------
 163 pwm[1-2]_auto_point4_pwm   full speed duty-cycle (hard-wired to 255)
 164 pwm[1-2]_auto_point3_pwm   high speed duty-cycle
 165 pwm[1-2]_auto_point2_pwm   low speed duty-cycle
 166 pwm[1-2]_auto_point1_pwm   off duty-cycle (hard-wired to 0)
 167
 168 Temp Auto Point             Thermal Threshold
 169 ---------------------------------------------
 170 pwm[1-2]_auto_point4_temp   full speed temp
 171 pwm[1-2]_auto_point3_temp   high speed temp
 172 pwm[1-2]_auto_point2_temp   low speed temp
 173 pwm[1-2]_auto_point1_temp   off temp
 174
 175 Long story short, the controller implements the following algorithm to set the
 176 PWM output duty-cycle based on the input temperature:
 177
 178 Thermal Threshold             Output Duty-Cycle
 179                     (Rising Temp)           (Falling Temp)
 180 ----------------------------------------------------------
 181                     full speed duty-cycle   full speed duty-cycle
 182 full speed temp
 183                     high speed duty-cycle   full speed duty-cycle
 184 high speed temp
 185                     low speed duty-cycle    high speed duty-cycle
 186 low speed temp
 187                     off duty-cycle          low speed duty-cycle
 188 off temp