tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1I2C topology
2============
3
4There are a couple of reasons for building more complex i2c topologies
5than a straight-forward i2c bus with one adapter and one or more devices.
6
71. A mux may be needed on the bus to prevent address collisions.
8
92. The bus may be accessible from some external bus master, and arbitration
10 may be needed to determine if it is ok to access the bus.
11
123. A device (particularly RF tuners) may want to avoid the digital noise
13 from the i2c bus, at least most of the time, and sits behind a gate
14 that has to be operated before the device can be accessed.
15
16Etc
17
18These constructs are represented as i2c adapter trees by Linux, where
19each adapter has a parent adapter (except the root adapter) and zero or
20more child adapters. The root adapter is the actual adapter that issues
21i2c transfers, and all adapters with a parent are part of an "i2c-mux"
22object (quoted, since it can also be an arbitrator or a gate).
23
24Depending of the particular mux driver, something happens when there is
25an i2c transfer on one of its child adapters. The mux driver can
26obviously operate a mux, but it can also do arbitration with an external
27bus master or open a gate. The mux driver has two operations for this,
28select and deselect. select is called before the transfer and (the
29optional) deselect is called after the transfer.
30
31
32Locking
33=======
34
35There are two variants of locking available to i2c muxes, they can be
36mux-locked or parent-locked muxes. As is evident from below, it can be
37useful to know if a mux is mux-locked or if it is parent-locked. The
38following list was correct at the time of writing:
39
40In drivers/i2c/muxes/
41i2c-arb-gpio-challenge Parent-locked
42i2c-mux-gpio Normally parent-locked, mux-locked iff
43 all involved gpio pins are controlled by the
44 same i2c root adapter that they mux.
45i2c-mux-pca9541 Parent-locked
46i2c-mux-pca954x Parent-locked
47i2c-mux-pinctrl Normally parent-locked, mux-locked iff
48 all involved pinctrl devices are controlled
49 by the same i2c root adapter that they mux.
50i2c-mux-reg Parent-locked
51
52In drivers/iio/
53imu/inv_mpu6050/ Mux-locked
54
55In drivers/media/
56dvb-frontends/m88ds3103 Parent-locked
57dvb-frontends/rtl2830 Parent-locked
58dvb-frontends/rtl2832 Mux-locked
59dvb-frontends/si2168 Mux-locked
60usb/cx231xx/ Parent-locked
61
62
63Mux-locked muxes
64----------------
65
66Mux-locked muxes does not lock the entire parent adapter during the
67full select-transfer-deselect transaction, only the muxes on the parent
68adapter are locked. Mux-locked muxes are mostly interesting if the
69select and/or deselect operations must use i2c transfers to complete
70their tasks. Since the parent adapter is not fully locked during the
71full transaction, unrelated i2c transfers may interleave the different
72stages of the transaction. This has the benefit that the mux driver
73may be easier and cleaner to implement, but it has some caveats.
74
75ML1. If you build a topology with a mux-locked mux being the parent
76 of a parent-locked mux, this might break the expectation from the
77 parent-locked mux that the root adapter is locked during the
78 transaction.
79
80ML2. It is not safe to build arbitrary topologies with two (or more)
81 mux-locked muxes that are not siblings, when there are address
82 collisions between the devices on the child adapters of these
83 non-sibling muxes.
84
85 I.e. the select-transfer-deselect transaction targeting e.g. device
86 address 0x42 behind mux-one may be interleaved with a similar
87 operation targeting device address 0x42 behind mux-two. The
88 intension with such a topology would in this hypothetical example
89 be that mux-one and mux-two should not be selected simultaneously,
90 but mux-locked muxes do not guarantee that in all topologies.
91
92ML3. A mux-locked mux cannot be used by a driver for auto-closing
93 gates/muxes, i.e. something that closes automatically after a given
94 number (one, in most cases) of i2c transfers. Unrelated i2c transfers
95 may creep in and close prematurely.
96
97ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
98 the driver has to lock the root adapter during that operation.
99 Otherwise garbage may appear on the bus as seen from devices
100 behind the mux, when an unrelated i2c transfer is in flight during
101 the non-i2c mux-changing operation.
102
103
104Mux-locked Example
105------------------
106
107 .----------. .--------.
108 .--------. | mux- |-----| dev D1 |
109 | root |--+--| locked | '--------'
110 '--------' | | mux M1 |--. .--------.
111 | '----------' '--| dev D2 |
112 | .--------. '--------'
113 '--| dev D3 |
114 '--------'
115
116When there is an access to D1, this happens:
117
118 1. Someone issues an i2c-transfer to D1.
119 2. M1 locks muxes on its parent (the root adapter in this case).
120 3. M1 calls ->select to ready the mux.
121 4. M1 (presumably) does some i2c-transfers as part of its select.
122 These transfers are normal i2c-transfers that locks the parent
123 adapter.
124 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a
125 normal i2c-transfer that locks the parent adapter.
126 6. M1 calls ->deselect, if it has one.
127 7. Same rules as in step 4, but for ->deselect.
128 8. M1 unlocks muxes on its parent.
129
130This means that accesses to D2 are lockout out for the full duration
131of the entire operation. But accesses to D3 are possibly interleaved
132at any point.
133
134
135Parent-locked muxes
136-------------------
137
138Parent-locked muxes lock the parent adapter during the full select-
139transfer-deselect transaction. The implication is that the mux driver
140has to ensure that any and all i2c transfers through that parent
141adapter during the transaction are unlocked i2c transfers (using e.g.
142__i2c_transfer), or a deadlock will follow. There are a couple of
143caveats.
144
145PL1. If you build a topology with a parent-locked mux being the child
146 of another mux, this might break a possible assumption from the
147 child mux that the root adapter is unused between its select op
148 and the actual transfer (e.g. if the child mux is auto-closing
149 and the parent mux issus i2c-transfers as part of its select).
150 This is especially the case if the parent mux is mux-locked, but
151 it may also happen if the parent mux is parent-locked.
152
153PL2. If select/deselect calls out to other subsystems such as gpio,
154 pinctrl, regmap or iio, it is essential that any i2c transfers
155 caused by these subsystems are unlocked. This can be convoluted to
156 accomplish, maybe even impossible if an acceptably clean solution
157 is sought.
158
159
160Parent-locked Example
161---------------------
162
163 .----------. .--------.
164 .--------. | parent- |-----| dev D1 |
165 | root |--+--| locked | '--------'
166 '--------' | | mux M1 |--. .--------.
167 | '----------' '--| dev D2 |
168 | .--------. '--------'
169 '--| dev D3 |
170 '--------'
171
172When there is an access to D1, this happens:
173
174 1. Someone issues an i2c-transfer to D1.
175 2. M1 locks muxes on its parent (the root adapter in this case).
176 3. M1 locks its parent adapter.
177 4. M1 calls ->select to ready the mux.
178 5. If M1 does any i2c-transfers (on this root adapter) as part of
179 its select, those transfers must be unlocked i2c-transfers so
180 that they do not deadlock the root adapter.
181 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an
182 unlocked i2c-transfer, so that it does not deadlock the parent
183 adapter.
184 7. M1 calls ->deselect, if it has one.
185 8. Same rules as in step 5, but for ->deselect.
186 9. M1 unlocks its parent adapter.
18710. M1 unlocks muxes on its parent.
188
189
190This means that accesses to both D2 and D3 are locked out for the full
191duration of the entire operation.
192
193
194Complex Examples
195================
196
197Parent-locked mux as parent of parent-locked mux
198------------------------------------------------
199
200This is a useful topology, but it can be bad.
201
202 .----------. .----------. .--------.
203 .--------. | parent- |-----| parent- |-----| dev D1 |
204 | root |--+--| locked | | locked | '--------'
205 '--------' | | mux M1 |--. | mux M2 |--. .--------.
206 | '----------' | '----------' '--| dev D2 |
207 | .--------. | .--------. '--------'
208 '--| dev D4 | '--| dev D3 |
209 '--------' '--------'
210
211When any device is accessed, all other devices are locked out for
212the full duration of the operation (both muxes lock their parent,
213and specifically when M2 requests its parent to lock, M1 passes
214the buck to the root adapter).
215
216This topology is bad if M2 is an auto-closing mux and M1->select
217issues any unlocked i2c transfers on the root adapter that may leak
218through and be seen by the M2 adapter, thus closing M2 prematurely.
219
220
221Mux-locked mux as parent of mux-locked mux
222------------------------------------------
223
224This is a good topology.
225
226 .----------. .----------. .--------.
227 .--------. | mux- |-----| mux- |-----| dev D1 |
228 | root |--+--| locked | | locked | '--------'
229 '--------' | | mux M1 |--. | mux M2 |--. .--------.
230 | '----------' | '----------' '--| dev D2 |
231 | .--------. | .--------. '--------'
232 '--| dev D4 | '--| dev D3 |
233 '--------' '--------'
234
235When device D1 is accessed, accesses to D2 are locked out for the
236full duration of the operation (muxes on the top child adapter of M1
237are locked). But accesses to D3 and D4 are possibly interleaved at
238any point. Accesses to D3 locks out D1 and D2, but accesses to D4
239are still possibly interleaved.
240
241
242Mux-locked mux as parent of parent-locked mux
243---------------------------------------------
244
245This is probably a bad topology.
246
247 .----------. .----------. .--------.
248 .--------. | mux- |-----| parent- |-----| dev D1 |
249 | root |--+--| locked | | locked | '--------'
250 '--------' | | mux M1 |--. | mux M2 |--. .--------.
251 | '----------' | '----------' '--| dev D2 |
252 | .--------. | .--------. '--------'
253 '--| dev D4 | '--| dev D3 |
254 '--------' '--------'
255
256When device D1 is accessed, accesses to D2 and D3 are locked out
257for the full duration of the operation (M1 locks child muxes on the
258root adapter). But accesses to D4 are possibly interleaved at any
259point.
260
261This kind of topology is generally not suitable and should probably
262be avoided. The reason is that M2 probably assumes that there will
263be no i2c transfers during its calls to ->select and ->deselect, and
264if there are, any such transfers might appear on the slave side of M2
265as partial i2c transfers, i.e. garbage or worse. This might cause
266device lockups and/or other problems.
267
268The topology is especially troublesome if M2 is an auto-closing
269mux. In that case, any interleaved accesses to D4 might close M2
270prematurely, as might any i2c-transfers part of M1->select.
271
272But if M2 is not making the above stated assumption, and if M2 is not
273auto-closing, the topology is fine.
274
275
276Parent-locked mux as parent of mux-locked mux
277---------------------------------------------
278
279This is a good topology.
280
281 .----------. .----------. .--------.
282 .--------. | parent- |-----| mux- |-----| dev D1 |
283 | root |--+--| locked | | locked | '--------'
284 '--------' | | mux M1 |--. | mux M2 |--. .--------.
285 | '----------' | '----------' '--| dev D2 |
286 | .--------. | .--------. '--------'
287 '--| dev D4 | '--| dev D3 |
288 '--------' '--------'
289
290When D1 is accessed, accesses to D2 are locked out for the full
291duration of the operation (muxes on the top child adapter of M1
292are locked). Accesses to D3 and D4 are possibly interleaved at
293any point, just as is expected for mux-locked muxes.
294
295When D3 or D4 are accessed, everything else is locked out. For D3
296accesses, M1 locks the root adapter. For D4 accesses, the root
297adapter is locked directly.
298
299
300Two mux-locked sibling muxes
301----------------------------
302
303This is a good topology.
304
305 .--------.
306 .----------. .--| dev D1 |
307 | mux- |--' '--------'
308 .--| locked | .--------.
309 | | mux M1 |-----| dev D2 |
310 | '----------' '--------'
311 | .----------. .--------.
312 .--------. | | mux- |-----| dev D3 |
313 | root |--+--| locked | '--------'
314 '--------' | | mux M2 |--. .--------.
315 | '----------' '--| dev D4 |
316 | .--------. '--------'
317 '--| dev D5 |
318 '--------'
319
320When D1 is accessed, accesses to D2, D3 and D4 are locked out. But
321accesses to D5 may be interleaved at any time.
322
323
324Two parent-locked sibling muxes
325-------------------------------
326
327This is a good topology.
328
329 .--------.
330 .----------. .--| dev D1 |
331 | parent- |--' '--------'
332 .--| locked | .--------.
333 | | mux M1 |-----| dev D2 |
334 | '----------' '--------'
335 | .----------. .--------.
336 .--------. | | parent- |-----| dev D3 |
337 | root |--+--| locked | '--------'
338 '--------' | | mux M2 |--. .--------.
339 | '----------' '--| dev D4 |
340 | .--------. '--------'
341 '--| dev D5 |
342 '--------'
343
344When any device is accessed, accesses to all other devices are locked
345out.
346
347
348Mux-locked and parent-locked sibling muxes
349------------------------------------------
350
351This is a good topology.
352
353 .--------.
354 .----------. .--| dev D1 |
355 | mux- |--' '--------'
356 .--| locked | .--------.
357 | | mux M1 |-----| dev D2 |
358 | '----------' '--------'
359 | .----------. .--------.
360 .--------. | | parent- |-----| dev D3 |
361 | root |--+--| locked | '--------'
362 '--------' | | mux M2 |--. .--------.
363 | '----------' '--| dev D4 |
364 | .--------. '--------'
365 '--| dev D5 |
366 '--------'
367
368When D1 or D2 are accessed, accesses to D3 and D4 are locked out while
369accesses to D5 may interleave. When D3 or D4 are accessed, accesses to
370all other devices are locked out.