Re: [PATCH 2/4] dt-bindings: net: dsa: Add SoC-e switch IP and DSA bindings

On Thu, 2026-07-30 at 10:56 +0200, Krzysztof Kozlowski wrote:

On Wed, Jul 29, 2026 at 06:36:55PM +0200, Vasilij Strassheim wrote:

quoted

Add DT schema documentation for SoC-e FPGA switch devices.
The binding is split into:
 - a switch IP node describing the MMIO register block
 - a DSA MDIO node describing the DSA-facing switch instance
Both nodes are linked through the soce,switch-ip phandle.

Signed-off-by: Vasilij Strassheim <redacted>
---
 .../bindings/net/dsa/soce,switch-dsa.yaml          | 195 +++++++++++++++++++++
 .../bindings/net/dsa/soce,switch-ip.yaml           |  54 ++++++
 2 files changed, 249 insertions(+)

diff --git a/Documentation/devicetree/bindings/net/dsa/soce,switch-dsa.yaml b/Documentation/devicetree/bindings/net/dsa/soce,switch-dsa.yaml
new file mode 100644
index 000000000000..a04e2838d14e
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/dsa/soce,switch-dsa.yaml

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/dsa/soce,switch-dsa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SoC-e DSA switch MDIO device
+
+maintainers:
+  - SoC-e <info@soc-e.com>

Nope, as explained more than once group boxes are not accepted.

That rule makes actually sense. I just saw UNGLinuxDriver@microchip.com in
several places and thought it wasn't completely forbidden here.
Will change it to my address in the next version.

quoted

+
+description: |
+  This node is the MDIO-bus device entry for the SoC-e DSA switch driver.

Node is not for a driver. Explain the hardware, not drivers, not DTS.

Got it, will change it for the next version.

quoted

+  It is a lightweight configuration node that lives on the MDIO bus of the
+  SoC Ethernet controller acting as the DSA conduit (CPU port).
+
+  The switch hardware itself (MMIO register interface) is a separate IP core
+  described by a companion node with one of the SoC-e compatible strings,
+  for example:
+    - soce,mrs-<version>

How is this relevant here? do you describe this compatible?

I will completely rework the documentation to reflect other code changes and
take the comment into account.

quoted

+  See the consolidated IP-core binding:
+    - Documentation/devicetree/bindings/net/dsa/soce,switch-ip.yaml
+  The two nodes are linked via the "soce,switch-ip" phandle property.
+
+  Port sub-nodes follow the DSA port binding documented in dsa-port.yaml.
+  User ports should reference PHY nodes through "phy-handle". These PHY nodes
+  live under the optional "mdio" child node of the switch and are exposed on
+  the switch's synthetic DSA user MDIO bus.
+
+  The PHY-specific properties "soce,mdio-output" and "soce,phy-addr" describe
+  the MDIO bus index and hardware PHY address used by the on-chip MDIO master
+  of the switch IP core.
+
+properties:
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0

You need to follow DTS coding style.

I will check and correct this.

quoted

+
+  compatible:
+    const: soce,switch-dsa

Way too generic. I understand that SoCe will NEVER - and you certify
that - develop a second, different "switch-dsa" model and they call this
one like this?

It is intentionally generic to cover the common basics of all variants and
configurations of the synthesized switch in DSA.
I'm not sure what kind of guarantee I'm supposed to provide here regarding
SoCe. If switch-dsa is already mainline in the future, then a different
compatible will be needed for incompatible new models.

quoted

+
+  reg:
+    description: MDIO address of this device on the parent MDIO bus.

Drop.

Will do.

quoted

+    maxItems: 1
+
+  soce,switch-ip:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: |
+      Phandle to the SoC-e switch IP core node that provides the MMIO register
+      window for this switch instance. The referenced node must carry a
+      compatible string documented in
+      Documentation/devicetree/bindings/net/dsa/soce,switch-ip.yaml.
+
+  dsa,member:
+    $ref: /schemas/types.yaml#/definitions/uint32-array

Why do you need to redefine existing property?

This will be reworked in the next version.

quoted

+    minItems: 2
+    maxItems: 2
+    description:
+      DSA cluster membership; see Documentation/devicetree/bindings/net/dsa/dsa.yaml.

Drop. Do not redefine properties. See other bindings how this is done.

I will do that.

quoted

+
+  mdio:
+    $ref: /schemas/net/mdio.yaml#
+    description: |
+      Optional child MDIO bus exposing PHY devices attached to switch user
+      ports. PHY nodes referenced by port "phy-handle" properties should be
+      placed here. The PHY address seen by Linux on this bus is the switch port
+      index, not necessarily the hardware PHY address selected internally by
+      the switch IP.
+    unevaluatedProperties: false
+
+    patternProperties:
+      "^ethernet-phy@[0-9a-f]+$":

Use consistent quotes.

Got it.

quoted

+        type: object
+        $ref: /schemas/net/ethernet-phy.yaml#
+        unevaluatedProperties: false
+        description:
+          PHY attached to a switch user port through the synthetic switch MDIO
+          bus.
+        properties:
+          soce,mdio-output:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            description: |
+              Zero-based index of the MDIO bus output of the switch IP core to
+              which this PHY is connected.
+
+          soce,phy-addr:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            description: |
+              Hardware PHY address on the MDIO bus selected by
+              "soce,mdio-output".
+
+        required:
+          - soce,mdio-output
+          - soce,phy-addr
+
+  ports:
+    type: object
+    description: Container node for the switch port sub-nodes.
+    properties:
+      '#address-cells':
+        const: 1
+      '#size-cells':
+        const: 0
+
+    patternProperties:
+      "^port@[0-9a-f]+$":
+        $ref: dsa-port.yaml#
+        unevaluatedProperties: false
+        description: |
+          Switch port. In addition to the standard DSA port properties
+          (label, phy-mode, ethernet, fixed-link) the following
+          vendor-specific properties are used for data ports connected to
+          external PHYs.
+
+    required:
+      - '#address-cells'
+      - '#size-cells'
+
+    additionalProperties: false
+
+required:
+  - compatible
+  - reg
+  - soce,switch-ip
+  - ports
+
+additionalProperties: false
+
+examples:
+  - |
+    /* Excerpt from a Xilinx ZynqMP design (ARM64) */
+    mdio {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        soce_switch: switch@10 {
+            #address-cells = <1>;
+            #size-cells = <0>;
+            compatible = "soce,switch-dsa";
+            reg = <0x10>;
+            soce,switch-ip = <&soce_switch_ip>;
+            dsa,member = <0 0>;
+
+            ports {
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                port@0 {
+                    reg = <0x0>;
+                    label = "PORT_0";
+                    phy-handle = <&switchphy0>;
+                    phy-mode = "rgmii-id";
+                };
+
+                port@1 {
+                    reg = <0x1>;
+                    label = "PORT_1";
+                    phy-handle = <&switchphy1>;
+                    phy-mode = "rgmii-id";
+                };
+
+                port@2 {
+                    reg = <0x2>;
+                    label = "INTERNAL_PORT";
+                    ethernet = <&gem3>;
+                    phy-mode = "gmii";
+                    fixed-link {
+                        speed = <1000>;
+                        full-duplex;
+                    };
+                };
+            };
+
+            mdio {
+              #address-cells = <1>;
+              #size-cells = <0>;
+
+                switchphy0: ethernet-phy@0 {
+                    compatible = "ethernet-phy-ieee802.3-c22";
+                    reg = <0x0>;
+                    soce,mdio-output = <0x00000000>;
+                    soce,phy-addr = <1>;
+                };
+
+                switchphy1: ethernet-phy@1 {
+                    compatible = "ethernet-phy-ieee802.3-c22";
+                    reg = <0x1>;
+                    soce,mdio-output = <0x00000001>;
+                    soce,phy-addr = <1>;
+                };
+            };
+        };
+    };

diff --git a/Documentation/devicetree/bindings/net/dsa/soce,switch-ip.yaml b/Documentation/devicetree/bindings/net/dsa/soce,switch-ip.yaml
new file mode 100644
index 000000000000..ba9bb396235f
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/dsa/soce,switch-ip.yaml

Filename must match compatible.

I will rewrite the entire documentation to have a single file and take that
into account.

quoted

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/dsa/soce,switch-ip.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SoC-e Ethernet Switch IP core
+
+maintainers:
+  - SoC-e <info@soc-e.com>
+
+description: |
+  SoC-e Ethernet switch IP cores are configurable FPGA switch fabrics with
+  Layer-2 bridging features (including STP/MSTP state control and FDB
+  fast-age support). Some variants also provide TSN functionality.
+
+  This binding describes only the MMIO switch IP core node. The Linux DSA
+  driver is bound via a companion MDIO node described in:
+    Documentation/devicetree/bindings/net/dsa/soce,switch-dsa.yaml.
+
+properties:
+  compatible:
+    enum:
+      - soce,mrs-21-01
+      - soce,mrs-23-02
+      - soce,mrs-24-01
+
+  reg:
+    description: |
+      MMIO base address and size of the switch register window.
+      On 64-bit platforms (ARM64), this is typically encoded as two-cell
+      address and two-cell size values.

Pointless. Please open any other existing binding.

Got it.

quoted

+    maxItems: 1
+
+  soce,num-ports:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: |
+      Total number of switch ports (external/user ports plus the CPU uplink
+      port). Must be greater than zero and not exceed the selected IP variant.

Either implied by compatible or not properly placed. Looks like propertt
of the DSA.

This will be removed.

quoted

+
+required:
+  - compatible
+  - reg
+  - soce,num-ports
+
+additionalProperties: false
+
+examples:
+  - |
+    switch_ip: switch@80020000 {

ethernet-switch

And drop unused label.

I will adjust it.

Considering this wasn't tested I should not even give here review...

Thank you very much for the review!
I'm not sure what you mean by not tested. I ran make dt_binding_check` few
times, but forgot to do it after making the latest adjustments.
The driver also worked for different people with the device tree that I tried
to reflect here.

I will take a closer look at the documentation and other drivers, before I
send the next version.

Best regards,
Krzysztof

Thanks,
Vasilij