tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
i2c: mux: document i2c muxes and elaborate on parent-/mux-locked muxes
Signed-off-by: Peter Rosin <peda@axentia.se>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>
authored by
Peter Rosin
and committed by
Wolfram Sang
2254d24a
6ef91fcc
+371
+370
Documentation/i2c/i2c-topology
+370
Documentation/i2c/i2c-topology
···
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.
45
+
i2c-mux-pca9541 Parent-locked
46
+
i2c-mux-pca954x Parent-locked
47
+
i2c-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.
50
+
i2c-mux-reg Parent-locked
51
+
52
+
In drivers/iio/
53
+
imu/inv_mpu6050/ Parent-locked
54
+
55
+
In drivers/media/
56
+
dvb-frontends/m88ds3103 Parent-locked
57
+
dvb-frontends/rtl2830 Parent-locked
58
+
dvb-frontends/rtl2832 Parent-locked
59
+
dvb-frontends/si2168 Parent-locked
60
+
usb/cx231xx/ Parent-locked
61
+
62
+
63
+
Mux-locked muxes
64
+
----------------
65
+
66
+
Mux-locked muxes does not lock the entire parent adapter during the
67
+
full select-transfer-deselect transaction, only the muxes on the parent
68
+
adapter are locked. Mux-locked muxes are mostly interesting if the
69
+
select and/or deselect operations must use i2c transfers to complete
70
+
their tasks. Since the parent adapter is not fully locked during the
71
+
full transaction, unrelated i2c transfers may interleave the different
72
+
stages of the transaction. This has the benefit that the mux driver
73
+
may be easier and cleaner to implement, but it has some caveats.
74
+
75
+
ML1. 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
+
80
+
ML2. 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
+
92
+
ML3. 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
+
97
+
ML4. 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
+
104
+
Mux-locked Example
105
+
------------------
106
+
107
+
.----------. .--------.
108
+
.--------. | mux- |-----| dev D1 |
109
+
| root |--+--| locked | '--------'
110
+
'--------' | | mux M1 |--. .--------.
111
+
| '----------' '--| dev D2 |
112
+
| .--------. '--------'
113
+
'--| dev D3 |
114
+
'--------'
115
+
116
+
When 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
+
130
+
This means that accesses to D2 are lockout out for the full duration
131
+
of the entire operation. But accesses to D3 are possibly interleaved
132
+
at any point.
133
+
134
+
135
+
Parent-locked muxes
136
+
-------------------
137
+
138
+
Parent-locked muxes lock the parent adapter during the full select-
139
+
transfer-deselect transaction. The implication is that the mux driver
140
+
has to ensure that any and all i2c transfers through that parent
141
+
adapter during the transaction are unlocked i2c transfers (using e.g.
142
+
__i2c_transfer), or a deadlock will follow. There are a couple of
143
+
caveats.
144
+
145
+
PL1. 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
+
153
+
PL2. 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
+
160
+
Parent-locked Example
161
+
---------------------
162
+
163
+
.----------. .--------.
164
+
.--------. | parent- |-----| dev D1 |
165
+
| root |--+--| locked | '--------'
166
+
'--------' | | mux M1 |--. .--------.
167
+
| '----------' '--| dev D2 |
168
+
| .--------. '--------'
169
+
'--| dev D3 |
170
+
'--------'
171
+
172
+
When 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.
187
+
10. M1 unlocks muxes on its parent.
188
+
189
+
190
+
This means that accesses to both D2 and D3 are locked out for the full
191
+
duration of the entire operation.
192
+
193
+
194
+
Complex Examples
195
+
================
196
+
197
+
Parent-locked mux as parent of parent-locked mux
198
+
------------------------------------------------
199
+
200
+
This 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
+
211
+
When any device is accessed, all other devices are locked out for
212
+
the full duration of the operation (both muxes lock their parent,
213
+
and specifically when M2 requests its parent to lock, M1 passes
214
+
the buck to the root adapter).
215
+
216
+
This topology is bad if M2 is an auto-closing mux and M1->select
217
+
issues any unlocked i2c transfers on the root adapter that may leak
218
+
through and be seen by the M2 adapter, thus closing M2 prematurely.
219
+
220
+
221
+
Mux-locked mux as parent of mux-locked mux
222
+
------------------------------------------
223
+
224
+
This 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
+
235
+
When device D1 is accessed, accesses to D2 are locked out for the
236
+
full duration of the operation (muxes on the top child adapter of M1
237
+
are locked). But accesses to D3 and D4 are possibly interleaved at
238
+
any point. Accesses to D3 locks out D1 and D2, but accesses to D4
239
+
are still possibly interleaved.
240
+
241
+
242
+
Mux-locked mux as parent of parent-locked mux
243
+
---------------------------------------------
244
+
245
+
This 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
+
256
+
When device D1 is accessed, accesses to D2 and D3 are locked out
257
+
for the full duration of the operation (M1 locks child muxes on the
258
+
root adapter). But accesses to D4 are possibly interleaved at any
259
+
point.
260
+
261
+
This kind of topology is generally not suitable and should probably
262
+
be avoided. The reason is that M2 probably assumes that there will
263
+
be no i2c transfers during its calls to ->select and ->deselect, and
264
+
if there are, any such transfers might appear on the slave side of M2
265
+
as partial i2c transfers, i.e. garbage or worse. This might cause
266
+
device lockups and/or other problems.
267
+
268
+
The topology is especially troublesome if M2 is an auto-closing
269
+
mux. In that case, any interleaved accesses to D4 might close M2
270
+
prematurely, as might any i2c-transfers part of M1->select.
271
+
272
+
But if M2 is not making the above stated assumption, and if M2 is not
273
+
auto-closing, the topology is fine.
274
+
275
+
276
+
Parent-locked mux as parent of mux-locked mux
277
+
---------------------------------------------
278
+
279
+
This 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
+
290
+
When D1 is accessed, accesses to D2 are locked out for the full
291
+
duration of the operation (muxes on the top child adapter of M1
292
+
are locked). Accesses to D3 and D4 are possibly interleaved at
293
+
any point, just as is expected for mux-locked muxes.
294
+
295
+
When D3 or D4 are accessed, everything else is locked out. For D3
296
+
accesses, M1 locks the root adapter. For D4 accesses, the root
297
+
adapter is locked directly.
298
+
299
+
300
+
Two mux-locked sibling muxes
301
+
----------------------------
302
+
303
+
This 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
+
320
+
When D1 is accessed, accesses to D2, D3 and D4 are locked out. But
321
+
accesses to D5 may be interleaved at any time.
322
+
323
+
324
+
Two parent-locked sibling muxes
325
+
-------------------------------
326
+
327
+
This 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
+
344
+
When any device is accessed, accesses to all other devices are locked
345
+
out.
346
+
347
+
348
+
Mux-locked and parent-locked sibling muxes
349
+
------------------------------------------
350
+
351
+
This 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
+
368
+
When D1 or D2 are accessed, accesses to D3 and D4 are locked out while
369
+
accesses to D5 may interleave. When D3 or D4 are accessed, accesses to
370
+
all other devices are locked out.