Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) Architecture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) This document describes the **Distributed Switch Architecture (DSA)** subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) design principles, limitations, interactions with other subsystems, and how to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) develop drivers for this subsystem as well as a TODO for developers interested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) in joining the effort.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Design principles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) The Distributed Switch Architecture is a subsystem which was primarily designed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) to support Marvell Ethernet switches (MV88E6xxx, a.k.a Linkstreet product line)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) using Linux, but has since evolved to support other vendors as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) The original philosophy behind this design was to be able to use unmodified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) Linux tools such as bridge, iproute2, ifconfig to work transparently whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) they configured/queried a switch port network device or a regular network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) An Ethernet switch is typically comprised of multiple front-panel ports, and one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) or more CPU or management port. The DSA subsystem currently relies on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) presence of a management port connected to an Ethernet controller capable of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) receiving Ethernet frames from the switch. This is a very common setup for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) kinds of Ethernet switches found in Small Home and Office products: routers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) gateways, or even top-of-the rack switches. This host Ethernet controller will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) be later referred to as "master" and "cpu" in DSA terminology and code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) The D in DSA stands for Distributed, because the subsystem has been designed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) with the ability to configure and manage cascaded switches on top of each other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) using upstream and downstream Ethernet links between switches. These specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) ports are referred to as "dsa" ports in DSA terminology and code. A collection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) of multiple switches connected to each other is called a "switch tree".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) For each front-panel port, DSA will create specialized network devices which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) used as controlling and data-flowing endpoints for use by the Linux networking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) stack. These specialized network interfaces are referred to as "slave" network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) interfaces in DSA terminology and code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) The ideal case for using DSA is when an Ethernet switch supports a "switch tag"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) which is a hardware feature making the switch insert a specific tag for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) Ethernet frames it received to/from specific ports to help the management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) interface figure out:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) - what port is this frame coming from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) - what was the reason why this frame got forwarded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) - how to send CPU originated traffic to specific ports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) The subsystem does support switches not capable of inserting/stripping tags, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) the features might be slightly limited in that case (traffic separation relies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) on Port-based VLAN IDs).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) Note that DSA does not currently create network interfaces for the "cpu" and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) "dsa" ports because:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) - the "cpu" port is the Ethernet switch facing side of the management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58)   controller, and as such, would create a duplication of feature, since you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59)   would get two interfaces for the same conduit: master netdev, and "cpu" netdev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) - the "dsa" port(s) are just conduits between two or more switches, and as such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62)   cannot really be used as proper network interfaces either, only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63)   downstream, or the top-most upstream interface makes sense with that model
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) Switch tagging protocols
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) DSA currently supports 5 different tagging protocols, and a tag-less mode as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) well. The different protocols are implemented in:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) - ``net/dsa/tag_trailer.c``: Marvell's 4 trailer tag mode (legacy)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) - ``net/dsa/tag_dsa.c``: Marvell's original DSA tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) - ``net/dsa/tag_edsa.c``: Marvell's enhanced DSA tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) - ``net/dsa/tag_brcm.c``: Broadcom's 4 bytes tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) - ``net/dsa/tag_qca.c``: Qualcomm's 2 bytes tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) The exact format of the tag protocol is vendor specific, but in general, they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) all contain something which:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) - identifies which port the Ethernet frame came from/should be sent to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) - provides a reason why this frame was forwarded to the management interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) Master network devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) Master network devices are regular, unmodified Linux network device drivers for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) the CPU/management Ethernet interface. Such a driver might occasionally need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) know whether DSA is enabled (e.g.: to enable/disable specific offload features),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) but the DSA subsystem has been proven to work with industry standard drivers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) ``e1000e,`` ``mv643xx_eth`` etc. without having to introduce modifications to these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) drivers. Such network devices are also often referred to as conduit network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) devices since they act as a pipe between the host processor and the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) Ethernet switch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) Networking stack hooks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) When a master netdev is used with DSA, a small hook is placed in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) networking stack is in order to have the DSA subsystem process the Ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) switch specific tagging protocol. DSA accomplishes this by registering a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) specific (and fake) Ethernet type (later becoming ``skb->protocol``) with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) networking stack, this is also known as a ``ptype`` or ``packet_type``. A typical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) Ethernet Frame receive sequence looks like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) Master network device (e.g.: e1000e):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 1. Receive interrupt fires:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)         - receive function is invoked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)         - basic packet processing is done: getting length, status etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)         - packet is prepared to be processed by the Ethernet layer by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)           ``eth_type_trans``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 2. net/ethernet/eth.c::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)           eth_type_trans(skb, dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)                   if (dev->dsa_ptr != NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)                           -> skb->protocol = ETH_P_XDSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 3. drivers/net/ethernet/\*::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)           netif_receive_skb(skb)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)                   -> iterate over registered packet_type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)                           -> invoke handler for ETH_P_XDSA, calls dsa_switch_rcv()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 4. net/dsa/dsa.c::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)           -> dsa_switch_rcv()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)                   -> invoke switch tag specific protocol handler in 'net/dsa/tag_*.c'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 5. net/dsa/tag_*.c:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)         - inspect and strip switch tag protocol to determine originating port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)         - locate per-port network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)         - invoke ``eth_type_trans()`` with the DSA slave network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)         - invoked ``netif_receive_skb()``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) Past this point, the DSA slave network devices get delivered regular Ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) frames that can be processed by the networking stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Slave network devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Slave network devices created by DSA are stacked on top of their master network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) device, each of these network interfaces will be responsible for being a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) controlling and data-flowing end-point for each front-panel port of the switch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) These interfaces are specialized in order to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) - insert/remove the switch tag protocol (if it exists) when sending traffic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)   to/from specific switch ports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) - query the switch for ethtool operations: statistics, link state,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)   Wake-on-LAN, register dumps...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) - external/internal PHY management: link, auto-negotiation etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) These slave network devices have custom net_device_ops and ethtool_ops function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) pointers which allow DSA to introduce a level of layering between the networking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) stack/ethtool, and the switch driver implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) Upon frame transmission from these slave network devices, DSA will look up which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) switch tagging protocol is currently registered with these network devices, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) invoke a specific transmit routine which takes care of adding the relevant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) switch tag in the Ethernet frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) These frames are then queued for transmission using the master network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) ``ndo_start_xmit()`` function, since they contain the appropriate switch tag, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) Ethernet switch will be able to process these incoming frames from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) management interface and delivers these frames to the physical switch port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) Graphical representation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) Summarized, this is basically how DSA looks like from a network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) perspective::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)                 |---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)                 | CPU network device (eth0)|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)                 ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)                 | <tag added by switch     |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)                 |                          |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)                 |                          |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)                 |        tag added by CPU> |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)         |--------------------------------------------|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)         |            Switch driver                   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)         |--------------------------------------------|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)                   ||        ||         ||
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)               |-------|  |-------|  |-------|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)               | sw0p0 |  | sw0p1 |  | sw0p2 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)               |-------|  |-------|  |-------|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) Slave MDIO bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) In order to be able to read to/from a switch PHY built into it, DSA creates a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) slave MDIO bus which allows a specific switch driver to divert and intercept
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) MDIO reads/writes towards specific PHY addresses. In most MDIO-connected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) switches, these functions would utilize direct or indirect PHY addressing mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) to return standard MII registers from the switch builtin PHYs, allowing the PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) library and/or to return link status, link partner pages, auto-negotiation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) results etc..
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) For Ethernet switches which have both external and internal MDIO busses, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) slave MII bus can be utilized to mux/demux MDIO reads and writes towards either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) internal or external MDIO devices this switch might be connected to: internal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) PHYs, external PHYs, or even external switches.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) Data structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) DSA data structures are defined in ``include/net/dsa.h`` as well as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) ``net/dsa/dsa_priv.h``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) - ``dsa_chip_data``: platform data configuration for a given switch device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)   this structure describes a switch device's parent device, its address, as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)   well as various properties of its ports: names/labels, and finally a routing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)   table indication (when cascading switches)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) - ``dsa_platform_data``: platform device configuration data which can reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)   a collection of dsa_chip_data structure if multiples switches are cascaded,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)   the master network device this switch tree is attached to needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)   referenced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) - ``dsa_switch_tree``: structure assigned to the master network device under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)   ``dsa_ptr``, this structure references a dsa_platform_data structure as well as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)   the tagging protocol supported by the switch tree, and which receive/transmit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)   function hooks should be invoked, information about the directly attached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)   switch is also provided: CPU port. Finally, a collection of dsa_switch are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)   referenced to address individual switches in the tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) - ``dsa_switch``: structure describing a switch device in the tree, referencing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)   a ``dsa_switch_tree`` as a backpointer, slave network devices, master network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)   device, and a reference to the backing``dsa_switch_ops``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) - ``dsa_switch_ops``: structure referencing function pointers, see below for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)   full description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) Design limitations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) Limits on the number of devices and ports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) DSA currently limits the number of maximum switches within a tree to 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) (``DSA_MAX_SWITCHES``), and the number of ports per switch to 12 (``DSA_MAX_PORTS``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) These limits could be extended to support larger configurations would this need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) arise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) Lack of CPU/DSA network devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) DSA does not currently create slave network devices for the CPU or DSA ports, as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) described before. This might be an issue in the following cases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) - inability to fetch switch CPU port statistics counters using ethtool, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)   can make it harder to debug MDIO switch connected using xMII interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) - inability to configure the CPU port link parameters based on the Ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)   controller capabilities attached to it: http://patchwork.ozlabs.org/patch/509806/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) - inability to configure specific VLAN IDs / trunking VLANs between switches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)   when using a cascaded setup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) Common pitfalls using DSA setups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) Once a master network device is configured to use DSA (dev->dsa_ptr becomes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) non-NULL), and the switch behind it expects a tagging protocol, this network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) interface can only exclusively be used as a conduit interface. Sending packets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) directly through this interface (e.g.: opening a socket using this interface)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) will not make us go through the switch tagging protocol transmit function, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) the Ethernet switch on the other end, expecting a tag will typically drop this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) frame.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) Slave network devices check that the master network device is UP before allowing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) you to administratively bring UP these slave network devices. A common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) configuration mistake is forgetting to bring UP the master network device first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) Interactions with other subsystems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) DSA currently leverages the following subsystems:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) - MDIO/PHY library: ``drivers/net/phy/phy.c``, ``mdio_bus.c``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) - Switchdev:``net/switchdev/*``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) - Device Tree for various of_* functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) MDIO/PHY library
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) Slave network devices exposed by DSA may or may not be interfacing with PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) devices (``struct phy_device`` as defined in ``include/linux/phy.h)``, but the DSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) subsystem deals with all possible combinations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) - internal PHY devices, built into the Ethernet switch hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) - external PHY devices, connected via an internal or external MDIO bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) - internal PHY devices, connected via an internal MDIO bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) - special, non-autonegotiated or non MDIO-managed PHY devices: SFPs, MoCA; a.k.a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)   fixed PHYs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) The PHY configuration is done by the ``dsa_slave_phy_setup()`` function and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) logic basically looks like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) - if Device Tree is used, the PHY device is looked up using the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)   "phy-handle" property, if found, this PHY device is created and registered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)   using ``of_phy_connect()``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) - if Device Tree is used, and the PHY device is "fixed", that is, conforms to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)   the definition of a non-MDIO managed PHY as defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)   ``Documentation/devicetree/bindings/net/fixed-link.txt``, the PHY is registered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)   and connected transparently using the special fixed MDIO bus driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) - finally, if the PHY is built into the switch, as is very common with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)   standalone switch packages, the PHY is probed using the slave MII bus created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)   by DSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) SWITCHDEV
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) DSA directly utilizes SWITCHDEV when interfacing with the bridge layer, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) more specifically with its VLAN filtering portion when configuring VLANs on top
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) of per-port slave network devices. Since DSA primarily deals with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) MDIO-connected switches, although not exclusively, SWITCHDEV's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) prepare/abort/commit phases are often simplified into a prepare phase which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) checks whether the operation is supported by the DSA switch driver, and a commit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) phase which applies the changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) As of today, the only SWITCHDEV objects supported by DSA are the FDB and VLAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) objects.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) Device Tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) DSA features a standardized binding which is documented in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) ``Documentation/devicetree/bindings/net/dsa/dsa.txt``. PHY/MDIO library helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) functions such as ``of_get_phy_mode()``, ``of_phy_connect()`` are also used to query
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) per-port PHY specific details: interface connection, MDIO bus location etc..
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) Driver development
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) DSA switch drivers need to implement a dsa_switch_ops structure which will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) contain the various members described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) ``register_switch_driver()`` registers this dsa_switch_ops in its internal list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) of drivers to probe for. ``unregister_switch_driver()`` does the exact opposite.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) Unless requested differently by setting the priv_size member accordingly, DSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) does not allocate any driver private context space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) Switch configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) - ``tag_protocol``: this is to indicate what kind of tagging protocol is supported,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)   should be a valid value from the ``dsa_tag_protocol`` enum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) - ``probe``: probe routine which will be invoked by the DSA platform device upon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)   registration to test for the presence/absence of a switch device. For MDIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)   devices, it is recommended to issue a read towards internal registers using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)   the switch pseudo-PHY and return whether this is a supported device. For other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)   buses, return a non-NULL string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) - ``setup``: setup function for the switch, this function is responsible for setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)   up the ``dsa_switch_ops`` private structure with all it needs: register maps,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)   interrupts, mutexes, locks etc.. This function is also expected to properly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)   configure the switch to separate all network interfaces from each other, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)   is, they should be isolated by the switch hardware itself, typically by creating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)   a Port-based VLAN ID for each port and allowing only the CPU port and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)   specific port to be in the forwarding vector. Ports that are unused by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)   platform should be disabled. Past this function, the switch is expected to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)   fully configured and ready to serve any kind of request. It is recommended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)   to issue a software reset of the switch during this setup function in order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)   avoid relying on what a previous software agent such as a bootloader/firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376)   may have previously configured.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) PHY devices and link management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) - ``get_phy_flags``: Some switches are interfaced to various kinds of Ethernet PHYs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)   if the PHY library PHY driver needs to know about information it cannot obtain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)   on its own (e.g.: coming from switch memory mapped registers), this function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)   should return a 32-bits bitmask of "flags", that is private between the switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)   driver and the Ethernet PHY driver in ``drivers/net/phy/\*``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) - ``phy_read``: Function invoked by the DSA slave MDIO bus when attempting to read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)   the switch port MDIO registers. If unavailable, return 0xffff for each read.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)   For builtin switch Ethernet PHYs, this function should allow reading the link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)   status, auto-negotiation results, link partner pages etc..
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) - ``phy_write``: Function invoked by the DSA slave MDIO bus when attempting to write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)   to the switch port MDIO registers. If unavailable return a negative error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)   code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) - ``adjust_link``: Function invoked by the PHY library when a slave network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)   is attached to a PHY device. This function is responsible for appropriately
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)   configuring the switch port link parameters: speed, duplex, pause based on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)   what the ``phy_device`` is providing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) - ``fixed_link_update``: Function invoked by the PHY library, and specifically by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)   the fixed PHY driver asking the switch driver for link parameters that could
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)   not be auto-negotiated, or obtained by reading the PHY registers through MDIO.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)   This is particularly useful for specific kinds of hardware such as QSGMII,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)   MoCA or other kinds of non-MDIO managed PHYs where out of band link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)   information is obtained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) Ethtool operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) - ``get_strings``: ethtool function used to query the driver's strings, will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)   typically return statistics strings, private flags strings etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) - ``get_ethtool_stats``: ethtool function used to query per-port statistics and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415)   return their values. DSA overlays slave network devices general statistics:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416)   RX/TX counters from the network device, with switch driver specific statistics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)   per port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) - ``get_sset_count``: ethtool function used to query the number of statistics items
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) - ``get_wol``: ethtool function used to obtain Wake-on-LAN settings per-port, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)   function may, for certain implementations also query the master network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)   Wake-on-LAN settings if this interface needs to participate in Wake-on-LAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) - ``set_wol``: ethtool function used to configure Wake-on-LAN settings per-port,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)   direct counterpart to set_wol with similar restrictions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) - ``set_eee``: ethtool function which is used to configure a switch port EEE (Green
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)   Ethernet) settings, can optionally invoke the PHY library to enable EEE at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430)   PHY level if relevant. This function should enable EEE at the switch port MAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)   controller and data-processing logic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) - ``get_eee``: ethtool function which is used to query a switch port EEE settings,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)   this function should return the EEE state of the switch port MAC controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)   and data-processing logic as well as query the PHY for its currently configured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436)   EEE settings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) - ``get_eeprom_len``: ethtool function returning for a given switch the EEPROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)   length/size in bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) - ``get_eeprom``: ethtool function returning for a given switch the EEPROM contents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) - ``set_eeprom``: ethtool function writing specified data to a given switch EEPROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) - ``get_regs_len``: ethtool function returning the register length for a given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)   switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) - ``get_regs``: ethtool function returning the Ethernet switch internal register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)   contents. This function might require user-land code in ethtool to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)   pretty-print register values and registers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) Power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) - ``suspend``: function invoked by the DSA platform device when the system goes to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)   suspend, should quiesce all Ethernet switch activities, but keep ports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)   participating in Wake-on-LAN active as well as additional wake-up logic if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)   supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) - ``resume``: function invoked by the DSA platform device when the system resumes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)   should resume all Ethernet switch activities and re-configure the switch to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462)   in a fully active state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) - ``port_enable``: function invoked by the DSA slave network device ndo_open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465)   function when a port is administratively brought up, this function should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)   fully enabling a given switch port. DSA takes care of marking the port with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467)   ``BR_STATE_BLOCKING`` if the port is a bridge member, or ``BR_STATE_FORWARDING`` if it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)   was not, and propagating these changes down to the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) - ``port_disable``: function invoked by the DSA slave network device ndo_close
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)   function when a port is administratively brought down, this function should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)   fully disabling a given switch port. DSA takes care of marking the port with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473)   ``BR_STATE_DISABLED`` and propagating changes to the hardware if this port is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)   disabled while being a bridge member
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) Bridge layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) - ``port_bridge_join``: bridge layer function invoked when a given switch port is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480)   added to a bridge, this function should be doing the necessary at the switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481)   level to permit the joining port from being added to the relevant logical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)   domain for it to ingress/egress traffic with other members of the bridge.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) - ``port_bridge_leave``: bridge layer function invoked when a given switch port is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485)   removed from a bridge, this function should be doing the necessary at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)   switch level to deny the leaving port from ingress/egress traffic from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)   remaining bridge members. When the port leaves the bridge, it should be aged
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488)   out at the switch hardware for the switch to (re) learn MAC addresses behind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)   this port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) - ``port_stp_state_set``: bridge layer function invoked when a given switch port STP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)   state is computed by the bridge layer and should be propagated to switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)   hardware to forward/block/learn traffic. The switch driver is responsible for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494)   computing a STP state change based on current and asked parameters and perform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)   the relevant ageing based on the intersection results
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) Bridge VLAN filtering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) - ``port_vlan_filtering``: bridge layer function invoked when the bridge gets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)   configured for turning on or off VLAN filtering. If nothing specific needs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)   be done at the hardware level, this callback does not need to be implemented.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503)   When VLAN filtering is turned on, the hardware must be programmed with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)   rejecting 802.1Q frames which have VLAN IDs outside of the programmed allowed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)   VLAN ID map/rules.  If there is no PVID programmed into the switch port,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506)   untagged frames must be rejected as well. When turned off the switch must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507)   accept any 802.1Q frames irrespective of their VLAN ID, and untagged frames are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)   allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) - ``port_vlan_prepare``: bridge layer function invoked when the bridge prepares the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511)   configuration of a VLAN on the given port. If the operation is not supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512)   by the hardware, this function should return ``-EOPNOTSUPP`` to inform the bridge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)   code to fallback to a software implementation. No hardware setup must be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514)   in this function. See port_vlan_add for this and details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) - ``port_vlan_add``: bridge layer function invoked when a VLAN is configured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517)   (tagged or untagged) for the given switch port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) - ``port_vlan_del``: bridge layer function invoked when a VLAN is removed from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)   given switch port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) - ``port_vlan_dump``: bridge layer function invoked with a switchdev callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523)   function that the driver has to call for each VLAN the given port is a member
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)   of. A switchdev object is used to carry the VID and bridge flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) - ``port_fdb_add``: bridge layer function invoked when the bridge wants to install a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527)   Forwarding Database entry, the switch hardware should be programmed with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)   specified address in the specified VLAN Id in the forwarding database
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529)   associated with this VLAN ID. If the operation is not supported, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530)   function should return ``-EOPNOTSUPP`` to inform the bridge code to fallback to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531)   a software implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) .. note:: VLAN ID 0 corresponds to the port private database, which, in the context
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)         of DSA, would be its port-based VLAN, used by the associated bridge device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) - ``port_fdb_del``: bridge layer function invoked when the bridge wants to remove a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537)   Forwarding Database entry, the switch hardware should be programmed to delete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)   the specified MAC address from the specified VLAN ID if it was mapped into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)   this port forwarding database
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) - ``port_fdb_dump``: bridge layer function invoked with a switchdev callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)   function that the driver has to call for each MAC address known to be behind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543)   the given port. A switchdev object is used to carry the VID and FDB info.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) - ``port_mdb_prepare``: bridge layer function invoked when the bridge prepares the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)   installation of a multicast database entry. If the operation is not supported,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547)   this function should return ``-EOPNOTSUPP`` to inform the bridge code to fallback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)   to a software implementation. No hardware setup must be done in this function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549)   See ``port_fdb_add`` for this and details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) - ``port_mdb_add``: bridge layer function invoked when the bridge wants to install
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)   a multicast database entry, the switch hardware should be programmed with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553)   specified address in the specified VLAN ID in the forwarding database
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)   associated with this VLAN ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) .. note:: VLAN ID 0 corresponds to the port private database, which, in the context
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557)         of DSA, would be its port-based VLAN, used by the associated bridge device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) - ``port_mdb_del``: bridge layer function invoked when the bridge wants to remove a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560)   multicast database entry, the switch hardware should be programmed to delete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)   the specified MAC address from the specified VLAN ID if it was mapped into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)   this port forwarding database.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) - ``port_mdb_dump``: bridge layer function invoked with a switchdev callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)   function that the driver has to call for each MAC address known to be behind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566)   the given port. A switchdev object is used to carry the VID and MDB info.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) TODO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) Making SWITCHDEV and DSA converge towards an unified codebase
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) -------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) SWITCHDEV properly takes care of abstracting the networking stack with offload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) capable hardware, but does not enforce a strict switch device driver model. On
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) the other DSA enforces a fairly strict device driver model, and deals with most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) of the switch specific. At some point we should envision a merger between these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) two subsystems and get the best of both worlds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) Other hanging fruits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) - making the number of ports fully dynamic and not dependent on ``DSA_MAX_PORTS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) - allowing more than one CPU/management interface:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)   http://comments.gmane.org/gmane.linux.network/365657
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) - porting more drivers from other vendors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587)   http://comments.gmane.org/gmane.linux.network/365510