Documentation/hwmon/max31827.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Kernel driver max31827
   4 ======================
   5
   6 Supported chips:
   7
   8   * Maxim MAX31827
   9
  10     Prefix: 'max31827'
  11
  12     Addresses scanned: I2C 0x40 - 0x5f
  13
  14     Datasheet: Publicly available at the Analog Devices website
  15
  16   * Maxim MAX31828
  17
  18     Prefix: 'max31828'
  19
  20     Addresses scanned: I2C 0x40 - 0x5f
  21
  22     Datasheet: Publicly available at the Analog Devices website
  23
  24   * Maxim MAX31829
  25
  26     Prefix: 'max31829'
  27
  28     Addresses scanned: I2C 0x40 - 0x5f
  29
  30     Datasheet: Publicly available at the Analog Devices website
  31
  32
  33 Authors:
  34         - Daniel Matyas <daniel.matyas@analog.com>
  35
  36 Description
  37 -----------
  38
  39 The chips supported by this driver are quite similar. The only difference
  40 between them is found in the default power-on behaviour of the chips. While the
  41 MAX31827's fault queue is set to 1, the other two chip's fault queue is set to
  42 4. Besides this, the MAX31829's alarm active state is high, while the other two
  43 chip's alarms are active on low. It is important to note that the chips can be
  44 configured to operate in the same manner with 1 write operation to the
  45 configuration register. From here on, we will refer to all these chips as
  46 MAX31827.
  47
  48 MAX31827 implements a temperature sensor with a 6 WLP packaging scheme. This
  49 sensor measures the temperature of the chip itself.
  50
  51 MAX31827 has low and over temperature alarms with an effective value and a
  52 hysteresis value: -40 and -30 degrees for under temperature alarm and +100 and
  53 +90 degrees for over temperature alarm.
  54
  55 The alarm can be configured in comparator and interrupt mode from the
  56 devicetree. In Comparator mode, the OT/UT status bits have a value of 1 when the
  57 temperature rises above the TH value or falls below TL, which is also subject to
  58 the Fault Queue selection. OT status returns to 0 when the temperature drops
  59 below the TH_HYST value or when shutdown mode is entered. Similarly, UT status
  60 returns to 0 when the temperature rises above TL_HYST value or when shutdown
  61 mode is entered.
  62
  63 In interrupt mode exceeding TH also sets OT status to 1, which remains set until
  64 a read operation is performed on the configuration/status register (max or min
  65 attribute); at this point, it returns to 0. Once OT status is set to 1 from
  66 exceeding TH and reset, it is set to 1 again only when the temperature drops
  67 below TH_HYST. The output remains asserted until it is reset by a read. It is
  68 set again if the temperature rises above TH, and so on. The same logic applies
  69 to the operation of the UT status bit.
  70
  71 Putting the MAX31827 into shutdown mode also resets the OT/UT status bits. Note
  72 that if the mode is changed while OT/UT status bits are set, an OT/UT status
  73 reset may be required before it begins to behave normally. To prevent this,
  74 it is recommended to perform a read of the configuration/status register to
  75 clear the status bits before changing the operating mode.
  76
  77 The conversions can be manual with the one-shot functionality and automatic with
  78 a set frequency. When powered on, the chip measures temperatures with 1 conv/s.
  79 The conversion rate can be modified with update_interval attribute of the chip.
  80 Conversion/second = 1/update_interval. Thus, the available options according to
  81 the data sheet are:
  82
  83 - 64000 (ms) = 1 conv/64 sec
  84 - 32000 (ms) = 1 conv/32 sec
  85 - 16000 (ms) = 1 conv/16 sec
  86 - 4000 (ms) = 1 conv/4 sec
  87 - 1000 (ms) = 1 conv/sec (default)
  88 - 250 (ms) = 4 conv/sec
  89 - 125 (ms) = 8 conv/sec
  90
  91 Enabling the device when it is already enabled has the side effect of setting
  92 the conversion frequency to 1 conv/s. The conversion time varies depending on
  93 the resolution.
  94
  95 The conversion time doubles with every bit of increased resolution. The
  96 available resolutions are:
  97
  98 - 8 bit -> 8.75 ms conversion time
  99 - 9 bit -> 17.5 ms conversion time
 100 - 10 bit -> 35 ms conversion time
 101 - 12 bit (default) -> 140 ms conversion time
 102
 103 There is a temp1_resolution attribute which indicates the unit change in the
 104 input temperature in milli-degrees C.
 105
 106 - 1000 mC -> 8 bit
 107 - 500 mC -> 9 bit
 108 - 250 mC -> 10 bit
 109 - 62 mC -> 12 bit (default) - actually this is 62.5, but the fil returns 62
 110
 111 When chip is in shutdown mode and a read operation is requested, one-shot is
 112 triggered, the device waits for <conversion time> ms, and only after that is
 113 the temperature value register read. Note that the conversion times are rounded
 114 up to the nearest possible integer.
 115
 116 The LSB of the temperature values is 0.0625 degrees Celsius, but the values of
 117 the temperatures are displayed in milli-degrees. This means, that some data is
 118 lost. The step between 2 consecutive values is 62 or 63. This effect can be seen
 119 in the writing of alarm values too. For positive numbers the user-input value
 120 will always be rounded down to the nearest possible value, for negative numbers
 121 the user-input will always be rounded up to the nearest possible value.
 122
 123 Bus timeout resets the I2C-compatible interface when SCL is low for more than
 124 30ms (nominal).
 125
 126 Alarm polarity determines if the active state of the alarm is low or high. The
 127 behavior for both settings is dependent on the Fault Queue setting. The ALARM
 128 pin is an open-drain output and requires a pullup resistor to operate.
 129
 130 The Fault Queue bits select how many consecutive temperature faults must occur
 131 before overtemperature or undertemperature faults are indicated in the
 132 corresponding status bits.
 133
 134 PEC Support
 135 -----------
 136
 137 When reading a register value, the PEC byte is computed and sent by the chip.
 138
 139 PEC on word data transaction represents a significant increase in bandwidth
 140 usage (+33% for both write and reads) in normal conditions.
 141
 142 Since this operation implies there will be an extra delay to each
 143 transaction, PEC can be disabled or enabled through sysfs.
 144 Just write 1  to the "pec" file for enabling PEC and 0 for disabling it.