diff options
author | 2023-02-21 18:24:12 -0800 | |
---|---|---|
committer | 2023-02-21 18:24:12 -0800 | |
commit | 5b7c4cabbb65f5c469464da6c5f614cbd7f730f2 (patch) | |
tree | cc5c2d0a898769fd59549594fedb3ee6f84e59a0 /Documentation/i2c/i2c-topology.rst | |
download | linux-5b7c4cabbb65f5c469464da6c5f614cbd7f730f2.tar.gz linux-5b7c4cabbb65f5c469464da6c5f614cbd7f730f2.zip |
Merge tag 'net-next-6.3' of git://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-nextgrafted
Pull networking updates from Jakub Kicinski:
"Core:
- Add dedicated kmem_cache for typical/small skb->head, avoid having
to access struct page at kfree time, and improve memory use.
- Introduce sysctl to set default RPS configuration for new netdevs.
- Define Netlink protocol specification format which can be used to
describe messages used by each family and auto-generate parsers.
Add tools for generating kernel data structures and uAPI headers.
- Expose all net/core sysctls inside netns.
- Remove 4s sleep in netpoll if carrier is instantly detected on
boot.
- Add configurable limit of MDB entries per port, and port-vlan.
- Continue populating drop reasons throughout the stack.
- Retire a handful of legacy Qdiscs and classifiers.
Protocols:
- Support IPv4 big TCP (TSO frames larger than 64kB).
- Add IP_LOCAL_PORT_RANGE socket option, to control local port range
on socket by socket basis.
- Track and report in procfs number of MPTCP sockets used.
- Support mixing IPv4 and IPv6 flows in the in-kernel MPTCP path
manager.
- IPv6: don't check net.ipv6.route.max_size and rely on garbage
collection to free memory (similarly to IPv4).
- Support Penultimate Segment Pop (PSP) flavor in SRv6 (RFC8986).
- ICMP: add per-rate limit counters.
- Add support for user scanning requests in ieee802154.
- Remove static WEP support.
- Support minimal Wi-Fi 7 Extremely High Throughput (EHT) rate
reporting.
- WiFi 7 EHT channel puncturing support (client & AP).
BPF:
- Add a rbtree data structure following the "next-gen data structure"
precedent set by recently added linked list, that is, by using
kfunc + kptr instead of adding a new BPF map type.
- Expose XDP hints via kfuncs with initial support for RX hash and
timestamp metadata.
- Add BPF_F_NO_TUNNEL_KEY extension to bpf_skb_set_tunnel_key to
better support decap on GRE tunnel devices not operating in collect
metadata.
- Improve x86 JIT's codegen for PROBE_MEM runtime error checks.
- Remove the need for trace_printk_lock for bpf_trace_printk and
bpf_trace_vprintk helpers.
- Extend libbpf's bpf_tracing.h support for tracing arguments of
kprobes/uprobes and syscall as a special case.
- Significantly reduce the search time for module symbols by
livepatch and BPF.
- Enable cpumasks to be used as kptrs, which is useful for tracing
programs tracking which tasks end up running on which CPUs in
different time intervals.
- Add support for BPF trampoline on s390x and riscv64.
- Add capability to export the XDP features supported by the NIC.
- Add __bpf_kfunc tag for marking kernel functions as kfuncs.
- Add cgroup.memory=nobpf kernel parameter option to disable BPF
memory accounting for container environments.
Netfilter:
- Remove the CLUSTERIP target. It has been marked as obsolete for
years, and we still have WARN splats wrt races of the out-of-band
/proc interface installed by this target.
- Add 'destroy' commands to nf_tables. They are identical to the
existing 'delete' commands, but do not return an error if the
referenced object (set, chain, rule...) did not exist.
Driver API:
- Improve cpumask_local_spread() locality to help NICs set the right
IRQ affinity on AMD platforms.
- Separate C22 and C45 MDIO bus transactions more clearly.
- Introduce new DCB table to control DSCP rewrite on egress.
- Support configuration of Physical Layer Collision Avoidance (PLCA)
Reconciliation Sublayer (RS) (802.3cg-2019). Modern version of
shared medium Ethernet.
- Support for MAC Merge layer (IEEE 802.3-2018 clause 99). Allowing
preemption of low priority frames by high priority frames.
- Add support for controlling MACSec offload using netlink SET.
- Rework devlink instance refcounts to allow registration and
de-registration under the instance lock. Split the code into
multiple files, drop some of the unnecessarily granular locks and
factor out common parts of netlink operation handling.
- Add TX frame aggregation parameters (for USB drivers).
- Add a new attr TCA_EXT_WARN_MSG to report TC (offload) warning
messages with notifications for debug.
- Allow offloading of UDP NEW connections via act_ct.
- Add support for per action HW stats in TC.
- Support hardware miss to TC action (continue processing in SW from
a specific point in the action chain).
- Warn if old Wireless Extension user space interface is used with
modern cfg80211/mac80211 drivers. Do not support Wireless
Extensions for Wi-Fi 7 devices at all. Everyone should switch to
using nl80211 interface instead.
- Improve the CAN bit timing configuration. Use extack to return
error messages directly to user space, update the SJW handling,
including the definition of a new default value that will benefit
CAN-FD controllers, by increasing their oscillator tolerance.
New hardware / drivers:
- Ethernet:
- nVidia BlueField-3 support (control traffic driver)
- Ethernet support for imx93 SoCs
- Motorcomm yt8531 gigabit Ethernet PHY
- onsemi NCN26000 10BASE-T1S PHY (with support for PLCA)
- Microchip LAN8841 PHY (incl. cable diagnostics and PTP)
- Amlogic gxl MDIO mux
- WiFi:
- RealTek RTL8188EU (rtl8xxxu)
- Qualcomm Wi-Fi 7 devices (ath12k)
- CAN:
- Renesas R-Car V4H
Drivers:
- Bluetooth:
- Set Per Platform Antenna Gain (PPAG) for Intel controllers.
- Ethernet NICs:
- Intel (1G, igc):
- support TSN / Qbv / packet scheduling features of i226 model
- Intel (100G, ice):
- use GNSS subsystem instead of TTY
- multi-buffer XDP support
- extend support for GPIO pins to E823 devices
- nVidia/Mellanox:
- update the shared buffer configuration on PFC commands
- implement PTP adjphase function for HW offset control
- TC support for Geneve and GRE with VF tunnel offload
- more efficient crypto key management method
- multi-port eswitch support
- Netronome/Corigine:
- add DCB IEEE support
- support IPsec offloading for NFP3800
- Freescale/NXP (enetc):
- support XDP_REDIRECT for XDP non-linear buffers
- improve reconfig, avoid link flap and waiting for idle
- support MAC Merge layer
- Other NICs:
- sfc/ef100: add basic devlink support for ef100
- ionic: rx_push mode operation (writing descriptors via MMIO)
- bnxt: use the auxiliary bus abstraction for RDMA
- r8169: disable ASPM and reset bus in case of tx timeout
- cpsw: support QSGMII mode for J721e CPSW9G
- cpts: support pulse-per-second output
- ngbe: add an mdio bus driver
- usbnet: optimize usbnet_bh() by avoiding unnecessary queuing
- r8152: handle devices with FW with NCM support
- amd-xgbe: support 10Mbps, 2.5GbE speeds and rx-adaptation
- virtio-net: support multi buffer XDP
- virtio/vsock: replace virtio_vsock_pkt with sk_buff
- tsnep: XDP support
- Ethernet high-speed switches:
- nVidia/Mellanox (mlxsw):
- add support for latency TLV (in FW control messages)
- Microchip (sparx5):
- separate explicit and implicit traffic forwarding rules, make
the implicit rules always active
- add support for egress DSCP rewrite
- IS0 VCAP support (Ingress Classification)
- IS2 VCAP filters (protos, L3 addrs, L4 ports, flags, ToS
etc.)
- ES2 VCAP support (Egress Access Control)
- support for Per-Stream Filtering and Policing (802.1Q,
8.6.5.1)
- Ethernet embedded switches:
- Marvell (mv88e6xxx):
- add MAB (port auth) offload support
- enable PTP receive for mv88e6390
- NXP (ocelot):
- support MAC Merge layer
- support for the the vsc7512 internal copper phys
- Microchip:
- lan9303: convert to PHYLINK
- lan966x: support TC flower filter statistics
- lan937x: PTP support for KSZ9563/KSZ8563 and LAN937x
- lan937x: support Credit Based Shaper configuration
- ksz9477: support Energy Efficient Ethernet
- other:
- qca8k: convert to regmap read/write API, use bulk operations
- rswitch: Improve TX timestamp accuracy
- Intel WiFi (iwlwifi):
- EHT (Wi-Fi 7) rate reporting
- STEP equalizer support: transfer some STEP (connection to radio
on platforms with integrated wifi) related parameters from the
BIOS to the firmware.
- Qualcomm 802.11ax WiFi (ath11k):
- IPQ5018 support
- Fine Timing Measurement (FTM) responder role support
- channel 177 support
- MediaTek WiFi (mt76):
- per-PHY LED support
- mt7996: EHT (Wi-Fi 7) support
- Wireless Ethernet Dispatch (WED) reset support
- switch to using page pool allocator
- RealTek WiFi (rtw89):
- support new version of Bluetooth co-existance
- Mobile:
- rmnet: support TX aggregation"
* tag 'net-next-6.3' of git://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next: (1872 commits)
page_pool: add a comment explaining the fragment counter usage
net: ethtool: fix __ethtool_dev_mm_supported() implementation
ethtool: pse-pd: Fix double word in comments
xsk: add linux/vmalloc.h to xsk.c
sefltests: netdevsim: wait for devlink instance after netns removal
selftest: fib_tests: Always cleanup before exit
net/mlx5e: Align IPsec ASO result memory to be as required by hardware
net/mlx5e: TC, Set CT miss to the specific ct action instance
net/mlx5e: Rename CHAIN_TO_REG to MAPPED_OBJ_TO_REG
net/mlx5: Refactor tc miss handling to a single function
net/mlx5: Kconfig: Make tc offload depend on tc skb extension
net/sched: flower: Support hardware miss to tc action
net/sched: flower: Move filter handle initialization earlier
net/sched: cls_api: Support hardware miss to tc action
net/sched: Rename user cookie and act cookie
sfc: fix builds without CONFIG_RTC_LIB
sfc: clean up some inconsistent indentings
net/mlx4_en: Introduce flexible array to silence overflow warning
net: lan966x: Fix possible deadlock inside PTP
net/ulp: Remove redundant ->clone() test in inet_clone_ulp().
...
Diffstat (limited to '')
-rw-r--r-- | Documentation/i2c/i2c-topology.rst | 412 |
1 files changed, 412 insertions, 0 deletions
diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst new file mode 100644 index 000000000..48fce0f74 --- /dev/null +++ b/Documentation/i2c/i2c-topology.rst @@ -0,0 +1,412 @@ +================================ +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 +======================= ============================================= |