Kernel driver ds1621

DS1621 계열과 polarity parameter

드라이버는 Dallas Semiconductor / Maxim Integrated DS1621(prefix `ds1621`), DS1625(`ds1625`), DS1631(`ds1631`), DS1721(`ds1721`), DS1731(`ds1731`)을 지원합니다. 어느 chip도 주소를 scan하지 않으며 datasheet는 각 제조사 또는 archive에서 공개되어 있습니다.

저자는 Christian W. Zuckschwerdt이고 Jan M. Sendler가 기여했으며 Aurelien Jarno가 Jean Delvare의 도움으로 Linux 2.6에 port했습니다.

Module parameter `polarity`는 thermostat output polarity를 정합니다. `0`은 active high, `1`은 active low입니다.

Kernel driver ds1621
====================

Supported chips:

  * Dallas Semiconductor / Maxim Integrated DS1621

    Prefix: 'ds1621'

    Addresses scanned: none

    Datasheet: Publicly available from www.maximintegrated.com

  * Dallas Semiconductor DS1625

    Prefix: 'ds1625'

    Addresses scanned: none

    Datasheet: Publicly available from www.datasheetarchive.com

  * Maxim Integrated DS1631

    Prefix: 'ds1631'

    Addresses scanned: none

    Datasheet: Publicly available from www.maximintegrated.com

  * Maxim Integrated DS1721

    Prefix: 'ds1721'

    Addresses scanned: none

    Datasheet: Publicly available from www.maximintegrated.com

  * Maxim Integrated DS1731

    Prefix: 'ds1731'

    Addresses scanned: none

    Datasheet: Publicly available from www.maximintegrated.com

Authors:
      - Christian W. Zuckschwerdt <[email protected]>
      - valuable contributions by Jan M. Sendler <[email protected]>
      - ported to 2.6 by Aurelien Jarno <[email protected]>
        with the help of Jean Delvare <[email protected]>

Module Parameters
------------------

* polarity int
  Output's polarity:

  * 0 = active high,
  * 1 = active low

Thermostat hysteresis와 alarm 이력

DS1621은 단일 digital thermometer·thermostat입니다. 사용자 정의 high·low limit를 non-volatile on-chip register에 programming할 수 있습니다. 범위는 -55C~+125C, step은 0.5C이며 Fahrenheit로는 -67~+257도, step 0.9도입니다. `polarity`를 주지 않으면 원래 값을 유지합니다.

Thermostat 동작은 polarity로 programming합니다. Heater(active low)에서는 low limit에 도달하거나 밑돌면 `Tout`이 trigger되고 high limit에 도달하거나 넘을 때까지 high 상태를 유지합니다. Cooler 또는 conditioner(active high)에서는 반대로 동작합니다. Datasheet 표현과 달리 polarity bit는 `Tout`을 단순 반전하는 것이 아닙니다.

Extensive test에서 정확한 temperature reading과 비교해도 `Tout` tolerance가 최대 +/-0.5C였습니다. `Tout` bouncing을 피하려면 high와 low limit 사이를 최소 1.0C로 두어야 합니다.

High 또는 low limit에 도달·초과하면 alarm bit가 설정되고, 각각의 temperature range를 벗어나면 module이 reset합니다. 그러나 alarm register는 실제 `Tout` 상태를 알려주지 못합니다. 마지막 power-up 또는 reset 이후 limit에 도달한 이력만 나타내며, test에서는 alarm이 하나도 설정되지 않은 채 `Tout`이 바뀌기도 했습니다.

Version·vendor identification register가 없어 device를 고유 식별할 수 없습니다. 따라서 0x48~0x4f 범위에서 주소당 한 device를 명시적으로 instantiate해야 정확한 식별과 기능을 얻습니다.

DS1625는 DS1621과 pin-compatible·functionally equivalent지만 DS1621이 대체품입니다. DS1631, DS1721, DS1731도 pin-compatible하며 multi-resolution을 제공합니다. DS1721 datasheet는 THF·TLF flag를 internal 용도라고 하지만 실제로는 temperature가 기본 min 75C·max 80C 설정을 넘을 때 set·clear됩니다.

Description
-----------

The DS1621 is a (one instance) digital thermometer and thermostat. It has
both high and low temperature limits which can be user defined (i.e.
programmed into non-volatile on-chip registers). Temperature range is -55
degree Celsius to +125 in 0.5 increments. You may convert this into a
Fahrenheit range of -67 to +257 degrees with 0.9 steps. If polarity
parameter is not provided, original value is used.

As for the thermostat, behavior can also be programmed using the polarity
toggle. On the one hand ("heater"), the thermostat output of the chip,
Tout, will trigger when the low limit temperature is met or underrun and
stays high until the high limit is met or exceeded. On the other hand
("cooler"), vice versa. That way "heater" equals "active low", whereas
"conditioner" equals "active high". Please note that the DS1621 data sheet
is somewhat misleading in this point since setting the polarity bit does
not simply invert Tout.

A second thing is that, during extensive testing, Tout showed a tolerance
of up to +/- 0.5 degrees even when compared against precise temperature
readings. Be sure to have a high vs. low temperature limit gap of al least
1.0 degree Celsius to avoid Tout "bouncing", though!

The alarm bits are set when the high or low limits are met or exceeded and
are reset by the module as soon as the respective temperature ranges are
left.

The alarm registers are in no way suitable to find out about the actual
status of Tout. They will only tell you about its history, whether or not
any of the limits have ever been met or exceeded since last power-up or
reset. Be aware: When testing, it showed that the status of Tout can change
with neither of the alarms set.

Since there is no version or vendor identification register, there is
no unique identification for these devices. Therefore, explicit device
instantiation is required for correct device identification and functionality
(one device per address in this address range: 0x48..0x4f).

The DS1625 is pin compatible and functionally equivalent with the DS1621,
but the DS1621 is meant to replace it. The DS1631, DS1721, and DS1731 are
also pin compatible with the DS1621 and provide multi-resolution support.

Additionally, the DS1721 data sheet says the temperature flags (THF and TLF)
are used internally, however, these flags do get set and cleared as the actual
temperature crosses the min or max settings (which by default are set to 75
and 80 degrees respectively).

Conversion time과 accuracy

Temperature conversion time은 DS1621 750ms(older device는 최대 1000ms), DS1625 500ms입니다. DS1631·DS1721·DS1731은 9~12-bit resolution에 따라 93ms~750ms입니다.

DS1621의 non-volatile register 내부 접근은 10ms 이하 걸릴 수 있습니다. 다른 device에서는 검증되지 않았습니다.

0~+70C 구간에서 DS1621, DS1625, DS1631 accuracy는 +/-0.5C입니다. DS1721과 DS1731은 -10~+85C에서 +/-1.0C입니다. 그 밖의 temperature accuracy는 device datasheet를 참조해야 합니다.

Temperature Conversion
----------------------

- DS1621 - 750ms (older devices may take up to 1000ms)
- DS1625 - 500ms
- DS1631 - 93ms..750ms for 9..12 bits resolution, respectively.
- DS1721 - 93ms..750ms for 9..12 bits resolution, respectively.
- DS1731 - 93ms..750ms for 9..12 bits resolution, respectively.

Note:
On the DS1621, internal access to non-volatile registers may last for 10ms
or less (unverified on the other devices).

Temperature Accuracy
--------------------

- DS1621: +/- 0.5 degree Celsius (from 0 to +70 degrees)
- DS1625: +/- 0.5 degree Celsius (from 0 to +70 degrees)
- DS1631: +/- 0.5 degree Celsius (from 0 to +70 degrees)
- DS1721: +/- 1.0 degree Celsius (from -10 to +85 degrees)
- DS1731: +/- 1.0 degree Celsius (from -10 to +85 degrees)

.. Note::

   Please refer to the device datasheets for accuracy at other temperatures.

R0·R1 resolution과 update_interval 정규화

DS1631, DS1721, DS1731은 config register의 R0·R1 bit로 multi-resolution을 제공합니다. `R0=0,R1=0`은 9-bit 0.5C, `1,0`은 10-bit 0.25C, `0,1`은 11-bit 0.125C, `1,1`은 12-bit 0.0625C입니다. 최초 power-on 기본값은 12-bit입니다.

Userspace는 `update_interval` sysfs attribute로 resolution mode를 바꿀 수 있습니다. Driver는 입력값 범위를 datasheet의 maximum-resolution conversion time 단계로 normalize합니다.

입력 0~94ms는 resolution 0.5C/LSB와 conversion 93.75ms, 95~187ms는 0.25C와 187.5ms, 188~375ms는 0.125C와 375ms, 376ms 이상은 0.0625C와 750ms를 선택합니다.

Temperature Resolution:
-----------------------
As mentioned above, the DS1631, DS1721, and DS1731 provide multi-resolution
support, which is achieved via the R0 and R1 config register bits, where:

R0..R1
------

== ==  ===============================
R0 R1
== ==  ===============================
 0  0  9 bits, 0.5 degrees Celsius
 1  0  10 bits, 0.25 degrees Celsius
 0  1  11 bits, 0.125 degrees Celsius
 1  1  12 bits, 0.0625 degrees Celsius
== ==  ===============================

.. Note::

   At initial device power-on, the default resolution is set to 12-bits.

The resolution mode for the DS1631, DS1721, or DS1731 can be changed from
userspace, via the device 'update_interval' sysfs attribute. This attribute
will normalize the range of input values to the device maximum resolution
values defined in the datasheet as follows:

============= ================== ===============
Resolution    Conversion Time    Input Range
 (C/LSB)       (msec)             (msec)
============= ================== ===============
0.5             93.75              0....94
0.25            187.5              95...187
0.125           375                188..375
0.0625          750                376..infinity
============= ================== ===============

update_interval 예제와 resolution 함수

예제에서 초기 `update_interval=750`일 때 `temp1_input=22062`입니다. `echo 300` 뒤 readback은 375이고 온도는 22125, `echo 150` 뒤 readback은 188이고 22250, `echo 1` 뒤 readback은 94이고 22000입니다. `echo 1000`은 750으로 정규화되고 22062를 반환합니다.

즉 ds1621 driver는 userspace 입력을 step function으로 자동 조정합니다. Write 뒤 `update_interval`을 다시 읽으면 device가 실제 사용하는 conversion time을 알 수 있습니다.

Conversion time에서 resolution을 구하는 원문 함수는 `g(x) = 0.5 * [minimum_conversion_time/x]`입니다. `x`는 `update_interval` 출력, `g(x)`는 degree C per LSB resolution, minimum conversion time은 93.75ms입니다.

The following examples show how the 'update_interval' attribute can be
used to change the conversion time::

  $ cat update_interval
  750
  $ cat temp1_input
  22062
  $
  $ echo 300 > update_interval
  $ cat update_interval
  375
  $ cat temp1_input
  22125
  $
  $ echo 150 > update_interval
  $ cat update_interval
  188
  $ cat temp1_input
  22250
  $
  $ echo 1 > update_interval
  $ cat update_interval
  94
  $ cat temp1_input
  22000
  $
  $ echo 1000 > update_interval
  $ cat update_interval
  750
  $ cat temp1_input
  22062
  $

As shown, the ds1621 driver automatically adjusts the 'update_interval'
user input, via a step function. Reading back the 'update_interval' value
after a write operation provides the conversion time used by the device.

Mathematically, the resolution can be derived from the conversion time
via the following function:

   g(x) = 0.5 * [minimum_conversion_time/x]

where:

 - 'x' = the output from 'update_interval'
 - 'g(x)' = the resolution in degrees C per LSB.
 - 93.75ms = minimum conversion time