1.. SPDX-License-Identifier: GPL-2.0 2 3======================= 4I2C Address Translators 5======================= 6 7Author: Luca Ceresoli <luca@lucaceresoli.net> 8Author: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> 9 10Description 11----------- 12 13An I2C Address Translator (ATR) is a device with an I2C slave parent 14("upstream") port and N I2C master child ("downstream") ports, and 15forwards transactions from upstream to the appropriate downstream port 16with a modified slave address. The address used on the parent bus is 17called the "alias" and is (potentially) different from the physical 18slave address of the child bus. Address translation is done by the 19hardware. 20 21An 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 24 parent bus implies it 25 26The ATR functionality can be provided by a chip with many other features. 27The kernel i2c-atr provides a helper to implement an ATR within a driver. 28 29The ATR creates a new I2C "child" adapter on each child bus. Adding 30devices on the child bus ends up in invoking the driver code to select 31an available alias. Maintaining an appropriate pool of available aliases 32and picking one for each new device is up to the driver implementer. The 33ATR maintains a table of currently assigned alias and uses it to modify 34all I2C transactions directed to devices on the child buses. 35 36A typical example follows. 37 38Topology:: 39 40 Slave X @ 0x10 41 .-----. | 42 .-----. | |---+---- B 43 | CPU |--A--| ATR | 44 `-----' | |---+---- C 45 `-----' | 46 Slave Y @ 0x10 47 48Alias table: 49 50A, B and C are three physical I2C busses, electrically independent from 51each other. The ATR receives the transactions initiated on bus A and 52propagates them on bus B or bus C or none depending on the device address 53in the transaction and based on the alias table. 54 55Alias table: 56 57.. table:: 58 59 =============== ===== 60 Client Alias 61 =============== ===== 62 X (bus B, 0x10) 0x20 63 Y (bus C, 0x10) 0x30 64 =============== ===== 65 66Transaction: 67 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 70 messages with address 0x20, forwards to adapter A 71 - Physical I2C transaction on bus A, slave address 0x20 72 - ATR chip detects transaction on address 0x20, finds it in table, 73 propagates transaction on bus B with address translated to 0x10, 74 keeps clock streched on bus A waiting for reply 75 - Slave X chip (on bus B) detects transaction at its own physical 76 address 0x10 and replies normally 77 - ATR chip stops clock stretching and forwards reply on bus A, 78 with address translated back to 0x20 79 - ATR driver receives the reply, rewrites messages with address 0x10 80 as they were initially 81 - Slave X driver gets back the msgs[], with reply and address 0x10 82 83Usage: 84 85 1. In the driver (typically in the probe function) add an ATR by 86 calling i2c_atr_new() passing attach/detach callbacks 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 89 alias_id parameter 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 92 93I2C ATR functions and data structures 94------------------------------------- 95 96.. kernel-doc:: include/linux/i2c-atr.h 97