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@ideasonb
9
10 Description
11 -----------
12
13 An I2C Address Translator (ATR) is a device wi
14 ("upstream") port and N I2C master child ("dow
15 forwards transactions from upstream to the app
16 with a modified slave address. The address use
17 called the "alias" and is (potentially) differ
18 slave address of the child bus. Address transl
19 hardware.
20
21 An ATR looks similar to an i2c-mux except:
22 - the address on the parent and child busses
23 - there is normally no need to select the chi
24 parent bus implies it
25
26 The ATR functionality can be provided by a chi
27 The kernel i2c-atr provides a helper to implem
28
29 The ATR creates a new I2C "child" adapter on e
30 devices on the child bus ends up in invoking t
31 an available alias. Maintaining an appropriate
32 and picking one for each new device is up to t
33 ATR maintains a table of currently assigned al
34 all I2C transactions directed to devices on th
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, elec
51 each other. The ATR receives the transactions
52 propagates them on bus B or bus C or none depe
53 in the transaction and based on the alias tabl
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 a
69 - ATR driver finds slave X is on bus B and ha
70 messages with address 0x20, forwards to ada
71 - Physical I2C transaction on bus A, slave ad
72 - ATR chip detects transaction on address 0x2
73 propagates transaction on bus B with addres
74 keeps clock stretched on bus A waiting for
75 - Slave X chip (on bus B) detects transaction
76 address 0x10 and replies normally
77 - ATR chip stops clock stretching and forward
78 with address translated back to 0x20
79 - ATR driver receives the reply, rewrites mes
80 as they were initially
81 - Slave X driver gets back the msgs[], with r
82
83 Usage:
84
85 1. In the driver (typically in the probe func
86 calling i2c_atr_new() passing attach/detac
87 2. When the attach callback is called pick an
88 configure it in the chip and return the ch
89 alias_id parameter
90 3. When the detach callback is called, deconf
91 the chip and put the alias back in the poo
92
93 I2C ATR functions and data structures
94 -------------------------------------
95
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.