Introduction to the 1-wire (w1) subsystem

단일 신호선의 master-slave 버스

1-Wire 버스는 신호선 하나와 접지, 총 두 선으로 통신하는 단순한 master-slave 버스입니다. 장치는 오픈 드레인 출력으로 신호선을 접지에 끌어내리고 신호선의 논리 레벨을 샘플링해 통신합니다.

Linux `w1` 서브시스템은 W1 master를 관리하고 slave와 통신하기 위한 공통 프레임워크를 제공합니다. 모든 W1 slave는 반드시 W1 bus master 장치에 연결되어야 합니다.

대표 master는 DS9490 USB 장치, GPIO 기반 W1, I2C-to-W1 브리지 DS2482, RS232 변환기나 병렬 포트 어댑터 같은 에뮬레이션 장치입니다.

=========================================
Introduction to the 1-wire (w1) subsystem
=========================================

The 1-wire bus is a simple master-slave bus that communicates via a single
signal wire (plus ground, so two wires).

Devices communicate on the bus by pulling the signal to ground via an open
drain output and by sampling the logic level of the signal line.

The w1 subsystem provides the framework for managing w1 masters and
communication with slaves.

All w1 slave devices must be connected to a w1 bus master device.

Example w1 master devices:

    - DS9490 usb device
    - W1-over-GPIO
    - DS2482 (i2c to w1 bridge)
    - Emulated devices, such as a RS232 converter, parallel port adapter, etc

master 등록·검색과 논리 트랜잭션

W1 master 드라이버가 서브시스템에 등록되면 해당 master의 sysfs 항목을 만들고 새 slave를 찾기 위해 버스를 주기적으로 검색합니다.

장치를 찾으면 W1 core는 family 드라이버를 불러와 로드 여부를 확인한 뒤 slave에 연결합니다. family 드라이버가 없으면 거의 모든 종류의 작업을 수행할 수 있는 기본 드라이버를 배정합니다.

논리 작업 하나는 하나 또는 두 개 이상의 저수준 동작으로 이루어진 트랜잭션입니다. EEPROM 읽기는 먼저 명령 바이트와 2바이트 주소를 담은 제어 버퍼를 씁니다. 이때 버스를 reset하고 `W1_SKIP_ROM` 또는 `W1_MATCH_ROM`으로 장치를 선택한 다음 버퍼를 전송합니다. 이어서 EEPROM 응답을 읽습니다.

두 단계 사이에 master 검색 스레드가 버스를 reset하거나 slave가 제거될 수 있습니다. 그러면 선택된 장치가 없으므로 읽기 결과는 `0xff`가 됩니다.

What does the w1 subsystem do?
------------------------------

When a w1 master driver registers with the w1 subsystem, the following occurs:

 - sysfs entries for that w1 master are created
 - the w1 bus is periodically searched for new slave devices

When a device is found on the bus, w1 core tries to load the driver for its family
and check if it is loaded. If so, the family driver is attached to the slave.
If there is no driver for the family, default one is assigned, which allows to perform
almost any kind of operations. Each logical operation is a transaction
in nature, which can contain several (two or one) low-level operations.
Let's see how one can read EEPROM context:
1. one must write control buffer, i.e. buffer containing command byte
and two byte address. At this step bus is reset and appropriate device
is selected using either W1_SKIP_ROM or W1_MATCH_ROM command.
Then provided control buffer is being written to the wire.
2. reading. This will issue reading eeprom response.

It is possible that between 1. and 2. w1 master thread will reset bus for searching
and slave device will be even removed, but in this case 0xff will
be read, since no device was selected.

W1 family 드라이버

Slave는 W1 장치 family별 드라이버가 처리합니다. family 드라이버는 `w1_family.h`의 `struct w1_family_ops`를 채워 W1 서브시스템에 등록합니다.

`w1_therm`은 DS18x20 온도 센서 family 드라이버이며 온도 읽기 기능을 `w1_family_ops`의 `rbin()` 메서드에 연결합니다. `w1_smem`은 단순한 64비트 메모리 셀을 위한 드라이버로 ID 읽기 메서드를 제공합니다.

사용자 공간은 해당 sysfs 파일을 읽어 family 메서드를 호출합니다.

W1 device families
------------------

Slave devices are handled by a driver written for a family of w1 devices.

A family driver populates a struct w1_family_ops (see w1_family.h) and
registers with the w1 subsystem.

Current family drivers:

w1_therm
  - (ds18?20 thermal sensor family driver)
    provides temperature reading function which is bound to ->rbin() method
    of the above w1_family_ops structure.

w1_smem
  - driver for simple 64bit memory cell provides ID reading method.

You can call above methods by reading appropriate sysfs files.

master 드라이버의 최소 구현

W1 bus master 드라이버는 최소 두 함수를 제공해야 합니다. 에뮬레이션 장치는 출력 신호 레벨을 설정하는 `write_bit`와 신호 레벨을 샘플링하는 `read_bit`를 구현합니다.

1-Wire를 네이티브로 지원하는 장치는 비트를 쓰고 샘플링하는 `touch_bit`와 버스를 reset하는 `reset_bus`를 구현합니다.

대부분의 하드웨어는 W1 처리를 덜어 주는 상위 수준 함수도 제공합니다. 자세한 콜백은 `w1.h`의 `struct w1_bus_master` 정의를 참조합니다.

What does a w1 master driver need to implement?
-----------------------------------------------

The driver for w1 bus master must provide at minimum two functions.

Emulated devices must provide the ability to set the output signal level
(write_bit) and sample the signal level (read_bit).

Devices that support the 1-wire natively must provide the ability to write and
sample a bit (touch_bit) and reset the bus (reset_bus).

Most hardware provides higher-level functions that offload w1 handling.
See struct w1_bus_master definition in w1.h for details.

W1 master sysfs

발견한 slave는 `family-serial` 형식의 `<xx-xxxxxxxxxxxx>` 디렉터리로 나타납니다. 표준 `bus`와 `driver` 심볼릭 링크도 제공합니다.

`w1_master_add`와 `w1_master_remove`는 slave를 수동으로 등록·제거합니다. `w1_master_attempts`는 검색 시도 횟수, `w1_master_max_slave_count`는 한 번에 찾을 최대 slave 수, `w1_master_slave_count`는 발견한 수, `w1_master_slaves`는 이름 목록입니다.

`w1_master_search`는 남은 검색 횟수이며 `-1`은 계속 검색하는 기본값입니다. `w1_master_timeout`과 `w1_master_timeout_us`는 각각 초와 마이크로초 검색 간격이고 `w1_master_pullup`은 5V strong pull-up 상태를 다룹니다. 원문 표의 값 정의는 0이 활성화, 1이 비활성화입니다.

버스 구성이 고정되어 있으면 `search_count`를 작은 양수로 두어 초기 검색만 하거나 0으로 두고 `w1_master_add`에 slave serial을 직접 쓸 수 있습니다. 검색이 켜져 있으면 수동 제거 장치를 다시 찾고 실제로 없는 수동 추가 장치는 timeout되므로 add/remove는 보통 검색을 끈 상태에서만 의미가 있습니다.

검색 간격은 `timeout + timeout_us`이고 두 값 중 하나는 0이어도 됩니다. `w1_master_search`가 0보다 크거나 -1인 동안 검색하며 각 시도는 search를 1 줄이고 attempts를 1 늘립니다.

w1 master sysfs interface
-------------------------

========================= =====================================================
<xx-xxxxxxxxxxxx>         A directory for a found device. The format is
                          family-serial
bus                       (standard) symlink to the w1 bus
driver                    (standard) symlink to the w1 driver
w1_master_add             (rw) manually register a slave device
w1_master_attempts        (ro) the number of times a search was attempted
w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
w1_master_name            (ro) the name of the device (w1_bus_masterX)
w1_master_pullup          (rw) 5V strong pullup 0 enabled, 1 disabled
w1_master_remove          (rw) manually remove a slave device
w1_master_search          (rw) the number of searches left to do,
                          -1=continual (default)
w1_master_slave_count     (ro) the number of slaves found
w1_master_slaves          (ro) the names of the slaves, one per line
w1_master_timeout         (ro) the delay in seconds between searches
w1_master_timeout_us      (ro) the delay in microseconds between searches
========================= =====================================================

If you have a w1 bus that never changes (you don't add or remove devices),
you can set the module parameter search_count to a small positive number
for an initially small number of bus searches.  Alternatively it could be
set to zero, then manually add the slave device serial numbers by
w1_master_add device file.  The w1_master_add and w1_master_remove files
generally only make sense when searching is disabled, as a search will
redetect manually removed devices that are present and timeout manually
added devices that aren't on the bus.

Bus searches occur at an interval, specified as a sum of timeout and
timeout_us module parameters (either of which may be 0) for as long as
w1_master_search remains greater than 0 or is -1.  Each search attempt
decrements w1_master_search by 1 (down to 0) and increments
w1_master_attempts by 1.

W1 slave sysfs

Slave에는 표준 `bus`·`driver` 심볼릭 링크와 보통 디렉터리 이름과 같은 `name`이 있습니다.

선택적인 `w1_slave`는 family 드라이버가 의미를 정하는 바이너리 파일입니다. 적절한 family 드라이버가 없는 slave에는 선택적인 `rw` 파일을 만들어 바이너리 데이터를 읽고 쓸 수 있게 합니다.

w1 slave sysfs interface
------------------------

=================== ============================================================
bus                 (standard) symlink to the w1 bus
driver              (standard) symlink to the w1 driver
name                the device name, usually the same as the directory name
w1_slave            (optional) a binary file whose meaning depends on the
                    family driver
rw                    (optional) created for slave devices which do not have
                    appropriate family driver. Allows to read/write binary data.
=================== ============================================================