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