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                http://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                http://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                http://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                http://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 MAX6657
 127
 128     Prefix: 'max6657'
 129
 130     Addresses scanned: I2C 0x4c
 131
 132     Datasheet: Publicly available at the Maxim website
 133
 134                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578
 135
 136   * Maxim MAX6658
 137
 138     Prefix: 'max6657'
 139
 140     Addresses scanned: I2C 0x4c
 141
 142     Datasheet: Publicly available at the Maxim website
 143
 144                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578
 145
 146   * Maxim MAX6659
 147
 148     Prefix: 'max6659'
 149
 150     Addresses scanned: I2C 0x4c, 0x4d, 0x4e
 151
 152     Datasheet: Publicly available at the Maxim website
 153
 154                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578
 155
 156   * Maxim MAX6680
 157
 158     Prefix: 'max6680'
 159
 160     Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b,
 161
 162                            0x4c, 0x4d and 0x4e
 163
 164     Datasheet: Publicly available at the Maxim website
 165
 166                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370
 167
 168   * Maxim MAX6681
 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 MAX6692
 181
 182     Prefix: 'max6646'
 183
 184     Addresses scanned: I2C 0x4c
 185
 186     Datasheet: Publicly available at the Maxim website
 187
 188                http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500
 189
 190   * Maxim MAX6695
 191
 192     Prefix: 'max6695'
 193
 194     Addresses scanned: I2C 0x18
 195
 196     Datasheet: Publicly available at the Maxim website
 197
 198                http://www.maxim-ic.com/datasheet/index.mvp/id/4199
 199
 200   * Maxim MAX6696
 201
 202     Prefix: 'max6695'
 203
 204     Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b,
 205
 206                            0x4c, 0x4d and 0x4e
 207
 208     Datasheet: Publicly available at the Maxim website
 209
 210                http://www.maxim-ic.com/datasheet/index.mvp/id/4199
 211
 212   * Winbond/Nuvoton W83L771W/G
 213
 214     Prefix: 'w83l771'
 215
 216     Addresses scanned: I2C 0x4c
 217
 218     Datasheet: No longer available
 219
 220   * Winbond/Nuvoton W83L771AWG/ASG
 221
 222     Prefix: 'w83l771'
 223
 224     Addresses scanned: I2C 0x4c
 225
 226     Datasheet: Not publicly available, can be requested from Nuvoton
 227
 228   * Philips/NXP SA56004X
 229
 230     Prefix: 'sa56004'
 231
 232     Addresses scanned: I2C 0x48 through 0x4F
 233
 234     Datasheet: Publicly available at NXP website
 235
 236                http://ics.nxp.com/products/interface/datasheet/sa56004x.pdf
 237
 238   * GMT G781
 239
 240     Prefix: 'g781'
 241
 242     Addresses scanned: I2C 0x4c, 0x4d
 243
 244     Datasheet: Not publicly available from GMT
 245
 246   * Texas Instruments TMP451
 247
 248     Prefix: 'tmp451'
 249
 250     Addresses scanned: I2C 0x4c
 251
 252     Datasheet: Publicly available at TI website
 253
 254                http://www.ti.com/litv/pdf/sbos686
 255
 256 Author: Jean Delvare <jdelvare@suse.de>
 257
 258
 259 Description
 260 -----------
 261
 262 The LM90 is a digital temperature sensor. It senses its own temperature as
 263 well as the temperature of up to one external diode. It is compatible
 264 with many other devices, many of which are supported by this driver.
 265
 266 Note that there is no easy way to differentiate between the MAX6657,
 267 MAX6658 and MAX6659 variants. The extra features of the MAX6659 are only
 268 supported by this driver if the chip is located at address 0x4d or 0x4e,
 269 or if the chip type is explicitly selected as max6659.
 270 The MAX6680 and MAX6681 only differ in their pinout, therefore they obviously
 271 can't (and don't need to) be distinguished.
 272
 273 The specificity of this family of chipsets over the ADM1021/LM84
 274 family is that it features critical limits with hysteresis, and an
 275 increased resolution of the remote temperature measurement.
 276
 277 The different chipsets of the family are not strictly identical, although
 278 very similar. For reference, here comes a non-exhaustive list of specific
 279 features:
 280
 281 LM90:
 282   * Filter and alert configuration register at 0xBF.
 283   * ALERT is triggered by temperatures over critical limits.
 284
 285 LM86 and LM89:
 286   * Same as LM90
 287   * Better external channel accuracy
 288
 289 LM99:
 290   * Same as LM89
 291   * External temperature shifted by 16 degrees down
 292
 293 ADM1032:
 294   * Consecutive alert register at 0x22.
 295   * Conversion averaging.
 296   * Up to 64 conversions/s.
 297   * ALERT is triggered by open remote sensor.
 298   * SMBus PEC support for Write Byte and Receive Byte transactions.
 299
 300 ADT7461, ADT7461A, NCT1008:
 301   * Extended temperature range (breaks compatibility)
 302   * Lower resolution for remote temperature
 303
 304 MAX6657 and MAX6658:
 305   * Better local resolution
 306   * Remote sensor type selection
 307
 308 MAX6659:
 309   * Better local resolution
 310   * Selectable address
 311   * Second critical temperature limit
 312   * Remote sensor type selection
 313
 314 MAX6680 and MAX6681:
 315   * Selectable address
 316   * Remote sensor type selection
 317
 318 MAX6695 and MAX6696:
 319   * Better local resolution
 320   * Selectable address (max6696)
 321   * Second critical temperature limit
 322   * Two remote sensors
 323
 324 W83L771W/G
 325   * The G variant is lead-free, otherwise similar to the W.
 326   * Filter and alert configuration register at 0xBF
 327   * Moving average (depending on conversion rate)
 328
 329 W83L771AWG/ASG
 330   * Successor of the W83L771W/G, same features.
 331   * The AWG and ASG variants only differ in package format.
 332   * Diode ideality factor configuration (remote sensor) at 0xE3
 333
 334 SA56004X:
 335   * Better local resolution
 336
 337 All temperature values are given in degrees Celsius. Resolution
 338 is 1.0 degree for the local temperature, 0.125 degree for the remote
 339 temperature, except for the MAX6657, MAX6658 and MAX6659 which have a
 340 resolution of 0.125 degree for both temperatures.
 341
 342 Each sensor has its own high and low limits, plus a critical limit.
 343 Additionally, there is a relative hysteresis value common to both critical
 344 values. To make life easier to user-space applications, two absolute values
 345 are exported, one for each channel, but these values are of course linked.
 346 Only the local hysteresis can be set from user-space, and the same delta
 347 applies to the remote hysteresis.
 348
 349 The lm90 driver will not update its values more frequently than configured with
 350 the update_interval attribute; reading them more often will do no harm, but will
 351 return 'old' values.
 352
 353 SMBus Alert Support
 354 -------------------
 355
 356 This driver has basic support for SMBus alert. When an alert is received,
 357 the status register is read and the faulty temperature channel is logged.
 358
 359 The Analog Devices chips (ADM1032, ADT7461 and ADT7461A) and ON
 360 Semiconductor chips (NCT1008) do not implement the SMBus alert protocol
 361 properly so additional care is needed: the ALERT output is disabled when
 362 an alert is received, and is re-enabled only when the alarm is gone.
 363 Otherwise the chip would block alerts from other chips in the bus as long
 364 as the alarm is active.
 365
 366 PEC Support
 367 -----------
 368
 369 The ADM1032 is the only chip of the family which supports PEC. It does
 370 not support PEC on all transactions though, so some care must be taken.
 371
 372 When reading a register value, the PEC byte is computed and sent by the
 373 ADM1032 chip. However, in the case of a combined transaction (SMBus Read
 374 Byte), the ADM1032 computes the CRC value over only the second half of
 375 the message rather than its entirety, because it thinks the first half
 376 of the message belongs to a different transaction. As a result, the CRC
 377 value differs from what the SMBus master expects, and all reads fail.
 378
 379 For this reason, the lm90 driver will enable PEC for the ADM1032 only if
 380 the bus supports the SMBus Send Byte and Receive Byte transaction types.
 381 These transactions will be used to read register values, instead of
 382 SMBus Read Byte, and PEC will work properly.
 383
 384 Additionally, the ADM1032 doesn't support SMBus Send Byte with PEC.
 385 Instead, it will try to write the PEC value to the register (because the
 386 SMBus Send Byte transaction with PEC is similar to a Write Byte transaction
 387 without PEC), which is not what we want. Thus, PEC is explicitly disabled
 388 on SMBus Send Byte transactions in the lm90 driver.
 389
 390 PEC on byte data transactions represents a significant increase in bandwidth
 391 usage (+33% for writes, +25% for reads) in normal conditions. With the need
 392 to use two SMBus transaction for reads, this overhead jumps to +50%. Worse,
 393 two transactions will typically mean twice as much delay waiting for
 394 transaction completion, effectively doubling the register cache refresh time.
 395 I guess reliability comes at a price, but it's quite expensive this time.
 396
 397 So, as not everyone might enjoy the slowdown, PEC can be disabled through
 398 sysfs. Just write 0 to the "pec" file and PEC will be disabled. Write 1
 399 to that file to enable PEC again.