I2C Address Translators

I2C 주소 변환기 개요

이 문서는 GPL-2.0 라이선스로 제공되며 Luca Ceresoli와 Tomi Valkeinen이 작성했습니다.

I2C Address Translator(ATR)는 I2C 슬레이브 역할을 하는 하나의 부모 포트, 즉 업스트림 포트와 I2C 마스터 역할을 하는 N개의 자식 포트, 즉 다운스트림 포트를 가진 장치입니다. 업스트림에서 받은 트랜잭션의 슬레이브 주소를 바꾸어 적절한 다운스트림 포트로 전달합니다.

부모 버스에서 사용하는 주소를 별칭(alias)이라고 하며, 자식 버스 장치의 실제 슬레이브 주소와 다를 수 있습니다. 주소 변환은 하드웨어가 수행합니다.

ATR은 `i2c-mux`와 비슷해 보이지만 부모 버스와 자식 버스의 주소가 서로 다를 수 있고, 부모 버스에서 사용한 별칭 자체가 자식 포트를 암시하므로 보통 포트를 별도로 선택할 필요가 없습니다.

ATR 기능은 여러 다른 기능을 함께 가진 칩이 제공할 수도 있습니다. 커널의 `i2c-atr`은 드라이버 안에 ATR을 구현하기 위한 도우미를 제공합니다.

ATR은 자식 버스마다 새로운 I2C 자식 어댑터를 만듭니다. 자식 버스에 장치를 추가하면 드라이버 코드가 호출되어 사용 가능한 별칭을 선택합니다. 사용 가능한 별칭 풀을 관리하고 새 장치마다 별칭을 고르는 책임은 드라이버 구현자에게 있습니다.

ATR은 현재 할당된 별칭 표를 유지하며, 자식 버스의 장치로 향하는 모든 I2C 트랜잭션의 주소를 이 표에 따라 수정합니다.

.. SPDX-License-Identifier: GPL-2.0

=======================
I2C Address Translators
=======================

Author: Luca Ceresoli <luca@lucaceresoli.net>
Author: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>

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

An I2C Address Translator (ATR) is a device with an I2C slave parent
("upstream") port and N I2C master child ("downstream") ports, and
forwards transactions from upstream to the appropriate downstream port
with a modified slave address. The address used on the parent bus is
called the "alias" and is (potentially) different from the physical
slave address of the child bus. Address translation is done by the
hardware.

An ATR looks similar to an i2c-mux except:
 - the address on the parent and child busses can be different
 - there is normally no need to select the child port; the alias used on the
   parent bus implies it

The ATR functionality can be provided by a chip with many other features.
The kernel i2c-atr provides a helper to implement an ATR within a driver.

The ATR creates a new I2C "child" adapter on each child bus. Adding
devices on the child bus ends up in invoking the driver code to select
an available alias. Maintaining an appropriate pool of available aliases
and picking one for each new device is up to the driver implementer. The
ATR maintains a table of currently assigned alias and uses it to modify
all I2C transactions directed to devices on the child buses.

토폴로지와 별칭 표

전형적인 구성에는 CPU가 연결된 물리 버스 A와 ATR 뒤의 서로 독립적인 물리 버스 B, C가 있습니다. 버스 B의 Slave X와 버스 C의 Slave Y는 모두 실제 주소 `0x10`을 사용하지만 전기적으로 분리되어 있으므로 충돌하지 않습니다.

ATR은 버스 A에서 시작된 트랜잭션을 받고 주소와 별칭 표에 따라 버스 B, 버스 C 또는 어느 쪽에도 전달하지 않습니다. X에는 별칭 `0x20`, Y에는 별칭 `0x30`이 배정되어 있으므로 업스트림 주소만으로 목적 포트와 실제 주소를 결정할 수 있습니다.

A typical example follows.

Topology::

                      Slave X @ 0x10
              .-----.   |
  .-----.     |     |---+---- B
  | CPU |--A--| ATR |
  `-----'     |     |---+---- C
              `-----'   |
                      Slave Y @ 0x10

Alias table:

A, B and C are three physical I2C busses, electrically independent from
each other. The ATR receives the transactions initiated on bus A and
propagates them on bus B or bus C or none depending on the device address
in the transaction and based on the alias table.

Alias table:

.. table::

   ===============   =====
   Client            Alias
   ===============   =====
   X (bus B, 0x10)   0x20
   Y (bus C, 0x10)   0x30
   ===============   =====

주소 변환 트랜잭션과 사용법

Slave X 드라이버가 어댑터 B에서 실제 슬레이브 주소 `0x10`으로 트랜잭션을 요청합니다. ATR 드라이버는 X가 버스 B에 있고 별칭이 `0x20`임을 찾아 메시지 주소를 `0x20`으로 다시 쓴 뒤 어댑터 A에 전달합니다.

버스 A에서는 슬레이브 주소 `0x20`으로 물리 I2C 트랜잭션이 수행됩니다. ATR 칩은 `0x20` 트랜잭션을 감지해 별칭 표에서 찾고, 주소를 `0x10`으로 바꾸어 버스 B에 전달합니다. 이때 응답을 기다리는 동안 버스 A의 클록을 스트레칭합니다.

버스 B의 Slave X 칩은 자신의 실제 주소 `0x10`에 대한 트랜잭션을 감지하고 정상 응답합니다. ATR 칩은 클록 스트레칭을 멈추고 응답 주소를 다시 `0x20`으로 바꾸어 버스 A로 전달합니다.

ATR 드라이버는 응답을 받은 뒤 메시지 주소를 처음과 같은 `0x10`으로 복원합니다. Slave X 드라이버는 응답과 실제 주소 `0x10`이 담긴 원래 형태의 `msgs[]`를 돌려받습니다.

드라이버에서는 보통 probe 함수에서 attach·detach 콜백을 넘겨 `i2c_atr_new()`를 호출해 ATR을 추가합니다. attach 콜백이 호출되면 적절한 별칭을 선택해 칩에 설정하고 선택한 값을 `alias_id` 매개변수로 반환합니다.

detach 콜백이 호출되면 칩에서 해당 별칭 설정을 제거하고, 나중에 다시 쓸 수 있도록 별칭 풀에 반환합니다.

Transaction:

 - Slave X driver requests a transaction (on adapter B), slave address 0x10
 - ATR driver finds slave X is on bus B and has alias 0x20, rewrites
   messages with address 0x20, forwards to adapter A
 - Physical I2C transaction on bus A, slave address 0x20
 - ATR chip detects transaction on address 0x20, finds it in table,
   propagates transaction on bus B with address translated to 0x10,
   keeps clock stretched on bus A waiting for reply
 - Slave X chip (on bus B) detects transaction at its own physical
   address 0x10 and replies normally
 - ATR chip stops clock stretching and forwards reply on bus A,
   with address translated back to 0x20
 - ATR driver receives the reply, rewrites messages with address 0x10
   as they were initially
 - Slave X driver gets back the msgs[], with reply and address 0x10

Usage:

 1. In the driver (typically in the probe function) add an ATR by
    calling i2c_atr_new() passing attach/detach callbacks
 2. When the attach callback is called pick an appropriate alias,
    configure it in the chip and return the chosen alias in the
    alias_id parameter
 3. When the detach callback is called, deconfigure the alias from
    the chip and put the alias back in the pool for later usage

I2C ATR 함수와 자료 구조

I2C ATR의 함수와 자료 구조에 대한 API 설명은 `include/linux/i2c-atr.h`의 kernel-doc에서 생성됩니다. 구현자는 이 헤더의 선언과 콜백 계약을 기준으로 드라이버를 작성해야 합니다.

I2C ATR functions and data structures
-------------------------------------

.. kernel-doc:: include/linux/i2c-atr.h