diff mbox series

[net-next,v2,07/10] dt-bindings: net: enforce phylink bindings on certain ethernet controllers

Message ID 20230916110902.234273-8-arinc.unal@arinc9.com (mailing list archive)
State Changes Requested
Delegated to: Netdev Maintainers
Headers show
Series define and enforce phylink bindings | expand

Checks

Context Check Description
netdev/tree_selection success Clearly marked for net-next
netdev/apply fail Patch does not apply to net-next

Commit Message

Arınç ÜNAL Sept. 16, 2023, 11:08 a.m. UTC
Phylink bindings are required for ethernet controllers that utilise
phylink_fwnode_phy_connect() directly or through phylink_of_phy_connect(),
and register OF-based only MDIO buses, if they register any.

All the drivers that utilise phylink_fwnode_phy_connect() directly or
through phylink_of_phy_connect():

- DSA
- drivers/net/ethernet/mscc/ocelot_net.c
  - mscc,vsc7514-switch.yaml
- drivers/net/ethernet/microchip/sparx5/sparx5_netdev.c
  - microchip,sparx5-switch.yaml
- drivers/net/ethernet/altera/altera_tse_main.c
  - altr,tse.yaml
- drivers/net/ethernet/xilinx/xilinx_axienet_main.c
  - xlnx,axi-ethernet.yaml
- drivers/net/ethernet/mediatek/mtk_eth_soc.c
  - mediatek,net.yaml
- drivers/net/ethernet/ti/am65-cpsw-nuss.c
  - ti,k3-am654-cpsw-nuss.yaml
- drivers/net/ethernet/atheros/ag71xx.c
  - qca,ar71xx.yaml
- drivers/net/ethernet/freescale/dpaa/dpaa_eth.c
  - fsl,fman-dtsec.yaml
- drivers/net/ethernet/microchip/lan966x/lan966x_main.c
  - microchip,lan966x-switch.yaml
- drivers/net/ethernet/marvell/mvpp2/mvpp2_main.c
  - marvell,pp2.yaml
- drivers/net/ethernet/freescale/dpaa2/dpaa2-mac.c
  - fsl,qoriq-mc-dpmac.yaml
- drivers/net/ethernet/cadence/macb_main.c
  - cdns,macb.yaml
  - Can register non-OF-based bus.
- drivers/net/ethernet/stmicro/stmmac/stmmac_main.c
  - snps,dwmac.yaml
  - Can register non-OF-based bus.
- drivers/net/ethernet/marvell/mvneta.c
  - marvell-armada-370-neta.txt
- drivers/net/ethernet/freescale/enetc/enetc.c
  - fsl-enetc.txt

RFC: The drivers marked with "can register non-OF-based bus" seem to search
the MDIO bus to connect the PHY to the MAC using phylink_connect_phy()
and/or phy_find_first() if phylink bindings don't exist. Should we enforce
phylink bindings on their schemas regardless?

DSA, like any other driver utilising the Linux MDIO infrastructure,
can register a bus. On certain conditions, it registers the MDIO
bus of the switch it controls non-OF-based.

We can know when DSA won't create any non-OF-based buses. That leaves us
with only OF-based buses in which case we can enforce phylink bindings for
user ports. The bindings are already enforced for shared ports so we can
enforce the bindings for all ports on the switch schemas which will achieve
the same result with fewer lines.

By looking at whether the mdio child node exists and what is explained on
it, we can enforce phylink bindings.

- mscc,vsc7514-switch.yaml
  - Enforce phylink bindings for all ports.

- arrow,xrs700x.yaml
  - Enforce phylink bindings for all ports.

- brcm,b53.yaml
  - Enforce phylink bindings for all ports if "mdio" is defined.

- brcm,sf2.yaml
  - Enforce phylink bindings for all ports.

- hirschmann,hellcreek.yaml
  - Enforce phylink bindings for all ports.

- mediatek,mt7530.yaml
  - Enforce phylink bindings for all ports if "mdio" is defined.

- microchip,ksz.yaml
  - Enforce phylink bindings for all ports if "mdio" is defined.

- microchip,lan937x.yaml
  - Enforce phylink bindings for all ports if "mdio" is defined.

- mscc,ocelot.yaml
  - Enforce phylink bindings for all ports.

- nxp,sja1105.yaml
  - Enforce phylink bindings for all ports.

- qca8k.yaml
  - Enforce phylink bindings for all ports if "mdio" is defined.

- realtek.yaml
  - Enforce phylink bindings for all ports if "mdio" is defined.

- renesas,rzn1-a5psw.yaml
  - Enforce phylink bindings for all ports.

- ar9331.txt
  - Enforce phylink bindings for all ports.

- lan9303.txt
  - Enforce phylink bindings for all ports if "mdio" is defined.

- lantiq-gswip.txt
  - Enforce phylink bindings for all ports.

- marvell.txt
  - Enforce phylink bindings for all ports if "mdio" is defined.

- vitesse,vsc73xx.txt
  - Enforce phylink bindings for all ports if "mdio" is defined.

I will convert the non json-schema documents accordingly.

Signed-off-by: Arınç ÜNAL <arinc.unal@arinc9.com>
---
 .../devicetree/bindings/net/altr,tse.yaml     |  1 +
 .../devicetree/bindings/net/cdns,macb.yaml    |  1 +
 .../bindings/net/dsa/arrow,xrs700x.yaml       |  6 ++
 .../devicetree/bindings/net/dsa/brcm,b53.yaml |  9 +++
 .../devicetree/bindings/net/dsa/brcm,sf2.yaml |  6 +-
 .../net/dsa/hirschmann,hellcreek.yaml         |  6 ++
 .../bindings/net/dsa/mediatek,mt7530.yaml     |  9 +++
 .../bindings/net/dsa/microchip,ksz.yaml       |  9 +++
 .../bindings/net/dsa/microchip,lan937x.yaml   |  9 +++
 .../bindings/net/dsa/mscc,ocelot.yaml         |  6 ++
 .../bindings/net/dsa/nxp,sja1105.yaml         |  1 +
 .../devicetree/bindings/net/dsa/qca8k.yaml    |  9 +++
 .../devicetree/bindings/net/dsa/realtek.yaml  | 57 +++++++++++--------
 .../bindings/net/dsa/renesas,rzn1-a5psw.yaml  |  2 +-
 .../bindings/net/fsl,fman-dtsec.yaml          |  1 +
 .../bindings/net/fsl,qoriq-mc-dpmac.yaml      |  1 +
 .../devicetree/bindings/net/marvell,pp2.yaml  |  4 +-
 .../devicetree/bindings/net/mediatek,net.yaml |  1 +
 .../net/microchip,lan966x-switch.yaml         |  4 +-
 .../bindings/net/microchip,sparx5-switch.yaml |  5 +-
 .../bindings/net/mscc,vsc7514-switch.yaml     |  5 ++
 .../devicetree/bindings/net/qca,ar71xx.yaml   |  1 +
 .../devicetree/bindings/net/snps,dwmac.yaml   |  1 +
 .../bindings/net/ti,k3-am654-cpsw-nuss.yaml   |  4 +-
 .../bindings/net/xlnx,axi-ethernet.yaml       |  3 +-
 25 files changed, 130 insertions(+), 31 deletions(-)

Comments

Rob Herring Sept. 16, 2023, 2:58 p.m. UTC | #1
On Sat, 16 Sep 2023 14:08:59 +0300, Arınç ÜNAL wrote:
> Phylink bindings are required for ethernet controllers that utilise
> phylink_fwnode_phy_connect() directly or through phylink_of_phy_connect(),
> and register OF-based only MDIO buses, if they register any.
> 
> All the drivers that utilise phylink_fwnode_phy_connect() directly or
> through phylink_of_phy_connect():
> 
> - DSA
> - drivers/net/ethernet/mscc/ocelot_net.c
>   - mscc,vsc7514-switch.yaml
> - drivers/net/ethernet/microchip/sparx5/sparx5_netdev.c
>   - microchip,sparx5-switch.yaml
> - drivers/net/ethernet/altera/altera_tse_main.c
>   - altr,tse.yaml
> - drivers/net/ethernet/xilinx/xilinx_axienet_main.c
>   - xlnx,axi-ethernet.yaml
> - drivers/net/ethernet/mediatek/mtk_eth_soc.c
>   - mediatek,net.yaml
> - drivers/net/ethernet/ti/am65-cpsw-nuss.c
>   - ti,k3-am654-cpsw-nuss.yaml
> - drivers/net/ethernet/atheros/ag71xx.c
>   - qca,ar71xx.yaml
> - drivers/net/ethernet/freescale/dpaa/dpaa_eth.c
>   - fsl,fman-dtsec.yaml
> - drivers/net/ethernet/microchip/lan966x/lan966x_main.c
>   - microchip,lan966x-switch.yaml
> - drivers/net/ethernet/marvell/mvpp2/mvpp2_main.c
>   - marvell,pp2.yaml
> - drivers/net/ethernet/freescale/dpaa2/dpaa2-mac.c
>   - fsl,qoriq-mc-dpmac.yaml
> - drivers/net/ethernet/cadence/macb_main.c
>   - cdns,macb.yaml
>   - Can register non-OF-based bus.
> - drivers/net/ethernet/stmicro/stmmac/stmmac_main.c
>   - snps,dwmac.yaml
>   - Can register non-OF-based bus.
> - drivers/net/ethernet/marvell/mvneta.c
>   - marvell-armada-370-neta.txt
> - drivers/net/ethernet/freescale/enetc/enetc.c
>   - fsl-enetc.txt
> 
> RFC: The drivers marked with "can register non-OF-based bus" seem to search
> the MDIO bus to connect the PHY to the MAC using phylink_connect_phy()
> and/or phy_find_first() if phylink bindings don't exist. Should we enforce
> phylink bindings on their schemas regardless?
> 
> DSA, like any other driver utilising the Linux MDIO infrastructure,
> can register a bus. On certain conditions, it registers the MDIO
> bus of the switch it controls non-OF-based.
> 
> We can know when DSA won't create any non-OF-based buses. That leaves us
> with only OF-based buses in which case we can enforce phylink bindings for
> user ports. The bindings are already enforced for shared ports so we can
> enforce the bindings for all ports on the switch schemas which will achieve
> the same result with fewer lines.
> 
> By looking at whether the mdio child node exists and what is explained on
> it, we can enforce phylink bindings.
> 
> - mscc,vsc7514-switch.yaml
>   - Enforce phylink bindings for all ports.
> 
> - arrow,xrs700x.yaml
>   - Enforce phylink bindings for all ports.
> 
> - brcm,b53.yaml
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - brcm,sf2.yaml
>   - Enforce phylink bindings for all ports.
> 
> - hirschmann,hellcreek.yaml
>   - Enforce phylink bindings for all ports.
> 
> - mediatek,mt7530.yaml
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - microchip,ksz.yaml
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - microchip,lan937x.yaml
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - mscc,ocelot.yaml
>   - Enforce phylink bindings for all ports.
> 
> - nxp,sja1105.yaml
>   - Enforce phylink bindings for all ports.
> 
> - qca8k.yaml
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - realtek.yaml
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - renesas,rzn1-a5psw.yaml
>   - Enforce phylink bindings for all ports.
> 
> - ar9331.txt
>   - Enforce phylink bindings for all ports.
> 
> - lan9303.txt
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - lantiq-gswip.txt
>   - Enforce phylink bindings for all ports.
> 
> - marvell.txt
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> - vitesse,vsc73xx.txt
>   - Enforce phylink bindings for all ports if "mdio" is defined.
> 
> I will convert the non json-schema documents accordingly.
> 
> Signed-off-by: Arınç ÜNAL <arinc.unal@arinc9.com>
> ---
>  .../devicetree/bindings/net/altr,tse.yaml     |  1 +
>  .../devicetree/bindings/net/cdns,macb.yaml    |  1 +
>  .../bindings/net/dsa/arrow,xrs700x.yaml       |  6 ++
>  .../devicetree/bindings/net/dsa/brcm,b53.yaml |  9 +++
>  .../devicetree/bindings/net/dsa/brcm,sf2.yaml |  6 +-
>  .../net/dsa/hirschmann,hellcreek.yaml         |  6 ++
>  .../bindings/net/dsa/mediatek,mt7530.yaml     |  9 +++
>  .../bindings/net/dsa/microchip,ksz.yaml       |  9 +++
>  .../bindings/net/dsa/microchip,lan937x.yaml   |  9 +++
>  .../bindings/net/dsa/mscc,ocelot.yaml         |  6 ++
>  .../bindings/net/dsa/nxp,sja1105.yaml         |  1 +
>  .../devicetree/bindings/net/dsa/qca8k.yaml    |  9 +++
>  .../devicetree/bindings/net/dsa/realtek.yaml  | 57 +++++++++++--------
>  .../bindings/net/dsa/renesas,rzn1-a5psw.yaml  |  2 +-
>  .../bindings/net/fsl,fman-dtsec.yaml          |  1 +
>  .../bindings/net/fsl,qoriq-mc-dpmac.yaml      |  1 +
>  .../devicetree/bindings/net/marvell,pp2.yaml  |  4 +-
>  .../devicetree/bindings/net/mediatek,net.yaml |  1 +
>  .../net/microchip,lan966x-switch.yaml         |  4 +-
>  .../bindings/net/microchip,sparx5-switch.yaml |  5 +-
>  .../bindings/net/mscc,vsc7514-switch.yaml     |  5 ++
>  .../devicetree/bindings/net/qca,ar71xx.yaml   |  1 +
>  .../devicetree/bindings/net/snps,dwmac.yaml   |  1 +
>  .../bindings/net/ti,k3-am654-cpsw-nuss.yaml   |  4 +-
>  .../bindings/net/xlnx,axi-ethernet.yaml       |  3 +-
>  25 files changed, 130 insertions(+), 31 deletions(-)
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@5800a000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/stm32-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@5800a000: Unevaluated properties are not allowed ('interrupt-names', 'interrupts', 'phy-mode', 'snps,axi-config', 'snps,pbl', 'snps,tso' were unexpected)
	from schema $id: http://devicetree.org/schemas/net/stm32-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@5800a000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/snps,dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@40028000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/stm32-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@40028000: Unevaluated properties are not allowed ('interrupt-names', 'interrupts', 'phy-mode', 'snps,mixed-burst', 'snps,pbl' were unexpected)
	from schema $id: http://devicetree.org/schemas/net/stm32-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@40028000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/snps,dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@40027000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/stm32-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@40027000: Unevaluated properties are not allowed ('interrupt-names', 'interrupts', 'phy-mode', 'snps,pbl' were unexpected)
	from schema $id: http://devicetree.org/schemas/net/stm32-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@40027000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/snps,dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/cdns,macb.example.dtb: ethernet@fffc4000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/cdns,macb.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/marvell,pp2.example.dtb: ethernet@f0000: ethernet-port@0: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/marvell,pp2.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/marvell,pp2.example.dtb: ethernet@f0000: ethernet-port@1: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/marvell,pp2.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/marvell,pp2.example.dtb: ethernet@0: ethernet-port@0: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/marvell,pp2.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/marvell,pp2.example.dtb: ethernet@0: ethernet-port@1: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/marvell,pp2.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/nxp,dwmac-imx.example.dtb: ethernet@30bf0000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/nxp,dwmac-imx.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/nxp,dwmac-imx.example.dtb: ethernet@30bf0000: Unevaluated properties are not allowed ('interrupt-names', 'interrupts', 'phy-mode', 'reg' were unexpected)
	from schema $id: http://devicetree.org/schemas/net/nxp,dwmac-imx.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/nxp,dwmac-imx.example.dtb: ethernet@30bf0000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/snps,dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/rockchip-dwmac.example.dtb: ethernet@ff290000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/rockchip-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/rockchip-dwmac.example.dtb: ethernet@ff290000: Unevaluated properties are not allowed ('interrupt-names', 'interrupts', 'phy-mode', 'reg' were unexpected)
	from schema $id: http://devicetree.org/schemas/net/rockchip-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.example.dtb: ethernet@c9410000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/amlogic,meson-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.example.dtb: ethernet@c9410000: Unevaluated properties are not allowed ('interrupt-names', 'interrupts', 'phy-mode' were unexpected)
	from schema $id: http://devicetree.org/schemas/net/amlogic,meson-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.example.dtb: ethernet@c9410000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/snps,dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/snps,dwmac.example.dtb: ethernet@e0800000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/snps,dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.example.dtb: ethernet@1c50000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/allwinner,sun7i-a20-gmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.example.dtb: ethernet@1c50000: Unevaluated properties are not allowed ('phy-mode' was unexpected)
	from schema $id: http://devicetree.org/schemas/net/allwinner,sun7i-a20-gmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/mediatek-dwmac.example.dtb: ethernet@1101c000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/snps,dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/mediatek-dwmac.example.dtb: ethernet@1101c000: 'anyOf' conditional failed, one must be fixed:
	'fixed-link' is a required property
	'pcs-handle' is a required property
	'tbi-handle' is a required property
	'phy-handle' is a required property
	'sfp' is a required property
	'managed' is a required property
	from schema $id: http://devicetree.org/schemas/net/mediatek-dwmac.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/mediatek-dwmac.example.dtb: ethernet@1101c000: Unevaluated properties are not allowed ('interrupt-names', 'interrupts', 'mac-address', 'phy-mode', 'reg', 'snps,reset-delays-us', 'snps,reset-gpio', 'snps,rxpbl', 'snps,txpbl' were unexpected)
	from schema $id: http://devicetree.org/schemas/net/mediatek-dwmac.yaml#

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20230916110902.234273-8-arinc.unal@arinc9.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.
Arınç ÜNAL Sept. 16, 2023, 4 p.m. UTC | #2
On 16.09.2023 17:58, Rob Herring wrote:
> My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
> on your patch (DT_CHECKER_FLAGS is new in v5.13):
> 
> yamllint warnings/errors:
> 
> dtschema/dtc warnings/errors:
> /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/stm32-dwmac.example.dtb: ethernet@5800a000: 'anyOf' conditional failed, one must be fixed:
> 	'fixed-link' is a required property
> 	'pcs-handle' is a required property
> 	'tbi-handle' is a required property
> 	'phy-handle' is a required property
> 	'sfp' is a required property
> 	'managed' is a required property
> 	from schema $id: http://devicetree.org/schemas/net/stm32-dwmac.yaml#

I will address the examples once I get a comment on my paragraph starting
with "RFC:" on the patch log.

Arınç
Rob Herring Sept. 18, 2023, 6:13 p.m. UTC | #3
On Sat, Sep 16, 2023 at 02:08:59PM +0300, Arınç ÜNAL wrote:
> Phylink bindings are required for ethernet controllers that utilise
> phylink_fwnode_phy_connect() directly or through phylink_of_phy_connect(),
> and register OF-based only MDIO buses, if they register any.

What is phylink?

Don't describe/justify binding changes based on some Linux functions.

> All the drivers that utilise phylink_fwnode_phy_connect() directly or
> through phylink_of_phy_connect():
> 
> - DSA
> - drivers/net/ethernet/mscc/ocelot_net.c
>   - mscc,vsc7514-switch.yaml
> - drivers/net/ethernet/microchip/sparx5/sparx5_netdev.c
>   - microchip,sparx5-switch.yaml
> - drivers/net/ethernet/altera/altera_tse_main.c
>   - altr,tse.yaml
> - drivers/net/ethernet/xilinx/xilinx_axienet_main.c
>   - xlnx,axi-ethernet.yaml
> - drivers/net/ethernet/mediatek/mtk_eth_soc.c
>   - mediatek,net.yaml
> - drivers/net/ethernet/ti/am65-cpsw-nuss.c
>   - ti,k3-am654-cpsw-nuss.yaml
> - drivers/net/ethernet/atheros/ag71xx.c
>   - qca,ar71xx.yaml
> - drivers/net/ethernet/freescale/dpaa/dpaa_eth.c
>   - fsl,fman-dtsec.yaml
> - drivers/net/ethernet/microchip/lan966x/lan966x_main.c
>   - microchip,lan966x-switch.yaml
> - drivers/net/ethernet/marvell/mvpp2/mvpp2_main.c
>   - marvell,pp2.yaml
> - drivers/net/ethernet/freescale/dpaa2/dpaa2-mac.c
>   - fsl,qoriq-mc-dpmac.yaml
> - drivers/net/ethernet/cadence/macb_main.c
>   - cdns,macb.yaml
>   - Can register non-OF-based bus.
> - drivers/net/ethernet/stmicro/stmmac/stmmac_main.c
>   - snps,dwmac.yaml
>   - Can register non-OF-based bus.
> - drivers/net/ethernet/marvell/mvneta.c
>   - marvell-armada-370-neta.txt
> - drivers/net/ethernet/freescale/enetc/enetc.c
>   - fsl-enetc.txt
> 
> RFC: The drivers marked with "can register non-OF-based bus" seem to search
> the MDIO bus to connect the PHY to the MAC using phylink_connect_phy()
> and/or phy_find_first() if phylink bindings don't exist. Should we enforce
> phylink bindings on their schemas regardless?

Generally, describing the MDIO bus in DT is optional because the devices 
on the bus can be discovered. But then sometimes a device can't be 
discovered or has additional properties which aren't discoverable. So in 
general, an MDIO bus in DT should always be optional, but always 
supported (and validated) if present. If the device has a separate node 
for the MDIO controller (i.e. one with a compatible and reg for the MDIO 
controller register), then that should always be there (because the h/w 
is always there).

Rob
Arınç ÜNAL Sept. 21, 2023, 11:38 a.m. UTC | #4
On 18.09.2023 21:13, Rob Herring wrote:
> On Sat, Sep 16, 2023 at 02:08:59PM +0300, Arınç ÜNAL wrote:
>> Phylink bindings are required for ethernet controllers that utilise
>> phylink_fwnode_phy_connect() directly or through phylink_of_phy_connect(),
>> and register OF-based only MDIO buses, if they register any.
> 
> What is phylink?
> 
> Don't describe/justify binding changes based on some Linux functions.

I'd like to discuss the influence of the Linux drivers on the devicetree
bindings. Before that let me clarify these "phylink" bindings. They are
certain rules to properly describe the link of the ethernet controller. Any
of the phy-handle, pcs-handle, sfp, and fixed-link properties describe the
link. They are already defined on ethernet-controller.yaml, just not
enforced.

Why I called them phylink bindings, is because when phylink is used on the
ethernet controller driver, only then we can be sure that the link
descriptions on the ethernet controller are needed. Because, some drivers
don't need the link descriptions on the ethernet controller as they can
search a certain MDIO bus to find and connect a MAC to a PHY or set up a
fixed link without looking at the devicetree.

I don't like this approach because, as you said, devicetree bindings should
describe the hardware, not driver policies. So I propose that we don't let
Linux drivers interfere with dt-bindings. To that extent:

- Link descriptions must be required on ethernet controllers. We don't care
   whether some Linux driver can or cannot find the PHY or set up a fixed
   link without looking at the devicetree.

- The MDIO bus description on an ethernet controller describes that the
   hardware comes with an MDIO bus. The MDIO property is optional not
   because some Linux driver can find and map the PHYs to MACs without DT
   descriptions but because the hardware doesn't have to use that or any
   MDIO bus.

Let's also talk about the elephant in the room: DSA bindings. Distributed
Switch Architecture is a Linux subsystem, not a hardware property.
Devicetree bindings are supposed to describe the hardware, yet we have
bindings specifically for DSA so that the DSA driver can properly control
the hardware.

Although I see dsa.yaml and dsa-port.yaml mostly consist of describing an
ethernet switch with CPU port(s), there're properties that are specific to
DSA, such as dsa,member on dsa.yaml and dsa-tag-protocol and label on
dsa-port.yaml.

Depending on how I get responses, I will address my patches. Then I can
further discuss the DSA bindings.

Arınç
Andrew Lunn Sept. 21, 2023, 1 p.m. UTC | #5
> - Link descriptions must be required on ethernet controllers. We don't care
>   whether some Linux driver can or cannot find the PHY or set up a fixed
>   link without looking at the devicetree.

That can lead to future surprises, and breakage.

Something which is not used is not tested, and so sometimes wrong, and
nobody knows. Say the driver is extended to a new device and actually
does need to use this never before used information. You then find it
is wrong, and you get a regression.

We have had issues like this before. There are four rgmii phy-link
modes. We have had PHY drivers which ignored one of those modes, it
silently accepted it, but did not change the hardware to actually use
that mode. The PHY continues to use its reset defaults or strapping,
and it worked. A lot of device trees ended up using this mode. And it
was not the same as reset defaults/strapping.

And then somebody needed that fourth mode, and made it actually
work. And all those boards wrongly using that mode broke.

The lesson i learned from that episode is that anything in device tree
must actually be used and tested.

> Although I see dsa.yaml and dsa-port.yaml mostly consist of describing an
> ethernet switch with CPU port(s), there're properties that are specific to
> DSA, such as dsa,member on dsa.yaml and dsa-tag-protocol and label on
> dsa-port.yaml.

I would say dsa,member does describe the hardware. It provides two
bits of information:

Which cluster of switches does this switch belong to. You probably can
derive it using the DSA links between switches, which is also a
hardware property. But having it in device tree makes it simpler.

Which switch is this within a cluster. You need to be able to say:
Send this frame out Port X of switch Y. How does a switch know it is
Y? It could be strapping, which is clearly a hardware property.

dsa-tag-protocol is similar to phy-mode. It tells you the protocol
running between the CPU port and the SoC master interface. You often
can imply it, but again, it could be determined by strapping on the
switch.

label is an interesting one, and probably would not be accepted if it
was proposed now. But it has been around a long time. It also does
describe the hardware, it is what is printed on the case next to the
RJ45. To make the user experience simpler, we then try to make the
linux interface name match the label on the case.

	Andrew
Arınç ÜNAL Sept. 21, 2023, 6:21 p.m. UTC | #6
On 21.09.2023 16:00, Andrew Lunn wrote:
>> - Link descriptions must be required on ethernet controllers. We don't care
>>    whether some Linux driver can or cannot find the PHY or set up a fixed
>>    link without looking at the devicetree.
> 
> That can lead to future surprises, and breakage.
> 
> Something which is not used is not tested, and so sometimes wrong, and
> nobody knows. Say the driver is extended to a new device and actually
> does need to use this never before used information. You then find it
> is wrong, and you get a regression.
> 
> We have had issues like this before. There are four rgmii phy-link
> modes. We have had PHY drivers which ignored one of those modes, it
> silently accepted it, but did not change the hardware to actually use
> that mode. The PHY continues to use its reset defaults or strapping,
> and it worked. A lot of device trees ended up using this mode. And it
> was not the same as reset defaults/strapping.
> 
> And then somebody needed that fourth mode, and made it actually
> work. And all those boards wrongly using that mode broke.
> 
> The lesson i learned from that episode is that anything in device tree
> must actually be used and tested.

It looks like the root cause here was the lack of dt-bindings to only allow
the phy-mode values the hardware supports. What I see here is the driver
change should've been tested on all different hardware the driver controls
then the improper describing of hardware on the devicetree source file
addressed.

If a devicetree change that ensures proper describing of hardware is found
to break a driver in the future, then that exposes a bug on the driver and
the driver will have to be fixed. I don't see this upholding writing
dt-bindings that ensures proper describing of the hardware.

> 
>> Although I see dsa.yaml and dsa-port.yaml mostly consist of describing an
>> ethernet switch with CPU port(s), there're properties that are specific to
>> DSA, such as dsa,member on dsa.yaml and dsa-tag-protocol and label on
>> dsa-port.yaml.
> 
> I would say dsa,member does describe the hardware. It provides two
> bits of information:
> 
> Which cluster of switches does this switch belong to. You probably can
> derive it using the DSA links between switches, which is also a
> hardware property. But having it in device tree makes it simpler.
> 
> Which switch is this within a cluster. You need to be able to say:
> Send this frame out Port X of switch Y. How does a switch know it is
> Y? It could be strapping, which is clearly a hardware property.
> 
> dsa-tag-protocol is similar to phy-mode. It tells you the protocol
> running between the CPU port and the SoC master interface. You often
> can imply it, but again, it could be determined by strapping on the
> switch.
> 
> label is an interesting one, and probably would not be accepted if it
> was proposed now. But it has been around a long time. It also does
> describe the hardware, it is what is printed on the case next to the
> RJ45. To make the user experience simpler, we then try to make the
> linux interface name match the label on the case.

Looks like we can incorporate dsa.port and dsa-port.yaml into
ethernet-switch.yaml and ethernet-switch-port.yaml with adjustments.

Arınç
Andrew Lunn Sept. 21, 2023, 11:29 p.m. UTC | #7
On Thu, Sep 21, 2023 at 09:21:40PM +0300, Arınç ÜNAL wrote:
> On 21.09.2023 16:00, Andrew Lunn wrote:
> > > - Link descriptions must be required on ethernet controllers. We don't care
> > >    whether some Linux driver can or cannot find the PHY or set up a fixed
> > >    link without looking at the devicetree.
> > 
> > That can lead to future surprises, and breakage.
> > 
> > Something which is not used is not tested, and so sometimes wrong, and
> > nobody knows. Say the driver is extended to a new device and actually
> > does need to use this never before used information. You then find it
> > is wrong, and you get a regression.
> > 
> > We have had issues like this before. There are four rgmii phy-link
> > modes. We have had PHY drivers which ignored one of those modes, it
> > silently accepted it, but did not change the hardware to actually use
> > that mode. The PHY continues to use its reset defaults or strapping,
> > and it worked. A lot of device trees ended up using this mode. And it
> > was not the same as reset defaults/strapping.
> > 
> > And then somebody needed that fourth mode, and made it actually
> > work. And all those boards wrongly using that mode broke.
> > 
> > The lesson i learned from that episode is that anything in device tree
> > must actually be used and tested.
> 
> It looks like the root cause here was the lack of dt-bindings to
> only allow the phy-mode values the hardware supports.

That would not help. The hardware supported all 4 RGMII modes. So
listing all four in the dt-binding would be correct. But the driver
for the hardware had a bug, and so silently ignored one of the
modes. That then masked the bugs in board DT files.

> What I see here is the driver change should've been tested on all
> different hardware the driver controls then the improper describing
> of hardware on the devicetree source file addressed.

Which is what did happen. But it took a while to find all those broken
boards.  For a period of time, we had regressions.

Bugs happen. It is a fact of life. But we want those bugs to be easy
to find as possible. If we force DT writers to add properties which
the driver never uses, they are going to be bugs in those
properties. And those bugs are not going to be easy to find, and quite
likely, they will only be found a long time after they are added. We
should not be adding unused properties and bugs just to keep a yaml
checker happy.

	Andrew
Arınç ÜNAL Sept. 22, 2023, 5:47 a.m. UTC | #8
On 22.09.2023 02:29, Andrew Lunn wrote:
> On Thu, Sep 21, 2023 at 09:21:40PM +0300, Arınç ÜNAL wrote:
>> On 21.09.2023 16:00, Andrew Lunn wrote:
>>>> - Link descriptions must be required on ethernet controllers. We don't care
>>>>     whether some Linux driver can or cannot find the PHY or set up a fixed
>>>>     link without looking at the devicetree.
>>>
>>> That can lead to future surprises, and breakage.
>>>
>>> Something which is not used is not tested, and so sometimes wrong, and
>>> nobody knows. Say the driver is extended to a new device and actually
>>> does need to use this never before used information. You then find it
>>> is wrong, and you get a regression.
>>>
>>> We have had issues like this before. There are four rgmii phy-link
>>> modes. We have had PHY drivers which ignored one of those modes, it
>>> silently accepted it, but did not change the hardware to actually use
>>> that mode. The PHY continues to use its reset defaults or strapping,
>>> and it worked. A lot of device trees ended up using this mode. And it
>>> was not the same as reset defaults/strapping.
>>>
>>> And then somebody needed that fourth mode, and made it actually
>>> work. And all those boards wrongly using that mode broke.
>>>
>>> The lesson i learned from that episode is that anything in device tree
>>> must actually be used and tested.
>>
>> It looks like the root cause here was the lack of dt-bindings to
>> only allow the phy-mode values the hardware supports.
> 
> That would not help. The hardware supported all 4 RGMII modes. So
> listing all four in the dt-binding would be correct. But the driver
> for the hardware had a bug, and so silently ignored one of the
> modes. That then masked the bugs in board DT files.
> 
>> What I see here is the driver change should've been tested on all
>> different hardware the driver controls then the improper describing
>> of hardware on the devicetree source file addressed.
> 
> Which is what did happen. But it took a while to find all those broken
> boards.  For a period of time, we had regressions.
> 
> Bugs happen. It is a fact of life. But we want those bugs to be easy
> to find as possible. If we force DT writers to add properties which
> the driver never uses, they are going to be bugs in those
> properties. And those bugs are not going to be easy to find, and quite
> likely, they will only be found a long time after they are added. We
> should not be adding unused properties and bugs just to keep a yaml
> checker happy.

Understood. Then I will refrain from enforcing link descriptions altogether
as I can't justify enforcing them on ethernet controllers selectively
because certain Linux drivers don't make use of the link properties and may
expose bugs if used.

The link properties are still allowed for all ethernet controllers though,
just not enforced. But I suppose it's better to optionally find the bug
instead of causing a regression then finding the bug.

Arınç
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/net/altr,tse.yaml b/Documentation/devicetree/bindings/net/altr,tse.yaml
index f5d3b70af07a..24e0f1213109 100644
--- a/Documentation/devicetree/bindings/net/altr,tse.yaml
+++ b/Documentation/devicetree/bindings/net/altr,tse.yaml
@@ -67,6 +67,7 @@  required:
 
 allOf:
   - $ref: ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#/$defs/phylink
   - if:
       properties:
         compatible:
diff --git a/Documentation/devicetree/bindings/net/cdns,macb.yaml b/Documentation/devicetree/bindings/net/cdns,macb.yaml
index bf8894a0257e..a455de04c5f1 100644
--- a/Documentation/devicetree/bindings/net/cdns,macb.yaml
+++ b/Documentation/devicetree/bindings/net/cdns,macb.yaml
@@ -156,6 +156,7 @@  required:
 
 allOf:
   - $ref: ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#/$defs/phylink
 
   - if:
       not:
diff --git a/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml
index 9565a7402146..7829fc9e202d 100644
--- a/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml
@@ -29,6 +29,12 @@  properties:
   reg:
     maxItems: 1
 
+patternProperties:
+  "^(ethernet-)?ports$":
+    patternProperties:
+      "^(ethernet-)?port@[0-9]+$":
+        $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 required:
   - compatible
   - reg
diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml
index 0bb2ff0cf2d0..ed5b3eab1948 100644
--- a/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml
@@ -142,6 +142,15 @@  allOf:
         reg:
           maxItems: 1
 
+  - if:
+      required: [ mdio ]
+    then:
+      patternProperties:
+        "^(ethernet-)?ports$":
+          patternProperties:
+            "^(ethernet-)?port@[0-9]+$":
+              $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 unevaluatedProperties: false
 
 examples:
diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml
index c745407f2f68..6cffcd35a943 100644
--- a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml
@@ -81,7 +81,10 @@  properties:
 
     patternProperties:
       '^port@[0-9a-f]$':
-        $ref: dsa-port.yaml#
+        type: object
+        allOf:
+          - $ref: dsa-port.yaml#
+          - $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
         unevaluatedProperties: false
 
         properties:
@@ -161,6 +164,7 @@  examples:
                     port@0 {
                             label = "gphy";
                             reg = <0>;
+                            phy-handle = <&phy8>;
                     };
             };
     };
diff --git a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml
index 4021b054f684..30b4c7b1fd08 100644
--- a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml
@@ -67,6 +67,12 @@  properties:
 
     additionalProperties: false
 
+patternProperties:
+  "^(ethernet-)?ports$":
+    patternProperties:
+      "^(ethernet-)?port@[0-9]+$":
+        $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 required:
   - compatible
   - reg
diff --git a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml
index 31a7dbbf704d..a8e1134707e4 100644
--- a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml
@@ -297,6 +297,15 @@  allOf:
         mediatek,mcm: false
         reset-names: false
 
+  - if:
+      required: [ mdio ]
+    then:
+      patternProperties:
+        "^(ethernet-)?ports$":
+          patternProperties:
+            "^(ethernet-)?port@[0-9]+$":
+              $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 unevaluatedProperties: false
 
 examples:
diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
index 20e4174fe1ab..d8f12234eec6 100644
--- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
@@ -60,6 +60,15 @@  required:
   - compatible
   - reg
 
+if:
+  required: [ mdio ]
+then:
+  patternProperties:
+    "^(ethernet-)?ports$":
+      patternProperties:
+        "^(ethernet-)?port@[0-9]+$":
+          $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 unevaluatedProperties: false
 
 examples:
diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml
index 33a4926b2d94..44a892b93eca 100644
--- a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml
@@ -65,6 +65,15 @@  required:
   - compatible
   - reg
 
+if:
+  required: [ mdio ]
+then:
+  patternProperties:
+    "^(ethernet-)?ports$":
+      patternProperties:
+        "^(ethernet-)?port@[0-9]+$":
+          $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 unevaluatedProperties: false
 
 examples:
diff --git a/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml b/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml
index fe02d05196e4..80cc9c49282b 100644
--- a/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml
@@ -73,6 +73,12 @@  properties:
   little-endian: true
   big-endian: true
 
+patternProperties:
+  "^(ethernet-)?ports$":
+    patternProperties:
+      "^(ethernet-)?port@[0-9]+$":
+        $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 required:
   - compatible
   - reg
diff --git a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml
index 6838dc165d06..1d5c4a81caf6 100644
--- a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml
@@ -79,6 +79,7 @@  patternProperties:
   "^(ethernet-)?ports$":
     patternProperties:
       "^(ethernet-)?port@[0-9]+$":
+        $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
         allOf:
           - if:
               properties:
diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml
index c472050582be..546939ab2053 100644
--- a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml
@@ -114,6 +114,15 @@  required:
   - compatible
   - reg
 
+if:
+  required: [ mdio ]
+then:
+  patternProperties:
+    "^(ethernet-)?ports$":
+      patternProperties:
+        "^(ethernet-)?port@[0-6]$":
+          $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
+
 unevaluatedProperties: false
 
 examples:
diff --git a/Documentation/devicetree/bindings/net/dsa/realtek.yaml b/Documentation/devicetree/bindings/net/dsa/realtek.yaml
index 62ebaa4b5ae3..ec0428b74157 100644
--- a/Documentation/devicetree/bindings/net/dsa/realtek.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/realtek.yaml
@@ -6,8 +6,7 @@  $schema: http://devicetree.org/meta-schemas/core.yaml#
 
 title: Realtek switches for unmanaged switches
 
-allOf:
-  - $ref: dsa.yaml#/$defs/ethernet-ports
+$ref: dsa.yaml#/$defs/ethernet-ports
 
 maintainers:
   - Linus Walleij <linus.walleij@linaro.org>
@@ -107,33 +106,43 @@  properties:
       compatible:
         const: realtek,smi-mdio
 
-if:
-  required:
-    - reg
+allOf:
+  - if:
+      required:
+        - reg
 
-then:
-  $ref: /schemas/spi/spi-peripheral-props.yaml#
-  properties:
-    mdc-gpios: false
-    mdio-gpios: false
-    mdio:
+    then:
+      $ref: /schemas/spi/spi-peripheral-props.yaml#
       properties:
-        compatible: false
+        mdc-gpios: false
+        mdio-gpios: false
+        mdio:
+          properties:
+            compatible: false
 
-else:
-  properties:
-    mdio:
-      required:
-        - compatible
+    else:
+      properties:
+        mdio:
+          required:
+            - compatible
 
-  required:
-    - mdc-gpios
-    - mdio-gpios
-    - mdio
-    - reset-gpios
+      required:
+        - mdc-gpios
+        - mdio-gpios
+        - mdio
+        - reset-gpios
 
-required:
-  - compatible
+    required:
+      - compatible
+
+  - if:
+      required: [ mdio ]
+    then:
+      patternProperties:
+        "^(ethernet-)?ports$":
+          patternProperties:
+            "^(ethernet-)?port@[0-9]+$":
+              $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
 
 unevaluatedProperties: false
 
diff --git a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml
index 9ad9f5cdf688..7ec4371932ef 100644
--- a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml
@@ -72,7 +72,7 @@  properties:
 
     patternProperties:
       "^(ethernet-)?port@[0-4]$":
-        type: object
+        $ref: /schemas/net/ethernet-controller.yaml#/$defs/phylink
         description: Ethernet switch ports
 
         properties:
diff --git a/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml
index c80c880a9dab..c31db5f7d548 100644
--- a/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml
+++ b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml
@@ -136,6 +136,7 @@  dependencies:
 
 allOf:
   - $ref: ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#/$defs/phylink
   - if:
       properties:
         compatible:
diff --git a/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml b/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml
index a1b71b35319e..b2cab0fa7b35 100644
--- a/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml
+++ b/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml
@@ -15,6 +15,7 @@  description:
 
 allOf:
   - $ref: ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#/$defs/phylink
 
 properties:
   compatible:
diff --git a/Documentation/devicetree/bindings/net/marvell,pp2.yaml b/Documentation/devicetree/bindings/net/marvell,pp2.yaml
index 4eadafc43d4f..8e60cc4bbbc9 100644
--- a/Documentation/devicetree/bindings/net/marvell,pp2.yaml
+++ b/Documentation/devicetree/bindings/net/marvell,pp2.yaml
@@ -59,7 +59,9 @@  patternProperties:
   '^(ethernet-)?port@[0-2]$':
     type: object
     description: subnode for each ethernet port.
-    $ref: ethernet-controller.yaml#
+    allOf:
+      - $ref: ethernet-controller.yaml#
+      - $ref: ethernet-controller.yaml#/$defs/phylink
     unevaluatedProperties: false
 
     properties:
diff --git a/Documentation/devicetree/bindings/net/mediatek,net.yaml b/Documentation/devicetree/bindings/net/mediatek,net.yaml
index e74502a0afe8..7562bb64baa9 100644
--- a/Documentation/devicetree/bindings/net/mediatek,net.yaml
+++ b/Documentation/devicetree/bindings/net/mediatek,net.yaml
@@ -391,6 +391,7 @@  patternProperties:
     unevaluatedProperties: false
     allOf:
       - $ref: ethernet-controller.yaml#
+      - $ref: ethernet-controller.yaml#/$defs/phylink
     description:
       Ethernet MAC node
     properties:
diff --git a/Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml b/Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml
index 306ef9ecf2b9..a770cfc490a9 100644
--- a/Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml
+++ b/Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml
@@ -73,7 +73,9 @@  properties:
       "^port@[0-9a-f]+$":
         type: object
 
-        $ref: /schemas/net/ethernet-controller.yaml#
+        allOf:
+          - $ref: ethernet-controller.yaml#
+          - $ref: ethernet-controller.yaml#/$defs/phylink
         unevaluatedProperties: false
 
         properties:
diff --git a/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml b/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml
index fcafef8d5a33..da4b4d934705 100644
--- a/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml
+++ b/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml
@@ -84,7 +84,10 @@  properties:
 
     patternProperties:
       "^port@[0-9a-f]+$":
-        $ref: /schemas/net/ethernet-controller.yaml#
+        type: object
+        allOf:
+          - $ref: ethernet-controller.yaml#
+          - $ref: ethernet-controller.yaml#/$defs/phylink
         unevaluatedProperties: false
 
         properties:
diff --git a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml
index 8ee2c7d7ff42..b3aff7b0790e 100644
--- a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml
+++ b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml
@@ -126,6 +126,11 @@  properties:
       - const: xtr
       - const: fdma
 
+  ethernet-ports:
+    patternProperties:
+      "^port@[0-9a-f]+$":
+        $ref: ethernet-controller.yaml#/$defs/phylink
+
 required:
   - compatible
   - reg
diff --git a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml
index 89f94b31b546..d021bfb4ad20 100644
--- a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml
+++ b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml
@@ -8,6 +8,7 @@  title: QCA AR71XX MAC
 
 allOf:
   - $ref: ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#/$defs/phylink
 
 maintainers:
   - Oleksij Rempel <o.rempel@pengutronix.de>
diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml
index ddf9522a5dc2..62d8c2cfafe9 100644
--- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml
+++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml
@@ -567,6 +567,7 @@  dependencies:
 
 allOf:
   - $ref: ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#/$defs/phylink
   - if:
       properties:
         compatible:
diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml
index c9c25132d154..d4366a11918e 100644
--- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml
+++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml
@@ -117,7 +117,9 @@  properties:
         type: object
         description: CPSWxG NUSS external ports
 
-        $ref: ethernet-controller.yaml#
+        allOf:
+          - $ref: ethernet-controller.yaml#
+          - $ref: ethernet-controller.yaml#/$defs/phylink
         unevaluatedProperties: false
 
         properties:
diff --git a/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml b/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml
index 1d33d80af11c..f8894546c02a 100644
--- a/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml
+++ b/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml
@@ -130,7 +130,8 @@  required:
   - phy-handle
 
 allOf:
-  - $ref: /schemas/net/ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#
+  - $ref: ethernet-controller.yaml#/$defs/phylink
 
 additionalProperties: false