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.