Re: [PATCH net-next 08/12] dt-bindings: net: toshiba,tc965x-dwmac: add TC956x Ethernet bridge

[Krzysztof Kozlowski <krzk@kernel.org>]

On Fri, May 01, 2026 at 10:54:16AM -0500, Alex Elder wrote:
> From: Daniel Thompson <daniel@riscstar.com>
> 
> Add devicetree bindings for the Toshiba TC956x family of Ethernet-AVB/TSN
> bridges.
> 
> Signed-off-by: Daniel Thompson <daniel@riscstar.com>
> Signed-off-by: Alex Elder <elder@riscstar.com>
> ---
>  .../bindings/net/toshiba,tc956x-dwmac.yaml    | 111 ++++++++++++++++++
>  1 file changed, 111 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/toshiba,tc956x-dwmac.yaml
> 
> diff --git a/Documentation/devicetree/bindings/net/toshiba,tc956x-dwmac.yaml b/Documentation/devicetree/bindings/net/toshiba,tc956x-dwmac.yaml
> new file mode 100644
> index 0000000000000..d95d22a3761da
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/toshiba,tc956x-dwmac.yaml
> @@ -0,0 +1,111 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/toshiba,tc956x-dwmac.yaml#

Filename and here: toshiba,tc9564-dwmac
(s/x/4/)


> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Toshiba TC956x Ethernet-AVB/TSN Controller
> +
> +maintainers:
> +  - Alex Elder <elder@riscstar.com>
> +  - Daniel Thompson <daniel@riscstar.com>
> +
> +description: |
> +  This node provides properties for configuring the Ethernet PCI functions
> +  that are attached to the internal downstream port of the TC956x's PCIe
> +  switch.

Describe rather the hardware directly, not the DTS or the binding
itself.

Just say what is the hardware, what is consists of, what is less
obvious or usual (if there is such).

> +
> +  TC956x are a family of Ethernet-AVB/TSN bridge chips that combine a PCIe
> +  switch together with a number of Ethernet controllers. These bindings
> +  cover only the Ethernet functions of these devices.

What about the rest of the hardware - a PCIe switch? Shouldn't it be
described?

> +
> +allOf:
> +  - $ref: /schemas/pci/pci-bus-common.yaml#
> +  - $ref: /schemas/pci/pci-device.yaml#
> +
> +unevaluatedProperties: false

Place both (allOf+unevaluatedProperties) after "required:".

> +
> +properties:
> +  compatible:
> +    enum:
> +      - pci1179,0220 # Toshiba TC9564 (a.k.a. Qualcomm QPS615)
> +
> +  "#gpio-cells":
> +    const: 2
> +
> +  gpio-controller: true
> +
> +  # We can't allOf reference Ethernet-controller.yaml because we end up with

s/Ethernet-controller.yaml/ethernet-controller.yaml/

> +  # contradictory $nodename rules (`ethernet@` versus `pci@`). Happily only a

But which schema requires pci@ for devices? If I am not mistaken, only
dtschema/schemas/pci/pci-bus-common.yaml requires it, and it does not
apply to actual PCI device.


> +  # small number of the properties are useful on TC956x so we can just reference
> +  # what we need.
> +  phy-connection-type:
> +    $ref: ethernet-controller.yaml#/properties/phy-connection-type
> +
> +  phy-handle:
> +    $ref: ethernet-controller.yaml#/properties/phy-handle
> +
> +  phy-mode:
> +    $ref: ethernet-controller.yaml#/properties/phy-mode
> +
> +  mdio:
> +    $ref: snps,dwmac.yaml#/properties/mdio
> +
> +required:
> +  - compatible
> +  - reg
> +
> +examples:
> +  - |
> +    pcie {
> +      #address-cells = <3>;
> +      #size-cells = <2>;
> +
> +      tc956x_emac0: pci@0,0 {
> +        compatible = "pci1179,0220";
> +        reg = <0x50000 0x0 0x0 0x0 0x0>;
> +        #address-cells = <3>;
> +        #size-cells = <2>;
> +        device_type = "pci";
> +        ranges;
> +
> +        gpio-controller;
> +        #gpio-cells = <2>;
> +
> +        phy-mode = "10gbase-r";
> +        phy-handle = <&tc956x_emac0_phy>;
> +
> +        mdio {
> +          compatible = "snps,dwmac-mdio";
> +          #address-cells = <1>;
> +          #size-cells = <0>;
> +
> +          tc956x_emac0_phy: ethernet-phy@1c {
> +            compatible = "ethernet-phy-id311c.1c12";
> +            reg = <0x1c>;
> +          };
> +        };
> +      };

Keep only one example, unless you have different properties (not their
values, but their presence),


Best regards,
Krzysztof