Commit 6ca80638 authored by Florian Fainelli's avatar Florian Fainelli Committed by Jakub Kicinski
Browse files

net: dsa: Use conduit and user terms 



Use more inclusive terms throughout the DSA subsystem by moving away
from "master" which is replaced by "conduit" and "slave" which is
replaced by "user". No functional changes.

Acked-by: default avatarRob Herring <robh@kernel.org>
Acked-by: default avatarStephen Hemminger <stephen@networkplumber.org>
Reviewed-by: default avatarVladimir Oltean <vladimir.oltean@nxp.com>
Signed-off-by: default avatarFlorian Fainelli <florian.fainelli@broadcom.com>
Link: https://lore.kernel.org/r/20231023181729.1191071-2-florian.fainelli@broadcom.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent 00e984cb

Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml

+1 −1
Original line number Diff line number Diff line
@@ -60,7 +60,7 @@ description: | 


      Check out example 6.



    - Port 5 can be wired to an external phy. Port 5 becomes a DSA slave.

    - Port 5 can be wired to an external phy. Port 5 becomes a DSA user port.



      For the multi-chip module MT7530, the external phy must be wired TX to TX

      to gmac1 of the SoC for this to work. Ubiquiti EdgeRouter X SFP is wired

Documentation/networking/dsa/b53.rst

+7 −7
Original line number Diff line number Diff line
@@ -52,7 +52,7 @@ 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 slave interface configuration in

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.
@@ -68,13 +68,13 @@ By default packages are tagged with vid 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 master interface needs to be brought up before the slave ports.

  # 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 slave interfaces

  # bring up the user interfaces

  ip link set wan up

  ip link set lan1 up

  ip link set lan2 up
@@ -113,11 +113,11 @@ bridge 
  # tag traffic on CPU port

  ip link add link eth0 name eth0.1 type vlan id 1



  # The master interface needs to be brought up before the slave ports.

  # 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 slave interfaces

  # bring up the user interfaces

  ip link set wan up

  ip link set lan1 up

  ip link set lan2 up
@@ -149,12 +149,12 @@ gateway 
  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 master interface needs to be brought up before the slave ports.

  # 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 slave interfaces

  # bring up the user interfaces

  ip link set wan up

  ip link set lan1 up

  ip link set lan2 up

Documentation/networking/dsa/bcm_sf2.rst

+1 −1
Original line number Diff line number Diff line
@@ -67,7 +67,7 @@ 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 slave MDIO bus

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

Documentation/networking/dsa/configuration.rst

+50 −50
Original line number Diff line number Diff line
@@ -31,38 +31,38 @@ 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 master interface.

All other corresponding linux interfaces are called slave interfaces.

The corresponding linux Ethernet interface is called the conduit interface.

All other corresponding linux interfaces are called user interfaces.



The slave interfaces depend on the master interface being up in order for them

to send or receive traffic. Prior to kernel v5.12, the state of the master

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 slave interface is brought up, the master interface is

- when a DSA user interface is brought up, the conduit interface is

  automatically brought up.

- when the master interface is brought down, all DSA slave interfaces are

- 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 master interface

  the conduit interface



*eth1*

  another master interface

  another conduit interface



*lan1*

  a slave interface

  a user interface



*lan2*

  another slave interface

  another user interface



*lan3*

  a third slave interface

  a third user interface



*wan*

  A slave interface dedicated for upstream traffic

  A user interface dedicated for upstream traffic



Further Ethernet interfaces can be configured similar.

The configured IPs and networks are:
@@ -96,11 +96,11 @@ without using a VLAN based configuration. 
    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 master interface needs to be

    # brought up manually before the slave ports.

    # 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 slave interfaces

    # bring up the user interfaces

    ip link set lan1 up

    ip link set lan2 up

    ip link set lan3 up
@@ -108,11 +108,11 @@ without using a VLAN based configuration. 
*bridge*

  .. code-block:: sh



    # For kernels earlier than v5.12, the master interface needs to be

    # brought up manually before the slave ports.

    # 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 slave interfaces

    # bring up the user interfaces

    ip link set lan1 up

    ip link set lan2 up

    ip link set lan3 up
@@ -134,11 +134,11 @@ without using a VLAN based configuration. 
*gateway*

  .. code-block:: sh



    # For kernels earlier than v5.12, the master interface needs to be

    # brought up manually before the slave ports.

    # 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 slave interfaces

    # bring up the user interfaces

    ip link set wan up

    ip link set lan1 up

    ip link set lan2 up
@@ -178,14 +178,14 @@ configuration. 
    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 master interface needs to be

    # brought up manually before the slave ports.

    # 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 slave interfaces

    # bring up the user interfaces

    ip link set lan1 up

    ip link set lan2 up

    ip link set lan3 up
@@ -221,12 +221,12 @@ configuration. 
    # tag traffic on CPU port

    ip link add link eth0 name eth0.1 type vlan id 1



    # For kernels earlier than v5.12, the master interface needs to be

    # brought up manually before the slave ports.

    # 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 slave interfaces

    # bring up the user interfaces

    ip link set lan1 up

    ip link set lan2 up

    ip link set lan3 up
@@ -261,13 +261,13 @@ configuration. 
    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 master interface needs to be

    # brought up manually before the slave ports.

    # 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 slave interfaces

    # bring up the user interfaces

    ip link set wan up

    ip link set lan1 up

    ip link set lan2 up
@@ -380,22 +380,22 @@ 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 masters under a LAG interface (bonding

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 masters that constitute the LAG slave

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 masters

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 master will be used - the numerically first port from the firmware

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 masters.

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 master of a user port. The ``IFLA_DSA_MASTER`` u32 netlink

attribute contains the ifindex of the master device that handles each slave

device. The DSA master must be a valid candidate based on firmware node

changing the DSA conduit of a user port. The ``IFLA_DSA_MASTER`` 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.
@@ -403,7 +403,7 @@ Using iproute2, the following manipulations are possible: 


  .. code-block:: sh



    # See the DSA master in current use

    # See the DSA conduit in current use

    ip -d link show dev swp0

        (...)

        dsa master eth0
@@ -414,7 +414,7 @@ Using iproute2, the following manipulations are possible: 
    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 master

    # 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
@@ -426,7 +426,7 @@ Using iproute2, the following manipulations are possible: 
        (...)

        dsa master bond0



    # CPU ports in LAG, relying on implicit migration of the DSA master

    # 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
@@ -436,23 +436,23 @@ Using iproute2, the following manipulations are possible: 


Notice that in the case of CPU ports under a LAG, the use of the

``IFLA_DSA_MASTER`` netlink attribute is not strictly needed, but rather, DSA

reacts to the ``IFLA_MASTER`` attribute change of its present master (``eth0``)

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 master which is

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 masters. It is not

possible to statically assign a user port towards a DSA master that has any

upper interfaces (this includes LAG devices - the master must always be the LAG

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 master (and thus CPU port) affinity of a user port is

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 masters are allowed to join and leave at any time a LAG interface

used as a DSA master; however, DSA will reject a LAG interface as a valid

candidate for being a DSA master unless it has at least one physical DSA master

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.

Documentation/networking/dsa/dsa.rst

+83 −79

File changed.

Preview size limit exceeded, changes collapsed.