[linux-block.git] / Documentation / i2c / i2c-topology.rst

================================
I2C muxes and complex topologies
================================

There are a couple of reasons for building more complex I2C topologies
than a straight-forward I2C bus with one adapter and one or more devices.

Some example use cases are:

1. A mux may be needed on the bus to prevent address collisions.

2. The bus may be accessible from some external bus master, and arbitration
   may be needed to determine if it is ok to access the bus.

3. A device (particularly RF tuners) may want to avoid the digital noise
   from the I2C bus, at least most of the time, and sits behind a gate
   that has to be operated before the device can be accessed.

Several types of hardware components such as I2C muxes, I2C gates and I2C
arbitrators allow to handle such needs.

These components are represented as I2C adapter trees by Linux, where
each adapter has a parent adapter (except the root adapter) and zero or
more child adapters. The root adapter is the actual adapter that issues
I2C transfers, and all adapters with a parent are part of an "i2c-mux"
object (quoted, since it can also be an arbitrator or a gate).

Depending of the particular mux driver, something happens when there is
an I2C transfer on one of its child adapters. The mux driver can
obviously operate a mux, but it can also do arbitration with an external
bus master or open a gate. The mux driver has two operations for this,
select and deselect. select is called before the transfer and (the
optional) deselect is called after the transfer.


Locking
=======

There are two variants of locking available to I2C muxes, they can be
mux-locked or parent-locked muxes.


Mux-locked muxes
----------------

Mux-locked muxes does not lock the entire parent adapter during the
full select-transfer-deselect transaction, only the muxes on the parent
adapter are locked. Mux-locked muxes are mostly interesting if the
select and/or deselect operations must use I2C transfers to complete
their tasks. Since the parent adapter is not fully locked during the
full transaction, unrelated I2C transfers may interleave the different
stages of the transaction. This has the benefit that the mux driver
may be easier and cleaner to implement, but it has some caveats.

Mux-locked Example
~~~~~~~~~~~~~~~~~~

::

                   .----------.     .--------.
    .--------.     |   mux-   |-----| dev D1 |
    |  root  |--+--|  locked  |     '--------'
    '--------'  |  |  mux M1  |--.  .--------.
                |  '----------'  '--| dev D2 |
                |  .--------.       '--------'
                '--| dev D3 |
                   '--------'

When there is an access to D1, this happens:

 1. Someone issues an I2C transfer to D1.
 2. M1 locks muxes on its parent (the root adapter in this case).
 3. M1 calls ->select to ready the mux.
 4. M1 (presumably) does some I2C transfers as part of its select.
    These transfers are normal I2C transfers that locks the parent
    adapter.
 5. M1 feeds the I2C transfer from step 1 to its parent adapter as a
    normal I2C transfer that locks the parent adapter.
 6. M1 calls ->deselect, if it has one.
 7. Same rules as in step 4, but for ->deselect.
 8. M1 unlocks muxes on its parent.

This means that accesses to D2 are lockout out for the full duration
of the entire operation. But accesses to D3 are possibly interleaved
at any point.

Mux-locked caveats
~~~~~~~~~~~~~~~~~~

When using a mux-locked mux, be aware of the following restrictions:

[ML1]
  If you build a topology with a mux-locked mux being the parent
  of a parent-locked mux, this might break the expectation from the
  parent-locked mux that the root adapter is locked during the
  transaction.

[ML2]
  It is not safe to build arbitrary topologies with two (or more)
  mux-locked muxes that are not siblings, when there are address
  collisions between the devices on the child adapters of these
  non-sibling muxes.

  I.e. the select-transfer-deselect transaction targeting e.g. device
  address 0x42 behind mux-one may be interleaved with a similar
  operation targeting device address 0x42 behind mux-two. The
  intent with such a topology would in this hypothetical example
  be that mux-one and mux-two should not be selected simultaneously,
  but mux-locked muxes do not guarantee that in all topologies.

[ML3]
  A mux-locked mux cannot be used by a driver for auto-closing
  gates/muxes, i.e. something that closes automatically after a given
  number (one, in most cases) of I2C transfers. Unrelated I2C transfers
  may creep in and close prematurely.

[ML4]
  If any non-I2C operation in the mux driver changes the I2C mux state,
  the driver has to lock the root adapter during that operation.
  Otherwise garbage may appear on the bus as seen from devices
  behind the mux, when an unrelated I2C transfer is in flight during
  the non-I2C mux-changing operation.


Parent-locked muxes
-------------------

Parent-locked muxes lock the parent adapter during the full select-
transfer-deselect transaction. The implication is that the mux driver
has to ensure that any and all I2C transfers through that parent
adapter during the transaction are unlocked I2C transfers (using e.g.
__i2c_transfer), or a deadlock will follow.

Parent-locked Example
~~~~~~~~~~~~~~~~~~~~~

::

                   .----------.     .--------.
    .--------.     |  parent- |-----| dev D1 |
    |  root  |--+--|  locked  |     '--------'
    '--------'  |  |  mux M1  |--.  .--------.
                |  '----------'  '--| dev D2 |
                |  .--------.       '--------'
                '--| dev D3 |
                   '--------'

When there is an access to D1, this happens:

 1.  Someone issues an I2C transfer to D1.
 2.  M1 locks muxes on its parent (the root adapter in this case).
 3.  M1 locks its parent adapter.
 4.  M1 calls ->select to ready the mux.
 5.  If M1 does any I2C transfers (on this root adapter) as part of
     its select, those transfers must be unlocked I2C transfers so
     that they do not deadlock the root adapter.
 6.  M1 feeds the I2C transfer from step 1 to the root adapter as an
     unlocked I2C transfer, so that it does not deadlock the parent
     adapter.
 7.  M1 calls ->deselect, if it has one.
 8.  Same rules as in step 5, but for ->deselect.
 9.  M1 unlocks its parent adapter.
 10. M1 unlocks muxes on its parent.

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

Parent-locked Caveats
~~~~~~~~~~~~~~~~~~~~~

When using a parent-locked mux, be aware of the following restrictions:

[PL1]
  If you build a topology with a parent-locked mux being the child
  of another mux, this might break a possible assumption from the
  child mux that the root adapter is unused between its select op
  and the actual transfer (e.g. if the child mux is auto-closing
  and the parent mux issues I2C transfers as part of its select).
  This is especially the case if the parent mux is mux-locked, but
  it may also happen if the parent mux is parent-locked.

[PL2]
  If select/deselect calls out to other subsystems such as gpio,
  pinctrl, regmap or iio, it is essential that any I2C transfers
  caused by these subsystems are unlocked. This can be convoluted to
  accomplish, maybe even impossible if an acceptably clean solution
  is sought.


Complex Examples
================

Parent-locked mux as parent of parent-locked mux
------------------------------------------------

This is a useful topology, but it can be bad::

                   .----------.     .----------.     .--------.
    .--------.     |  parent- |-----|  parent- |-----| dev D1 |
    |  root  |--+--|  locked  |     |  locked  |     '--------'
    '--------'  |  |  mux M1  |--.  |  mux M2  |--.  .--------.
                |  '----------'  |  '----------'  '--| dev D2 |
                |  .--------.    |  .--------.       '--------'
                '--| dev D4 |    '--| dev D3 |
                   '--------'       '--------'

When any device is accessed, all other devices are locked out for
the full duration of the operation (both muxes lock their parent,
and specifically when M2 requests its parent to lock, M1 passes
the buck to the root adapter).

This topology is bad if M2 is an auto-closing mux and M1->select
issues any unlocked I2C transfers on the root adapter that may leak
through and be seen by the M2 adapter, thus closing M2 prematurely.


Mux-locked mux as parent of mux-locked mux
------------------------------------------

This is a good topology::

                   .----------.     .----------.     .--------.
    .--------.     |   mux-   |-----|   mux-   |-----| dev D1 |
    |  root  |--+--|  locked  |     |  locked  |     '--------'
    '--------'  |  |  mux M1  |--.  |  mux M2  |--.  .--------.
                |  '----------'  |  '----------'  '--| dev D2 |
                |  .--------.    |  .--------.       '--------'
                '--| dev D4 |    '--| dev D3 |
                   '--------'       '--------'

When device D1 is accessed, accesses to D2 are locked out for the
full duration of the operation (muxes on the top child adapter of M1
are locked). But accesses to D3 and D4 are possibly interleaved at
any point.

Accesses to D3 locks out D1 and D2, but accesses to D4 are still possibly
interleaved.


Mux-locked mux as parent of parent-locked mux
---------------------------------------------

This is probably a bad topology::

                   .----------.     .----------.     .--------.
    .--------.     |   mux-   |-----|  parent- |-----| dev D1 |
    |  root  |--+--|  locked  |     |  locked  |     '--------'
    '--------'  |  |  mux M1  |--.  |  mux M2  |--.  .--------.
                |  '----------'  |  '----------'  '--| dev D2 |
                |  .--------.    |  .--------.       '--------'
                '--| dev D4 |    '--| dev D3 |
                   '--------'       '--------'

When device D1 is accessed, accesses to D2 and D3 are locked out
for the full duration of the operation (M1 locks child muxes on the
root adapter). But accesses to D4 are possibly interleaved at any
point.

This kind of topology is generally not suitable and should probably
be avoided. The reason is that M2 probably assumes that there will
be no I2C transfers during its calls to ->select and ->deselect, and
if there are, any such transfers might appear on the slave side of M2
as partial I2C transfers, i.e. garbage or worse. This might cause
device lockups and/or other problems.

The topology is especially troublesome if M2 is an auto-closing
mux. In that case, any interleaved accesses to D4 might close M2
prematurely, as might any I2C transfers part of M1->select.

But if M2 is not making the above stated assumption, and if M2 is not
auto-closing, the topology is fine.


Parent-locked mux as parent of mux-locked mux
---------------------------------------------

This is a good topology::

                   .----------.     .----------.     .--------.
    .--------.     |  parent- |-----|   mux-   |-----| dev D1 |
    |  root  |--+--|  locked  |     |  locked  |     '--------'
    '--------'  |  |  mux M1  |--.  |  mux M2  |--.  .--------.
                |  '----------'  |  '----------'  '--| dev D2 |
                |  .--------.    |  .--------.       '--------'
                '--| dev D4 |    '--| dev D3 |
                   '--------'       '--------'

When D1 is accessed, accesses to D2 are locked out for the full
duration of the operation (muxes on the top child adapter of M1
are locked). Accesses to D3 and D4 are possibly interleaved at
any point, just as is expected for mux-locked muxes.

When D3 or D4 are accessed, everything else is locked out. For D3
accesses, M1 locks the root adapter. For D4 accesses, the root
adapter is locked directly.


Two mux-locked sibling muxes
----------------------------

This is a good topology::

                                    .--------.
                   .----------.  .--| dev D1 |
                   |   mux-   |--'  '--------'
                .--|  locked  |     .--------.
                |  |  mux M1  |-----| dev D2 |
                |  '----------'     '--------'
                |  .----------.     .--------.
    .--------.  |  |   mux-   |-----| dev D3 |
    |  root  |--+--|  locked  |     '--------'
    '--------'  |  |  mux M2  |--.  .--------.
                |  '----------'  '--| dev D4 |
                |  .--------.       '--------'
                '--| dev D5 |
                   '--------'

When D1 is accessed, accesses to D2, D3 and D4 are locked out. But
accesses to D5 may be interleaved at any time.


Two parent-locked sibling muxes
-------------------------------

This is a good topology::

                                    .--------.
                   .----------.  .--| dev D1 |
                   |  parent- |--'  '--------'
                .--|  locked  |     .--------.
                |  |  mux M1  |-----| dev D2 |
                |  '----------'     '--------'
                |  .----------.     .--------.
    .--------.  |  |  parent- |-----| dev D3 |
    |  root  |--+--|  locked  |     '--------'
    '--------'  |  |  mux M2  |--.  .--------.
                |  '----------'  '--| dev D4 |
                |  .--------.       '--------'
                '--| dev D5 |
                   '--------'

When any device is accessed, accesses to all other devices are locked
out.


Mux-locked and parent-locked sibling muxes
------------------------------------------

This is a good topology::

                                    .--------.
                   .----------.  .--| dev D1 |
                   |   mux-   |--'  '--------'
                .--|  locked  |     .--------.
                |  |  mux M1  |-----| dev D2 |
                |  '----------'     '--------'
                |  .----------.     .--------.
    .--------.  |  |  parent- |-----| dev D3 |
    |  root  |--+--|  locked  |     '--------'
    '--------'  |  |  mux M2  |--.  .--------.
                |  '----------'  '--| dev D4 |
                |  .--------.       '--------'
                '--| dev D5 |
                   '--------'

When D1 or D2 are accessed, accesses to D3 and D4 are locked out while
accesses to D5 may interleave. When D3 or D4 are accessed, accesses to
all other devices are locked out.


Mux type of existing device drivers
===================================

Whether a device is mux-locked or parent-locked depends on its
implementation. The following list was correct at the time of writing:

In drivers/i2c/muxes/:

======================    =============================================
i2c-arb-gpio-challenge    Parent-locked
i2c-mux-gpio              Normally parent-locked, mux-locked iff
                          all involved gpio pins are controlled by the
                          same I2C root adapter that they mux.
i2c-mux-gpmux             Normally parent-locked, mux-locked iff
                          specified in device-tree.
i2c-mux-ltc4306           Mux-locked
i2c-mux-mlxcpld           Parent-locked
i2c-mux-pca9541           Parent-locked
i2c-mux-pca954x           Parent-locked
i2c-mux-pinctrl           Normally parent-locked, mux-locked iff
                          all involved pinctrl devices are controlled
                          by the same I2C root adapter that they mux.
i2c-mux-reg               Parent-locked
======================    =============================================

In drivers/iio/:

======================    =============================================
gyro/mpu3050              Mux-locked
imu/inv_mpu6050/          Mux-locked
======================    =============================================

In drivers/media/:

=======================   =============================================
dvb-frontends/lgdt3306a   Mux-locked
dvb-frontends/m88ds3103   Parent-locked
dvb-frontends/rtl2830     Parent-locked
dvb-frontends/rtl2832     Mux-locked
dvb-frontends/si2168      Mux-locked
usb/cx231xx/              Parent-locked
=======================   =============================================
Commit	Line	Data
f6fcefa1 LC	1	================================
	2	I2C muxes and complex topologies
	3	================================
2254d24a	4
2f07c05f LC	5	There are a couple of reasons for building more complex I2C topologies
2f07c05f LC	6	than a straight-forward I2C bus with one adapter and one or more devices.
2254d24a	7
12c035a1 LC	8	Some example use cases are:
12c035a1 LC	9
2254d24a PR	10	1. A mux may be needed on the bus to prevent address collisions.
	11
	12	2. The bus may be accessible from some external bus master, and arbitration
	13	may be needed to determine if it is ok to access the bus.
	14
	15	3. A device (particularly RF tuners) may want to avoid the digital noise
2f07c05f	16	from the I2C bus, at least most of the time, and sits behind a gate
2254d24a PR	17	that has to be operated before the device can be accessed.
2254d24a PR	18
92d5d643 LC	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
2254d24a PR	23	each adapter has a parent adapter (except the root adapter) and zero or
2254d24a PR	24	more child adapters. The root adapter is the actual adapter that issues
2f07c05f	25	I2C transfers, and all adapters with a parent are part of an "i2c-mux"
2254d24a PR	26	object (quoted, since it can also be an arbitrator or a gate).
	27
	28	Depending of the particular mux driver, something happens when there is
2f07c05f	29	an I2C transfer on one of its child adapters. The mux driver can
2254d24a PR	30	obviously operate a mux, but it can also do arbitration with an external
	31	bus master or open a gate. The mux driver has two operations for this,
	32	select and deselect. select is called before the transfer and (the
	33	optional) deselect is called after the transfer.
	34
	35
	36	Locking
	37	=======
	38
2f07c05f	39	There are two variants of locking available to I2C muxes, they can be
92d5d643	40	mux-locked or parent-locked muxes.
2254d24a PR	41
	42
	43	Mux-locked muxes
	44	----------------
	45
	46	Mux-locked muxes does not lock the entire parent adapter during the
	47	full select-transfer-deselect transaction, only the muxes on the parent
	48	adapter are locked. Mux-locked muxes are mostly interesting if the
2f07c05f	49	select and/or deselect operations must use I2C transfers to complete
2254d24a	50	their tasks. Since the parent adapter is not fully locked during the
2f07c05f	51	full transaction, unrelated I2C transfers may interleave the different
2254d24a PR	52	stages of the transaction. This has the benefit that the mux driver
	53	may be easier and cleaner to implement, but it has some caveats.
	54
2254d24a	55	Mux-locked Example
92d5d643	56	~~~~~~~~~~~~~~~~~~
ccf988b6 MCC	57
	58	::
	59
2254d24a PR	60	.----------. .--------.
	61	.--------. \| mux- \|-----\| dev D1 \|
	62	\| root \|--+--\| locked \| '--------'
	63	'--------' \| \| mux M1 \|--. .--------.
	64	\| '----------' '--\| dev D2 \|
	65	\| .--------. '--------'
	66	'--\| dev D3 \|
	67	'--------'
	68
	69	When there is an access to D1, this happens:
	70
48ca3b7f	71	1. Someone issues an I2C transfer to D1.
2254d24a PR	72	2. M1 locks muxes on its parent (the root adapter in this case).
2254d24a PR	73	3. M1 calls ->select to ready the mux.
48ca3b7f LC	74	4. M1 (presumably) does some I2C transfers as part of its select.
48ca3b7f LC	75	These transfers are normal I2C transfers that locks the parent
2254d24a	76	adapter.
48ca3b7f LC	77	5. M1 feeds the I2C transfer from step 1 to its parent adapter as a
48ca3b7f LC	78	normal I2C transfer that locks the parent adapter.
2254d24a PR	79	6. M1 calls ->deselect, if it has one.
	80	7. Same rules as in step 4, but for ->deselect.
	81	8. M1 unlocks muxes on its parent.
	82
	83	This means that accesses to D2 are lockout out for the full duration
	84	of the entire operation. But accesses to D3 are possibly interleaved
	85	at any point.
	86
92d5d643 LC	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
2254d24a PR	124
	125	Parent-locked muxes
	126	-------------------
	127
	128	Parent-locked muxes lock the parent adapter during the full select-
	129	transfer-deselect transaction. The implication is that the mux driver
2f07c05f LC	130	has to ensure that any and all I2C transfers through that parent
2f07c05f LC	131	adapter during the transaction are unlocked I2C transfers (using e.g.
92d5d643	132	__i2c_transfer), or a deadlock will follow.
2254d24a PR	133
2254d24a PR	134	Parent-locked Example
92d5d643	135	~~~~~~~~~~~~~~~~~~~~~
2254d24a	136
ccf988b6 MCC	137	::
ccf988b6 MCC	138
2254d24a PR	139	.----------. .--------.
	140	.--------. \| parent- \|-----\| dev D1 \|
	141	\| root \|--+--\| locked \| '--------'
	142	'--------' \| \| mux M1 \|--. .--------.
	143	\| '----------' '--\| dev D2 \|
	144	\| .--------. '--------'
	145	'--\| dev D3 \|
	146	'--------'
	147
	148	When there is an access to D1, this happens:
	149
48ca3b7f	150	1. Someone issues an I2C transfer to D1.
ccf988b6 MCC	151	2. M1 locks muxes on its parent (the root adapter in this case).
	152	3. M1 locks its parent adapter.
	153	4. M1 calls ->select to ready the mux.
48ca3b7f LC	154	5. If M1 does any I2C transfers (on this root adapter) as part of
48ca3b7f LC	155	its select, those transfers must be unlocked I2C transfers so
ccf988b6	156	that they do not deadlock the root adapter.
48ca3b7f LC	157	6. M1 feeds the I2C transfer from step 1 to the root adapter as an
48ca3b7f LC	158	unlocked I2C transfer, so that it does not deadlock the parent
ccf988b6 MCC	159	adapter.
	160	7. M1 calls ->deselect, if it has one.
	161	8. Same rules as in step 5, but for ->deselect.
	162	9. M1 unlocks its parent adapter.
	163	10. M1 unlocks muxes on its parent.
2254d24a	164
2254d24a PR	165	This means that accesses to both D2 and D3 are locked out for the full
	166	duration of the entire operation.
	167
92d5d643 LC	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
2254d24a PR	189
	190	Complex Examples
	191	================
	192
	193	Parent-locked mux as parent of parent-locked mux
	194	------------------------------------------------
	195
ccf988b6	196	This is a useful topology, but it can be bad::
2254d24a PR	197
	198	.----------. .----------. .--------.
	199	.--------. \| parent- \|-----\| parent- \|-----\| dev D1 \|
	200	\| root \|--+--\| locked \| \| locked \| '--------'
	201	'--------' \| \| mux M1 \|--. \| mux M2 \|--. .--------.
	202	\| '----------' \| '----------' '--\| dev D2 \|
	203	\| .--------. \| .--------. '--------'
	204	'--\| dev D4 \| '--\| dev D3 \|
	205	'--------' '--------'
	206
	207	When any device is accessed, all other devices are locked out for
	208	the full duration of the operation (both muxes lock their parent,
	209	and specifically when M2 requests its parent to lock, M1 passes
	210	the buck to the root adapter).
	211
	212	This topology is bad if M2 is an auto-closing mux and M1->select
2f07c05f	213	issues any unlocked I2C transfers on the root adapter that may leak
2254d24a PR	214	through and be seen by the M2 adapter, thus closing M2 prematurely.
	215
	216
	217	Mux-locked mux as parent of mux-locked mux
	218	------------------------------------------
	219
ccf988b6	220	This is a good topology::
2254d24a PR	221
	222	.----------. .----------. .--------.
	223	.--------. \| mux- \|-----\| mux- \|-----\| dev D1 \|
	224	\| root \|--+--\| locked \| \| locked \| '--------'
	225	'--------' \| \| mux M1 \|--. \| mux M2 \|--. .--------.
	226	\| '----------' \| '----------' '--\| dev D2 \|
	227	\| .--------. \| .--------. '--------'
	228	'--\| dev D4 \| '--\| dev D3 \|
	229	'--------' '--------'
	230
	231	When device D1 is accessed, accesses to D2 are locked out for the
	232	full duration of the operation (muxes on the top child adapter of M1
	233	are locked). But accesses to D3 and D4 are possibly interleaved at
92d5d643 LC	234	any point.
	235
	236	Accesses to D3 locks out D1 and D2, but accesses to D4 are still possibly
	237	interleaved.
2254d24a PR	238
	239
	240	Mux-locked mux as parent of parent-locked mux
	241	---------------------------------------------
	242
ccf988b6	243	This is probably a bad topology::
2254d24a PR	244
	245	.----------. .----------. .--------.
	246	.--------. \| mux- \|-----\| parent- \|-----\| dev D1 \|
	247	\| root \|--+--\| locked \| \| locked \| '--------'
	248	'--------' \| \| mux M1 \|--. \| mux M2 \|--. .--------.
	249	\| '----------' \| '----------' '--\| dev D2 \|
	250	\| .--------. \| .--------. '--------'
	251	'--\| dev D4 \| '--\| dev D3 \|
	252	'--------' '--------'
	253
	254	When device D1 is accessed, accesses to D2 and D3 are locked out
	255	for the full duration of the operation (M1 locks child muxes on the
	256	root adapter). But accesses to D4 are possibly interleaved at any
	257	point.
	258
	259	This kind of topology is generally not suitable and should probably
	260	be avoided. The reason is that M2 probably assumes that there will
2f07c05f	261	be no I2C transfers during its calls to ->select and ->deselect, and
2254d24a	262	if there are, any such transfers might appear on the slave side of M2
2f07c05f	263	as partial I2C transfers, i.e. garbage or worse. This might cause
2254d24a PR	264	device lockups and/or other problems.
	265
	266	The topology is especially troublesome if M2 is an auto-closing
	267	mux. In that case, any interleaved accesses to D4 might close M2
48ca3b7f	268	prematurely, as might any I2C transfers part of M1->select.
2254d24a PR	269
	270	But if M2 is not making the above stated assumption, and if M2 is not
	271	auto-closing, the topology is fine.
	272
	273
	274	Parent-locked mux as parent of mux-locked mux
	275	---------------------------------------------
	276
ccf988b6	277	This is a good topology::
2254d24a PR	278
	279	.----------. .----------. .--------.
	280	.--------. \| parent- \|-----\| mux- \|-----\| dev D1 \|
	281	\| root \|--+--\| locked \| \| locked \| '--------'
	282	'--------' \| \| mux M1 \|--. \| mux M2 \|--. .--------.
	283	\| '----------' \| '----------' '--\| dev D2 \|
	284	\| .--------. \| .--------. '--------'
	285	'--\| dev D4 \| '--\| dev D3 \|
	286	'--------' '--------'
	287
	288	When D1 is accessed, accesses to D2 are locked out for the full
	289	duration of the operation (muxes on the top child adapter of M1
	290	are locked). Accesses to D3 and D4 are possibly interleaved at
	291	any point, just as is expected for mux-locked muxes.
	292
	293	When D3 or D4 are accessed, everything else is locked out. For D3
	294	accesses, M1 locks the root adapter. For D4 accesses, the root
	295	adapter is locked directly.
	296
	297
	298	Two mux-locked sibling muxes
	299	----------------------------
	300
ccf988b6	301	This is a good topology::
2254d24a PR	302
	303	.--------.
	304	.----------. .--\| dev D1 \|
	305	\| mux- \|--' '--------'
	306	.--\| locked \| .--------.
	307	\| \| mux M1 \|-----\| dev D2 \|
	308	\| '----------' '--------'
	309	\| .----------. .--------.
	310	.--------. \| \| mux- \|-----\| dev D3 \|
	311	\| root \|--+--\| locked \| '--------'
	312	'--------' \| \| mux M2 \|--. .--------.
	313	\| '----------' '--\| dev D4 \|
	314	\| .--------. '--------'
	315	'--\| dev D5 \|
	316	'--------'
	317
	318	When D1 is accessed, accesses to D2, D3 and D4 are locked out. But
	319	accesses to D5 may be interleaved at any time.
	320
	321
	322	Two parent-locked sibling muxes
	323	-------------------------------
	324
ccf988b6	325	This is a good topology::
2254d24a	326
f10a59eb	327	.--------.
2254d24a PR	328	.----------. .--\| dev D1 \|
	329	\| parent- \|--' '--------'
	330	.--\| locked \| .--------.
	331	\| \| mux M1 \|-----\| dev D2 \|
	332	\| '----------' '--------'
	333	\| .----------. .--------.
	334	.--------. \| \| parent- \|-----\| dev D3 \|
	335	\| root \|--+--\| locked \| '--------'
	336	'--------' \| \| mux M2 \|--. .--------.
	337	\| '----------' '--\| dev D4 \|
	338	\| .--------. '--------'
	339	'--\| dev D5 \|
	340	'--------'
	341
	342	When any device is accessed, accesses to all other devices are locked
	343	out.
	344
	345
	346	Mux-locked and parent-locked sibling muxes
	347	------------------------------------------
	348
ccf988b6	349	This is a good topology::
2254d24a	350
f10a59eb	351	.--------.
2254d24a PR	352	.----------. .--\| dev D1 \|
	353	\| mux- \|--' '--------'
	354	.--\| locked \| .--------.
	355	\| \| mux M1 \|-----\| dev D2 \|
	356	\| '----------' '--------'
	357	\| .----------. .--------.
	358	.--------. \| \| parent- \|-----\| dev D3 \|
	359	\| root \|--+--\| locked \| '--------'
	360	'--------' \| \| mux M2 \|--. .--------.
	361	\| '----------' '--\| dev D4 \|
	362	\| .--------. '--------'
	363	'--\| dev D5 \|
	364	'--------'
	365
	366	When D1 or D2 are accessed, accesses to D3 and D4 are locked out while
	367	accesses to D5 may interleave. When D3 or D4 are accessed, accesses to
	368	all other devices are locked out.
92d5d643 LC	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	======================= =============================================