lastdragon/linux-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Resguardo inicial

Browse Source
This commit is contained in:
lastdragon
2026-09-06 12:53:21 -06:00
parent 662efe3c2a
commit ad2088d178
94853 changed files with 43200404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
linux-7.2.3/Documentation/networking/dsa/b53.rst
+183
View File
@@ -0,0 +1,183 @@
.. SPDX-License-Identifier: GPL-2.0
==========================================
Broadcom RoboSwitch Ethernet switch driver
==========================================
The Broadcom RoboSwitch Ethernet switch family is used in quite a range of
xDSL router, cable modems and other multimedia devices.
The actual implementation supports the devices BCM5325E, BCM5365, BCM539x,
BCM53115 and BCM53125 as well as BCM63XX.
Implementation details
======================
The driver is located in ``drivers/net/dsa/b53/`` and is implemented as a
DSA driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the
subsystem and what it provides.
The switch is, if possible, configured to enable a Broadcom specific 4-bytes
switch tag which gets inserted by the switch for every packet forwarded to the
CPU interface, conversely, the CPU network interface should insert a similar
tag for packets entering the CPU port. The tag format is described in
``net/dsa/tag_brcm.c``.
The configuration of the device depends on whether or not tagging is
supported.
The interface names and example network configuration are used according the
configuration described in the :ref:`dsa-config-showcases`.
Configuration with tagging support
----------------------------------
The tagging based configuration is desired. It is not specific to the b53
DSA driver and will work like all DSA drivers which supports tagging.
See :ref:`dsa-tagged-configuration`.
Configuration without tagging support
-------------------------------------
Older models (5325, 5365) support a different tag format that is not supported
yet. 539x and 531x5 require managed mode and some special handling, which is
also not yet supported. The tagging support is disabled in these cases and the
switch need a different configuration.
The configuration slightly differ from the :ref:`dsa-vlan-configuration`.
The b53 tags the CPU port in all VLANs, since otherwise any PVID untagged
VLAN programming would basically change the CPU port's default PVID and make
it untagged, undesirable.
In difference to the configuration described in :ref:`dsa-vlan-configuration`
the default VLAN 1 has to be removed from the user interface configuration in
single port and gateway configuration, while there is no need to add an extra
VLAN configuration in the bridge showcase.
single port
~~~~~~~~~~~
The configuration can only be set up via VLAN tagging and bridge setup.
By default packages are tagged with vid 1:
.. code-block:: sh
# tag traffic on CPU port
ip link add link eth0 name eth0.1 type vlan id 1
ip link add link eth0 name eth0.2 type vlan id 2
ip link add link eth0 name eth0.3 type vlan id 3
# The conduit interface needs to be brought up before the user ports.
ip link set eth0 up
ip link set eth0.1 up
ip link set eth0.2 up
ip link set eth0.3 up
# bring up the user interfaces
ip link set wan up
ip link set lan1 up
ip link set lan2 up
# create bridge
ip link add name br0 type bridge
# activate VLAN filtering
ip link set dev br0 type bridge vlan_filtering 1
# add ports to bridges
ip link set dev wan master br0
ip link set dev lan1 master br0
ip link set dev lan2 master br0
# tag traffic on ports
bridge vlan add dev lan1 vid 2 pvid untagged
bridge vlan del dev lan1 vid 1
bridge vlan add dev lan2 vid 3 pvid untagged
bridge vlan del dev lan2 vid 1
# configure the VLANs
ip addr add 192.0.2.1/30 dev eth0.1
ip addr add 192.0.2.5/30 dev eth0.2
ip addr add 192.0.2.9/30 dev eth0.3
# bring up the bridge devices
ip link set br0 up
bridge
~~~~~~
.. code-block:: sh
# tag traffic on CPU port
ip link add link eth0 name eth0.1 type vlan id 1
# The conduit interface needs to be brought up before the user ports.
ip link set eth0 up
ip link set eth0.1 up
# bring up the user interfaces
ip link set wan up
ip link set lan1 up
ip link set lan2 up
# create bridge
ip link add name br0 type bridge
# activate VLAN filtering
ip link set dev br0 type bridge vlan_filtering 1
# add ports to bridge
ip link set dev wan master br0
ip link set dev lan1 master br0
ip link set dev lan2 master br0
ip link set eth0.1 master br0
# configure the bridge
ip addr add 192.0.2.129/25 dev br0
# bring up the bridge
ip link set dev br0 up
gateway
~~~~~~~
.. code-block:: sh
# tag traffic on CPU port
ip link add link eth0 name eth0.1 type vlan id 1
ip link add link eth0 name eth0.2 type vlan id 2
# The conduit interface needs to be brought up before the user ports.
ip link set eth0 up
ip link set eth0.1 up
ip link set eth0.2 up
# bring up the user interfaces
ip link set wan up
ip link set lan1 up
ip link set lan2 up
# create bridge
ip link add name br0 type bridge
# activate VLAN filtering
ip link set dev br0 type bridge vlan_filtering 1
# add ports to bridges
ip link set dev wan master br0
ip link set eth0.1 master br0
ip link set dev lan1 master br0
ip link set dev lan2 master br0
# tag traffic on ports
bridge vlan add dev wan vid 2 pvid untagged
bridge vlan del dev wan vid 1
# configure the VLANs
ip addr add 192.0.2.1/30 dev eth0.2
ip addr add 192.0.2.129/25 dev br0
# bring up the bridge devices
ip link set br0 up
linux-7.2.3/Documentation/networking/dsa/bcm_sf2.rst
+115
View File
@@ -0,0 +1,115 @@
=============================================
Broadcom Starfighter 2 Ethernet switch driver
=============================================
Broadcom's Starfighter 2 Ethernet switch hardware block is commonly found and
deployed in the following products:
- xDSL gateways such as BCM63138
- streaming/multimedia Set Top Box such as BCM7445
- Cable Modem/residential gateways such as BCM7145/BCM3390
The switch is typically deployed in a configuration involving between 5 to 13
ports, offering a range of built-in and customizable interfaces:
- single integrated Gigabit PHY
- quad integrated Gigabit PHY
- quad external Gigabit PHY w/ MDIO multiplexer
- integrated MoCA PHY
- several external MII/RevMII/GMII/RGMII interfaces
The switch also supports specific congestion control features which allow MoCA
fail-over not to lose packets during a MoCA role re-election, as well as out of
band back-pressure to the host CPU network interface when downstream interfaces
are connected at a lower speed.
The switch hardware block is typically interfaced using MMIO accesses and
contains a bunch of sub-blocks/registers:
- ``SWITCH_CORE``: common switch registers
- ``SWITCH_REG``: external interfaces switch register
- ``SWITCH_MDIO``: external MDIO bus controller (there is another one in SWITCH_CORE,
which is used for indirect PHY accesses)
- ``SWITCH_INDIR_RW``: 64-bits wide register helper block
- ``SWITCH_INTRL2_0/1``: Level-2 interrupt controllers
- ``SWITCH_ACB``: Admission control block
- ``SWITCH_FCB``: Fail-over control block
Implementation details
======================
The driver is located in ``drivers/net/dsa/bcm_sf2.c`` and is implemented as a DSA
driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the subsystem
and what it provides.
The SF2 switch is configured to enable a Broadcom specific 4-bytes switch tag
which gets inserted by the switch for every packet forwarded to the CPU
interface, conversely, the CPU network interface should insert a similar tag for
packets entering the CPU port. The tag format is described in
``net/dsa/tag_brcm.c``.
Overall, the SF2 driver is a fairly regular DSA driver; there are a few
specifics covered below.
Device Tree probing
-------------------
The DSA platform device driver is probed using a specific compatible string
provided in ``net/dsa/dsa.c``. The reason for that is because the DSA subsystem gets
registered as a platform device driver currently. DSA will provide the needed
device_node pointers which are then accessible by the switch driver setup
function to setup resources such as register ranges and interrupts. This
currently works very well because none of the of_* functions utilized by the
driver require a struct device to be bound to a struct device_node, but things
may change in the future.
MDIO indirect accesses
----------------------
Due to a limitation in how Broadcom switches have been designed, external
Broadcom switches connected to a SF2 require the use of the DSA user MDIO bus
in order to properly configure them. By default, the SF2 pseudo-PHY address, and
an external switch pseudo-PHY address will both be snooping for incoming MDIO
transactions, since they are at the same address (30), resulting in some kind of
"double" programming. Using DSA, and setting ``ds->phys_mii_mask`` accordingly, we
selectively divert reads and writes towards external Broadcom switches
pseudo-PHY addresses. Newer revisions of the SF2 hardware have introduced a
configurable pseudo-PHY address which circumvents the initial design limitation.
Multimedia over CoAxial (MoCA) interfaces
-----------------------------------------
MoCA interfaces are fairly specific and require the use of a firmware blob which
gets loaded onto the MoCA processor(s) for packet processing. The switch
hardware contains logic which will assert/de-assert link states accordingly for
the MoCA interface whenever the MoCA coaxial cable gets disconnected or the
firmware gets reloaded. The SF2 driver relies on such events to properly set its
MoCA interface carrier state and properly report this to the networking stack.
The MoCA interfaces are supported using the PHY library's fixed PHY/emulated PHY
device and the switch driver registers a ``fixed_link_update`` callback for such
PHYs which reflects the link state obtained from the interrupt handler.
Power Management
----------------
Whenever possible, the SF2 driver tries to minimize the overall switch power
consumption by applying a combination of:
- turning off internal buffers/memories
- disabling packet processing logic
- putting integrated PHYs in IDDQ/low-power
- reducing the switch core clock based on the active port count
- enabling and advertising EEE
- turning off RGMII data processing logic when the link goes down
Wake-on-LAN
-----------
Wake-on-LAN is currently implemented by utilizing the host processor Ethernet
MAC controller wake-on logic. Whenever Wake-on-LAN is requested, an intersection
between the user request and the supported host Ethernet interface WoL
capabilities is done and the intersection result gets configured. During
system-wide suspend/resume, only ports not participating in Wake-on-LAN are
disabled.
linux-7.2.3/Documentation/networking/dsa/configuration.rst
+458
View File
@@ -0,0 +1,458 @@
.. SPDX-License-Identifier: GPL-2.0
=======================================
DSA switch configuration from userspace
=======================================
The DSA switch configuration is not integrated into the main userspace
network configuration suites by now and has to be performed manually.
.. _dsa-config-showcases:
Configuration showcases
-----------------------
To configure a DSA switch a couple of commands need to be executed. In this
documentation some common configuration scenarios are handled as showcases:
*single port*
Every switch port acts as a different configurable Ethernet port
*bridge*
Every switch port is part of one configurable Ethernet bridge
*gateway*
Every switch port except one upstream port is part of a configurable
Ethernet bridge.
The upstream port acts as different configurable Ethernet port.
All configurations are performed with tools from iproute2, which is available
at https://www.kernel.org/pub/linux/utils/net/iproute2/
Through DSA every port of a switch is handled like a normal linux Ethernet
interface. The CPU port is the switch port connected to an Ethernet MAC chip.
The corresponding linux Ethernet interface is called the conduit interface.
All other corresponding linux interfaces are called user interfaces.
The user interfaces depend on the conduit interface being up in order for them
to send or receive traffic. Prior to kernel v5.12, the state of the conduit
interface had to be managed explicitly by the user. Starting with kernel v5.12,
the behavior is as follows:
- when a DSA user interface is brought up, the conduit interface is
automatically brought up.
- when the conduit interface is brought down, all DSA user interfaces are
automatically brought down.
In this documentation the following Ethernet interfaces are used:
*eth0*
the conduit interface
*eth1*
another conduit interface
*lan1*
a user interface
*lan2*
another user interface
*lan3*
a third user interface
*wan*
A user interface dedicated for upstream traffic
Further Ethernet interfaces can be configured similar.
The configured IPs and networks are:
*single port*
* lan1: 192.0.2.1/30 (192.0.2.0 - 192.0.2.3)
* lan2: 192.0.2.5/30 (192.0.2.4 - 192.0.2.7)
* lan3: 192.0.2.9/30 (192.0.2.8 - 192.0.2.11)
*bridge*
* br0: 192.0.2.129/25 (192.0.2.128 - 192.0.2.255)
*gateway*
* br0: 192.0.2.129/25 (192.0.2.128 - 192.0.2.255)
* wan: 192.0.2.1/30 (192.0.2.0 - 192.0.2.3)
.. _dsa-tagged-configuration:
Configuration with tagging support
----------------------------------
The tagging based configuration is desired and supported by the majority of
DSA switches. These switches are capable to tag incoming and outgoing traffic
without using a VLAN based configuration.
*single port*
.. code-block:: sh
# configure each interface
ip addr add 192.0.2.1/30 dev lan1
ip addr add 192.0.2.5/30 dev lan2
ip addr add 192.0.2.9/30 dev lan3
# For kernels earlier than v5.12, the conduit interface needs to be
# brought up manually before the user ports.
ip link set eth0 up
# bring up the user interfaces
ip link set lan1 up
ip link set lan2 up
ip link set lan3 up
*bridge*
.. code-block:: sh
# For kernels earlier than v5.12, the conduit interface needs to be
# brought up manually before the user ports.
ip link set eth0 up
# bring up the user interfaces
ip link set lan1 up
ip link set lan2 up
ip link set lan3 up
# create bridge
ip link add name br0 type bridge
# add ports to bridge
ip link set dev lan1 master br0
ip link set dev lan2 master br0
ip link set dev lan3 master br0
# configure the bridge
ip addr add 192.0.2.129/25 dev br0
# bring up the bridge
ip link set dev br0 up
*gateway*
.. code-block:: sh
# For kernels earlier than v5.12, the conduit interface needs to be
# brought up manually before the user ports.
ip link set eth0 up
# bring up the user interfaces
ip link set wan up
ip link set lan1 up
ip link set lan2 up
# configure the upstream port
ip addr add 192.0.2.1/30 dev wan
# create bridge
ip link add name br0 type bridge
# add ports to bridge
ip link set dev lan1 master br0
ip link set dev lan2 master br0
# configure the bridge
ip addr add 192.0.2.129/25 dev br0
# bring up the bridge
ip link set dev br0 up
.. _dsa-vlan-configuration:
Configuration without tagging support
-------------------------------------
A minority of switches are not capable to use a taging protocol
(DSA_TAG_PROTO_NONE). These switches can be configured by a VLAN based
configuration.
*single port*
The configuration can only be set up via VLAN tagging and bridge setup.
.. code-block:: sh
# tag traffic on CPU port
ip link add link eth0 name eth0.1 type vlan id 1
ip link add link eth0 name eth0.2 type vlan id 2
ip link add link eth0 name eth0.3 type vlan id 3
# For kernels earlier than v5.12, the conduit interface needs to be
# brought up manually before the user ports.
ip link set eth0 up
ip link set eth0.1 up
ip link set eth0.2 up
ip link set eth0.3 up
# bring up the user interfaces
ip link set lan1 up
ip link set lan2 up
ip link set lan3 up
# create bridge
ip link add name br0 type bridge
# activate VLAN filtering
ip link set dev br0 type bridge vlan_filtering 1
# add ports to bridges
ip link set dev lan1 master br0
ip link set dev lan2 master br0
ip link set dev lan3 master br0
# tag traffic on ports
bridge vlan add dev lan1 vid 1 pvid untagged
bridge vlan add dev lan2 vid 2 pvid untagged
bridge vlan add dev lan3 vid 3 pvid untagged
# configure the VLANs
ip addr add 192.0.2.1/30 dev eth0.1
ip addr add 192.0.2.5/30 dev eth0.2
ip addr add 192.0.2.9/30 dev eth0.3
# bring up the bridge devices
ip link set br0 up
*bridge*
.. code-block:: sh
# tag traffic on CPU port
ip link add link eth0 name eth0.1 type vlan id 1
# For kernels earlier than v5.12, the conduit interface needs to be
# brought up manually before the user ports.
ip link set eth0 up
ip link set eth0.1 up
# bring up the user interfaces
ip link set lan1 up
ip link set lan2 up
ip link set lan3 up
# create bridge
ip link add name br0 type bridge
# activate VLAN filtering
ip link set dev br0 type bridge vlan_filtering 1
# add ports to bridge
ip link set dev lan1 master br0
ip link set dev lan2 master br0
ip link set dev lan3 master br0
ip link set eth0.1 master br0
# tag traffic on ports
bridge vlan add dev lan1 vid 1 pvid untagged
bridge vlan add dev lan2 vid 1 pvid untagged
bridge vlan add dev lan3 vid 1 pvid untagged
# configure the bridge
ip addr add 192.0.2.129/25 dev br0
# bring up the bridge
ip link set dev br0 up
*gateway*
.. code-block:: sh
# tag traffic on CPU port
ip link add link eth0 name eth0.1 type vlan id 1
ip link add link eth0 name eth0.2 type vlan id 2
# For kernels earlier than v5.12, the conduit interface needs to be
# brought up manually before the user ports.
ip link set eth0 up
ip link set eth0.1 up
ip link set eth0.2 up
# bring up the user interfaces
ip link set wan up
ip link set lan1 up
ip link set lan2 up
# create bridge
ip link add name br0 type bridge
# activate VLAN filtering
ip link set dev br0 type bridge vlan_filtering 1
# add ports to bridges
ip link set dev wan master br0
ip link set eth0.1 master br0
ip link set dev lan1 master br0
ip link set dev lan2 master br0
# tag traffic on ports
bridge vlan add dev lan1 vid 1 pvid untagged
bridge vlan add dev lan2 vid 1 pvid untagged
bridge vlan add dev wan vid 2 pvid untagged
# configure the VLANs
ip addr add 192.0.2.1/30 dev eth0.2
ip addr add 192.0.2.129/25 dev br0
# bring up the bridge devices
ip link set br0 up
Forwarding database (FDB) management
------------------------------------
The existing DSA switches do not have the necessary hardware support to keep
the software FDB of the bridge in sync with the hardware tables, so the two
tables are managed separately (``bridge fdb show`` queries both, and depending
on whether the ``self`` or ``master`` flags are being used, a ``bridge fdb
add`` or ``bridge fdb del`` command acts upon entries from one or both tables).
Up until kernel v4.14, DSA only supported user space management of bridge FDB
entries using the bridge bypass operations (which do not update the software
FDB, just the hardware one) using the ``self`` flag (which is optional and can
be omitted).
.. code-block:: sh
bridge fdb add dev swp0 00:01:02:03:04:05 self static
# or shorthand
bridge fdb add dev swp0 00:01:02:03:04:05 static
Due to a bug, the bridge bypass FDB implementation provided by DSA did not
distinguish between ``static`` and ``local`` FDB entries (``static`` are meant
to be forwarded, while ``local`` are meant to be locally terminated, i.e. sent
to the host port). Instead, all FDB entries with the ``self`` flag (implicit or
explicit) are treated by DSA as ``static`` even if they are ``local``.
.. code-block:: sh
# This command:
bridge fdb add dev swp0 00:01:02:03:04:05 static
# behaves the same for DSA as this command:
bridge fdb add dev swp0 00:01:02:03:04:05 local
# or shorthand, because the 'local' flag is implicit if 'static' is not
# specified, it also behaves the same as:
bridge fdb add dev swp0 00:01:02:03:04:05
The last command is an incorrect way of adding a static bridge FDB entry to a
DSA switch using the bridge bypass operations, and works by mistake. Other
drivers will treat an FDB entry added by the same command as ``local`` and as
such, will not forward it, as opposed to DSA.
Between kernel v4.14 and v5.14, DSA has supported in parallel two modes of
adding a bridge FDB entry to the switch: the bridge bypass discussed above, as
well as a new mode using the ``master`` flag which installs FDB entries in the
software bridge too.
.. code-block:: sh
bridge fdb add dev swp0 00:01:02:03:04:05 master static
Since kernel v5.14, DSA has gained stronger integration with the bridge's
software FDB, and the support for its bridge bypass FDB implementation (using
the ``self`` flag) has been removed. This results in the following changes:
.. code-block:: sh
# This is the only valid way of adding an FDB entry that is supported,
# compatible with v4.14 kernels and later:
bridge fdb add dev swp0 00:01:02:03:04:05 master static
# This command is no longer buggy and the entry is properly treated as
# 'local' instead of being forwarded:
bridge fdb add dev swp0 00:01:02:03:04:05
# This command no longer installs a static FDB entry to hardware:
bridge fdb add dev swp0 00:01:02:03:04:05 static
Script writers are therefore encouraged to use the ``master static`` set of
flags when working with bridge FDB entries on DSA switch interfaces.
Affinity of user ports to CPU ports
-----------------------------------
Typically, DSA switches are attached to the host via a single Ethernet
interface, but in cases where the switch chip is discrete, the hardware design
may permit the use of 2 or more ports connected to the host, for an increase in
termination throughput.
DSA can make use of multiple CPU ports in two ways. First, it is possible to
statically assign the termination traffic associated with a certain user port
to be processed by a certain CPU port. This way, user space can implement
custom policies of static load balancing between user ports, by spreading the
affinities according to the available CPU ports.
Secondly, it is possible to perform load balancing between CPU ports on a per
packet basis, rather than statically assigning user ports to CPU ports.
This can be achieved by placing the DSA conduits under a LAG interface (bonding
or team). DSA monitors this operation and creates a mirror of this software LAG
on the CPU ports facing the physical DSA conduits that constitute the LAG slave
devices.
To make use of multiple CPU ports, the firmware (device tree) description of
the switch must mark all the links between CPU ports and their DSA conduits
using the ``ethernet`` reference/phandle. At startup, only a single CPU port
and DSA conduit will be used - the numerically first port from the firmware
description which has an ``ethernet`` property. It is up to the user to
configure the system for the switch to use other conduits.
DSA uses the ``rtnl_link_ops`` mechanism (with a "dsa" ``kind``) to allow
changing the DSA conduit of a user port. The ``IFLA_DSA_CONDUIT`` u32 netlink
attribute contains the ifindex of the conduit device that handles each user
device. The DSA conduit must be a valid candidate based on firmware node
information, or a LAG interface which contains only slaves which are valid
candidates.
Using iproute2, the following manipulations are possible:
.. code-block:: sh
# See the DSA conduit in current use
ip -d link show dev swp0
(...)
dsa master eth0
# Static CPU port distribution
ip link set swp0 type dsa master eth1
ip link set swp1 type dsa master eth0
ip link set swp2 type dsa master eth1
ip link set swp3 type dsa master eth0
# CPU ports in LAG, using explicit assignment of the DSA conduit
ip link add bond0 type bond mode balance-xor && ip link set bond0 up
ip link set eth1 down && ip link set eth1 master bond0
ip link set swp0 type dsa master bond0
ip link set swp1 type dsa master bond0
ip link set swp2 type dsa master bond0
ip link set swp3 type dsa master bond0
ip link set eth0 down && ip link set eth0 master bond0
ip -d link show dev swp0
(...)
dsa master bond0
# CPU ports in LAG, relying on implicit migration of the DSA conduit
ip link add bond0 type bond mode balance-xor && ip link set bond0 up
ip link set eth0 down && ip link set eth0 master bond0
ip link set eth1 down && ip link set eth1 master bond0
ip -d link show dev swp0
(...)
dsa master bond0
Notice that in the case of CPU ports under a LAG, the use of the
``IFLA_DSA_CONDUIT`` netlink attribute is not strictly needed, but rather, DSA
reacts to the ``IFLA_MASTER`` attribute change of its present conduit (``eth0``)
and migrates all user ports to the new upper of ``eth0``, ``bond0``. Similarly,
when ``bond0`` is destroyed using ``RTM_DELLINK``, DSA migrates the user ports
that were assigned to this interface to the first physical DSA conduit which is
eligible, based on the firmware description (it effectively reverts to the
startup configuration).
In a setup with more than 2 physical CPU ports, it is therefore possible to mix
static user to CPU port assignment with LAG between DSA conduits. It is not
possible to statically assign a user port towards a DSA conduit that has any
upper interfaces (this includes LAG devices - the conduit must always be the LAG
in this case).
Live changing of the DSA conduit (and thus CPU port) affinity of a user port is
permitted, in order to allow dynamic redistribution in response to traffic.
Physical DSA conduits are allowed to join and leave at any time a LAG interface
used as a DSA conduit; however, DSA will reject a LAG interface as a valid
candidate for being a DSA conduit unless it has at least one physical DSA conduit
as a slave device.
linux-7.2.3/Documentation/networking/dsa/dsa.rst
+1135
View File
File diff suppressed because it is too large Load Diff
linux-7.2.3/Documentation/networking/dsa/index.rst
+13
View File
@@ -0,0 +1,13 @@
===============================
Distributed Switch Architecture
===============================
.. toctree::
:maxdepth: 1
dsa
b53
bcm_sf2
lan9303
sja1105
configuration
linux-7.2.3/Documentation/networking/dsa/lan9303.rst
+37
View File
@@ -0,0 +1,37 @@
==============================
LAN9303 Ethernet switch driver
==============================
The LAN9303 is a three port 10/100 Mbps ethernet switch with integrated phys for
the two external ethernet ports. The third port is an RMII/MII interface to a
host conduit network interface (e.g. fixed link).
Driver details
==============
The driver is implemented as a DSA driver, see ``Documentation/networking/dsa/dsa.rst``.
See ``Documentation/devicetree/bindings/net/dsa/smsc,lan9303.yaml`` for device tree
binding.
The LAN9303 can be managed both via MDIO and I2C, both supported by this driver.
At startup the driver configures the device to provide two separate network
interfaces (which is the default state of a DSA device). Due to HW limitations,
no HW MAC learning takes place in this mode.
When both user ports are joined to the same bridge, the normal HW MAC learning
is enabled. This means that unicast traffic is forwarded in HW. Broadcast and
multicast is flooded in HW. STP is also supported in this mode. The driver
support fdb/mdb operations as well, meaning IGMP snooping is supported.
If one of the user ports leave the bridge, the ports goes back to the initial
separated operation.
Driver limitations
==================
- Support for VLAN filtering is not implemented
- The HW does not support VLAN-specific fdb entries
linux-7.2.3/Documentation/networking/dsa/sja1105.rst
+445
View File
@@ -0,0 +1,445 @@
=========================
NXP SJA1105 switch driver
=========================
Overview
========
The NXP SJA1105 is a family of 10 SPI-managed automotive switches:
- SJA1105E: First generation, no TTEthernet
- SJA1105T: First generation, TTEthernet
- SJA1105P: Second generation, no TTEthernet, no SGMII
- SJA1105Q: Second generation, TTEthernet, no SGMII
- SJA1105R: Second generation, no TTEthernet, SGMII
- SJA1105S: Second generation, TTEthernet, SGMII
- SJA1110A: Third generation, TTEthernet, SGMII, integrated 100base-T1 and
100base-TX PHYs
- SJA1110B: Third generation, TTEthernet, SGMII, 100base-T1, 100base-TX
- SJA1110C: Third generation, TTEthernet, SGMII, 100base-T1, 100base-TX
- SJA1110D: Third generation, TTEthernet, SGMII, 100base-T1
Being automotive parts, their configuration interface is geared towards
set-and-forget use, with minimal dynamic interaction at runtime. They
require a static configuration to be composed by software and packed
with CRC and table headers, and sent over SPI.
The static configuration is composed of several configuration tables. Each
table takes a number of entries. Some configuration tables can be (partially)
reconfigured at runtime, some not. Some tables are mandatory, some not:
============================= ================== =============================
Table Mandatory Reconfigurable
============================= ================== =============================
Schedule no no
Schedule entry points if Scheduling no
VL Lookup no no
VL Policing if VL Lookup no
VL Forwarding if VL Lookup no
L2 Lookup no no
L2 Policing yes no
VLAN Lookup yes yes
L2 Forwarding yes partially (fully on P/Q/R/S)
MAC Config yes partially (fully on P/Q/R/S)
Schedule Params if Scheduling no
Schedule Entry Points Params if Scheduling no
VL Forwarding Params if VL Forwarding no
L2 Lookup Params no partially (fully on P/Q/R/S)
L2 Forwarding Params yes no
Clock Sync Params no no
AVB Params no no
General Params yes partially
Retagging no yes
xMII Params yes no
SGMII no yes
============================= ================== =============================
Also the configuration is write-only (software cannot read it back from the
switch except for very few exceptions).
The driver creates a static configuration at probe time, and keeps it at
all times in memory, as a shadow for the hardware state. When required to
change a hardware setting, the static configuration is also updated.
If that changed setting can be transmitted to the switch through the dynamic
reconfiguration interface, it is; otherwise the switch is reset and
reprogrammed with the updated static configuration.
Switching features
==================
The driver supports the configuration of L2 forwarding rules in hardware for
port bridging. The forwarding, broadcast and flooding domain between ports can
be restricted through two methods: either at the L2 forwarding level (isolate
one bridge's ports from another's) or at the VLAN port membership level
(isolate ports within the same bridge). The final forwarding decision taken by
the hardware is a logical AND of these two sets of rules.
The hardware tags all traffic internally with a port-based VLAN (pvid), or it
decodes the VLAN information from the 802.1Q tag. Advanced VLAN classification
is not possible. Once attributed a VLAN tag, frames are checked against the
port's membership rules and dropped at ingress if they don't match any VLAN.
This behavior is available when switch ports join a bridge with
``vlan_filtering 1``.
Normally the hardware is not configurable with respect to VLAN awareness, but
by changing what TPID the switch searches 802.1Q tags for, the semantics of a
bridge with ``vlan_filtering 0`` can be kept (accept all traffic, tagged or
untagged), and therefore this mode is also supported.
Segregating the switch ports in multiple bridges is supported (e.g. 2 + 2), but
all bridges should have the same level of VLAN awareness (either both have
``vlan_filtering`` 0, or both 1).
Topology and loop detection through STP is supported.
Offloads
========
Time-aware scheduling
---------------------
The switch supports a variation of the enhancements for scheduled traffic
specified in IEEE 802.1Q-2018 (formerly 802.1Qbv). This means it can be used to
ensure deterministic latency for priority traffic that is sent in-band with its
gate-open event in the network schedule.
This capability can be managed through the tc-taprio offload ('flags 2'). The
difference compared to the software implementation of taprio is that the latter
would only be able to shape traffic originated from the CPU, but not
autonomously forwarded flows.
The device has 8 traffic classes, and maps incoming frames to one of them based
on the VLAN PCP bits (if no VLAN is present, the port-based default is used).
As described in the previous sections, depending on the value of
``vlan_filtering``, the EtherType recognized by the switch as being VLAN can
either be the typical 0x8100 or a custom value used internally by the driver
for tagging. Therefore, the switch ignores the VLAN PCP if used in standalone
or bridge mode with ``vlan_filtering=0``, as it will not recognize the 0x8100
EtherType. In these modes, injecting into a particular TX queue can only be
done by the DSA net devices, which populate the PCP field of the tagging header
on egress. Using ``vlan_filtering=1``, the behavior is the other way around:
offloaded flows can be steered to TX queues based on the VLAN PCP, but the DSA
net devices are no longer able to do that. To inject frames into a hardware TX
queue with VLAN awareness active, it is necessary to create a VLAN
sub-interface on the DSA conduit port, and send normal (0x8100) VLAN-tagged
towards the switch, with the VLAN PCP bits set appropriately.
Management traffic (having DMAC 01-80-C2-xx-xx-xx or 01-19-1B-xx-xx-xx) is the
notable exception: the switch always treats it with a fixed priority and
disregards any VLAN PCP bits even if present. The traffic class for management
traffic has a value of 7 (highest priority) at the moment, which is not
configurable in the driver.
Below is an example of configuring a 500 us cyclic schedule on egress port
``swp5``. The traffic class gate for management traffic (7) is open for 100 us,
and the gates for all other traffic classes are open for 400 us::
#!/bin/bash
set -e -u -o pipefail
NSEC_PER_SEC="1000000000"
gatemask() {
local tc_list="$1"
local mask=0
for tc in ${tc_list}; do
mask=$((${mask} | (1 << ${tc})))
done
printf "%02x" ${mask}
}
if ! systemctl is-active --quiet ptp4l; then
echo "Please start the ptp4l service"
exit
fi
now=$(phc_ctl /dev/ptp1 get | gawk '/clock time is/ { print $5; }')
# Phase-align the base time to the start of the next second.
sec=$(echo "${now}" | gawk -F. '{ print $1; }')
base_time="$(((${sec} + 1) * ${NSEC_PER_SEC}))"
tc qdisc add dev swp5 parent root handle 100 taprio \
num_tc 8 \
map 0 1 2 3 5 6 7 \
queues 1@0 1@1 1@2 1@3 1@4 1@5 1@6 1@7 \
base-time ${base_time} \
sched-entry S $(gatemask 7) 100000 \
sched-entry S $(gatemask "0 1 2 3 4 5 6") 400000 \
flags 2
It is possible to apply the tc-taprio offload on multiple egress ports. There
are hardware restrictions related to the fact that no gate event may trigger
simultaneously on two ports. The driver checks the consistency of the schedules
against this restriction and errors out when appropriate. Schedule analysis is
needed to avoid this, which is outside the scope of the document.
Routing actions (redirect, trap, drop)
--------------------------------------
The switch is able to offload flow-based redirection of packets to a set of
destination ports specified by the user. Internally, this is implemented by
making use of Virtual Links, a TTEthernet concept.
The driver supports 2 types of keys for Virtual Links:
- VLAN-aware virtual links: these match on destination MAC address, VLAN ID and
VLAN PCP.
- VLAN-unaware virtual links: these match on destination MAC address only.
The VLAN awareness state of the bridge (vlan_filtering) cannot be changed while
there are virtual link rules installed.
Composing multiple actions inside the same rule is supported. When only routing
actions are requested, the driver creates a "non-critical" virtual link. When
the action list also contains tc-gate (more details below), the virtual link
becomes "time-critical" (draws frame buffers from a reserved memory partition,
etc).
The 3 routing actions that are supported are "trap", "drop" and "redirect".
Example 1: send frames received on swp2 with a DA of 42:be:24:9b:76:20 to the
CPU and to swp3. This type of key (DA only) when the port's VLAN awareness
state is off::
tc qdisc add dev swp2 clsact
tc filter add dev swp2 ingress flower skip_sw dst_mac 42:be:24:9b:76:20 \
action mirred egress redirect dev swp3 \
action trap
Example 2: drop frames received on swp2 with a DA of 42:be:24:9b:76:20, a VID
of 100 and a PCP of 0::
tc filter add dev swp2 ingress protocol 802.1Q flower skip_sw \
dst_mac 42:be:24:9b:76:20 vlan_id 100 vlan_prio 0 action drop
Time-based ingress policing
---------------------------
The TTEthernet hardware abilities of the switch can be constrained to act
similarly to the Per-Stream Filtering and Policing (PSFP) clause specified in
IEEE 802.1Q-2018 (formerly 802.1Qci). This means it can be used to perform
tight timing-based admission control for up to 1024 flows (identified by a
tuple composed of destination MAC address, VLAN ID and VLAN PCP). Packets which
are received outside their expected reception window are dropped.
This capability can be managed through the offload of the tc-gate action. As
routing actions are intrinsic to virtual links in TTEthernet (which performs
explicit routing of time-critical traffic and does not leave that in the hands
of the FDB, flooding etc), the tc-gate action may never appear alone when
asking sja1105 to offload it. One (or more) redirect or trap actions must also
follow along.
Example: create a tc-taprio schedule that is phase-aligned with a tc-gate
schedule (the clocks must be synchronized by a 1588 application stack, which is
outside the scope of this document). No packet delivered by the sender will be
dropped. Note that the reception window is larger than the transmission window
(and much more so, in this example) to compensate for the packet propagation
delay of the link (which can be determined by the 1588 application stack).
Receiver (sja1105)::
tc qdisc add dev swp2 clsact
now=$(phc_ctl /dev/ptp1 get | awk '/clock time is/ {print $5}') && \
sec=$(echo $now | awk -F. '{print $1}') && \
base_time="$(((sec + 2) * 1000000000))" && \
echo "base time ${base_time}"
tc filter add dev swp2 ingress flower skip_sw \
dst_mac 42:be:24:9b:76:20 \
action gate base-time ${base_time} \
sched-entry OPEN 60000 -1 -1 \
sched-entry CLOSE 40000 -1 -1 \
action trap
Sender::
now=$(phc_ctl /dev/ptp0 get | awk '/clock time is/ {print $5}') && \
sec=$(echo $now | awk -F. '{print $1}') && \
base_time="$(((sec + 2) * 1000000000))" && \
echo "base time ${base_time}"
tc qdisc add dev eno0 parent root taprio \
num_tc 8 \
map 0 1 2 3 4 5 6 7 \
queues 1@0 1@1 1@2 1@3 1@4 1@5 1@6 1@7 \
base-time ${base_time} \
sched-entry S 01 50000 \
sched-entry S 00 50000 \
flags 2
The engine used to schedule the ingress gate operations is the same that the
one used for the tc-taprio offload. Therefore, the restrictions regarding the
fact that no two gate actions (either tc-gate or tc-taprio gates) may fire at
the same time (during the same 200 ns slot) still apply.
To come in handy, it is possible to share time-triggered virtual links across
more than 1 ingress port, via flow blocks. In this case, the restriction of
firing at the same time does not apply because there is a single schedule in
the system, that of the shared virtual link::
tc qdisc add dev swp2 ingress_block 1 clsact
tc qdisc add dev swp3 ingress_block 1 clsact
tc filter add block 1 flower skip_sw dst_mac 42:be:24:9b:76:20 \
action gate index 2 \
base-time 0 \
sched-entry OPEN 50000000 -1 -1 \
sched-entry CLOSE 50000000 -1 -1 \
action trap
Hardware statistics for each flow are also available ("pkts" counts the number
of dropped frames, which is a sum of frames dropped due to timing violations,
lack of destination ports and MTU enforcement checks). Byte-level counters are
not available.
Limitations
===========
The SJA1105 switch family always performs VLAN processing. When configured as
VLAN-unaware, frames carry a different VLAN tag internally, depending on
whether the port is standalone or under a VLAN-unaware bridge.
The virtual link keys are always fixed at {MAC DA, VLAN ID, VLAN PCP}, but the
driver asks for the VLAN ID and VLAN PCP when the port is under a VLAN-aware
bridge. Otherwise, it fills in the VLAN ID and PCP automatically, based on
whether the port is standalone or in a VLAN-unaware bridge, and accepts only
"VLAN-unaware" tc-flower keys (MAC DA).
The existing tc-flower keys that are offloaded using virtual links are no
longer operational after one of the following happens:
- port was standalone and joins a bridge (VLAN-aware or VLAN-unaware)
- port is part of a bridge whose VLAN awareness state changes
- port was part of a bridge and becomes standalone
- port was standalone, but another port joins a VLAN-aware bridge and this
changes the global VLAN awareness state of the bridge
The driver cannot veto all these operations, and it cannot update/remove the
existing tc-flower filters either. So for proper operation, the tc-flower
filters should be installed only after the forwarding configuration of the port
has been made, and removed by user space before making any changes to it.
Device Tree bindings and board design
=====================================
This section references ``Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml``
and aims to showcase some potential switch caveats.
RMII PHY role and out-of-band signaling
---------------------------------------
In the RMII spec, the 50 MHz clock signals are either driven by the MAC or by
an external oscillator (but not by the PHY).
But the spec is rather loose and devices go outside it in several ways.
Some PHYs go against the spec and may provide an output pin where they source
the 50 MHz clock themselves, in an attempt to be helpful.
On the other hand, the SJA1105 is only binary configurable - when in the RMII
MAC role it will also attempt to drive the clock signal. To prevent this from
happening it must be put in RMII PHY role.
But doing so has some unintended consequences.
In the RMII spec, the PHY can transmit extra out-of-band signals via RXD[1:0].
These are practically some extra code words (/J/ and /K/) sent prior to the
preamble of each frame. The MAC does not have this out-of-band signaling
mechanism defined by the RMII spec.
So when the SJA1105 port is put in PHY role to avoid having 2 drivers on the
clock signal, inevitably an RMII PHY-to-PHY connection is created. The SJA1105
emulates a PHY interface fully and generates the /J/ and /K/ symbols prior to
frame preambles, which the real PHY is not expected to understand. So the PHY
simply encodes the extra symbols received from the SJA1105-as-PHY onto the
100Base-Tx wire.
On the other side of the wire, some link partners might discard these extra
symbols, while others might choke on them and discard the entire Ethernet
frames that follow along. This looks like packet loss with some link partners
but not with others.
The take-away is that in RMII mode, the SJA1105 must be let to drive the
reference clock if connected to a PHY.
RGMII fixed-link and internal delays
------------------------------------
As mentioned in the bindings document, the second generation of devices has
tunable delay lines as part of the MAC, which can be used to establish the
correct RGMII timing budget.
When powered up, these can shift the Rx and Tx clocks with a phase difference
between 73.8 and 101.7 degrees.
The catch is that the delay lines need to lock onto a clock signal with a
stable frequency. This means that there must be at least 2 microseconds of
silence between the clock at the old vs at the new frequency. Otherwise the
lock is lost and the delay lines must be reset (powered down and back up).
In RGMII the clock frequency changes with link speed (125 MHz at 1000 Mbps, 25
MHz at 100 Mbps and 2.5 MHz at 10 Mbps), and link speed might change during the
AN process.
In the situation where the switch port is connected through an RGMII fixed-link
to a link partner whose link state life cycle is outside the control of Linux
(such as a different SoC), then the delay lines would remain unlocked (and
inactive) until there is manual intervention (ifdown/ifup on the switch port).
The take-away is that in RGMII mode, the switch's internal delays are only
reliable if the link partner never changes link speeds, or if it does, it does
so in a way that is coordinated with the switch port (practically, both ends of
the fixed-link are under control of the same Linux system).
As to why would a fixed-link interface ever change link speeds: there are
Ethernet controllers out there which come out of reset in 100 Mbps mode, and
their driver inevitably needs to change the speed and clock frequency if it's
required to work at gigabit.
MDIO bus and PHY management
---------------------------
The SJA1105 does not have an MDIO bus and does not perform in-band AN either.
Therefore there is no link state notification coming from the switch device.
A board would need to hook up the PHYs connected to the switch to any other
MDIO bus available to Linux within the system (e.g. to the DSA conduit's MDIO
bus). Link state management then works by the driver manually keeping in sync
(over SPI commands) the MAC link speed with the settings negotiated by the PHY.
By comparison, the SJA1110 supports an MDIO slave access point over which its
internal 100base-T1 PHYs can be accessed from the host. This is, however, not
used by the driver, instead the internal 100base-T1 and 100base-TX PHYs are
accessed through SPI commands, modeled in Linux as virtual MDIO buses.
The microcontroller attached to the SJA1110 port 0 also has an MDIO controller
operating in master mode, however the driver does not support this either,
since the microcontroller gets disabled when the Linux driver operates.
Discrete PHYs connected to the switch ports should have their MDIO interface
attached to an MDIO controller from the host system and not to the switch,
similar to SJA1105.
Port compatibility matrix
-------------------------
The SJA1105 port compatibility matrix is:
===== ============== ============== ==============
Port SJA1105E/T SJA1105P/Q SJA1105R/S
===== ============== ============== ==============
0 xMII xMII xMII
1 xMII xMII xMII
2 xMII xMII xMII
3 xMII xMII xMII
4 xMII xMII SGMII
===== ============== ============== ==============
The SJA1110 port compatibility matrix is:
===== ============== ============== ============== ==============
Port SJA1110A SJA1110B SJA1110C SJA1110D
===== ============== ============== ============== ==============
0 RevMII (uC) RevMII (uC) RevMII (uC) RevMII (uC)
1 100base-TX 100base-TX 100base-TX
or SGMII SGMII
2 xMII xMII xMII xMII
or SGMII or SGMII
3 xMII xMII xMII
or SGMII or SGMII SGMII
or 2500base-X or 2500base-X or 2500base-X
4 SGMII SGMII SGMII SGMII
or 2500base-X or 2500base-X or 2500base-X or 2500base-X
5 100base-T1 100base-T1 100base-T1 100base-T1
6 100base-T1 100base-T1 100base-T1 100base-T1
7 100base-T1 100base-T1 100base-T1 100base-T1
8 100base-T1 100base-T1 n/a n/a
9 100base-T1 100base-T1 n/a n/a
10 100base-T1 n/a n/a n/a
===== ============== ============== ============== ==============