Commit | Line | Data |
---|---|---|
a076a860 LC |
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, | |
5cb23af3 | 74 | keeps clock stretched on bus A waiting for reply |
a076a860 LC |
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 |