Skip to content

Commit 92d5d64

Browse files
lucaceresoliwsakernel
authored andcommitted
docs: i2c: i2c-topology: reorder sections more logically
The sequence of sections is a bit confusing here: * we list the mux locking scheme for existing drivers before introducing what mux locking schemes are * we list the caveats for each locking scheme (which are tricky) before the example of the simple use case Restructure it entirely with the following logic: * Intro ("I2C muxes and complex topologies") * Locking - mux-locked - example - caveats - parent-locked - example - caveats * Complex examples * Mux type of existing device drivers While there, also apply some other improvements: * convert the caveat list from a table (with only one column carrying content) to a bullet list. * add a small introductory text to bridge the gap from listing the use cases to telling about the hardware components to handle them and then the device drivers that implement those. * make empty lines usage more uniform Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com> Acked-by: Peter Rosin <peda@axentia.se> Signed-off-by: Wolfram Sang <wsa@kernel.org>
1 parent 12c035a commit 92d5d64

File tree

1 file changed

+114
-97
lines changed

1 file changed

+114
-97
lines changed

Documentation/i2c/i2c-topology.rst

Lines changed: 114 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@ Some example use cases are:
1616
from the I2C bus, at least most of the time, and sits behind a gate
1717
that has to be operated before the device can be accessed.
1818

19-
These constructs are represented as I2C adapter trees by Linux, where
19+
Several types of hardware components such as I2C muxes, I2C gates and I2C
20+
arbitrators allow to handle such needs.
21+
22+
These components are represented as I2C adapter trees by Linux, where
2023
each adapter has a parent adapter (except the root adapter) and zero or
2124
more child adapters. The root adapter is the actual adapter that issues
2225
I2C transfers, and all adapters with a parent are part of an "i2c-mux"
@@ -34,46 +37,7 @@ Locking
3437
=======
3538

3639
There are two variants of locking available to I2C muxes, they can be
37-
mux-locked or parent-locked muxes. As is evident from below, it can be
38-
useful to know if a mux is mux-locked or if it is parent-locked. The
39-
following list was correct at the time of writing:
40-
41-
In drivers/i2c/muxes/:
42-
43-
====================== =============================================
44-
i2c-arb-gpio-challenge Parent-locked
45-
i2c-mux-gpio Normally parent-locked, mux-locked iff
46-
all involved gpio pins are controlled by the
47-
same I2C root adapter that they mux.
48-
i2c-mux-gpmux Normally parent-locked, mux-locked iff
49-
specified in device-tree.
50-
i2c-mux-ltc4306 Mux-locked
51-
i2c-mux-mlxcpld Parent-locked
52-
i2c-mux-pca9541 Parent-locked
53-
i2c-mux-pca954x Parent-locked
54-
i2c-mux-pinctrl Normally parent-locked, mux-locked iff
55-
all involved pinctrl devices are controlled
56-
by the same I2C root adapter that they mux.
57-
i2c-mux-reg Parent-locked
58-
====================== =============================================
59-
60-
In drivers/iio/:
61-
62-
====================== =============================================
63-
gyro/mpu3050 Mux-locked
64-
imu/inv_mpu6050/ Mux-locked
65-
====================== =============================================
66-
67-
In drivers/media/:
68-
69-
======================= =============================================
70-
dvb-frontends/lgdt3306a Mux-locked
71-
dvb-frontends/m88ds3103 Parent-locked
72-
dvb-frontends/rtl2830 Parent-locked
73-
dvb-frontends/rtl2832 Mux-locked
74-
dvb-frontends/si2168 Mux-locked
75-
usb/cx231xx/ Parent-locked
76-
======================= =============================================
40+
mux-locked or parent-locked muxes.
7741

7842

7943
Mux-locked muxes
@@ -88,40 +52,8 @@ full transaction, unrelated I2C transfers may interleave the different
8852
stages of the transaction. This has the benefit that the mux driver
8953
may be easier and cleaner to implement, but it has some caveats.
9054

91-
==== =====================================================================
92-
ML1. If you build a topology with a mux-locked mux being the parent
93-
of a parent-locked mux, this might break the expectation from the
94-
parent-locked mux that the root adapter is locked during the
95-
transaction.
96-
97-
ML2. It is not safe to build arbitrary topologies with two (or more)
98-
mux-locked muxes that are not siblings, when there are address
99-
collisions between the devices on the child adapters of these
100-
non-sibling muxes.
101-
102-
I.e. the select-transfer-deselect transaction targeting e.g. device
103-
address 0x42 behind mux-one may be interleaved with a similar
104-
operation targeting device address 0x42 behind mux-two. The
105-
intent with such a topology would in this hypothetical example
106-
be that mux-one and mux-two should not be selected simultaneously,
107-
but mux-locked muxes do not guarantee that in all topologies.
108-
109-
ML3. A mux-locked mux cannot be used by a driver for auto-closing
110-
gates/muxes, i.e. something that closes automatically after a given
111-
number (one, in most cases) of I2C transfers. Unrelated I2C transfers
112-
may creep in and close prematurely.
113-
114-
ML4. If any non-I2C operation in the mux driver changes the I2C mux state,
115-
the driver has to lock the root adapter during that operation.
116-
Otherwise garbage may appear on the bus as seen from devices
117-
behind the mux, when an unrelated I2C transfer is in flight during
118-
the non-I2C mux-changing operation.
119-
==== =====================================================================
120-
121-
12255
Mux-locked Example
123-
------------------
124-
56+
~~~~~~~~~~~~~~~~~~
12557

12658
::
12759

@@ -152,6 +84,43 @@ This means that accesses to D2 are lockout out for the full duration
15284
of the entire operation. But accesses to D3 are possibly interleaved
15385
at any point.
15486

87+
Mux-locked caveats
88+
~~~~~~~~~~~~~~~~~~
89+
90+
When using a mux-locked mux, be aware of the following restrictions:
91+
92+
[ML1]
93+
If you build a topology with a mux-locked mux being the parent
94+
of a parent-locked mux, this might break the expectation from the
95+
parent-locked mux that the root adapter is locked during the
96+
transaction.
97+
98+
[ML2]
99+
It is not safe to build arbitrary topologies with two (or more)
100+
mux-locked muxes that are not siblings, when there are address
101+
collisions between the devices on the child adapters of these
102+
non-sibling muxes.
103+
104+
I.e. the select-transfer-deselect transaction targeting e.g. device
105+
address 0x42 behind mux-one may be interleaved with a similar
106+
operation targeting device address 0x42 behind mux-two. The
107+
intent with such a topology would in this hypothetical example
108+
be that mux-one and mux-two should not be selected simultaneously,
109+
but mux-locked muxes do not guarantee that in all topologies.
110+
111+
[ML3]
112+
A mux-locked mux cannot be used by a driver for auto-closing
113+
gates/muxes, i.e. something that closes automatically after a given
114+
number (one, in most cases) of I2C transfers. Unrelated I2C transfers
115+
may creep in and close prematurely.
116+
117+
[ML4]
118+
If any non-I2C operation in the mux driver changes the I2C mux state,
119+
the driver has to lock the root adapter during that operation.
120+
Otherwise garbage may appear on the bus as seen from devices
121+
behind the mux, when an unrelated I2C transfer is in flight during
122+
the non-I2C mux-changing operation.
123+
155124

156125
Parent-locked muxes
157126
-------------------
@@ -160,28 +129,10 @@ Parent-locked muxes lock the parent adapter during the full select-
160129
transfer-deselect transaction. The implication is that the mux driver
161130
has to ensure that any and all I2C transfers through that parent
162131
adapter during the transaction are unlocked I2C transfers (using e.g.
163-
__i2c_transfer), or a deadlock will follow. There are a couple of
164-
caveats.
165-
166-
==== ====================================================================
167-
PL1. If you build a topology with a parent-locked mux being the child
168-
of another mux, this might break a possible assumption from the
169-
child mux that the root adapter is unused between its select op
170-
and the actual transfer (e.g. if the child mux is auto-closing
171-
and the parent mux issues I2C transfers as part of its select).
172-
This is especially the case if the parent mux is mux-locked, but
173-
it may also happen if the parent mux is parent-locked.
174-
175-
PL2. If select/deselect calls out to other subsystems such as gpio,
176-
pinctrl, regmap or iio, it is essential that any I2C transfers
177-
caused by these subsystems are unlocked. This can be convoluted to
178-
accomplish, maybe even impossible if an acceptably clean solution
179-
is sought.
180-
==== ====================================================================
181-
132+
__i2c_transfer), or a deadlock will follow.
182133

183134
Parent-locked Example
184-
---------------------
135+
~~~~~~~~~~~~~~~~~~~~~
185136

186137
::
187138

@@ -211,10 +162,30 @@ When there is an access to D1, this happens:
211162
9. M1 unlocks its parent adapter.
212163
10. M1 unlocks muxes on its parent.
213164

214-
215165
This means that accesses to both D2 and D3 are locked out for the full
216166
duration of the entire operation.
217167

168+
Parent-locked Caveats
169+
~~~~~~~~~~~~~~~~~~~~~
170+
171+
When using a parent-locked mux, be aware of the following restrictions:
172+
173+
[PL1]
174+
If you build a topology with a parent-locked mux being the child
175+
of another mux, this might break a possible assumption from the
176+
child mux that the root adapter is unused between its select op
177+
and the actual transfer (e.g. if the child mux is auto-closing
178+
and the parent mux issues I2C transfers as part of its select).
179+
This is especially the case if the parent mux is mux-locked, but
180+
it may also happen if the parent mux is parent-locked.
181+
182+
[PL2]
183+
If select/deselect calls out to other subsystems such as gpio,
184+
pinctrl, regmap or iio, it is essential that any I2C transfers
185+
caused by these subsystems are unlocked. This can be convoluted to
186+
accomplish, maybe even impossible if an acceptably clean solution
187+
is sought.
188+
218189

219190
Complex Examples
220191
================
@@ -260,8 +231,10 @@ This is a good topology::
260231
When device D1 is accessed, accesses to D2 are locked out for the
261232
full duration of the operation (muxes on the top child adapter of M1
262233
are locked). But accesses to D3 and D4 are possibly interleaved at
263-
any point. Accesses to D3 locks out D1 and D2, but accesses to D4
264-
are still possibly interleaved.
234+
any point.
235+
236+
Accesses to D3 locks out D1 and D2, but accesses to D4 are still possibly
237+
interleaved.
265238

266239

267240
Mux-locked mux as parent of parent-locked mux
@@ -393,3 +366,47 @@ This is a good topology::
393366
When D1 or D2 are accessed, accesses to D3 and D4 are locked out while
394367
accesses to D5 may interleave. When D3 or D4 are accessed, accesses to
395368
all other devices are locked out.
369+
370+
371+
Mux type of existing device drivers
372+
===================================
373+
374+
Whether a device is mux-locked or parent-locked depends on its
375+
implementation. The following list was correct at the time of writing:
376+
377+
In drivers/i2c/muxes/:
378+
379+
====================== =============================================
380+
i2c-arb-gpio-challenge Parent-locked
381+
i2c-mux-gpio Normally parent-locked, mux-locked iff
382+
all involved gpio pins are controlled by the
383+
same I2C root adapter that they mux.
384+
i2c-mux-gpmux Normally parent-locked, mux-locked iff
385+
specified in device-tree.
386+
i2c-mux-ltc4306 Mux-locked
387+
i2c-mux-mlxcpld Parent-locked
388+
i2c-mux-pca9541 Parent-locked
389+
i2c-mux-pca954x Parent-locked
390+
i2c-mux-pinctrl Normally parent-locked, mux-locked iff
391+
all involved pinctrl devices are controlled
392+
by the same I2C root adapter that they mux.
393+
i2c-mux-reg Parent-locked
394+
====================== =============================================
395+
396+
In drivers/iio/:
397+
398+
====================== =============================================
399+
gyro/mpu3050 Mux-locked
400+
imu/inv_mpu6050/ Mux-locked
401+
====================== =============================================
402+
403+
In drivers/media/:
404+
405+
======================= =============================================
406+
dvb-frontends/lgdt3306a Mux-locked
407+
dvb-frontends/m88ds3103 Parent-locked
408+
dvb-frontends/rtl2830 Parent-locked
409+
dvb-frontends/rtl2832 Mux-locked
410+
dvb-frontends/si2168 Mux-locked
411+
usb/cx231xx/ Parent-locked
412+
======================= =============================================

0 commit comments

Comments
 (0)