1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4===================
5DPAA2 Switch driver
6===================
7
8:Copyright: |copy| 2021 NXP
9
10The DPAA2 Switch driver probes on the Datapath Switch (DPSW) object which can
11be instantiated on the following DPAA2 SoCs and their variants: LS2088A and
12LX2160A.
13
14The driver uses the switch device driver model and exposes each switch port as
15a network interface, which can be included in a bridge or used as a standalone
16interface. Traffic switched between ports is offloaded into the hardware.
17
18The DPSW can have ports connected to DPNIs or to DPMACs for external access.
19::
20
21         [ethA]     [ethB]      [ethC]     [ethD]     [ethE]     [ethF]
22            :          :          :          :          :          :
23            :          :          :          :          :          :
24       [dpaa2-eth]  [dpaa2-eth]  [              dpaa2-switch              ]
25            :          :          :          :          :          :        kernel
26       =============================================================================
27            :          :          :          :          :          :        hardware
28         [DPNI]      [DPNI]     [============= DPSW =================]
29            |          |          |          |          |          |
30            |           ----------           |       [DPMAC]    [DPMAC]
31             -------------------------------            |          |
32                                                        |          |
33                                                      [PHY]      [PHY]
34
35Creating an Ethernet Switch
36===========================
37
38The dpaa2-switch driver probes on DPSW devices found on the fsl-mc bus. These
39devices can be either created statically through the boot time configuration
40file - DataPath Layout (DPL) - or at runtime using the DPAA2 object APIs
41(incorporated already into the restool userspace tool).
42
43At the moment, the dpaa2-switch driver imposes the following restrictions on
44the DPSW object that it will probe:
45
46 * The minimum number of FDBs should be at least equal to the number of switch
47   interfaces. This is necessary so that separation of switch ports can be
48   done, ie when not under a bridge, each switch port will have its own FDB.
49   ::
50
51        fsl_dpaa2_switch dpsw.0: The number of FDBs is lower than the number of ports, cannot probe
52
53 * Both the broadcast and flooding configuration should be per FDB. This
54   enables the driver to restrict the broadcast and flooding domains of each
55   FDB depending on the switch ports that are sharing it (aka are under the
56   same bridge).
57   ::
58
59        fsl_dpaa2_switch dpsw.0: Flooding domain is not per FDB, cannot probe
60        fsl_dpaa2_switch dpsw.0: Broadcast domain is not per FDB, cannot probe
61
62 * The control interface of the switch should not be disabled
63   (DPSW_OPT_CTRL_IF_DIS not passed as a create time option). Without the
64   control interface, the driver is not capable to provide proper Rx/Tx traffic
65   support on the switch port netdevices.
66   ::
67
68        fsl_dpaa2_switch dpsw.0: Control Interface is disabled, cannot probe
69
70Besides the configuration of the actual DPSW object, the dpaa2-switch driver
71will need the following DPAA2 objects:
72
73 * 1 DPMCP - A Management Command Portal object is needed for any interraction
74   with the MC firmware.
75
76 * 1 DPBP - A Buffer Pool is used for seeding buffers intended for the Rx path
77   on the control interface.
78
79 * Access to at least one DPIO object (Software Portal) is needed for any
80   enqueue/dequeue operation to be performed on the control interface queues.
81   The DPIO object will be shared, no need for a private one.
82
83Switching features
84==================
85
86The driver supports the configuration of L2 forwarding rules in hardware for
87port bridging as well as standalone usage of the independent switch interfaces.
88
89The hardware is not configurable with respect to VLAN awareness, thus any DPAA2
90switch port should be used only in usecases with a VLAN aware bridge::
91
92        $ ip link add dev br0 type bridge vlan_filtering 1
93
94        $ ip link add dev br1 type bridge
95        $ ip link set dev ethX master br1
96        Error: fsl_dpaa2_switch: Cannot join a VLAN-unaware bridge
97
98Topology and loop detection through STP is supported when ``stp_state 1`` is
99used at bridge create ::
100
101        $ ip link add dev br0 type bridge vlan_filtering 1 stp_state 1
102
103L2 FDB manipulation (add/delete/dump) is supported.
104
105HW FDB learning can be configured on each switch port independently through
106bridge commands. When the HW learning is disabled, a fast age procedure will be
107run and any previously learnt addresses will be removed.
108::
109
110        $ bridge link set dev ethX learning off
111        $ bridge link set dev ethX learning on
112
113Restricting the unknown unicast and multicast flooding domain is supported, but
114not independently of each other::
115
116        $ ip link set dev ethX type bridge_slave flood off mcast_flood off
117        $ ip link set dev ethX type bridge_slave flood off mcast_flood on
118        Error: fsl_dpaa2_switch: Cannot configure multicast flooding independently of unicast.
119
120Broadcast flooding on a switch port can be disabled/enabled through the brport sysfs::
121
122        $ echo 0 > /sys/bus/fsl-mc/devices/dpsw.Y/net/ethX/brport/broadcast_flood
123
124Offloads
125========
126
127Routing actions (redirect, trap, drop)
128--------------------------------------
129
130The DPAA2 switch is able to offload flow-based redirection of packets making
131use of ACL tables. Shared filter blocks are supported by sharing a single ACL
132table between multiple ports.
133
134The following flow keys are supported:
135
136 * Ethernet: dst_mac/src_mac
137 * IPv4: dst_ip/src_ip/ip_proto/tos
138 * VLAN: vlan_id/vlan_prio/vlan_tpid/vlan_dei
139 * L4: dst_port/src_port
140
141Also, the matchall filter can be used to redirect the entire traffic received
142on a port.
143
144As per flow actions, the following are supported:
145
146 * drop
147 * mirred egress redirect
148 * trap
149
150Each ACL entry (filter) can be setup with only one of the listed
151actions.
152
153Example 1: send frames received on eth4 with a SA of 00:01:02:03:04:05 to the
154CPU::
155
156        $ tc qdisc add dev eth4 clsact
157        $ tc filter add dev eth4 ingress flower src_mac 00:01:02:03:04:05 skip_sw action trap
158
159Example 2: drop frames received on eth4 with VID 100 and PCP of 3::
160
161        $ tc filter add dev eth4 ingress protocol 802.1q flower skip_sw vlan_id 100 vlan_prio 3 action drop
162
163Example 3: redirect all frames received on eth4 to eth1::
164
165        $ tc filter add dev eth4 ingress matchall action mirred egress redirect dev eth1
166
167Example 4: Use a single shared filter block on both eth5 and eth6::
168
169        $ tc qdisc add dev eth5 ingress_block 1 clsact
170        $ tc qdisc add dev eth6 ingress_block 1 clsact
171        $ tc filter add block 1 ingress flower dst_mac 00:01:02:03:04:04 skip_sw \
172                action trap
173        $ tc filter add block 1 ingress protocol ipv4 flower src_ip 192.168.1.1 skip_sw \
174                action mirred egress redirect dev eth3
175
176Mirroring
177~~~~~~~~~
178
179The DPAA2 switch supports only per port mirroring and per VLAN mirroring.
180Adding mirroring filters in shared blocks is also supported.
181
182When using the tc-flower classifier with the 802.1q protocol, only the
183''vlan_id'' key will be accepted. Mirroring based on any other fields from the
184802.1q protocol will be rejected::
185
186        $ tc qdisc add dev eth8 ingress_block 1 clsact
187        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_prio 3 action mirred egress mirror dev eth6
188        Error: fsl_dpaa2_switch: Only matching on VLAN ID supported.
189        We have an error talking to the kernel
190
191If a mirroring VLAN filter is requested on a port, the VLAN must to be
192installed on the switch port in question either using ''bridge'' or by creating
193a VLAN upper device if the switch port is used as a standalone interface::
194
195        $ tc qdisc add dev eth8 ingress_block 1 clsact
196        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6
197        Error: VLAN must be installed on the switch port.
198        We have an error talking to the kernel
199
200        $ bridge vlan add vid 200 dev eth8
201        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6
202
203        $ ip link add link eth8 name eth8.200 type vlan id 200
204        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6
205
206Also, it should be noted that the mirrored traffic will be subject to the same
207egress restrictions as any other traffic. This means that when a mirrored
208packet will reach the mirror port, if the VLAN found in the packet is not
209installed on the port it will get dropped.
210
211The DPAA2 switch supports only a single mirroring destination, thus multiple
212mirror rules can be installed but their ''to'' port has to be the same::
213
214        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6
215        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 100 action mirred egress mirror dev eth7
216        Error: fsl_dpaa2_switch: Multiple mirror ports not supported.
217        We have an error talking to the kernel
218