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   * Texas Instruments TMP461
 269
 270     Prefix: 'tmp461'
 271
 272     Addresses scanned: I2C 0x48 through 0x4F
 273
 274     Datasheet: Publicly available at TI website
 275
 276                https://www.ti.com/lit/gpn/tmp461
 277
 278 Author: Jean Delvare <jdelvare@suse.de>
 279
 280
 281 Description
 282 -----------
 283
 284 The LM90 is a digital temperature sensor. It senses its own temperature as
 285 well as the temperature of up to one external diode. It is compatible
 286 with many other devices, many of which are supported by this driver.
 287
 288 Note that there is no easy way to differentiate between the MAX6657,
 289 MAX6658 and MAX6659 variants. The extra features of the MAX6659 are only
 290 supported by this driver if the chip is located at address 0x4d or 0x4e,
 291 or if the chip type is explicitly selected as max6659.
 292 The MAX6680 and MAX6681 only differ in their pinout, therefore they obviously
 293 can't (and don't need to) be distinguished.
 294
 295 The specificity of this family of chipsets over the ADM1021/LM84
 296 family is that it features critical limits with hysteresis, and an
 297 increased resolution of the remote temperature measurement.
 298
 299 The different chipsets of the family are not strictly identical, although
 300 very similar. For reference, here comes a non-exhaustive list of specific
 301 features:
 302
 303 LM90:
 304   * Filter and alert configuration register at 0xBF.
 305   * ALERT is triggered by temperatures over critical limits.
 306
 307 LM86 and LM89:
 308   * Same as LM90
 309   * Better external channel accuracy
 310
 311 LM99:
 312   * Same as LM89
 313   * External temperature shifted by 16 degrees down
 314
 315 ADM1032:
 316   * Consecutive alert register at 0x22.
 317   * Conversion averaging.
 318   * Up to 64 conversions/s.
 319   * ALERT is triggered by open remote sensor.
 320   * SMBus PEC support for Write Byte and Receive Byte transactions.
 321
 322 ADT7461, ADT7461A, NCT1008:
 323   * Extended temperature range (breaks compatibility)
 324   * Lower resolution for remote temperature
 325
 326 MAX6654:
 327   * Better local resolution
 328   * Selectable address
 329   * Remote sensor type selection
 330   * Extended temperature range
 331   * Extended resolution only available when conversion rate <= 1 Hz
 332
 333 MAX6657 and MAX6658:
 334   * Better local resolution
 335   * Remote sensor type selection
 336
 337 MAX6659:
 338   * Better local resolution
 339   * Selectable address
 340   * Second critical temperature limit
 341   * Remote sensor type selection
 342
 343 MAX6680 and MAX6681:
 344   * Selectable address
 345   * Remote sensor type selection
 346
 347 MAX6695 and MAX6696:
 348   * Better local resolution
 349   * Selectable address (max6696)
 350   * Second critical temperature limit
 351   * Two remote sensors
 352
 353 W83L771W/G
 354   * The G variant is lead-free, otherwise similar to the W.
 355   * Filter and alert configuration register at 0xBF
 356   * Moving average (depending on conversion rate)
 357
 358 W83L771AWG/ASG
 359   * Successor of the W83L771W/G, same features.
 360   * The AWG and ASG variants only differ in package format.
 361   * Diode ideality factor configuration (remote sensor) at 0xE3
 362
 363 SA56004X:
 364   * Better local resolution
 365
 366 All temperature values are given in degrees Celsius. Resolution
 367 is 1.0 degree for the local temperature, 0.125 degree for the remote
 368 temperature, except for the MAX6654, MAX6657, MAX6658 and MAX6659 which have
 369 a resolution of 0.125 degree for both temperatures.
 370
 371 Each sensor has its own high and low limits, plus a critical limit.
 372 Additionally, there is a relative hysteresis value common to both critical
 373 values. To make life easier to user-space applications, two absolute values
 374 are exported, one for each channel, but these values are of course linked.
 375 Only the local hysteresis can be set from user-space, and the same delta
 376 applies to the remote hysteresis.
 377
 378 The lm90 driver will not update its values more frequently than configured with
 379 the update_interval attribute; reading them more often will do no harm, but will
 380 return 'old' values.
 381
 382 SMBus Alert Support
 383 -------------------
 384
 385 This driver has basic support for SMBus alert. When an alert is received,
 386 the status register is read and the faulty temperature channel is logged.
 387
 388 The Analog Devices chips (ADM1032, ADT7461 and ADT7461A) and ON
 389 Semiconductor chips (NCT1008) do not implement the SMBus alert protocol
 390 properly so additional care is needed: the ALERT output is disabled when
 391 an alert is received, and is re-enabled only when the alarm is gone.
 392 Otherwise the chip would block alerts from other chips in the bus as long
 393 as the alarm is active.
 394
 395 PEC Support
 396 -----------
 397
 398 The ADM1032 is the only chip of the family which supports PEC. It does
 399 not support PEC on all transactions though, so some care must be taken.
 400
 401 When reading a register value, the PEC byte is computed and sent by the
 402 ADM1032 chip. However, in the case of a combined transaction (SMBus Read
 403 Byte), the ADM1032 computes the CRC value over only the second half of
 404 the message rather than its entirety, because it thinks the first half
 405 of the message belongs to a different transaction. As a result, the CRC
 406 value differs from what the SMBus master expects, and all reads fail.
 407
 408 For this reason, the lm90 driver will enable PEC for the ADM1032 only if
 409 the bus supports the SMBus Send Byte and Receive Byte transaction types.
 410 These transactions will be used to read register values, instead of
 411 SMBus Read Byte, and PEC will work properly.
 412
 413 Additionally, the ADM1032 doesn't support SMBus Send Byte with PEC.
 414 Instead, it will try to write the PEC value to the register (because the
 415 SMBus Send Byte transaction with PEC is similar to a Write Byte transaction
 416 without PEC), which is not what we want. Thus, PEC is explicitly disabled
 417 on SMBus Send Byte transactions in the lm90 driver.
 418
 419 PEC on byte data transactions represents a significant increase in bandwidth
 420 usage (+33% for writes, +25% for reads) in normal conditions. With the need
 421 to use two SMBus transaction for reads, this overhead jumps to +50%. Worse,
 422 two transactions will typically mean twice as much delay waiting for
 423 transaction completion, effectively doubling the register cache refresh time.
 424 I guess reliability comes at a price, but it's quite expensive this time.
 425
 426 So, as not everyone might enjoy the slowdown, PEC can be disabled through
 427 sysfs. Just write 0 to the "pec" file and PEC will be disabled. Write 1
 428 to that file to enable PEC again.