]> git.sur5r.net Git - groeck-it87/blob - README
Update TODO and README files
[groeck-it87] / README
1 Kernel driver it87
2 ==================
3
4 Supported chips:
5   * IT8603E/IT8623E
6     Prefix: 'it8603'
7     Addresses scanned: from Super I/O config space (8 I/O ports)
8     Datasheet: Not publicly available
9   * IT8620E
10     Prefix: 'it8620'
11     Addresses scanned: from Super I/O config space (8 I/O ports)
12   * IT8622E
13     Prefix: 'it8622'
14     Addresses scanned: from Super I/O config space (8 I/O ports)
15     Datasheet: Not publicly available
16   * IT8628E
17     Prefix: 'it8628'
18     Addresses scanned: from Super I/O config space (8 I/O ports)
19     Datasheet: Not publicly available
20   * IT8705F
21     Prefix: 'it87'
22     Addresses scanned: from Super I/O config space (8 I/O ports)
23     Datasheet: Once publicly available at the ITE website, but no longer
24   * IT8712F
25     Prefix: 'it8712'
26     Addresses scanned: from Super I/O config space (8 I/O ports)
27     Datasheet: Once publicly available at the ITE website, but no longer
28   * IT8716F/IT8726F
29     Prefix: 'it8716'
30     Addresses scanned: from Super I/O config space (8 I/O ports)
31     Datasheet: Once publicly available at the ITE website, but no longer
32   * IT8718F
33     Prefix: 'it8718'
34     Addresses scanned: from Super I/O config space (8 I/O ports)
35     Datasheet: Once publicly available at the ITE website, but no longer
36   * IT8720F
37     Prefix: 'it8720'
38     Addresses scanned: from Super I/O config space (8 I/O ports)
39     Datasheet: Not publicly available
40   * IT8721F/IT8758E
41     Prefix: 'it8721'
42     Addresses scanned: from Super I/O config space (8 I/O ports)
43     Datasheet: Not publicly available
44   * IT8728F
45     Prefix: 'it8728'
46     Addresses scanned: from Super I/O config space (8 I/O ports)
47     Datasheet: Not publicly available
48   * IT8732F
49     Prefix: 'it8732'
50     Addresses scanned: from Super I/O config space (8 I/O ports)
51     Datasheet: Not publicly available
52   * IT8771E
53     Prefix: 'it8771'
54     Addresses scanned: from Super I/O config space (8 I/O ports)
55     Datasheet: Not publicly available
56   * IT8772E
57     Prefix: 'it8772'
58     Addresses scanned: from Super I/O config space (8 I/O ports)
59     Datasheet: Not publicly available
60   * IT8781F
61     Prefix: 'it8781'
62     Addresses scanned: from Super I/O config space (8 I/O ports)
63     Datasheet: Not publicly available
64   * IT8782F
65     Prefix: 'it8782'
66     Addresses scanned: from Super I/O config space (8 I/O ports)
67     Datasheet: Not publicly available
68   * IT8783E/F
69     Prefix: 'it8783'
70     Addresses scanned: from Super I/O config space (8 I/O ports)
71     Datasheet: Not publicly available
72   * IT8786E
73     Prefix: 'it8786'
74     Addresses scanned: from Super I/O config space (8 I/O ports)
75     Datasheet: Not publicly available
76   * IT8790E
77     Prefix: 'it8790'
78     Addresses scanned: from Super I/O config space (8 I/O ports)
79     Datasheet: Not publicly available
80   * SiS950   [clone of IT8705F]
81     Prefix: 'it87'
82     Addresses scanned: from Super I/O config space (8 I/O ports)
83     Datasheet: No longer be available
84
85 Authors:
86     Christophe Gauthron
87     Jean Delvare <jdelvare@suse.de>
88
89
90 Module Parameters
91 -----------------
92
93 * update_vbat: int
94
95   0 if vbat should report power on value, 1 if vbat should be updated after
96   each read. Default is 0. On some boards the battery voltage is provided
97   by either the battery or the onboard power supply. Only the first reading
98   at power on will be the actual battery voltage (which the chip does
99   automatically). On other boards the battery voltage is always fed to
100   the chip so can be read at any time. Excessive reading may decrease
101   battery life but no information is given in the datasheet.
102
103 * fix_pwm_polarity int
104
105   Force PWM polarity to active high (DANGEROUS). Some chips are
106   misconfigured by BIOS - PWM values would be inverted. This option tries
107   to fix this. Please contact your BIOS manufacturer and ask him for fix.
108
109
110 Hardware Interfaces
111 -------------------
112
113 All the chips supported by this driver are LPC Super-I/O chips, accessed
114 through the LPC bus (ISA-like I/O ports). The IT8712F additionally has an
115 SMBus interface to the hardware monitoring functions. This driver no
116 longer supports this interface though, as it is slower and less reliable
117 than the ISA access, and was only available on a small number of
118 motherboard models.
119
120
121 Description
122 -----------
123
124 This driver implements support for the IT8603E, IT8620E, IT8622E, IT8623E,
125 IT8628E, IT8705F, IT8712F, IT8716F, IT8718F, IT8720F, IT8721F, IT8726F, IT8728F,
126 IT8732F, IT8758E, IT8771E, IT8772E, IT8781F, IT8782F, IT8783E/F, IT8786E,
127 IT8790E, and SiS950 chips.
128
129 These chips are 'Super I/O chips', supporting floppy disks, infrared ports,
130 joysticks and other miscellaneous stuff. For hardware monitoring, they
131 include an 'environment controller' with 3 temperature sensors, 3 fan
132 rotation speed sensors, 8 voltage sensors, associated alarms, and chassis
133 intrusion detection.
134
135 The IT8712F and IT8716F additionally feature VID inputs, used to report
136 the Vcore voltage of the processor. The early IT8712F have 5 VID pins,
137 the IT8716F and late IT8712F have 6. They are shared with other functions
138 though, so the functionality may not be available on a given system.
139
140 The IT8718F and IT8720F also features VID inputs (up to 8 pins) but the value
141 is stored in the Super-I/O configuration space. Due to technical limitations,
142 this value can currently only be read once at initialization time, so
143 the driver won't notice and report changes in the VID value. The two
144 upper VID bits share their pins with voltage inputs (in5 and in6) so you
145 can't have both on a given board.
146
147 The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E and later IT8712F revisions
148 have support for 2 additional fans. The additional fans are supported by the
149 driver.
150
151 The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E, IT8732F, IT8781F, IT8782F,
152 IT8783E/F, and late IT8712F and IT8705F also have optional 16-bit tachometer
153 counters for fans 1 to 3. This is better (no more fan clock divider mess) but
154 not compatible with the older chips and revisions. The 16-bit tachometer mode
155 is enabled by the driver when one of the above chips is detected.
156
157 The IT8726F is just bit enhanced IT8716F with additional hardware
158 for AMD power sequencing. Therefore the chip will appear as IT8716F
159 to userspace applications.
160
161 The IT8728F, IT8771E, and IT8772E are considered compatible with the IT8721F,
162 until a datasheet becomes available (hopefully.)
163
164 The IT8603E/IT8623E is a custom design, hardware monitoring part is similar to
165 IT8728F. It only supports 3 fans, 16-bit fan mode, and the full speed mode
166 of the fan is not supported (value 0 of pwmX_enable).
167
168 The IT8620E and IT8628E are custom designs, hardware monitoring part is similar
169 to IT8728F. It only supports 16-bit fan mode. Both chips support up to 6 fans.
170
171 The IT8790E supports up to 3 fans. 16-bit fan mode is always enabled.
172
173 The IT8732F supports a closed-loop mode for fan control, but this is not
174 currently implemented by the driver.
175
176 Temperatures are measured in degrees Celsius. An alarm is triggered once
177 when the Overtemperature Shutdown limit is crossed.
178
179 Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
180 triggered if the rotation speed has dropped below a programmable limit. When
181 16-bit tachometer counters aren't used, fan readings can be divided by
182 a programmable divider (1, 2, 4 or 8) to give the readings more range or
183 accuracy. With a divider of 2, the lowest representable value is around
184 2600 RPM. Not all RPM values can accurately be represented, so some rounding
185 is done.
186
187 Voltage sensors (also known as IN sensors) report their values in volts. An
188 alarm is triggered if the voltage has crossed a programmable minimum or
189 maximum limit. Note that minimum in this case always means 'closest to
190 zero'; this is important for negative voltage measurements. On most chips, all
191 voltage inputs can measure voltages between 0 and 4.08 volts, with a resolution
192 of 0.016 volt.  IT8603E, IT8721F/IT8758E and IT8728F can measure between 0 and
193 3.06 volts, with a resolution of 0.012 volt.  IT8732F can measure between 0 and
194 2.8 volts with a resolution of 0.0109 volt.  The battery voltage in8 does not
195 have limit registers.
196
197 On the IT8603E, IT8620E, IT8628E, IT8721F/IT8758E, IT8732F, IT8781F, IT8782F,
198 and IT8783E/F, some voltage inputs are internal and scaled inside the chip:
199 * in3 (optional)
200 * in7 (optional for IT8781F, IT8782F, and IT8783E/F)
201 * in8 (always)
202 * in9 (relevant for IT8603E only)
203 The driver handles this transparently so user-space doesn't have to care.
204
205 The VID lines (IT8712F/IT8716F/IT8718F/IT8720F) encode the core voltage value:
206 the voltage level your processor should work with. This is hardcoded by
207 the mainboard and/or processor itself. It is a value in volts.
208
209 If an alarm triggers, it will remain triggered until the hardware register
210 is read at least once. This means that the cause for the alarm may already
211 have disappeared! Note that in the current implementation, all hardware
212 registers are read whenever any data is read (unless it is less than 1.5
213 seconds since the last update). This means that you can easily miss
214 once-only alarms.
215
216 Out-of-limit readings can also result in beeping, if the chip is properly
217 wired and configured. Beeping can be enabled or disabled per sensor type
218 (temperatures, voltages and fans.)
219
220 The IT87xx only updates its values each 1.5 seconds; reading it more often
221 will do no harm, but will return 'old' values.
222
223 To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2,
224 or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'.
225 Give 0 for unused sensor. Any other value is invalid. To configure this at
226 startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor;
227 3 = thermal diode)
228
229
230 Fan speed control
231 -----------------
232
233 The fan speed control features are limited to manual PWM mode. Automatic
234 "Smart Guardian" mode control handling is only implemented for older chips
235 (see below.) However if you want to go for "manual mode" just write 1 to
236 pwmN_enable.
237
238 If you are only able to control the fan speed with very small PWM values,
239 try lowering the PWM base frequency (pwm1_freq). Depending on the fan,
240 it may give you a somewhat greater control range. The same frequency is
241 used to drive all fan outputs, which is why pwm2_freq and pwm3_freq are
242 read-only.
243
244
245 Automatic fan speed control (old interface)
246 -------------------------------------------
247
248 The driver supports the old interface to automatic fan speed control
249 which is implemented by IT8705F chips up to revision F and IT8712F
250 chips up to revision G.
251
252 This interface implements 4 temperature vs. PWM output trip points.
253 The PWM output of trip point 4 is always the maximum value (fan running
254 at full speed) while the PWM output of the other 3 trip points can be
255 freely chosen. The temperature of all 4 trip points can be freely chosen.
256 Additionally, trip point 1 has an hysteresis temperature attached, to
257 prevent fast switching between fan on and off.
258
259 The chip automatically computes the PWM output value based on the input
260 temperature, based on this simple rule: if the temperature value is
261 between trip point N and trip point N+1 then the PWM output value is
262 the one of trip point N. The automatic control mode is less flexible
263 than the manual control mode, but it reacts faster, is more robust and
264 doesn't use CPU cycles.
265
266 Trip points must be set properly before switching to automatic fan speed
267 control mode. The driver will perform basic integrity checks before
268 actually switching to automatic control mode.
269
270
271 Temperature offset attributes
272 -----------------------------
273
274 The driver supports temp[1-3]_offset sysfs attributes to adjust the reported
275 temperature for thermal diodes or diode-connected thermal transistors.
276 If a temperature sensor is configured for thermistors, the attribute values
277 are ignored. If the thermal sensor type is Intel PECI, the temperature offset
278 must be programmed to the critical CPU temperature.
279
280 Preliminary support
281 -------------------
282
283 Support for IT8607E, IT8665E, and IT8686E is preliminary. Voltage readings,
284 temperature readings, fan control, and fan speed measurements may be wrong
285 and/or missing. Fan control and fan speed may be enabled and reported for
286 non-existing fans. Please report any problems and inconsistencies.
287
288 Reporting information for unsupported chips
289 -------------------------------------------
290
291 If the chip in your system is not yet supported by the driver, please provide
292 the following information.
293
294 First, run sensors-detect. It will tell you something like
295
296     Probing for Super-I/O at 0x2e/0x2f
297     ...
298     Trying family `ITE'...                                      Yes
299     Found unknown chip with ID 0x8665
300         (logical device 4 has address 0x290, could be sensors)
301
302 With this information, run the following commands.
303
304 sudo isadump -k 0x87,0x01,0x55,0x55 0x2e 0x2f 7
305 sudo isadump 0x295 0x296
306
307 and report the results.
308
309 The addresses in the first command are from "Probing for Super-I/O at
310 0x2e/0x2f". Use those addresses in the first command.
311     sudo isadump -k 0x87,0x01,0x55,0x55 0x2e 0x2f 7
312
313 The addresses in the second command are from "has address 0x290".
314 Add 5 and 6 to this address for the next command.
315     sudo isadump 0x295 0x296
316
317 Next, force-install the driver by providing one of the already supported chips
318 as forced ID. Useful IDs to test are 0x8622, 0x8628, 0x8728, and 0x8732, though
319 feel free to test more IDs. For each ID, instantiate the driver as follows
320 (this example is instantiating driver with ID 0x8622).
321         sudo modprobe it87 force_id=0x8622
322 After entering this command, run the "sensors" command and provide the output.
323 Then unload the driver with
324         sudo modprobe -r it87
325 Repeat with different chip IDs, and report each result.
326
327 Please also report your board type as well as voltages and fan settings from
328 the BIOS. If possible, connect fans to different fan headers and let us know
329 if all fans are detected and reported.
330
331 This information _might_ give us enough information to add experimental support
332 for the chip in question. No guarantees, though - unless a datasheet is
333 available, something is likely to be wrong.