Documentation/hwmon/vt1211.rst

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