Documentation/i2c/i2c-address-translators.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 I2C Address Translators
11 -----------
13 An I2C Address Translator (ATR) is a device with an I2C slave parent
14 ("upstream") port and N I2C master child ("downstream") ports, and
17 called the "alias" and is (potentially) different from the physical
21 An ATR looks similar to an i2c-mux except:
22  - the address on the parent and child busses can be different
23  - there is normally no need to select the child port; the alias used on the
27 The kernel i2c-atr provides a helper to implement an ATR within a driver.
29 The ATR creates a new I2C "child" adapter on each child bus. Adding
31 an available alias. Maintaining an appropriate pool of available aliases
33 ATR maintains a table of currently assigned alias and uses it to modify
34 all I2C transactions directed to devices on the child buses.
41               .-----.   |
42   .-----.     |     |---+---- B
43   | CPU |--A--| ATR |
44   `-----'     |     |---+---- C
45               `-----'   |
48 Alias table:
50 A, B and C are three physical I2C busses, electrically independent from
53 in the transaction and based on the alias table.
55 Alias table:
60    Client            Alias
68  - Slave X driver requests a transaction (on adapter B), slave address 0x10
69  - ATR driver finds slave X is on bus B and has alias 0x20, rewrites
71  - Physical I2C transaction on bus A, slave address 0x20
72  - ATR chip detects transaction on address 0x20, finds it in table,
75  - Slave X chip (on bus B) detects transaction at its own physical
77  - ATR chip stops clock stretching and forwards reply on bus A,
79  - ATR driver receives the reply, rewrites messages with address 0x10
81  - Slave X driver gets back the msgs[], with reply and address 0x10
87  2. When the attach callback is called pick an appropriate alias,
88     configure it in the chip and return the chosen alias in the
90  3. When the detach callback is called, deconfigure the alias from
91     the chip and put the alias back in the pool for later usage
93 I2C ATR functions and data structures
94 -------------------------------------
96 .. kernel-doc:: include/linux/i2c-atr.h