mirror of
https://github.com/AuxXxilium/linux_dsm_epyc7002.git
synced 2024-12-15 08:56:48 +07:00
ccf988b66d
Convert each file at I2C subsystem, renaming them to .rst and adding to the driver-api book. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Wolfram Sang <wsa@the-dreams.de> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
397 lines
16 KiB
ReStructuredText
397 lines
16 KiB
ReStructuredText
============
|
|
I2C topology
|
|
============
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Etc
|
|
===
|
|
|
|
These constructs 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. As is evident from below, it can be
|
|
useful to know if a mux is mux-locked or if it is parent-locked. 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
|
|
======================= =============================================
|
|
|
|
|
|
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.
|
|
|
|
==== =====================================================================
|
|
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
|
|
intension 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.
|
|
==== =====================================================================
|
|
|
|
|
|
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.
|
|
|
|
|
|
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. There are a couple of
|
|
caveats.
|
|
|
|
==== ====================================================================
|
|
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 issus 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.
|
|
==== ====================================================================
|
|
|
|
|
|
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.
|
|
|
|
|
|
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.
|