networking/dsa/dsa.rst

5 This document describes the **Distributed Switch Architecture (DSA)** subsystem
23 or more CPU or management ports. The DSA subsystem currently relies on the
28 be later referred to as "master" and "cpu" in DSA terminology and code.
30 The D in DSA stands for Distributed, because the subsystem has been designed
33 ports are referred to as "dsa" ports in DSA terminology and code. A collection
36 For each front-panel port, DSA creates specialized network devices which are
39 interfaces in DSA terminology and code.
41 The ideal case for using DSA is when an Ethernet switch supports a "switch tag"
54 Note that DSA does not currently create network interfaces for the "cpu" and
68 DSA supports many vendor-specific tagging protocols, one software-defined
83    shifting to the right (from the perspective of the DSA master's frame
86    the MAC DA and MAC SA in place from the DSA master's perspective, but
90    that the DSA master's frame parser has.
97 with the length in octets of the longest switch frame header/trailer. The DSA
99 accommodate for this extra size in order for DSA user ports to support the
106 Even though applications are not expected to parse DSA-specific frame headers,
116 From the perspective of the network stack, all switches within the same DSA
130 CPU port can be configured to use either the DSA or the Ethertype DSA (EDSA)
131 format, but the DSA links are configured to use the shorter (without Ethertype)
132 DSA frame header, in order to reduce the autonomous packet forwarding overhead.
133 It still remains the case that, if the DSA switch tree is configured for the
135 leaf switches that tagged them with the shorter DSA header. This can be done
137 perform tag translation between DSA and EDSA (which is simply the operation of
140 It is possible to construct cascaded setups of DSA switches even if their
142 no DSA links in this fabric, and each switch constitutes a disjoint DSA switch
143 tree. The DSA links are viewed as simply a pair of a DSA master (the out-facing
144 port of the upstream DSA switch) and a CPU port (the in-facing port of the
145 downstream DSA switch).
147 The tagging protocol of the attached DSA switch tree can be viewed through the
148 ``dsa/tagging`` sysfs attribute of the DSA master::
152 If the hardware and driver are capable, the tagging protocol of the DSA switch
154 protocol name to the same sysfs device attribute as above (the DSA master and
162 for the DSA master.
167 ``struct net_device *dev`` represents the virtual DSA user network interface
174 properly, because DSA ensures there is enough space before calling this method.
182 virtual DSA user network interface corresponding to the physical front-facing
186 hardware) packet dissection on the DSA master, features such as RPS (Receive
187 Packet Steering) on the DSA master would be broken. The DSA framework deals
189 the IP header is to be found in the tagged frame as seen by the DSA master.
196 Checksum offload should work with category 1 and 2 taggers when the DSA master
198 csum_offset. For those cases, DSA will shift the checksum start and offset by
199 the tag size. If the DSA master driver still uses the legacy NETIF_F_IP_CSUM
202 vendors). DSA slaves inherit those flags from the master port, and it is up to
208 tag is inserted (i.e. inside the tagger). Otherwise, the DSA master would
214 with DSA-unaware masters, mangling what the master perceives as MAC DA), the
215 tagging protocol may require the DSA master to operate in promiscuous mode, to
218 Note that this assumes a DSA-unaware master driver, which is the norm.
225 know whether DSA is enabled (e.g.: to enable/disable specific offload features),
226 but the DSA subsystem has been proven to work with industry standard drivers:
235 When a master netdev is used with DSA, a small hook is placed in the
236 networking stack is in order to have the DSA subsystem process the Ethernet
237 switch specific tagging protocol. DSA accomplishes this by registering a
272         - invoke ``eth_type_trans()`` with the DSA slave network device
275 Past this point, the DSA slave network devices get delivered regular Ethernet
281 Slave network devices created by DSA are stacked on top of their master network
293 pointers which allow DSA to introduce a level of layering between the networking
296 Upon frame transmission from these slave network devices, DSA will look up which
307 device between the DSA slave devices and the physical DSA masters. The LAG
308 device is thus also a DSA master, but the LAG slave devices continue to be DSA
310 recovery in case the LAG DSA master disappears). Thus, the data path of the LAG
311 DSA master is used asymmetrically. On RX, the ``ETH_P_XDSA`` handler, which
312 calls ``dsa_switch_rcv()``, is invoked early (on the physical DSA master;
313 LAG slave). Therefore, the RX data path of the LAG DSA master is not used.
315 ``dsa_enqueue_skb``, which calls ``dev_queue_xmit`` towards the LAG DSA master.
316 The latter calls ``dev_queue_xmit`` towards one physical DSA master or the
323 Summarized, this is basically how DSA looks like from a network device
334            |          DSA switch driver        |
358 In order to be able to read to/from a switch PHY built into it, DSA creates a
374 DSA data structures are defined in ``include/net/dsa.h`` as well as
404 Lack of CPU/DSA network devices
407 DSA does not currently create slave network devices for the CPU or DSA ports, as
419 Common pitfalls using DSA setups
422 Once a master network device is configured to use DSA (dev->dsa_ptr becomes
433 DSA currently leverages the following subsystems:
443 Slave network devices exposed by DSA may or may not be interfacing with PHY
444 devices (``struct phy_device`` as defined in ``include/linux/phy.h)``, but the DSA
467   by DSA
473 DSA directly utilizes SWITCHDEV when interfacing with the bridge layer, and
476 supported by DSA are the FDB and VLAN objects.
481 DSA registers one devlink device per physical switch in the fabric.
482 For each devlink device, every physical port (i.e. user ports, CPU ports, DSA
485 DSA drivers can make use of the following devlink features:
512 DSA features a standardized binding which is documented in
520 DSA switch drivers need to implement a ``dsa_switch_ops`` structure which will
526 DSA switches are regular ``device`` structures on buses (be they platform, SPI,
527 I2C, MDIO or otherwise). The DSA framework is not involved in their probing
540 - ``ds->ops``: a pointer to the ``dsa_switch_ops`` structure holding the DSA
544   retrieved in all further DSA method callbacks.
547 be configured to obtain driver-specific behavior from the DSA core. Their
564 Internally, DSA keeps an array of switch trees (group of switches) global to
579 DSA links are present in the tree's port list). The tree becomes complete when
589 It is mandatory for DSA switch drivers to implement the ``shutdown()`` callback
592 The reason is that DSA keeps a reference on the master net device, and if the
593 driver for the master device decides to unbind on shutdown, DSA's reference
643   PHY cannot be found. In this case, probing of the DSA switch continues
653   the new DSA master ``net_device``. The CPU port associated with the new
656   all the slave devices are physical DSA masters. LAG DSA masters also have a
658   duplicate of the first physical DSA master's (LAG slave) ``dsa_ptr``. In case
659   of a LAG DSA master, a further call to ``port_lag_join`` will be emitted
660   separately for the physical CPU ports associated with the physical DSA
673 - ``phy_read``: Function invoked by the DSA slave MDIO bus when attempting to read
678 - ``phy_write``: Function invoked by the DSA slave MDIO bus when attempting to write
701   return their values. DSA overlays slave network devices general statistics:
741 - ``suspend``: function invoked by the DSA platform device when the system goes to
746 - ``resume``: function invoked by the DSA platform device when the system resumes,
750 - ``port_enable``: function invoked by the DSA slave network device ndo_open
752   fully enable a given switch port. DSA takes care of marking the port with
756 - ``port_disable``: function invoked by the DSA slave network device ndo_close
758   fully disable a given switch port. DSA takes care of marking the port with
811 DSA (cascade) and CPU ports are also called "shared" ports because they service
813 to is usually embedded in the DSA tag. This means that the CPU port may
825 DSA is able to perform host address filtering for the following kinds of
842 - Static bridge FDB entries installed towards foreign (non-DSA) interfaces
843   present in the same bridge as some DSA switch ports. These are also
847   bridge as some DSA switch ports, only if ``ds->assisted_learning_on_cpu_port``
851 For various operations detailed below, DSA provides a ``dsa_db`` structure
865 DSA associates each offloaded bridge and each offloaded LAG with a one-based ID
867 refcounting addresses on shared ports. Drivers may piggyback on DSA's numbering
884 another port) becomes the responsibility of the driver, because DSA is unaware
911 ingress switch port. DSA, through ``dsa_port_devlink_setup()``, considers all
959   types of traffic, then the DSA core notifies of any change to the bridge port
960   flags when the port joins and leaves a bridge. DSA does not currently manage
964   lack of an explicit address filtering mechanism in the DSA core.
1008   physical DSA port interfaces. Since DSA does not attempt to keep in sync its
1029 DSA is capable of offloading a link aggregation group (LAG) to hardware that
1032 ports constitutes a logical port, although DSA has no explicit concept of a
1037 are treated similarly: DSA offloads the same switchdev object / port attribute
1039 supported, since the DSA driver API does not have the concept of a logical port
1043   LAG. The driver may return ``-EOPNOTSUPP``, and in this case, DSA will fall
1055 retrieved by a DSA switch driver using the ``dsa_lag_id`` function.
1072 however in the case of a device with an offloaded data path such as DSA, it is
1075 implementation. DSA today has no driver which is MRP-aware, therefore it only
1113   DANP/DANH. The driver may return ``-EOPNOTSUPP`` and in this case, DSA will
1122 Making SWITCHDEV and DSA converge towards an unified codebase
1127 the other DSA enforces a fairly strict device driver model, and deals with most