[PATCH 1/2] Documentation: dsa: b53: fix stale tagging-support section

[PATCH 1/2] Documentation: dsa: b53: fix stale tagging-support section

[Christian Melendez]

5325/5365 were listed under "Configuration without tagging support".
b53_get_tag_protocol() assigns them DSA_TAG_PROTO_BRCM_LEGACY_FCS
(commit c3cf059a4d41), implemented in net/dsa/tag_brcm.c. Move them to
the tagging-supported section.

539x/531x5, the only chips left in that section, get no special case
in b53_get_tag_protocol() either. The section and its config examples
no longer apply to any b53 switch, so remove them.

Link: https://patch.msgid.link/CAOiHx==_ixY-VNWX=XxqCFoJvE-80i+r2y6SNnxwQe9uZQJL6w@mail.gmail.com
Signed-off-by: Christian Melendez <chrismelnu@gmail.com>
---
 Documentation/networking/dsa/b53.rst | 151 +--------------------------
 1 file changed, 3 insertions(+), 148 deletions(-)

diff --git a/Documentation/networking/dsa/b53.rst b/Documentation/networking/dsa/b53.rst
index 1cb3ff648f88..b67864b2d314 100644
--- a/Documentation/networking/dsa/b53.rst
+++ b/Documentation/networking/dsa/b53.rst
@@ -23,9 +23,6 @@ CPU interface, conversely, the CPU network interface should insert a similar
 tag for packets entering the CPU port. The tag format is described in
 ``net/dsa/tag_brcm.c``.
 
-The configuration of the device depends on whether or not tagging is
-supported.
-
 The interface names and example network configuration are used according the
 configuration described in the :ref:`dsa-config-showcases`.
 
@@ -35,149 +32,7 @@ Configuration with tagging support
 The tagging based configuration is desired. It is not specific to the b53
 DSA driver and will work like all DSA drivers which supports tagging.
 
-See :ref:`dsa-tagged-configuration`.
-
-Configuration without tagging support
--------------------------------------
-
-Older models (5325, 5365) support a different tag format that is not supported
-yet. 539x and 531x5 require managed mode and some special handling, which is
-also not yet supported. The tagging support is disabled in these cases and the
-switch need a different configuration.
-
-The configuration slightly differ from the :ref:`dsa-vlan-configuration`.
-
-The b53 tags the CPU port in all VLANs, since otherwise any PVID untagged
-VLAN programming would basically change the CPU port's default PVID and make
-it untagged, undesirable.
-
-In difference to the configuration described in :ref:`dsa-vlan-configuration`
-the default VLAN 1 has to be removed from the user interface configuration in
-single port and gateway configuration, while there is no need to add an extra
-VLAN configuration in the bridge showcase.
-
-single port
-~~~~~~~~~~~
-The configuration can only be set up via VLAN tagging and bridge setup.
-By default packages are tagged with vid 1:
-
-.. code-block:: sh
-
-  # tag traffic on CPU port
-  ip link add link eth0 name eth0.1 type vlan id 1
-  ip link add link eth0 name eth0.2 type vlan id 2
-  ip link add link eth0 name eth0.3 type vlan id 3
-
-  # The conduit interface needs to be brought up before the user ports.
-  ip link set eth0 up
-  ip link set eth0.1 up
-  ip link set eth0.2 up
-  ip link set eth0.3 up
-
-  # bring up the user interfaces
-  ip link set wan up
-  ip link set lan1 up
-  ip link set lan2 up
-
-  # create bridge
-  ip link add name br0 type bridge
-
-  # activate VLAN filtering
-  ip link set dev br0 type bridge vlan_filtering 1
-
-  # add ports to bridges
-  ip link set dev wan master br0
-  ip link set dev lan1 master br0
-  ip link set dev lan2 master br0
-
-  # tag traffic on ports
-  bridge vlan add dev lan1 vid 2 pvid untagged
-  bridge vlan del dev lan1 vid 1
-  bridge vlan add dev lan2 vid 3 pvid untagged
-  bridge vlan del dev lan2 vid 1
-
-  # configure the VLANs
-  ip addr add 192.0.2.1/30 dev eth0.1
-  ip addr add 192.0.2.5/30 dev eth0.2
-  ip addr add 192.0.2.9/30 dev eth0.3
-
-  # bring up the bridge devices
-  ip link set br0 up
-
-
-bridge
-~~~~~~
+Older models (5325, 5365) use a different, legacy tag format, but tagging
+is supported.
 
-.. code-block:: sh
-
-  # tag traffic on CPU port
-  ip link add link eth0 name eth0.1 type vlan id 1
-
-  # The conduit interface needs to be brought up before the user ports.
-  ip link set eth0 up
-  ip link set eth0.1 up
-
-  # bring up the user interfaces
-  ip link set wan up
-  ip link set lan1 up
-  ip link set lan2 up
-
-  # create bridge
-  ip link add name br0 type bridge
-
-  # activate VLAN filtering
-  ip link set dev br0 type bridge vlan_filtering 1
-
-  # add ports to bridge
-  ip link set dev wan master br0
-  ip link set dev lan1 master br0
-  ip link set dev lan2 master br0
-  ip link set eth0.1 master br0
-
-  # configure the bridge
-  ip addr add 192.0.2.129/25 dev br0
-
-  # bring up the bridge
-  ip link set dev br0 up
-
-gateway
-~~~~~~~
-
-.. code-block:: sh
-
-  # tag traffic on CPU port
-  ip link add link eth0 name eth0.1 type vlan id 1
-  ip link add link eth0 name eth0.2 type vlan id 2
-
-  # The conduit interface needs to be brought up before the user ports.
-  ip link set eth0 up
-  ip link set eth0.1 up
-  ip link set eth0.2 up
-
-  # bring up the user interfaces
-  ip link set wan up
-  ip link set lan1 up
-  ip link set lan2 up
-
-  # create bridge
-  ip link add name br0 type bridge
-
-  # activate VLAN filtering
-  ip link set dev br0 type bridge vlan_filtering 1
-
-  # add ports to bridges
-  ip link set dev wan master br0
-  ip link set eth0.1 master br0
-  ip link set dev lan1 master br0
-  ip link set dev lan2 master br0
-
-  # tag traffic on ports
-  bridge vlan add dev wan vid 2 pvid untagged
-  bridge vlan del dev wan vid 1
-
-  # configure the VLANs
-  ip addr add 192.0.2.1/30 dev eth0.2
-  ip addr add 192.0.2.129/25 dev br0
-
-  # bring up the bridge devices
-  ip link set br0 up
+See :ref:`dsa-tagged-configuration`.
-- 
2.34.1

[PATCH 2/2] MAINTAINERS: add missing entry for b53.rst

[Christian Melendez]

Documentation/networking/dsa/b53.rst is not covered by the BROADCOM
B53/SF2 ETHERNET SWITCH DRIVER entry.

Signed-off-by: Christian Melendez <chrismelnu@gmail.com>
---
 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index cc3cae2e378b..a1bf40c70a5f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5143,6 +5143,7 @@ L:	netdev@vger.kernel.org
 L:	openwrt-devel@lists.openwrt.org (subscribers-only)
 S:	Supported
 F:	Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml
+F:	Documentation/networking/dsa/b53.rst
 F:	drivers/net/dsa/b53/*
 F:	drivers/net/dsa/bcm_sf2*
 F:	include/linux/dsa/brcm.h
-- 
2.34.1

Re: [PATCH 1/2] Documentation: dsa: b53: fix stale tagging-support section

[netdev-bot+sashiko]

Thank you for your contribution! Sashiko AI review found 1 potential
issue(s) to consider.

Critical: 0 · High: 0 · Medium: 1 · Low: 0

If you believe none of the issues are legitimate, please reply to each
issue of Medium severity or higher and explain why the AI is wrong.
If any of them are legitimate and you plan to respin, please let patchwork
know by including "pw-bot: cr" as a separate line at the end of your reply
(one such reply per series is enough).

- [Medium] The patch deletes the whole "Configuration without tagging
  support" section of Documentation/networking/dsa/b53.rst, including…

--

Documentation: dsa: b53: fix stale tagging-support section

This commit moves the 5325/5365 note into the tagging-supported section of
b53.rst, because b53_get_tag_protocol() gives them
DSA_TAG_PROTO_BRCM_LEGACY_FCS. It also deletes the whole "Configuration
without tagging support" section, including its single port, bridge and
gateway VLAN examples, on the grounds that it no longer applies to any b53
switch.

Link: https://patch.msgid.link/CAOiHx==_ixY-VNWX=XxqCFoJvE-80i+r2y6SNnxwQe9uZQJL6w@mail.gmail.com

> diff --git a/Documentation/networking/dsa/b53.rst b/Documentation/networking/dsa/b53.rst
> index 1cb3ff648f889..b67864b2d3144 100644
> --- a/Documentation/networking/dsa/b53.rst
> +++ b/Documentation/networking/dsa/b53.rst

[ ... ]

> @@ -35,149 +32,7 @@ Configuration with tagging support
>  The tagging based configuration is desired. It is not specific to the b53
>  DSA driver and will work like all DSA drivers which supports tagging.
>  
> -See :ref:`dsa-tagged-configuration`.
> -
> -Configuration without tagging support
> --------------------------------------
> -
> -Older models (5325, 5365) support a different tag format that is not supported
> -yet. 539x and 531x5 require managed mode and some special handling, which is
> -also not yet supported. The tagging support is disabled in these cases and the
> -switch need a different configuration.
> -
> -The configuration slightly differ from the :ref:`dsa-vlan-configuration`.
> -
> -The b53 tags the CPU port in all VLANs, since otherwise any PVID untagged
> -VLAN programming would basically change the CPU port's default PVID and make
> -it untagged, undesirable.

[Severity: Medium]

The commit message says:

  "The section and its config examples no longer apply to any b53 switch,
  so remove them."

Is that accurate? In drivers/net/dsa/b53/b53_common.c,
b53_get_tag_protocol() still falls back to DSA_TAG_PROTO_NONE for every
chip family. This check runs before any per-model tag selection:

	if (!b53_can_enable_brcm_tags(ds, port, mprot)) {
		dev->tag_protocol = DSA_TAG_PROTO_NONE;
		goto out;
	}

b53_can_enable_brcm_tags() returns false in two cases. The first is when
the CPU port is not 5, 7 or 8, which b53_possible_cpu_port() enforces. The
second is when the switch is stacked behind a Broadcom-tagging conduit:

	case DSA_TAG_PROTO_BRCM:
	case DSA_TAG_PROTO_BRCM_PREPEND:
		dev_warn(ds->dev,
			 "Port %d is stacked to Broadcom tag switch\n", port);
		ret = false;

In that mode the driver still behaves the way the removed text describes.
b53_vlan_port_needs_forced_tagged() keeps the CPU port tagged in all VLANs:

	return dev->tag_protocol == DSA_TAG_PROTO_NONE && dsa_is_cpu_port(ds, port);

and b53_vlan_setup() does this:

	ds->untag_bridge_pvid = dev->tag_protocol == DSA_TAG_PROTO_NONE;

After this patch, b53.rst only points to dsa-tagged-configuration. It no
longer mentions the untagged mode or links to dsa-vlan-configuration.
Boards whose CPU port is not 5/7/8 and cascaded Broadcom switches can
still end up in that mode.

Would it be better to keep this section and change the stated reason?
Tagging is disabled because of CPU port placement or stacking, not
because of the chip model (5325/5365/539x/531x5).

The follow-up patch in this series, "MAINTAINERS: add missing entry for
b53.rst", only adds an F: line and doesn't restore this content.

[ ... ]

> +Older models (5325, 5365) use a different, legacy tag format, but tagging
> +is supported.

[ ... ]

> +See :ref:`dsa-tagged-configuration`.

-- 
Sashiko AI review · https://netdev-ai.bots.linux.dev/sashiko/#/patchset/20260922211439.369917-1-chrismelnu%40gmail.com