Kernel driver w1_therm

지원 센서와 family code

`w1_therm`은 Maxim DS18x20·DS1825 계열 온도 센서, GXCAS GX20MH01, Maxim MAX31850 열전대 인터페이스의 기본 온도 변환을 제공합니다. DS28EA00도 지원 대상입니다.

family code는 DS18S20 `0x10`, DS1822 `0x22`, DS18B20 `0x28`, DS1825 `0x3B`, DS28EA00 `0x42`입니다.

======================
Kernel driver w1_therm
======================

Supported chips:

  * Maxim ds18*20 based temperature sensors.
  * Maxim ds1825 based temperature sensors.
  * GXCAS GX20MH01 temperature sensor.
  * Maxim MAX31850 thermoelement interface.

Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>


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

w1_therm provides basic temperature conversion for ds18*20, ds28ea00, GX20MH01
and MAX31850 devices.

Supported family codes:

====================        ====
W1_THERM_DS18S20        0x10
W1_THERM_DS1822                0x22
W1_THERM_DS18B20        0x28
W1_THERM_DS1825                0x3B
W1_THERM_DS28EA00        0x42
====================        ====

개별 읽기와 일괄 변환

sysfs의 `w1_slave`를 열어 읽을 때마다 온도 변환을 시작한 뒤 ASCII 두 줄을 반환합니다. 첫 줄은 읽은 9개의 16진수 바이트, 계산 CRC, 일치 여부 `YES` 또는 `NO`를 담습니다.

CRC가 맞으면 값을 보관하고 둘째 줄에 보관한 값과 `t=` 뒤의 섭씨 밀리도 온도를 표시합니다. `temperature` 파일은 온도만 섭씨 밀리도 단위로 반환하는 간단한 대안입니다.

마스터의 `therm_bulk_read`에 `trigger`를 쓰면 버스의 모든 장치에 변환 명령을 보냅니다. 기생 전원 장치가 있고 모듈의 strong pull-up이 켜져 있으면 더 긴 변환 시간 동안 선을 high로 구동합니다.

`therm_bulk_read` 읽기 결과는 대기 중인 변환이 없으면 0, 하나 이상 변환 중이면 -1, 변환은 끝났지만 아직 읽지 않은 센서 값이 있으면 1입니다. 이후 각 장치의 `temperature`를 읽으며 변환 중이면 빈 결과가 나올 수 있습니다.

일괄 변환 뒤 센서를 즉시 읽지 않으면 다음 `temperature` 접근은 현재 온도가 아니라 일괄 명령을 발행했을 때 측정한 온도를 반환합니다. 필요하면 변환 동안 strong pull-up을 적용합니다.

Support is provided through the sysfs entry ``w1_slave``. Each open and
read sequence will initiate a temperature conversion, then provide two
lines of ASCII output. The first line contains the nine hex bytes
read along with a calculated crc value and YES or NO if it matched.
If the crc matched the returned values are retained. The second line
displays the retained values along with a temperature in millidegrees
Centigrade after t=.

Alternatively, temperature can be read using ``temperature`` sysfs, it
returns only the temperature in millidegrees Centigrade.

A bulk read of all devices on the bus could be done writing ``trigger``
to ``therm_bulk_read`` entry at w1_bus_master level. This will
send the convert command to all devices on the bus, and if parasite
powered devices are detected on the bus (and strong pullup is enabled
in the module), it will drive the line high during the longer conversion
time required by parasited powered device on the line. Reading
``therm_bulk_read`` will return 0 if no bulk conversion pending,
-1 if at least one sensor still in conversion, 1 if conversion is complete
but at least one sensor value has not been read yet. Result temperature is
then accessed by reading the ``temperature`` entry of each device, which
may return empty if conversion is still in progress. Note that if a bulk
read is sent but one sensor is not read immediately, the next access to
``temperature`` on this device will return the temperature measured at the
time of issue of the bulk read command (not the current temperature).

A strong pullup will be applied during the conversion if required.

``conv_time`` is used to get current conversion time (read), and

변환 시간과 해상도

`conv_time`은 현재 변환 시간을 읽거나 변경합니다. 변환 시간은 장치 종류와 현재 해상도에 따라 달라지며 드라이버 기본값은 데이터시트를 따릅니다. 복제 칩은 실제 시간이 사양과 다른 경우가 많습니다.

방법은 세 가지입니다. 밀리초 값을 직접 쓰거나, `1`을 써서 자동 측정·설정하거나, `features`로 변환 완료 polling을 켭니다. 자동 측정과 polling은 기생 전원 모드에서 사용할 수 없습니다. `0`을 쓰면 기본 변환 시간으로 돌아갑니다.

`w1_slave`에 비트 단위 해상도를 쓰면 다음 읽기의 정밀도가 바뀝니다. 허용 해상도는 센서별로 다르며 전원을 껐다 켜면 초기화됩니다.

현재 해상도를 EEPROM에 저장하려면 `w1_slave`에 `0`을 씁니다. EEPROM 쓰기 수명은 5만 회보다 많지만 제한되어 있으므로 신중히 사용해야 합니다. 지원 센서는 전용 `resolution` 파일로도 해상도를 읽고 쓸 수 있습니다.

일부 비정품 DS18B20은 12비트에 고정되어 있어 드라이버가 실제 해상도를 다시 읽어 검증합니다. 해상도를 바꾸면 변환 시간은 기본값으로 되돌아갑니다.

adjust it (write). A temperature conversion time depends on the device type and
its current resolution. Default conversion time is set by the driver according
to the device datasheet. A conversion time for many original device clones
deviate from datasheet specs. There are three options: 1) manually set the
correct conversion time by writing a value in milliseconds to ``conv_time``; 2)
auto measure and set a conversion time by writing ``1`` to
``conv_time``; 3) use ``features`` to enable poll for conversion
completion. Options 2, 3 can't be used in parasite power mode. To get back to
the default conversion time write ``0`` to ``conv_time``.

Writing a resolution value (in bits) to ``w1_slave`` will change the
precision of the sensor for the next readings. Allowed resolutions are defined by
the sensor. Resolution is reset when the sensor gets power-cycled.

To store the current resolution in EEPROM, write ``0`` to ``w1_slave``.
Since the EEPROM has a limited amount of writes (>50k), this command should be
used wisely.

Alternatively, resolution can be read or written using the dedicated
``resolution`` entry on each device, if supported by the sensor.

Some non-genuine DS18B20 chips are fixed in 12-bit mode only, so the actual
resolution is read back from the chip and verified.

Note: Changing the resolution reverts the conversion time to default.

The write-only sysfs entry ``eeprom_cmd`` is an alternative for EEPROM operations.
Write ``save`` to save device RAM to EEPROM. Write ``restore`` to restore EEPROM
data in device RAM.

EEPROM·전원·경보·strong pull-up

쓰기 전용 `eeprom_cmd`는 EEPROM 작업의 대안입니다. `save`는 장치 RAM을 EEPROM에 저장하고 `restore`는 EEPROM 데이터를 RAM으로 복원합니다.

`ext_power`는 전원 상태를 확인하며 기생 전원이면 `0`, 외부 전원이면 `1`을 반환합니다.

`alarms`는 TH와 TL 온도 경보를 읽거나 씁니다. 값은 공백으로 구분한 정수이고 장치 범위, 보통 -55°C~125°C 안이어야 합니다. 8비트 레지스터에 저장되며 낮은 값은 자동으로 TL에 배치됩니다. 설정한 경보는 마스터 수준에서 검색할 수 있습니다.

`strong_pullup` 모듈 매개변수는 0이면 비활성화, 1이면 자동 감지, 2이면 강제 활성화입니다. 자동 모드는 `READ POWER SUPPLY` 명령으로 기생 전원 장치를 찾고 발견하면 마스터 strong pull-up을 켭니다. 일부 DS18S20처럼 감지가 실패하면 강제 모드를 쓸 수 있습니다.

strong pull-up을 켜고 마스터가 지원하면 변환 동안 선을 강하게 구동하며, 지원하지 않으면 pull-up 저항으로 대체됩니다. DS18B20의 최대 소비 전류는 1.5mA이고 5kΩ pull-up만으로 부족하므로 추가 전류 공급이 필요합니다.

``ext_power`` entry allows checking the power state of each device. Reads
``0`` if the device is parasite powered, ``1`` if the device is externally powered.

Sysfs ``alarms`` allow read or write TH and TL (Temperature High an Low) alarms.
Values shall be space separated and in the device range (typical -55 degC
to 125 degC). Values are integer as they are store in a 8bit register in
the device. Lowest value is automatically put to TL. Once set, alarms could
be search at master level.

The module parameter strong_pullup can be set to 0 to disable the
strong pullup, 1 to enable autodetection or 2 to force strong pullup.
In case of autodetection, the driver will use the "READ POWER SUPPLY"
command to check if there are pariste powered devices on the bus.
If so, it will activate the master's strong pullup.
In case the detection of parasite devices using this command fails
(seems to be the case with some DS18S20) the strong pullup can
be force-enabled.

If the strong pullup is enabled, the master's strong pullup will be
driven when the conversion is taking place, provided the master driver
does support the strong pullup (or it falls back to a pullup
resistor).  The DS18b20 temperature sensor specification lists a
maximum current draw of 1.5mA and that a 5k pullup resistor is not
sufficient.  The strong pullup is designed to provide the additional
current required.

The DS28EA00 provides an additional two pins for implementing a sequence
detection algorithm.  This feature allows you to determine the physical
location of the chip in the 1-wire bus without needing pre-existing
knowledge of the bus ordering.  Support is provided through the sysfs

순서 검출·기능 비트·호환 장치

DS28EA00은 버스 순서를 검출하는 두 핀을 추가로 제공합니다. 사전에 배선 순서를 몰라도 칩의 물리 위치를 알아낼 수 있으며 `w1_seq`가 0부터 시작하는 장치 인덱스를 한 줄 정수로 반환합니다.

장치별 `features`는 선택 기능을 제어합니다. 기생 전원의 전력 부족, 선로 잡음, 짧은 변환 시간은 실패를 일으킬 수 있습니다. 비트 마스크 `1`은 변환 성공 검사를 켭니다. 변환 뒤 scratchpad 바이트 6이 `0xC`이고 온도가 85.00°C 또는 127.94°C이면 드라이버가 변환 오류를 반환합니다.

비트 마스크 `2`는 정상 전원 장치에서 변환 시작 뒤 버스 읽기 주기를 생성해 완료를 polling합니다. 기생 전원 모드에서는 사용할 수 없으며 기능 비트는 OR로 결합할 수 있습니다. 자세한 ABI는 `Documentation/ABI/testing/sysfs-driver-w1_therm`에 있습니다.

GX20MH01은 DS18x20과 family `0x28`을 공유하고 DS18B20과 대체로 호환됩니다. Config 레지스터에 2^-5·2^-6 온도 비트와 13·14비트 해상도를 켜는 R2 비트가 추가되며 전원 투입 시 14비트입니다. 데이터시트 변환 시간은 너무 짧아 늘려야 하고 features 1과 2를 지원합니다.

MAX31850은 DS1825와 family `0x3B`을 공유하고 대체로 호환됩니다. Config 레지스터 상위 4비트는 모두 1이라 15로 읽히지만 실제 동작 해상도는 항상 14비트입니다.

``w1_seq``. The file will contain a single line with an integer value
representing the device index in the bus starting at 0.

``features`` sysfs entry controls optional driver settings per device.
Insufficient power in parasite mode, line noise and insufficient conversion
time may lead to conversion failure. Original DS18B20 and some clones allow for
detection of invalid conversion. Write bit mask ``1`` to ``features`` to enable
checking the conversion success. If byte 6 of scratchpad memory is 0xC after
conversion and temperature reads 85.00 (powerup value) or 127.94 (insufficient
power), the driver returns a conversion error. Bit mask ``2`` enables poll for
conversion completion (normal power only) by generating read cycles on the bus
after conversion starts. In parasite power mode this feature is not available.
Feature bit masks may be combined (OR). More details in
Documentation/ABI/testing/sysfs-driver-w1_therm

GX20MH01 device shares family number 0x28 with DS18*20. The device is generally
compatible with DS18B20. Added are lowest 2\ :sup:`-5`, 2\ :sup:`-6` temperature
bits in Config register; R2 bit in Config register enabling 13 and 14 bit
resolutions. The device is powered up in 14-bit resolution mode. The conversion
times specified in the datasheet are too low and have to be increased. The
device supports driver features ``1`` and ``2``.

MAX31850 device shares family number 0x3B with DS1825. The device is generally
compatible with DS1825. The higher 4 bits of Config register read all 1,
indicating 15, but the device is always operating in 14-bit resolution mode.