Merge tag 'pinctrl-v5.16-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw...
[linux-2.6-microblaze.git] / Documentation / hwmon / w83781d.rst
1 Kernel driver w83781d
2 =====================
3
4 Supported chips:
5
6   * Winbond W83781D
7
8     Prefix: 'w83781d'
9
10     Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports)
11
12     Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/w83781d.pdf
13
14   * Winbond W83782D
15
16     Prefix: 'w83782d'
17
18     Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports)
19
20     Datasheet: https://www.winbond.com
21
22   * Winbond W83783S
23
24     Prefix: 'w83783s'
25
26     Addresses scanned: I2C 0x2d
27
28     Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/w83783s.pdf
29
30   * Asus AS99127F
31
32     Prefix: 'as99127f'
33
34     Addresses scanned: I2C 0x28 - 0x2f
35
36     Datasheet: Unavailable from Asus
37
38
39
40 Authors:
41
42       - Frodo Looijaard <frodol@dds.nl>,
43       - Philip Edelbrock <phil@netroedge.com>,
44       - Mark Studebaker <mdsxyz123@yahoo.com>
45
46 Module parameters
47 -----------------
48
49 * init int
50     (default 1)
51
52     Use 'init=0' to bypass initializing the chip.
53     Try this if your computer crashes when you load the module.
54
55 * reset int
56     (default 0)
57     The driver used to reset the chip on load, but does no more. Use
58     'reset=1' to restore the old behavior. Report if you need to do this.
59
60 force_subclients=bus,caddr,saddr,saddr
61   This is used to force the i2c addresses for subclients of
62   a certain chip. Typical usage is `force_subclients=0,0x2d,0x4a,0x4b`
63   to force the subclients of chip 0x2d on bus 0 to i2c addresses
64   0x4a and 0x4b. This parameter is useful for certain Tyan boards.
65
66 Description
67 -----------
68
69 This driver implements support for the Winbond W83781D, W83782D, W83783S
70 chips, and the Asus AS99127F chips. We will refer to them collectively as
71 W8378* chips.
72
73 There is quite some difference between these chips, but they are similar
74 enough that it was sensible to put them together in one driver.
75 The Asus chips are similar to an I2C-only W83782D.
76
77 +----------+---------+--------+-------+-------+---------+--------+------+-----+
78 | Chip     | #vin    | #fanin | #pwm  | #temp | wchipid | vendid | i2c  | ISA |
79 +----------+---------+--------+-------+-------+---------+--------+------+-----+
80 | as99127f | 7       | 3      | 0     | 3     | 0x31    | 0x12c3 | yes  |  no |
81 +----------+---------+--------+-------+-------+---------+--------+------+-----+
82 | as99127f rev.2 (type_name = as99127f)       | 0x31    | 0x5ca3 | yes  |  no |
83 +----------+---------+--------+-------+-------+---------+--------+------+-----+
84 | w83781d  | 7       | 3      | 0     | 3     | 0x10-1  | 0x5ca3 | yes  | yes |
85 +----------+---------+--------+-------+-------+---------+--------+------+-----+
86 | w83782d  | 9       | 3      | 2-4   | 3     | 0x30    | 0x5ca3 | yes  | yes |
87 +----------+---------+--------+-------+-------+---------+--------+------+-----+
88 | w83783s  | 5-6     | 3      | 2     |  1-2  | 0x40    | 0x5ca3 | yes  |  no |
89 +----------+---------+--------+-------+-------+---------+--------+------+-----+
90
91 Detection of these chips can sometimes be foiled because they can be in
92 an internal state that allows no clean access. If you know the address
93 of the chip, use a 'force' parameter; this will put them into a more
94 well-behaved state first.
95
96 The W8378* implements temperature sensors (three on the W83781D and W83782D,
97 two on the W83783S), three fan rotation speed sensors, voltage sensors
98 (seven on the W83781D, nine on the W83782D and six on the W83783S), VID
99 lines, alarms with beep warnings, and some miscellaneous stuff.
100
101 Temperatures are measured in degrees Celsius. There is always one main
102 temperature sensor, and one (W83783S) or two (W83781D and W83782D) other
103 sensors. An alarm is triggered for the main sensor once when the
104 Overtemperature Shutdown limit is crossed; it is triggered again as soon as
105 it drops below the Hysteresis value. A more useful behavior
106 can be found by setting the Hysteresis value to +127 degrees Celsius; in
107 this case, alarms are issued during all the time when the actual temperature
108 is above the Overtemperature Shutdown value. The driver sets the
109 hysteresis value for temp1 to 127 at initialization.
110
111 For the other temperature sensor(s), an alarm is triggered when the
112 temperature gets higher then the Overtemperature Shutdown value; it stays
113 on until the temperature falls below the Hysteresis value. But on the
114 W83781D, there is only one alarm that functions for both other sensors!
115 Temperatures are guaranteed within a range of -55 to +125 degrees. The
116 main temperature sensors has a resolution of 1 degree; the other sensor(s)
117 of 0.5 degree.
118
119 Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
120 triggered if the rotation speed has dropped below a programmable limit. Fan
121 readings can be divided by a programmable divider (1, 2, 4 or 8 for the
122 W83781D; 1, 2, 4, 8, 16, 32, 64 or 128 for the others) to give
123 the readings more range or accuracy. Not all RPM values can accurately
124 be represented, so some rounding is done. With a divider of 2, the lowest
125 representable value is around 2600 RPM.
126
127 Voltage sensors (also known as IN sensors) report their values in volts.
128 An alarm is triggered if the voltage has crossed a programmable minimum
129 or maximum limit. Note that minimum in this case always means 'closest to
130 zero'; this is important for negative voltage measurements. All voltage
131 inputs can measure voltages between 0 and 4.08 volts, with a resolution
132 of 0.016 volt.
133
134 The VID lines encode the core voltage value: the voltage level your processor
135 should work with. This is hardcoded by the mainboard and/or processor itself.
136 It is a value in volts. When it is unconnected, you will often find the
137 value 3.50 V here.
138
139 The W83782D and W83783S temperature conversion machine understands about
140 several kinds of temperature probes. You can program the so-called
141 beta value in the sensor files. '1' is the PII/Celeron diode, '2' is the
142 TN3904 transistor, and 3435 the default thermistor value. Other values
143 are (not yet) supported.
144
145 In addition to the alarms described above, there is a CHAS alarm on the
146 chips which triggers if your computer case is open.
147
148 When an alarm goes off, you can be warned by a beeping signal through
149 your computer speaker. It is possible to enable all beeping globally,
150 or only the beeping for some alarms.
151
152 Individual alarm and beep bits:
153
154 ======== ==========================
155 0x000001 in0
156 0x000002 in1
157 0x000004 in2
158 0x000008 in3
159 0x000010 temp1
160 0x000020 temp2 (+temp3 on W83781D)
161 0x000040 fan1
162 0x000080 fan2
163 0x000100 in4
164 0x000200 in5
165 0x000400 in6
166 0x000800 fan3
167 0x001000 chassis
168 0x002000 temp3 (W83782D only)
169 0x010000 in7 (W83782D only)
170 0x020000 in8 (W83782D only)
171 ======== ==========================
172
173 If an alarm triggers, it will remain triggered until the hardware register
174 is read at least once. This means that the cause for the alarm may
175 already have disappeared! Note that in the current implementation, all
176 hardware registers are read whenever any data is read (unless it is less
177 than 1.5 seconds since the last update). This means that you can easily
178 miss once-only alarms.
179
180 The chips only update values each 1.5 seconds; reading them more often
181 will do no harm, but will return 'old' values.
182
183 AS99127F PROBLEMS
184 -----------------
185 The as99127f support was developed without the benefit of a datasheet.
186 In most cases it is treated as a w83781d (although revision 2 of the
187 AS99127F looks more like a w83782d).
188 This support will be BETA until a datasheet is released.
189 One user has reported problems with fans stopping
190 occasionally.
191
192 Note that the individual beep bits are inverted from the other chips.
193 The driver now takes care of this so that user-space applications
194 don't have to know about it.
195
196 Known problems:
197         - Problems with diode/thermistor settings (supported?)
198         - One user reports fans stopping under high server load.
199         - Revision 2 seems to have 2 PWM registers but we don't know
200           how to handle them. More details below.
201
202 These will not be fixed unless we get a datasheet.
203 If you have problems, please lobby Asus to release a datasheet.
204 Unfortunately several others have without success.
205 Please do not send mail to us asking for better as99127f support.
206 We have done the best we can without a datasheet.
207 Please do not send mail to the author or the sensors group asking for
208 a datasheet or ideas on how to convince Asus. We can't help.
209
210
211 NOTES
212 -----
213   783s has no in1 so that in[2-6] are compatible with the 781d/782d.
214
215   783s pin is programmable for -5V or temp1; defaults to -5V,
216   no control in driver so temp1 doesn't work.
217
218   782d and 783s datasheets differ on which is pwm1 and which is pwm2.
219   We chose to follow 782d.
220
221   782d and 783s pin is programmable for fan3 input or pwm2 output;
222   defaults to fan3 input.
223   If pwm2 is enabled (with echo 255 1 > pwm2), then
224   fan3 will report 0.
225
226   782d has pwm1-2 for ISA, pwm1-4 for i2c. (pwm3-4 share pins with
227   the ISA pins)
228
229 Data sheet updates
230 ------------------
231         - PWM clock registers:
232                 * 000: master /  512
233                 * 001: master / 1024
234                 * 010: master / 2048
235                 * 011: master / 4096
236                 * 100: master / 8192
237
238
239 Answers from Winbond tech support
240 ---------------------------------
241
242 ::
243
244   >
245   > 1) In the W83781D data sheet section 7.2 last paragraph, it talks about
246   >    reprogramming the R-T table if the Beta of the thermistor is not
247   >    3435K. The R-T table is described briefly in section 8.20.
248   >    What formulas do I use to program a new R-T table for a given Beta?
249   >
250
251   We are sorry that the calculation for R-T table value is
252   confidential. If you have another Beta value of thermistor, we can help
253   to calculate the R-T table for you. But you should give us real R-T
254   Table which can be gotten by thermistor vendor. Therefore we will calculate
255   them and obtain 32-byte data, and you can fill the 32-byte data to the
256   register in Bank0.CR51 of W83781D.
257
258
259   > 2) In the W83782D data sheet, it mentions that pins 38, 39, and 40 are
260   >    programmable to be either thermistor or Pentium II diode inputs.
261   >    How do I program them for diode inputs? I can't find any register
262   >    to program these to be diode inputs.
263
264   You may program Bank0 CR[5Dh] and CR[59h] registers.
265
266   =============================== =============== ============== ============
267         CR[5Dh]                 bit 1(VTIN1)    bit 2(VTIN2)   bit 3(VTIN3)
268
269                 thermistor                0              0              0
270         diode                     1              1              1
271
272
273   (error) CR[59h]               bit 4(VTIN1)    bit 2(VTIN2)   bit 3(VTIN3)
274   (right) CR[59h]               bit 4(VTIN1)    bit 5(VTIN2)   bit 6(VTIN3)
275
276         PII thermal diode         1              1              1
277         2N3904  diode             0              0              0
278   =============================== =============== ============== ============
279
280
281 Asus Clones
282 -----------
283
284 We have no datasheets for the Asus clones (AS99127F and ASB100 Bach).
285 Here are some very useful information that were given to us by Alex Van
286 Kaam about how to detect these chips, and how to read their values. He
287 also gives advice for another Asus chipset, the Mozart-2 (which we
288 don't support yet). Thanks Alex!
289
290 I reworded some parts and added personal comments.
291
292 Detection
293 ^^^^^^^^^
294
295 AS99127F rev.1, AS99127F rev.2 and ASB100:
296 - I2C address range: 0x29 - 0x2F
297 - If register 0x58 holds 0x31 then we have an Asus (either ASB100 or AS99127F)
298 - Which one depends on register 0x4F (manufacturer ID):
299
300   - 0x06 or 0x94: ASB100
301   - 0x12 or 0xC3: AS99127F rev.1
302   - 0x5C or 0xA3: AS99127F rev.2
303
304   Note that 0x5CA3 is Winbond's ID (WEC), which let us think Asus get their
305   AS99127F rev.2 direct from Winbond. The other codes mean ATT and DVC,
306   respectively. ATT could stand for Asustek something (although it would be
307   very badly chosen IMHO), I don't know what DVC could stand for. Maybe
308   these codes simply aren't meant to be decoded that way.
309
310 Mozart-2:
311 - I2C address: 0x77
312 - If register 0x58 holds 0x56 or 0x10 then we have a Mozart-2
313 - Of the Mozart there are 3 types:
314
315   - 0x58=0x56, 0x4E=0x94, 0x4F=0x36: Asus ASM58 Mozart-2
316   - 0x58=0x56, 0x4E=0x94, 0x4F=0x06: Asus AS2K129R Mozart-2
317   - 0x58=0x10, 0x4E=0x5C, 0x4F=0xA3: Asus ??? Mozart-2
318
319   You can handle all 3 the exact same way :)
320
321 Temperature sensors
322 ^^^^^^^^^^^^^^^^^^^
323
324 ASB100:
325   - sensor 1: register 0x27
326   - sensor 2 & 3 are the 2 LM75's on the SMBus
327   - sensor 4: register 0x17
328
329 Remark:
330
331   I noticed that on Intel boards sensor 2 is used for the CPU
332   and 4 is ignored/stuck, on AMD boards sensor 4 is the CPU and sensor 2 is
333   either ignored or a socket temperature.
334
335 AS99127F (rev.1 and 2 alike):
336   - sensor 1: register 0x27
337   - sensor 2 & 3 are the 2 LM75's on the SMBus
338
339 Remark:
340
341   Register 0x5b is suspected to be temperature type selector. Bit 1
342   would control temp1, bit 3 temp2 and bit 5 temp3.
343
344 Mozart-2:
345   - sensor 1: register 0x27
346   - sensor 2: register 0x13
347
348 Fan sensors
349 ^^^^^^^^^^^
350
351 ASB100, AS99127F (rev.1 and 2 alike):
352   - 3 fans, identical to the W83781D
353
354 Mozart-2:
355   - 2 fans only, 1350000/RPM/div
356   - fan 1: register 0x28,  divisor on register 0xA1 (bits 4-5)
357   - fan 2: register 0x29,  divisor on register 0xA1 (bits 6-7)
358
359 Voltages
360 ^^^^^^^^
361
362 This is where there is a difference between AS99127F rev.1 and 2.
363
364 Remark:
365
366   The difference is similar to the difference between
367   W83781D and W83782D.
368
369 ASB100:
370   - in0=r(0x20)*0.016
371   - in1=r(0x21)*0.016
372   - in2=r(0x22)*0.016
373   - in3=r(0x23)*0.016*1.68
374   - in4=r(0x24)*0.016*3.8
375   - in5=r(0x25)*(-0.016)*3.97
376   - in6=r(0x26)*(-0.016)*1.666
377
378 AS99127F rev.1:
379   - in0=r(0x20)*0.016
380   - in1=r(0x21)*0.016
381   - in2=r(0x22)*0.016
382   - in3=r(0x23)*0.016*1.68
383   - in4=r(0x24)*0.016*3.8
384   - in5=r(0x25)*(-0.016)*3.97
385   - in6=r(0x26)*(-0.016)*1.503
386
387 AS99127F rev.2:
388   - in0=r(0x20)*0.016
389   - in1=r(0x21)*0.016
390   - in2=r(0x22)*0.016
391   - in3=r(0x23)*0.016*1.68
392   - in4=r(0x24)*0.016*3.8
393   - in5=(r(0x25)*0.016-3.6)*5.14+3.6
394   - in6=(r(0x26)*0.016-3.6)*3.14+3.6
395
396 Mozart-2:
397   - in0=r(0x20)*0.016
398   - in1=255
399   - in2=r(0x22)*0.016
400   - in3=r(0x23)*0.016*1.68
401   - in4=r(0x24)*0.016*4
402   - in5=255
403   - in6=255
404
405
406 PWM
407 ^^^
408
409 * Additional info about PWM on the AS99127F (may apply to other Asus
410   chips as well) by Jean Delvare as of 2004-04-09:
411
412 AS99127F revision 2 seems to have two PWM registers at 0x59 and 0x5A,
413 and a temperature sensor type selector at 0x5B (which basically means
414 that they swapped registers 0x59 and 0x5B when you compare with Winbond
415 chips).
416 Revision 1 of the chip also has the temperature sensor type selector at
417 0x5B, but PWM registers have no effect.
418
419 We don't know exactly how the temperature sensor type selection works.
420 Looks like bits 1-0 are for temp1, bits 3-2 for temp2 and bits 5-4 for
421 temp3, although it is possible that only the most significant bit matters
422 each time. So far, values other than 0 always broke the readings.
423
424 PWM registers seem to be split in two parts: bit 7 is a mode selector,
425 while the other bits seem to define a value or threshold.
426
427 When bit 7 is clear, bits 6-0 seem to hold a threshold value. If the value
428 is below a given limit, the fan runs at low speed. If the value is above
429 the limit, the fan runs at full speed. We have no clue as to what the limit
430 represents. Note that there seem to be some inertia in this mode, speed
431 changes may need some time to trigger. Also, an hysteresis mechanism is
432 suspected since walking through all the values increasingly and then
433 decreasingly led to slightly different limits.
434
435 When bit 7 is set, bits 3-0 seem to hold a threshold value, while bits 6-4
436 would not be significant. If the value is below a given limit, the fan runs
437 at full speed, while if it is above the limit it runs at low speed (so this
438 is the contrary of the other mode, in a way). Here again, we don't know
439 what the limit is supposed to represent.
440
441 One remarkable thing is that the fans would only have two or three
442 different speeds (transitional states left apart), not a whole range as
443 you usually get with PWM.
444
445 As a conclusion, you can write 0x00 or 0x8F to the PWM registers to make
446 fans run at low speed, and 0x7F or 0x80 to make them run at full speed.
447
448 Please contact us if you can figure out how it is supposed to work. As
449 long as we don't know more, the w83781d driver doesn't handle PWM on
450 AS99127F chips at all.
451
452 * Additional info about PWM on the AS99127F rev.1 by Hector Martin:
453
454 I've been fiddling around with the (in)famous 0x59 register and
455 found out the following values do work as a form of coarse pwm:
456
457 0x80
458  - seems to turn fans off after some time(1-2 minutes)... might be
459    some form of auto-fan-control based on temp? hmm (Qfan? this mobo is an
460    old ASUS, it isn't marketed as Qfan. Maybe some beta pre-attempt at Qfan
461    that was dropped at the BIOS)
462 0x81
463  - off
464 0x82
465  - slightly "on-ner" than off, but my fans do not get to move. I can
466    hear the high-pitched PWM sound that motors give off at too-low-pwm.
467 0x83
468  - now they do move. Estimate about 70% speed or so.
469 0x84-0x8f
470  - full on
471
472 Changing the high nibble doesn't seem to do much except the high bit
473 (0x80) must be set for PWM to work, else the current pwm doesn't seem to
474 change.
475
476 My mobo is an ASUS A7V266-E. This behavior is similar to what I got
477 with speedfan under Windows, where 0-15% would be off, 15-2x% (can't
478 remember the exact value) would be 70% and higher would be full on.
479
480 * Additional info about PWM on the AS99127F rev.1 from lm-sensors
481   ticket #2350:
482
483 I conducted some experiment on Asus P3B-F motherboard with AS99127F
484 (Ver. 1).
485
486 I confirm that 0x59 register control the CPU_Fan Header on this
487 motherboard, and 0x5a register control PWR_Fan.
488
489 In order to reduce the dependency of specific fan, the measurement is
490 conducted with a digital scope without fan connected. I found out that
491 P3B-F actually output variable DC voltage on fan header center pin,
492 looks like PWM is filtered on this motherboard.
493
494 Here are some of measurements:
495
496 ==== =========
497 0x80     20 mV
498 0x81     20 mV
499 0x82    232 mV
500 0x83   1.2  V
501 0x84   2.31 V
502 0x85   3.44 V
503 0x86   4.62 V
504 0x87   5.81 V
505 0x88   7.01 V
506 9x89   8.22 V
507 0x8a   9.42 V
508 0x8b  10.6  V
509 0x8c  11.9  V
510 0x8d  12.4  V
511 0x8e  12.4  V
512 0x8f  12.4  V
513 ==== =========