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