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