|
| 1 | +.. SPDX-License-Identifier: GPL-2.0 |
| 2 | +
|
| 3 | +======================= |
| 4 | +I2C Address Translators |
| 5 | +======================= |
| 6 | + |
| 7 | +Author: Luca Ceresoli <luca@lucaceresoli.net> |
| 8 | +Author: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> |
| 9 | + |
| 10 | +Description |
| 11 | +----------- |
| 12 | + |
| 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 |
| 15 | +forwards transactions from upstream to the appropriate downstream port |
| 16 | +with a modified slave address. The address used on the parent bus is |
| 17 | +called the "alias" and is (potentially) different from the physical |
| 18 | +slave address of the child bus. Address translation is done by the |
| 19 | +hardware. |
| 20 | + |
| 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 |
| 24 | + parent bus implies it |
| 25 | + |
| 26 | +The ATR functionality can be provided by a chip with many other features. |
| 27 | +The kernel i2c-atr provides a helper to implement an ATR within a driver. |
| 28 | + |
| 29 | +The ATR creates a new I2C "child" adapter on each child bus. Adding |
| 30 | +devices on the child bus ends up in invoking the driver code to select |
| 31 | +an available alias. Maintaining an appropriate pool of available aliases |
| 32 | +and picking one for each new device is up to the driver implementer. The |
| 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. |
| 35 | + |
| 36 | +A typical example follows. |
| 37 | + |
| 38 | +Topology:: |
| 39 | + |
| 40 | + Slave X @ 0x10 |
| 41 | + .-----. | |
| 42 | + .-----. | |---+---- B |
| 43 | + | CPU |--A--| ATR | |
| 44 | + `-----' | |---+---- C |
| 45 | + `-----' | |
| 46 | + Slave Y @ 0x10 |
| 47 | + |
| 48 | +Alias table: |
| 49 | + |
| 50 | +A, B and C are three physical I2C busses, electrically independent from |
| 51 | +each other. The ATR receives the transactions initiated on bus A and |
| 52 | +propagates them on bus B or bus C or none depending on the device address |
| 53 | +in the transaction and based on the alias table. |
| 54 | + |
| 55 | +Alias table: |
| 56 | + |
| 57 | +.. table:: |
| 58 | + |
| 59 | + =============== ===== |
| 60 | + Client Alias |
| 61 | + =============== ===== |
| 62 | + X (bus B, 0x10) 0x20 |
| 63 | + Y (bus C, 0x10) 0x30 |
| 64 | + =============== ===== |
| 65 | + |
| 66 | +Transaction: |
| 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 | + |
| 83 | +Usage: |
| 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 | + |
| 93 | +I2C ATR functions and data structures |
| 94 | +------------------------------------- |
| 95 | + |
| 96 | +.. kernel-doc:: include/linux/i2c-atr.h |
0 commit comments