218 lines · plain
1Kernel driver ds16212====================3 4Supported chips:5 6 * Dallas Semiconductor / Maxim Integrated DS16217 8 Prefix: 'ds1621'9 10 Addresses scanned: none11 12 Datasheet: Publicly available from www.maximintegrated.com13 14 * Dallas Semiconductor DS162515 16 Prefix: 'ds1625'17 18 Addresses scanned: none19 20 Datasheet: Publicly available from www.datasheetarchive.com21 22 * Maxim Integrated DS163123 24 Prefix: 'ds1631'25 26 Addresses scanned: none27 28 Datasheet: Publicly available from www.maximintegrated.com29 30 * Maxim Integrated DS172131 32 Prefix: 'ds1721'33 34 Addresses scanned: none35 36 Datasheet: Publicly available from www.maximintegrated.com37 38 * Maxim Integrated DS173139 40 Prefix: 'ds1731'41 42 Addresses scanned: none43 44 Datasheet: Publicly available from www.maximintegrated.com45 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 Parameters53------------------54 55* polarity int56 Output's polarity:57 58 * 0 = active high,59 * 1 = active low60 61Description62-----------63 64The DS1621 is a (one instance) digital thermometer and thermostat. It has65both high and low temperature limits which can be user defined (i.e.66programmed into non-volatile on-chip registers). Temperature range is -5567degree Celsius to +125 in 0.5 increments. You may convert this into a68Fahrenheit range of -67 to +257 degrees with 0.9 steps. If polarity69parameter is not provided, original value is used.70 71As for the thermostat, behavior can also be programmed using the polarity72toggle. On the one hand ("heater"), the thermostat output of the chip,73Tout, will trigger when the low limit temperature is met or underrun and74stays high until the high limit is met or exceeded. On the other hand75("cooler"), vice versa. That way "heater" equals "active low", whereas76"conditioner" equals "active high". Please note that the DS1621 data sheet77is somewhat misleading in this point since setting the polarity bit does78not simply invert Tout.79 80A second thing is that, during extensive testing, Tout showed a tolerance81of up to +/- 0.5 degrees even when compared against precise temperature82readings. Be sure to have a high vs. low temperature limit gap of al least831.0 degree Celsius to avoid Tout "bouncing", though!84 85The alarm bits are set when the high or low limits are met or exceeded and86are reset by the module as soon as the respective temperature ranges are87left.88 89The alarm registers are in no way suitable to find out about the actual90status of Tout. They will only tell you about its history, whether or not91any of the limits have ever been met or exceeded since last power-up or92reset. Be aware: When testing, it showed that the status of Tout can change93with neither of the alarms set.94 95Since there is no version or vendor identification register, there is96no unique identification for these devices. Therefore, explicit device97instantiation is required for correct device identification and functionality98(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 are102also 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 actual106temperature crosses the min or max settings (which by default are set to 75107and 80 degrees respectively).108 109Temperature Conversion110----------------------111 112- DS1621 - 750ms (older devices may take up to 1000ms)113- DS1625 - 500ms114- 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 10ms120or less (unverified on the other devices).121 122Temperature Accuracy123--------------------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-resolution138support, which is achieved via the R0 and R1 config register bits, where:139 140R0..R1141------142 143== == ===============================144R0 R1145== == ===============================146 0 0 9 bits, 0.5 degrees Celsius147 1 0 10 bits, 0.25 degrees Celsius148 0 1 11 bits, 0.125 degrees Celsius149 1 1 12 bits, 0.0625 degrees Celsius150== == ===============================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 from157userspace, via the device 'update_interval' sysfs attribute. This attribute158will normalize the range of input values to the device maximum resolution159values defined in the datasheet as follows:160 161============= ================== ===============162Resolution Conversion Time Input Range163 (C/LSB) (msec) (msec)164============= ================== ===============1650.5 93.75 0....941660.25 187.5 95...1871670.125 375 188..3751680.0625 750 376..infinity169============= ================== ===============170 171The following examples show how the 'update_interval' attribute can be172used to change the conversion time::173 174 $ cat update_interval175 750176 $ cat temp1_input177 22062178 $179 $ echo 300 > update_interval180 $ cat update_interval181 375182 $ cat temp1_input183 22125184 $185 $ echo 150 > update_interval186 $ cat update_interval187 188188 $ cat temp1_input189 22250190 $191 $ echo 1 > update_interval192 $ cat update_interval193 94194 $ cat temp1_input195 22000196 $197 $ echo 1000 > update_interval198 $ cat update_interval199 750200 $ cat temp1_input201 22062202 $203 204As shown, the ds1621 driver automatically adjusts the 'update_interval'205user input, via a step function. Reading back the 'update_interval' value206after a write operation provides the conversion time used by the device.207 208Mathematically, the resolution can be derived from the conversion time209via 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 time218