Merge tag 'hyperv-fixes-signed' of git://git.kernel.org/pub/scm/linux/kernel/git...
[platform/kernel/linux-rpi.git] / Documentation / hwmon / lm90.rst
1 Kernel driver lm90
2 ==================
3
4 Supported chips:
5
6   * National Semiconductor LM90
7
8     Prefix: 'lm90'
9
10     Addresses scanned: I2C 0x4c
11
12     Datasheet: Publicly available at the National Semiconductor website
13
14                http://www.national.com/pf/LM/LM90.html
15
16   * National Semiconductor LM89
17
18     Prefix: 'lm89' (no auto-detection)
19
20     Addresses scanned: I2C 0x4c and 0x4d
21
22     Datasheet: Publicly available at the National Semiconductor website
23
24                http://www.national.com/mpf/LM/LM89.html
25
26   * National Semiconductor LM99
27
28     Prefix: 'lm99'
29
30     Addresses scanned: I2C 0x4c and 0x4d
31
32     Datasheet: Publicly available at the National Semiconductor website
33
34                http://www.national.com/pf/LM/LM99.html
35
36   * National Semiconductor LM86
37
38     Prefix: 'lm86'
39
40     Addresses scanned: I2C 0x4c
41
42     Datasheet: Publicly available at the National Semiconductor website
43
44                http://www.national.com/mpf/LM/LM86.html
45
46   * Analog Devices ADM1032
47
48     Prefix: 'adm1032'
49
50     Addresses scanned: I2C 0x4c and 0x4d
51
52     Datasheet: Publicly available at the ON Semiconductor website
53
54                https://www.onsemi.com/PowerSolutions/product.do?id=ADM1032
55
56   * Analog Devices ADT7461
57
58     Prefix: 'adt7461'
59
60     Addresses scanned: I2C 0x4c and 0x4d
61
62     Datasheet: Publicly available at the ON Semiconductor website
63
64                https://www.onsemi.com/PowerSolutions/product.do?id=ADT7461
65
66   * Analog Devices ADT7461A
67
68     Prefix: 'adt7461a'
69
70     Addresses scanned: I2C 0x4c and 0x4d
71
72     Datasheet: Publicly available at the ON Semiconductor website
73
74                https://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A
75
76   * ON Semiconductor NCT1008
77
78     Prefix: 'nct1008'
79
80     Addresses scanned: I2C 0x4c and 0x4d
81
82     Datasheet: Publicly available at the ON Semiconductor website
83
84                https://www.onsemi.com/PowerSolutions/product.do?id=NCT1008
85
86   * Maxim MAX6646
87
88     Prefix: 'max6646'
89
90     Addresses scanned: I2C 0x4d
91
92     Datasheet: Publicly available at the Maxim website
93
94                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497
95
96   * Maxim MAX6647
97
98     Prefix: 'max6646'
99
100     Addresses scanned: I2C 0x4e
101
102     Datasheet: Publicly available at the Maxim website
103
104                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497
105
106   * Maxim MAX6648
107
108     Prefix: 'max6646'
109
110     Addresses scanned: I2C 0x4c
111
112     Datasheet: Publicly available at the Maxim website
113
114                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500
115
116   * Maxim MAX6649
117
118     Prefix: 'max6646'
119
120     Addresses scanned: I2C 0x4c
121
122     Datasheet: Publicly available at the Maxim website
123
124                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497
125
126   * Maxim MAX6654
127
128     Prefix: 'max6654'
129
130     Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b,
131
132                            0x4c, 0x4d and 0x4e
133
134     Datasheet: Publicly available at the Maxim website
135
136                https://www.maximintegrated.com/en/products/sensors/MAX6654.html
137
138   * Maxim MAX6657
139
140     Prefix: 'max6657'
141
142     Addresses scanned: I2C 0x4c
143
144     Datasheet: Publicly available at the Maxim website
145
146                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578
147
148   * Maxim MAX6658
149
150     Prefix: 'max6657'
151
152     Addresses scanned: I2C 0x4c
153
154     Datasheet: Publicly available at the Maxim website
155
156                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578
157
158   * Maxim MAX6659
159
160     Prefix: 'max6659'
161
162     Addresses scanned: I2C 0x4c, 0x4d, 0x4e
163
164     Datasheet: Publicly available at the Maxim website
165
166                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578
167
168   * Maxim MAX6680
169
170     Prefix: 'max6680'
171
172     Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b,
173
174                            0x4c, 0x4d and 0x4e
175
176     Datasheet: Publicly available at the Maxim website
177
178                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370
179
180   * Maxim MAX6681
181
182     Prefix: 'max6680'
183
184     Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b,
185
186                            0x4c, 0x4d and 0x4e
187
188     Datasheet: Publicly available at the Maxim website
189
190                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370
191
192   * Maxim MAX6692
193
194     Prefix: 'max6646'
195
196     Addresses scanned: I2C 0x4c
197
198     Datasheet: Publicly available at the Maxim website
199
200                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500
201
202   * Maxim MAX6695
203
204     Prefix: 'max6695'
205
206     Addresses scanned: I2C 0x18
207
208     Datasheet: Publicly available at the Maxim website
209
210                http://www.maxim-ic.com/datasheet/index.mvp/id/4199
211
212   * Maxim MAX6696
213
214     Prefix: 'max6695'
215
216     Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b,
217
218                            0x4c, 0x4d and 0x4e
219
220     Datasheet: Publicly available at the Maxim website
221
222                http://www.maxim-ic.com/datasheet/index.mvp/id/4199
223
224   * Winbond/Nuvoton W83L771W/G
225
226     Prefix: 'w83l771'
227
228     Addresses scanned: I2C 0x4c
229
230     Datasheet: No longer available
231
232   * Winbond/Nuvoton W83L771AWG/ASG
233
234     Prefix: 'w83l771'
235
236     Addresses scanned: I2C 0x4c
237
238     Datasheet: Not publicly available, can be requested from Nuvoton
239
240   * Philips/NXP SA56004X
241
242     Prefix: 'sa56004'
243
244     Addresses scanned: I2C 0x48 through 0x4F
245
246     Datasheet: Publicly available at NXP website
247
248                http://ics.nxp.com/products/interface/datasheet/sa56004x.pdf
249
250   * GMT G781
251
252     Prefix: 'g781'
253
254     Addresses scanned: I2C 0x4c, 0x4d
255
256     Datasheet: Not publicly available from GMT
257
258   * Texas Instruments TMP451
259
260     Prefix: 'tmp451'
261
262     Addresses scanned: I2C 0x4c
263
264     Datasheet: Publicly available at TI website
265
266                https://www.ti.com/litv/pdf/sbos686
267
268 Author: Jean Delvare <jdelvare@suse.de>
269
270
271 Description
272 -----------
273
274 The LM90 is a digital temperature sensor. It senses its own temperature as
275 well as the temperature of up to one external diode. It is compatible
276 with many other devices, many of which are supported by this driver.
277
278 Note that there is no easy way to differentiate between the MAX6657,
279 MAX6658 and MAX6659 variants. The extra features of the MAX6659 are only
280 supported by this driver if the chip is located at address 0x4d or 0x4e,
281 or if the chip type is explicitly selected as max6659.
282 The MAX6680 and MAX6681 only differ in their pinout, therefore they obviously
283 can't (and don't need to) be distinguished.
284
285 The specificity of this family of chipsets over the ADM1021/LM84
286 family is that it features critical limits with hysteresis, and an
287 increased resolution of the remote temperature measurement.
288
289 The different chipsets of the family are not strictly identical, although
290 very similar. For reference, here comes a non-exhaustive list of specific
291 features:
292
293 LM90:
294   * Filter and alert configuration register at 0xBF.
295   * ALERT is triggered by temperatures over critical limits.
296
297 LM86 and LM89:
298   * Same as LM90
299   * Better external channel accuracy
300
301 LM99:
302   * Same as LM89
303   * External temperature shifted by 16 degrees down
304
305 ADM1032:
306   * Consecutive alert register at 0x22.
307   * Conversion averaging.
308   * Up to 64 conversions/s.
309   * ALERT is triggered by open remote sensor.
310   * SMBus PEC support for Write Byte and Receive Byte transactions.
311
312 ADT7461, ADT7461A, NCT1008:
313   * Extended temperature range (breaks compatibility)
314   * Lower resolution for remote temperature
315
316 MAX6654:
317   * Better local resolution
318   * Selectable address
319   * Remote sensor type selection
320   * Extended temperature range
321   * Extended resolution only available when conversion rate <= 1 Hz
322
323 MAX6657 and MAX6658:
324   * Better local resolution
325   * Remote sensor type selection
326
327 MAX6659:
328   * Better local resolution
329   * Selectable address
330   * Second critical temperature limit
331   * Remote sensor type selection
332
333 MAX6680 and MAX6681:
334   * Selectable address
335   * Remote sensor type selection
336
337 MAX6695 and MAX6696:
338   * Better local resolution
339   * Selectable address (max6696)
340   * Second critical temperature limit
341   * Two remote sensors
342
343 W83L771W/G
344   * The G variant is lead-free, otherwise similar to the W.
345   * Filter and alert configuration register at 0xBF
346   * Moving average (depending on conversion rate)
347
348 W83L771AWG/ASG
349   * Successor of the W83L771W/G, same features.
350   * The AWG and ASG variants only differ in package format.
351   * Diode ideality factor configuration (remote sensor) at 0xE3
352
353 SA56004X:
354   * Better local resolution
355
356 All temperature values are given in degrees Celsius. Resolution
357 is 1.0 degree for the local temperature, 0.125 degree for the remote
358 temperature, except for the MAX6654, MAX6657, MAX6658 and MAX6659 which have
359 a resolution of 0.125 degree for both temperatures.
360
361 Each sensor has its own high and low limits, plus a critical limit.
362 Additionally, there is a relative hysteresis value common to both critical
363 values. To make life easier to user-space applications, two absolute values
364 are exported, one for each channel, but these values are of course linked.
365 Only the local hysteresis can be set from user-space, and the same delta
366 applies to the remote hysteresis.
367
368 The lm90 driver will not update its values more frequently than configured with
369 the update_interval attribute; reading them more often will do no harm, but will
370 return 'old' values.
371
372 SMBus Alert Support
373 -------------------
374
375 This driver has basic support for SMBus alert. When an alert is received,
376 the status register is read and the faulty temperature channel is logged.
377
378 The Analog Devices chips (ADM1032, ADT7461 and ADT7461A) and ON
379 Semiconductor chips (NCT1008) do not implement the SMBus alert protocol
380 properly so additional care is needed: the ALERT output is disabled when
381 an alert is received, and is re-enabled only when the alarm is gone.
382 Otherwise the chip would block alerts from other chips in the bus as long
383 as the alarm is active.
384
385 PEC Support
386 -----------
387
388 The ADM1032 is the only chip of the family which supports PEC. It does
389 not support PEC on all transactions though, so some care must be taken.
390
391 When reading a register value, the PEC byte is computed and sent by the
392 ADM1032 chip. However, in the case of a combined transaction (SMBus Read
393 Byte), the ADM1032 computes the CRC value over only the second half of
394 the message rather than its entirety, because it thinks the first half
395 of the message belongs to a different transaction. As a result, the CRC
396 value differs from what the SMBus master expects, and all reads fail.
397
398 For this reason, the lm90 driver will enable PEC for the ADM1032 only if
399 the bus supports the SMBus Send Byte and Receive Byte transaction types.
400 These transactions will be used to read register values, instead of
401 SMBus Read Byte, and PEC will work properly.
402
403 Additionally, the ADM1032 doesn't support SMBus Send Byte with PEC.
404 Instead, it will try to write the PEC value to the register (because the
405 SMBus Send Byte transaction with PEC is similar to a Write Byte transaction
406 without PEC), which is not what we want. Thus, PEC is explicitly disabled
407 on SMBus Send Byte transactions in the lm90 driver.
408
409 PEC on byte data transactions represents a significant increase in bandwidth
410 usage (+33% for writes, +25% for reads) in normal conditions. With the need
411 to use two SMBus transaction for reads, this overhead jumps to +50%. Worse,
412 two transactions will typically mean twice as much delay waiting for
413 transaction completion, effectively doubling the register cache refresh time.
414 I guess reliability comes at a price, but it's quite expensive this time.
415
416 So, as not everyone might enjoy the slowdown, PEC can be disabled through
417 sysfs. Just write 0 to the "pec" file and PEC will be disabled. Write 1
418 to that file to enable PEC again.