1Kernel driver ds1621
2====================
3
4Supported chips:
5
6  * Dallas Semiconductor / Maxim Integrated DS1621
7
8    Prefix: 'ds1621'
9
10    Addresses scanned: none
11
12    Datasheet: Publicly available from www.maximintegrated.com
13
14  * Dallas Semiconductor DS1625
15
16    Prefix: 'ds1625'
17
18    Addresses scanned: none
19
20    Datasheet: Publicly available from www.datasheetarchive.com
21
22  * Maxim Integrated DS1631
23
24    Prefix: 'ds1631'
25
26    Addresses scanned: none
27
28    Datasheet: Publicly available from www.maximintegrated.com
29
30  * Maxim Integrated DS1721
31
32    Prefix: 'ds1721'
33
34    Addresses scanned: none
35
36    Datasheet: Publicly available from www.maximintegrated.com
37
38  * Maxim Integrated DS1731
39
40    Prefix: 'ds1731'
41
42    Addresses scanned: none
43
44    Datasheet: Publicly available from www.maximintegrated.com
45
46Authors:
47      - Christian W. Zuckschwerdt <zany@triq.net>
48      - valuable contributions by Jan M. Sendler <sendler@sendler.de>
49      - ported to 2.6 by Aurelien Jarno <aurelien@aurel32.net>
50	with the help of Jean Delvare <jdelvare@suse.de>
51
52Module Parameters
53------------------
54
55* polarity int
56  Output's polarity:
57
58  * 0 = active high,
59  * 1 = active low
60
61Description
62-----------
63
64The DS1621 is a (one instance) digital thermometer and thermostat. It has
65both high and low temperature limits which can be user defined (i.e.
66programmed into non-volatile on-chip registers). Temperature range is -55
67degree Celsius to +125 in 0.5 increments. You may convert this into a
68Fahrenheit range of -67 to +257 degrees with 0.9 steps. If polarity
69parameter is not provided, original value is used.
70
71As for the thermostat, behavior can also be programmed using the polarity
72toggle. On the one hand ("heater"), the thermostat output of the chip,
73Tout, will trigger when the low limit temperature is met or underrun and
74stays high until the high limit is met or exceeded. On the other hand
75("cooler"), vice versa. That way "heater" equals "active low", whereas
76"conditioner" equals "active high". Please note that the DS1621 data sheet
77is somewhat misleading in this point since setting the polarity bit does
78not simply invert Tout.
79
80A second thing is that, during extensive testing, Tout showed a tolerance
81of up to +/- 0.5 degrees even when compared against precise temperature
82readings. Be sure to have a high vs. low temperature limit gap of al least
831.0 degree Celsius to avoid Tout "bouncing", though!
84
85The alarm bits are set when the high or low limits are met or exceeded and
86are reset by the module as soon as the respective temperature ranges are
87left.
88
89The alarm registers are in no way suitable to find out about the actual
90status of Tout. They will only tell you about its history, whether or not
91any of the limits have ever been met or exceeded since last power-up or
92reset. Be aware: When testing, it showed that the status of Tout can change
93with neither of the alarms set.
94
95Since there is no version or vendor identification register, there is
96no unique identification for these devices. Therefore, explicit device
97instantiation is required for correct device identification and functionality
98(one device per address in this address range: 0x48..0x4f).
99
100The DS1625 is pin compatible and functionally equivalent with the DS1621,
101but the DS1621 is meant to replace it. The DS1631, DS1721, and DS1731 are
102also pin compatible with the DS1621 and provide multi-resolution support.
103
104Additionally, the DS1721 data sheet says the temperature flags (THF and TLF)
105are used internally, however, these flags do get set and cleared as the actual
106temperature crosses the min or max settings (which by default are set to 75
107and 80 degrees respectively).
108
109Temperature Conversion
110----------------------
111
112- DS1621 - 750ms (older devices may take up to 1000ms)
113- DS1625 - 500ms
114- DS1631 - 93ms..750ms for 9..12 bits resolution, respectively.
115- DS1721 - 93ms..750ms for 9..12 bits resolution, respectively.
116- DS1731 - 93ms..750ms for 9..12 bits resolution, respectively.
117
118Note:
119On the DS1621, internal access to non-volatile registers may last for 10ms
120or less (unverified on the other devices).
121
122Temperature Accuracy
123--------------------
124
125- DS1621: +/- 0.5 degree Celsius (from 0 to +70 degrees)
126- DS1625: +/- 0.5 degree Celsius (from 0 to +70 degrees)
127- DS1631: +/- 0.5 degree Celsius (from 0 to +70 degrees)
128- DS1721: +/- 1.0 degree Celsius (from -10 to +85 degrees)
129- DS1731: +/- 1.0 degree Celsius (from -10 to +85 degrees)
130
131.. Note::
132
133   Please refer to the device datasheets for accuracy at other temperatures.
134
135Temperature Resolution:
136-----------------------
137As mentioned above, the DS1631, DS1721, and DS1731 provide multi-resolution
138support, which is achieved via the R0 and R1 config register bits, where:
139
140R0..R1
141------
142
143== ==  ===============================
144R0 R1
145== ==  ===============================
146 0  0  9 bits, 0.5 degrees Celsius
147 1  0  10 bits, 0.25 degrees Celsius
148 0  1  11 bits, 0.125 degrees Celsius
149 1  1  12 bits, 0.0625 degrees Celsius
150== ==  ===============================
151
152.. Note::
153
154   At initial device power-on, the default resolution is set to 12-bits.
155
156The resolution mode for the DS1631, DS1721, or DS1731 can be changed from
157userspace, via the device 'update_interval' sysfs attribute. This attribute
158will normalize the range of input values to the device maximum resolution
159values defined in the datasheet as follows:
160
161============= ================== ===============
162Resolution    Conversion Time    Input Range
163 (C/LSB)       (msec)             (msec)
164============= ================== ===============
1650.5             93.75              0....94
1660.25            187.5              95...187
1670.125           375                188..375
1680.0625          750                376..infinity
169============= ================== ===============
170
171The following examples show how the 'update_interval' attribute can be
172used to change the conversion time::
173
174  $ cat update_interval
175  750
176  $ cat temp1_input
177  22062
178  $
179  $ echo 300 > update_interval
180  $ cat update_interval
181  375
182  $ cat temp1_input
183  22125
184  $
185  $ echo 150 > update_interval
186  $ cat update_interval
187  188
188  $ cat temp1_input
189  22250
190  $
191  $ echo 1 > update_interval
192  $ cat update_interval
193  94
194  $ cat temp1_input
195  22000
196  $
197  $ echo 1000 > update_interval
198  $ cat update_interval
199  750
200  $ cat temp1_input
201  22062
202  $
203
204As shown, the ds1621 driver automatically adjusts the 'update_interval'
205user input, via a step function. Reading back the 'update_interval' value
206after a write operation provides the conversion time used by the device.
207
208Mathematically, the resolution can be derived from the conversion time
209via the following function:
210
211   g(x) = 0.5 * [minimum_conversion_time/x]
212
213where:
214
215 - 'x' = the output from 'update_interval'
216 - 'g(x)' = the resolution in degrees C per LSB.
217 - 93.75ms = minimum conversion time
218