[PATCH net-next] docs: networking: dpaa2: add documentation for the switch driver

[PATCH net-next] docs: networking: dpaa2: add documentation for the switch driver

[Ioana Ciornei]

From: Ioana Ciornei <ioana.ciornei@nxp.com>

Add a documentation entry for the DPAA2 switch listing it's
requirements, features and some examples to go along them.

Signed-off-by: Ioana Ciornei <ioana.ciornei@nxp.com>
---
 .../ethernet/freescale/dpaa2/index.rst        |   1 +
 .../freescale/dpaa2/switch-driver.rst         | 167 ++++++++++++++++++
 MAINTAINERS                                   |   1 +
 3 files changed, 169 insertions(+)
 create mode 100644 Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst

diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst
index ee40fcc5ddff..62f4a4aff6ec 100644
--- a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst
+++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst
@@ -9,3 +9,4 @@ DPAA2 Documentation
    dpio-driver
    ethernet-driver
    mac-phy-support
+   switch-driver
diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst
new file mode 100644
index 000000000000..dbeed66e0e4d
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst
@@ -0,0 +1,167 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================
+DPAA2 Switch driver
+===================
+
+:Copyright: |copy| 2021 NXP
+
+The DPAA2 Switch driver probes on the Datapath Switch (DPSW) object which can
+be instantiated on the following DPAA2 SoCs and their variants: LS2088A and
+LX2160A.
+
+The driver uses the switch device driver model and exposes each switch port as
+a network interface, which can be included in a bridge or used as a standalone
+interface. Traffic switched between ports is offloaded into the hardware.
+
+The DPSW can have ports connected to DPNIs or to DPMACs for external access.
+::
+
+         [ethA]     [ethB]      [ethC]     [ethD]     [ethE]     [ethF]
+            :          :          :          :          :          :
+            :          :          :          :          :          :
+       [dpaa2-eth]  [dpaa2-eth]  [              dpaa2-switch              ]
+            :          :          :          :          :          :        kernel
+       =============================================================================
+            :          :          :          :          :          :        hardware
+         [DPNI]      [DPNI]     [============= DPSW =================]
+            |          |          |          |          |          |
+            |           ----------           |       [DPMAC]    [DPMAC]
+             -------------------------------            |          |
+                                                        |          |
+                                                      [PHY]      [PHY]
+
+Creating an Ethernet Switch
+===========================
+
+The dpaa2-switch driver probes on DPSW devices found on the fsl-mc bus. These
+devices can be either created statically through the boot time configuration
+file - DataPath Layout (DPL) - or at runtime using the DPAA2 object APIs
+(incorporated already into the restool userspace tool).
+
+At the moment, the dpaa2-switch driver imposes the following restrictions on
+the DPSW object that it will probe:
+
+ * The maximum number of FDBs should be at least equal to the number of switch
+   interfaces. This is necessary so that separation of switch ports can be
+   done, ie when not under a bridge, each switch port will have its own FDB.
+
+ * Both the broadcast and flooding configuration should be per FDB. This
+   enables the driver to restrict the broadcast and flooding domains of each
+   FDB depending on the switch ports that are sharing it (aka are under the
+   same bridge).
+
+ * The control interface of the switch should not be disabled
+   (DPSW_OPT_CTRL_IF_DIS not passed as a create time option). Without the
+   control interface, the driver is not capable to provide proper Rx/Tx traffic
+   support on the switch port netdevices.
+
+Besides the configuration of the actual DPSW object, the dpaa2-switch driver
+will need the following DPAA2 objects:
+
+ * 1 DPMCP - A Management Command Portal object is needed for any interraction
+   with the MC firmware.
+
+ * 1 DPBP - A Buffer Pool is used for seeding buffers intended for the Rx path
+   on the control interface.
+
+ * Access to at least one DPIO object (Software Portal) is needed for any
+   enqueue/dequeue operation to be performed on the control interface queues.
+   The DPIO object will be shared, no need for a private one.
+
+Switching features
+==================
+
+The driver supports the configuration of L2 forwarding rules in hardware for
+port bridging as well as standalone usage of the independent switch interfaces.
+
+The hardware is not configurable with respect to VLAN awareness, thus any DPAA2 switch port should be used only in usecases with a VLAN aware bridge::
+
+        $ ip link add dev br0 type bridge vlan_filtering 1
+
+        $ ip link add dev br1 type bridge
+        $ ip link set dev ethX master br1
+        Error: fsl_dpaa2_switch: Cannot join a VLAN-unaware bridge
+
+Topology and loop detection through STP is supported when ``stp_state 1`` is used at bridge create ::
+
+        $ ip link add dev br0 type bridge vlan_filtering 1 stp_state 1
+
+L2 FDB manipulation (add/delete/dump) is supported.
+
+HW FDB learning can be configured on each switch port independently through
+bridge commands. When the HW learning is disabled, a fast age procedure will be
+run and any previously learnt addresses will be removed.
+::
+
+        $ bridge link set dev ethX learning off
+        $ bridge link set dev ethX learning on
+
+Restricting the unknown unicast and multicast flooding domain is supported, but
+not independently of each other::
+
+        $ ip link set dev ethX type bridge_slave flood off mcast_flood off
+        $ ip link set dev ethX type bridge_slave flood off mcast_flood on
+        Error: fsl_dpaa2_switch: Cannot configure multicast flooding independently of unicast.
+
+Broadcast flooding on a switch port can be disabled/enabled through the brport sysfs::
+
+        $ echo 0 > /sys/bus/fsl-mc/devices/dpsw.Y/net/ethX/brport/broadcast_flood
+
+Offloads
+========
+
+Routing actions (redirect, trap, drop)
+--------------------------------------
+
+The DPAA2 switch is able to offload flow-based redirection of packets making
+use of ACL tables. Shared filter blocks are supported by sharing a single ACL
+table between multiple ports.
+
+The following flow keys are supported:
+
+ * Ethernet: dst_mac/src_mac
+ * IPv4: dst_ip/src_ip/ip_proto/tos
+ * VLAN: vlan_id/vlan_prio/vlan_tpid/vlan_dei
+ * L4: dst_port/src_port
+
+Also, the matchall filter can be used to redirect the entire traffic received
+on a port.
+
+As per flow actions, the following are supported:
+
+ * drop
+ * mirred egress redirect
+ * trap
+
+Each ACL entry (filter) can be setup with only one of the listed
+actions.
+
+A sorted single linked list is used to keep the ACL entries by their
+order of priority. When adding a new filter, this enables us to quickly
+ascertain if the new entry has the highest priority of the entire block
+or if we should make some space in the ACL table by increasing the
+priority of the filters already in the table.
+
+
+Example 1: send frames received on eth4 with a SA of 00:01:02:03:04:05 to the
+CPU::
+
+        $ tc qdisc add dev eth4 clsact
+        $ tc filter add dev eth4 ingress flower src_mac 00:01:02:03:04:05 skip_sw action trap
+
+Example 2: drop frames received on eth4 with VID 100 and PCP of 3::
+
+        $ tc filter add dev eth4 ingress protocol 802.1q flower skip_sw vlan_id 100 vlan_prio 3 action drop
+
+Example 3: redirect all frames received on eth4 to eth1::
+
+        $ tc filter add dev eth4 ingress matchall action mirred egress redirect dev eth1
+
+
+Example 4: Use a single shared filter block on both eth5 and eth6::
+
+        $ tc qdisc add dev eth5 ingress_block 1 clsact
+        $ tc qdisc add dev eth6 ingress_block 1 clsact
+        $ tc filter add block 1 ingress flower dst_mac 00:01:02:03:04:04 skip_sw action trap
diff --git a/MAINTAINERS b/MAINTAINERS
index da478d5c8b0c..a483934ac8f0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5683,6 +5683,7 @@ DPAA2 ETHERNET SWITCH DRIVER
 M:	Ioana Ciornei <ioana.ciornei@nxp.com>
 L:	netdev@vger.kernel.org
 S:	Maintained
+F:	Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst
 F:	drivers/net/ethernet/freescale/dpaa2/dpaa2-switch*
 F:	drivers/net/ethernet/freescale/dpaa2/dpsw*
 
-- 
2.31.1

Re: [PATCH net-next] docs: networking: dpaa2: add documentation for the switch driver

[Andrew Lunn]

> +At the moment, the dpaa2-switch driver imposes the following restrictions on
> +the DPSW object that it will probe:
> +
> + * The maximum number of FDBs should be at least equal to the number of switch
> +   interfaces.

Should maximum actually be minimum?

This is necessary so that separation of switch ports can be
> +   done, ie when not under a bridge, each switch port will have its own FDB.
> +
> + * Both the broadcast and flooding configuration should be per FDB. This
> +   enables the driver to restrict the broadcast and flooding domains of each
> +   FDB depending on the switch ports that are sharing it (aka are under the
> +   same bridge).
> +
> + * The control interface of the switch should not be disabled
> +   (DPSW_OPT_CTRL_IF_DIS not passed as a create time option). Without the
> +   control interface, the driver is not capable to provide proper Rx/Tx traffic
> +   support on the switch port netdevices.
> +
> +Besides the configuration of the actual DPSW object, the dpaa2-switch driver
> +will need the following DPAA2 objects:
> +
> + * 1 DPMCP - A Management Command Portal object is needed for any interraction
> +   with the MC firmware.
> +
> + * 1 DPBP - A Buffer Pool is used for seeding buffers intended for the Rx path
> +   on the control interface.
> +
> + * Access to at least one DPIO object (Software Portal) is needed for any
> +   enqueue/dequeue operation to be performed on the control interface queues.
> +   The DPIO object will be shared, no need for a private one.

Are these requirements tested? Will the driver fail probe if they are
not met?

> +Routing actions (redirect, trap, drop)
> +--------------------------------------
> +
> +The DPAA2 switch is able to offload flow-based redirection of packets making
> +use of ACL tables. Shared filter blocks are supported by sharing a single ACL
> +table between multiple ports.
> +
> +The following flow keys are supported:
> +
> + * Ethernet: dst_mac/src_mac
> + * IPv4: dst_ip/src_ip/ip_proto/tos
> + * VLAN: vlan_id/vlan_prio/vlan_tpid/vlan_dei
> + * L4: dst_port/src_port
> +
> +Also, the matchall filter can be used to redirect the entire traffic received
> +on a port.
> +
> +As per flow actions, the following are supported:
> +
> + * drop
> + * mirred egress redirect
> + * trap
> +
> +Each ACL entry (filter) can be setup with only one of the listed
> +actions.
> +
> +A sorted single linked list is used to keep the ACL entries by their
> +order of priority. When adding a new filter, this enables us to quickly
> +ascertain if the new entry has the highest priority of the entire block
> +or if we should make some space in the ACL table by increasing the
> +priority of the filters already in the table.

It would be nice to have an example which shows priority in action,
since i don't understand what you are saying here.

      Andrew

Re: [PATCH net-next] docs: networking: dpaa2: add documentation for the switch driver

[Ioana Ciornei]

On Thu, Jul 22, 2021 at 04:27:22PM +0200, Andrew Lunn wrote:
> > +At the moment, the dpaa2-switch driver imposes the following restrictions on
> > +the DPSW object that it will probe:
> > +
> > + * The maximum number of FDBs should be at least equal to the number of switch
> > +   interfaces.
> 
> Should maximum actually be minimum?
> 

Uhh, it should have been minimum indeed. Will fix. Thanks!

> This is necessary so that separation of switch ports can be
> > +   done, ie when not under a bridge, each switch port will have its own FDB.
> > +
> > + * Both the broadcast and flooding configuration should be per FDB. This
> > +   enables the driver to restrict the broadcast and flooding domains of each
> > +   FDB depending on the switch ports that are sharing it (aka are under the
> > +   same bridge).
> > +
> > + * The control interface of the switch should not be disabled
> > +   (DPSW_OPT_CTRL_IF_DIS not passed as a create time option). Without the
> > +   control interface, the driver is not capable to provide proper Rx/Tx traffic
> > +   support on the switch port netdevices.
> > +
> > +Besides the configuration of the actual DPSW object, the dpaa2-switch driver
> > +will need the following DPAA2 objects:
> > +
> > + * 1 DPMCP - A Management Command Portal object is needed for any interraction
> > +   with the MC firmware.
> > +
> > + * 1 DPBP - A Buffer Pool is used for seeding buffers intended for the Rx path
> > +   on the control interface.
> > +
> > + * Access to at least one DPIO object (Software Portal) is needed for any
> > +   enqueue/dequeue operation to be performed on the control interface queues.
> > +   The DPIO object will be shared, no need for a private one.
> 
> Are these requirements tested? Will the driver fail probe if they are
> not met?

Yes, they are tested.

If the DPSW object configuration does not meet the requirements, the
driver will error out on probe with a message explictly saying what
is happening.

> 
> > +Routing actions (redirect, trap, drop)
> > +--------------------------------------
> > +
> > +The DPAA2 switch is able to offload flow-based redirection of packets making
> > +use of ACL tables. Shared filter blocks are supported by sharing a single ACL
> > +table between multiple ports.
> > +
> > +The following flow keys are supported:
> > +
> > + * Ethernet: dst_mac/src_mac
> > + * IPv4: dst_ip/src_ip/ip_proto/tos
> > + * VLAN: vlan_id/vlan_prio/vlan_tpid/vlan_dei
> > + * L4: dst_port/src_port
> > +
> > +Also, the matchall filter can be used to redirect the entire traffic received
> > +on a port.
> > +
> > +As per flow actions, the following are supported:
> > +
> > + * drop
> > + * mirred egress redirect
> > + * trap
> > +
> > +Each ACL entry (filter) can be setup with only one of the listed
> > +actions.
> > +
> > +A sorted single linked list is used to keep the ACL entries by their
> > +order of priority. When adding a new filter, this enables us to quickly
> > +ascertain if the new entry has the highest priority of the entire block
> > +or if we should make some space in the ACL table by increasing the
> > +priority of the filters already in the table.
> 
> It would be nice to have an example which shows priority in action,
> since i don't understand what you are saying here.
> 

Sure, will add an example.

On the other hand, I think this section might give too much details on
the actual implementation (I took it from the commit message of the
patch adding the support). Might as well just remove it and add the
example.

All that I was trying to say is that the filters will not be added in
the ACL table with the explicit priority specified by the user but
rather with one determined based on all the rules currently present in
the table.
Nothing is unusual in the usage, the order in which the rules are
executed will be respected.

Ioana

Re: [PATCH net-next] docs: networking: dpaa2: add documentation for the switch driver

[Andrew Lunn]

> > Are these requirements tested? Will the driver fail probe if they are
> > not met?
> 
> Yes, they are tested.
> 
> If the DPSW object configuration does not meet the requirements, the
> driver will error out on probe with a message explictly saying what
> is happening.

Good. Maybe reference that here, so somebody googling the error
message lands on this document.

> On the other hand, I think this section might give too much details on
> the actual implementation (I took it from the commit message of the
> patch adding the support). Might as well just remove it and add the
> example.
> 
> All that I was trying to say is that the filters will not be added in
> the ACL table with the explicit priority specified by the user but
> rather with one determined based on all the rules currently present in
> the table.
> Nothing is unusual in the usage, the order in which the rules are
> executed will be respected.

So if it is an implementation detail, it probably is not relevant
here.

	Andrew