1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ======================= 3 =======================
4 I2C Address Translators 4 I2C Address Translators
5 ======================= 5 =======================
6 6
7 Author: Luca Ceresoli <luca@lucaceresoli.net> 7 Author: Luca Ceresoli <luca@lucaceresoli.net>
8 Author: Tomi Valkeinen <tomi.valkeinen@ideasonb 8 Author: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
9 9
10 Description 10 Description
11 ----------- 11 -----------
12 12
13 An I2C Address Translator (ATR) is a device wi 13 An I2C Address Translator (ATR) is a device with an I2C slave parent
14 ("upstream") port and N I2C master child ("dow 14 ("upstream") port and N I2C master child ("downstream") ports, and
15 forwards transactions from upstream to the app 15 forwards transactions from upstream to the appropriate downstream port
16 with a modified slave address. The address use 16 with a modified slave address. The address used on the parent bus is
17 called the "alias" and is (potentially) differ 17 called the "alias" and is (potentially) different from the physical
18 slave address of the child bus. Address transl 18 slave address of the child bus. Address translation is done by the
19 hardware. 19 hardware.
20 20
21 An ATR looks similar to an i2c-mux except: 21 An ATR looks similar to an i2c-mux except:
22 - the address on the parent and child busses 22 - the address on the parent and child busses can be different
23 - there is normally no need to select the chi 23 - there is normally no need to select the child port; the alias used on the
24 parent bus implies it 24 parent bus implies it
25 25
26 The ATR functionality can be provided by a chi 26 The ATR functionality can be provided by a chip with many other features.
27 The kernel i2c-atr provides a helper to implem 27 The kernel i2c-atr provides a helper to implement an ATR within a driver.
28 28
29 The ATR creates a new I2C "child" adapter on e 29 The ATR creates a new I2C "child" adapter on each child bus. Adding
30 devices on the child bus ends up in invoking t 30 devices on the child bus ends up in invoking the driver code to select
31 an available alias. Maintaining an appropriate 31 an available alias. Maintaining an appropriate pool of available aliases
32 and picking one for each new device is up to t 32 and picking one for each new device is up to the driver implementer. The
33 ATR maintains a table of currently assigned al 33 ATR maintains a table of currently assigned alias and uses it to modify
34 all I2C transactions directed to devices on th 34 all I2C transactions directed to devices on the child buses.
35 35
36 A typical example follows. 36 A typical example follows.
37 37
38 Topology:: 38 Topology::
39 39
40 Slave X @ 0x10 40 Slave X @ 0x10
41 .-----. | 41 .-----. |
42 .-----. | |---+---- B 42 .-----. | |---+---- B
43 | CPU |--A--| ATR | 43 | CPU |--A--| ATR |
44 `-----' | |---+---- C 44 `-----' | |---+---- C
45 `-----' | 45 `-----' |
46 Slave Y @ 0x10 46 Slave Y @ 0x10
47 47
48 Alias table: 48 Alias table:
49 49
50 A, B and C are three physical I2C busses, elec 50 A, B and C are three physical I2C busses, electrically independent from
51 each other. The ATR receives the transactions 51 each other. The ATR receives the transactions initiated on bus A and
52 propagates them on bus B or bus C or none depe 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 tabl 53 in the transaction and based on the alias table.
54 54
55 Alias table: 55 Alias table:
56 56
57 .. table:: 57 .. table::
58 58
59 =============== ===== 59 =============== =====
60 Client Alias 60 Client Alias
61 =============== ===== 61 =============== =====
62 X (bus B, 0x10) 0x20 62 X (bus B, 0x10) 0x20
63 Y (bus C, 0x10) 0x30 63 Y (bus C, 0x10) 0x30
64 =============== ===== 64 =============== =====
65 65
66 Transaction: 66 Transaction:
67 67
68 - Slave X driver requests a transaction (on a 68 - Slave X driver requests a transaction (on adapter B), slave address 0x10
69 - ATR driver finds slave X is on bus B and ha 69 - ATR driver finds slave X is on bus B and has alias 0x20, rewrites
70 messages with address 0x20, forwards to ada 70 messages with address 0x20, forwards to adapter A
71 - Physical I2C transaction on bus A, slave ad 71 - Physical I2C transaction on bus A, slave address 0x20
72 - ATR chip detects transaction on address 0x2 72 - ATR chip detects transaction on address 0x20, finds it in table,
73 propagates transaction on bus B with addres 73 propagates transaction on bus B with address translated to 0x10,
74 keeps clock stretched on bus A waiting for 74 keeps clock stretched on bus A waiting for reply
75 - Slave X chip (on bus B) detects transaction 75 - Slave X chip (on bus B) detects transaction at its own physical
76 address 0x10 and replies normally 76 address 0x10 and replies normally
77 - ATR chip stops clock stretching and forward 77 - ATR chip stops clock stretching and forwards reply on bus A,
78 with address translated back to 0x20 78 with address translated back to 0x20
79 - ATR driver receives the reply, rewrites mes 79 - ATR driver receives the reply, rewrites messages with address 0x10
80 as they were initially 80 as they were initially
81 - Slave X driver gets back the msgs[], with r 81 - Slave X driver gets back the msgs[], with reply and address 0x10
82 82
83 Usage: 83 Usage:
84 84
85 1. In the driver (typically in the probe func 85 1. In the driver (typically in the probe function) add an ATR by
86 calling i2c_atr_new() passing attach/detac 86 calling i2c_atr_new() passing attach/detach callbacks
87 2. When the attach callback is called pick an 87 2. When the attach callback is called pick an appropriate alias,
88 configure it in the chip and return the ch 88 configure it in the chip and return the chosen alias in the
89 alias_id parameter 89 alias_id parameter
90 3. When the detach callback is called, deconf 90 3. When the detach callback is called, deconfigure the alias from
91 the chip and put the alias back in the poo 91 the chip and put the alias back in the pool for later usage
92 92
93 I2C ATR functions and data structures 93 I2C ATR functions and data structures
94 ------------------------------------- 94 -------------------------------------
95 95
96 .. kernel-doc:: include/linux/i2c-atr.h 96 .. kernel-doc:: include/linux/i2c-atr.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.