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

[Krzysztof Kozlowski]

On Wed, Jul 29, 2026 at 06:36:55PM +0200, Vasilij Strassheim wrote:
> 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 <v.strassheim@xxxxxxxxxxxxx>
> ---
>  .../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@xxxxxxxxx>

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

> +
> +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.


> +  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?

> +  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.

> +
> +  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?

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

Drop.

> +    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?

> +    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.

> +
> +  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.

> +        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.

> @@ -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@xxxxxxxxx>
> +
> +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.

> +    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.

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

ethernet-switch

And drop unused label.

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

Best regards,
Krzysztof