networking/dsa/dsa.rst

5 This document describes the **Distributed Switch Architecture (DSA)** subsystem
23 or more CPU or management port. 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 will create 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
55 "dsa" ports because:
61 - the "dsa" port(s) are just conduits between two or more switches, and as such
68 DSA currently supports 5 different tagging protocols, and a tag-less mode as
71 - ``net/dsa/tag_trailer.c``: Marvell's 4 trailer tag mode (legacy)
72 - ``net/dsa/tag_dsa.c``: Marvell's original DSA tag
73 - ``net/dsa/tag_edsa.c``: Marvell's enhanced DSA tag
74 - ``net/dsa/tag_brcm.c``: Broadcom's 4 bytes tag
75 - ``net/dsa/tag_qca.c``: Qualcomm's 2 bytes tag
88 know whether DSA is enabled (e.g.: to enable/disable specific offload features),
89 but the DSA subsystem has been proven to work with industry standard drivers:
98 When a master netdev is used with DSA, a small hook is placed in the
99 networking stack is in order to have the DSA subsystem process the Ethernet
100 switch specific tagging protocol. DSA accomplishes this by registering a
126 4. net/dsa/dsa.c::
129                   -> invoke switch tag specific protocol handler in 'net/dsa/tag_*.c'
131 5. net/dsa/tag_*.c:
135         - invoke ``eth_type_trans()`` with the DSA slave network device
138 Past this point, the DSA slave network devices get delivered regular Ethernet
144 Slave network devices created by DSA are stacked on top of their master network
156 pointers which allow DSA to introduce a level of layering between the networking
159 Upon frame transmission from these slave network devices, DSA will look up which
172 Summarized, this is basically how DSA looks like from a network device
196 In order to be able to read to/from a switch PHY built into it, DSA creates a
212 DSA data structures are defined in ``include/net/dsa.h`` as well as
213 ``net/dsa/dsa_priv.h``:
245 DSA currently limits the number of maximum switches within a tree to 4
250 Lack of CPU/DSA network devices
253 DSA does not currently create slave network devices for the CPU or DSA ports, as
265 Common pitfalls using DSA setups
268 Once a master network device is configured to use DSA (dev->dsa_ptr becomes
283 DSA currently leverages the following subsystems:
292 Slave network devices exposed by DSA may or may not be interfacing with PHY
293 devices (``struct phy_device`` as defined in ``include/linux/phy.h)``, but the DSA
316   by DSA
322 DSA directly utilizes SWITCHDEV when interfacing with the bridge layer, and
324 of per-port slave network devices. Since DSA primarily deals with
327 checks whether the operation is supported by the DSA switch driver, and a commit
330 As of today, the only SWITCHDEV objects supported by DSA are the FDB and VLAN
336 DSA features a standardized binding which is documented in
337 ``Documentation/devicetree/bindings/net/dsa/dsa.txt``. PHY/MDIO library helper
344 DSA switch drivers need to implement a dsa_switch_ops structure which will
350 Unless requested differently by setting the priv_size member accordingly, DSA
359 - ``probe``: probe routine which will be invoked by the DSA platform device upon
387 - ``phy_read``: Function invoked by the DSA slave MDIO bus when attempting to read
392 - ``phy_write``: Function invoked by the DSA slave MDIO bus when attempting to write
415   return their values. DSA overlays slave network devices general statistics:
455 - ``suspend``: function invoked by the DSA platform device when the system goes to
460 - ``resume``: function invoked by the DSA platform device when the system resumes,
464 - ``port_enable``: function invoked by the DSA slave network device ndo_open
466   fully enabling a given switch port. DSA takes care of marking the port with
470 - ``port_disable``: function invoked by the DSA slave network device ndo_close
472   fully disabling a given switch port. DSA takes care of marking the port with
534         of DSA, would be its port-based VLAN, used by the associated bridge device.
557         of DSA, would be its port-based VLAN, used by the associated bridge device.
571 Making SWITCHDEV and DSA converge towards an unified codebase
576 the other DSA enforces a fairly strict device driver model, and deals with most