diff mbox series

[RFC,net-next,1/9] dt-bindings: net: dsa: convert ksz bindings document to yaml

Message ID 20201019172435.4416-2-ceggers@arri.de
State RFC
Delegated to: David Miller
Headers show
Series net: dsa: microchip: PTP support for KSZ956x | expand

Commit Message

Christian Eggers Oct. 19, 2020, 5:24 p.m. UTC 
Convert the bindings document for Microchip KSZ Series Ethernet switches
from txt to yaml.

Signed-off-by: Christian Eggers <ceggers@arri.de>
---
 .../devicetree/bindings/net/dsa/ksz.txt       | 125 ---------------
 .../bindings/net/dsa/microchip,ksz.yaml       | 147 ++++++++++++++++++
 MAINTAINERS                                   |   2 +-
 3 files changed, 148 insertions(+), 126 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/net/dsa/ksz.txt
 create mode 100644 Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml

Comments

Kurt Kanzenbach Oct. 21, 2020, 6:52 a.m. UTC | #1 
On Mon Oct 19 2020, Christian Eggers wrote:
> Convert the bindings document for Microchip KSZ Series Ethernet switches
> from txt to yaml.

A few comments/questions below.

> diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
> new file mode 100644
> index 000000000000..f93c3bdd0b83
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml

Currently the bindings don't have the company names in front of it.

> @@ -0,0 +1,147 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/dsa/microchip,ksz.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Microchip KSZ Series Ethernet switches
> +
> +maintainers:
> +  - Marek Vasut <marex@denx.de>
> +  - Woojung Huh <Woojung.Huh@microchip.com>
> +
> +properties:
> +  # See Documentation/devicetree/bindings/net/dsa/dsa.yaml for a list of additional
> +  # required and optional properties.

Don't you need to reference the dsa.yaml binding somehow?

> +  compatible:
> +    enum:
> +      - "microchip,ksz8765"
> +      - "microchip,ksz8794"
> +      - "microchip,ksz8795"
> +      - "microchip,ksz9477"
> +      - "microchip,ksz9897"
> +      - "microchip,ksz9896"
> +      - "microchip,ksz9567"
> +      - "microchip,ksz8565"
> +      - "microchip,ksz9893"
> +      - "microchip,ksz9563"
> +      - "microchip,ksz8563"
> +
> +  reset-gpios:
> +    description:
> +      Should be a gpio specifier for a reset line.
> +    maxItems: 1
> +
> +  microchip,synclko-125:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description:
> +      Set if the output SYNCLKO frequency should be set to 125MHz instead of 25MHz.
> +
> +required:
> +  - compatible
> +  - reg
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    // Ethernet switch connected via SPI to the host, CPU port wired to eth0:
> +    eth0 {
> +        fixed-link {
> +            speed = <1000>;
> +            full-duplex;
> +        };
> +    };
> +
> +    spi0 {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        pinctrl-0 = <&pinctrl_spi_ksz>;
> +        cs-gpios = <&pioC 25 0>;
> +        id = <1>;
> +
> +        ksz9477: ksz9477@0 {

The node names should be switch. See dsa.yaml.

> +            compatible = "microchip,ksz9477";
> +            reg = <0>;
> +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
> +
> +            spi-max-frequency = <44000000>;
> +            spi-cpha;
> +            spi-cpol;
> +
> +            ports {

ethernet-ports are preferred.

Thanks,
Kurt
Christian Eggers Oct. 21, 2020, 8:46 a.m. UTC | #2 
On Wednesday, 21 October 2020, 08:52:01 CEST, Kurt Kanzenbach wrote:
> On Mon Oct 19 2020, Christian Eggers wrote:
> > Convert the bindings document for Microchip KSZ Series Ethernet switches
> > from txt to yaml.
> 
> A few comments/questions below.
> 
> > diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
> > b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml new file
> > mode 100644
> > index 000000000000..f93c3bdd0b83
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
> 
> Currently the bindings don't have the company names in front of it.
All current bindings are in .txt format. In other subsystems (like iio),
company names have been added when converting to yaml.

> > @@ -0,0 +1,147 @@
> > +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/net/dsa/microchip,ksz.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Microchip KSZ Series Ethernet switches
> > +
> > +maintainers:
> > +  - Marek Vasut <marex@denx.de>
> > +  - Woojung Huh <Woojung.Huh@microchip.com>
> > +
> > +properties:
> > +  # See Documentation/devicetree/bindings/net/dsa/dsa.yaml for a list of
> > additional +  # required and optional properties.
> 
> Don't you need to reference the dsa.yaml binding somehow?
I should have taken a look into your binding beforehand...
allOf:
  - $ref: dsa.yaml#

> > ...
> > +examples:
> > +  - |
> > +    #include <dt-bindings/gpio/gpio.h>
> > +
> > +    // Ethernet switch connected via SPI to the host, CPU port wired to eth0:
> > +    eth0 {
> > +        fixed-link {
> > +            speed = <1000>;
> > +            full-duplex;
> > +        };
> > +    };
> > +
> > +    spi0 {
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        pinctrl-0 = <&pinctrl_spi_ksz>;
> > +        cs-gpios = <&pioC 25 0>;
> > +        id = <1>;
> > +
> > +        ksz9477: ksz9477@0 {
> 
> The node names should be switch. See dsa.yaml.
changed

> 
> > +            compatible = "microchip,ksz9477";
> > +            reg = <0>;
> > +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
> > +
> > +            spi-max-frequency = <44000000>;
> > +            spi-cpha;
> > +            spi-cpol;
> > +
> > +            ports {
> 
> ethernet-ports are preferred.
"ports" is also used in the existing driver code (ksz_switch_register()).
Would like to keep it for now, probably I can be changed later.

> 
> Thanks,
> Kurt

Below the current version for the version of the patch series.

Best regards
Christian


# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/net/dsa/microchip,ksz.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Microchip KSZ Series Ethernet switches

allOf:
  - $ref: dsa.yaml#

maintainers:
  - Marek Vasut <marex@denx.de>
  - Woojung Huh <Woojung.Huh@microchip.com>

properties:
  # See Documentation/devicetree/bindings/net/dsa/dsa.yaml for a list of additional
  # required and optional properties.
  compatible:
    enum:
      - "microchip,ksz8765"
      - "microchip,ksz8794"
      - "microchip,ksz8795"
      - "microchip,ksz9477"
      - "microchip,ksz9897"
      - "microchip,ksz9896"
      - "microchip,ksz9567"
      - "microchip,ksz8565"
      - "microchip,ksz9893"
      - "microchip,ksz9563"
      - "microchip,ksz8563"

  reset-gpios:
    description:
      Should be a gpio specifier for a reset line.
    maxItems: 1

  microchip,synclko-125:
    $ref: /schemas/types.yaml#/definitions/flag
    description:
      Set if the output SYNCLKO frequency should be set to 125MHz instead of 25MHz.

required:
  - compatible
  - reg

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>

    // Ethernet switch connected via SPI to the host, CPU port wired to eth0:
    eth0 {
        fixed-link {
            speed = <1000>;
            full-duplex;
        };
    };

    spi0 {
        #address-cells = <1>;
        #size-cells = <0>;

        pinctrl-0 = <&pinctrl_spi_ksz>;
        cs-gpios = <&pioC 25 0>;
        id = <1>;

        ksz9477: switch@0 {
            compatible = "microchip,ksz9477";
            reg = <0>;
            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;

            spi-max-frequency = <44000000>;
            spi-cpha;
            spi-cpol;

            ethernet-ports {
                #address-cells = <1>;
                #size-cells = <0>;
                port@0 {
                    reg = <0>;
                    label = "lan1";
                };
                port@1 {
                    reg = <1>;
                    label = "lan2";
                };
                port@2 {
                    reg = <2>;
                    label = "lan3";
                };
                port@3 {
                    reg = <3>;
                    label = "lan4";
                };
                port@4 {
                    reg = <4>;
                    label = "lan5";
                };
                port@5 {
                    reg = <5>;
                    label = "cpu";
                    ethernet = <&eth0>;
                    fixed-link {
                        speed = <1000>;
                        full-duplex;
                    };
                };
            };
        };

        ksz8565: switch@1 {
            compatible = "microchip,ksz8565";
            reg = <1>;

            spi-max-frequency = <44000000>;
            spi-cpha;
            spi-cpol;

            ethernet-ports {
                #address-cells = <1>;
                #size-cells = <0>;
                port@0 {
                    reg = <0>;
                    label = "lan1";
                };
                port@1 {
                    reg = <1>;
                    label = "lan2";
                };
                port@2 {
                    reg = <2>;
                    label = "lan3";
                };
                port@3 {
                    reg = <3>;
                    label = "lan4";
                };
                port@6 {
                    reg = <6>;
                    label = "cpu";
                    ethernet = <&eth0>;
                    fixed-link {
                        speed = <1000>;
                        full-duplex;
                    };
                };
            };
        };
    };
...
Vladimir Oltean Oct. 22, 2020, 12:16 a.m. UTC | #3 
On Wed, Oct 21, 2020 at 08:52:01AM +0200, Kurt Kanzenbach wrote:
> On Mon Oct 19 2020, Christian Eggers wrote:
> The node names should be switch. See dsa.yaml.
> 
> > +            compatible = "microchip,ksz9477";
> > +            reg = <0>;
> > +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
> > +
> > +            spi-max-frequency = <44000000>;
> > +            spi-cpha;
> > +            spi-cpol;
> > +
> > +            ports {
> 
> ethernet-ports are preferred.

This is backwards to me, instead of an 'ethernet-switch' with 'ports',
we have a 'switch' with 'ethernet-ports'. Whatever.
Florian Fainelli Oct. 22, 2020, 12:40 a.m. UTC | #4 
On 10/21/2020 5:16 PM, Vladimir Oltean wrote:
> On Wed, Oct 21, 2020 at 08:52:01AM +0200, Kurt Kanzenbach wrote:
>> On Mon Oct 19 2020, Christian Eggers wrote:
>> The node names should be switch. See dsa.yaml.
>>
>>> +            compatible = "microchip,ksz9477";
>>> +            reg = <0>;
>>> +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
>>> +
>>> +            spi-max-frequency = <44000000>;
>>> +            spi-cpha;
>>> +            spi-cpol;
>>> +
>>> +            ports {
>>
>> ethernet-ports are preferred.
> 
> This is backwards to me, instead of an 'ethernet-switch' with 'ports',
> we have a 'switch' with 'ethernet-ports'. Whatever.

The rationale AFAIR was that dual Ethernet port controllers like TI's 
CPSW needed to describe each port as a pseudo Ethernet MAC and using 
'ethernet-ports' as a contained allowed to disambiguate with the 'ports' 
container used in display subsystem descriptions. We should probably 
enforce or recommend 'ethernet-switch' to be used as the node name for 
Ethernet switch devices though.
Kurt Kanzenbach Oct. 22, 2020, 10:54 a.m. UTC | #5 
On Wed Oct 21 2020, Florian Fainelli wrote:
> On 10/21/2020 5:16 PM, Vladimir Oltean wrote:
>> On Wed, Oct 21, 2020 at 08:52:01AM +0200, Kurt Kanzenbach wrote:
>>> On Mon Oct 19 2020, Christian Eggers wrote:
>>> The node names should be switch. See dsa.yaml.
>>>
>>>> +            compatible = "microchip,ksz9477";
>>>> +            reg = <0>;
>>>> +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
>>>> +
>>>> +            spi-max-frequency = <44000000>;
>>>> +            spi-cpha;
>>>> +            spi-cpol;
>>>> +
>>>> +            ports {
>>>
>>> ethernet-ports are preferred.
>> 
>> This is backwards to me, instead of an 'ethernet-switch' with 'ports',
>> we have a 'switch' with 'ethernet-ports'. Whatever.
>
> The rationale AFAIR was that dual Ethernet port controllers like TI's 
> CPSW needed to describe each port as a pseudo Ethernet MAC and using 
> 'ethernet-ports' as a contained allowed to disambiguate with the 'ports' 
> container used in display subsystem descriptions.

Yes, that was the outcome of previous discussions.

> We should probably enforce or recommend 'ethernet-switch' to be used
> as the node name for Ethernet switch devices though.

After using grep, it seems like 'ethernet-switch' as well as simply
'switch' are being used today. Yes, maybe both should be allowed.

Thanks,
Kurt
Vladimir Oltean Oct. 22, 2020, 12:37 p.m. UTC | #6 
On Thu, Oct 22, 2020 at 12:54:52PM +0200, Kurt Kanzenbach wrote:
> On Wed Oct 21 2020, Florian Fainelli wrote:
> > On 10/21/2020 5:16 PM, Vladimir Oltean wrote:
> >> On Wed, Oct 21, 2020 at 08:52:01AM +0200, Kurt Kanzenbach wrote:
> >>> On Mon Oct 19 2020, Christian Eggers wrote:
> >>> The node names should be switch. See dsa.yaml.
> >>>
> >>>> +            compatible = "microchip,ksz9477";
> >>>> +            reg = <0>;
> >>>> +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
> >>>> +
> >>>> +            spi-max-frequency = <44000000>;
> >>>> +            spi-cpha;
> >>>> +            spi-cpol;
> >>>> +
> >>>> +            ports {
> >>>
> >>> ethernet-ports are preferred.
> >> 
> >> This is backwards to me, instead of an 'ethernet-switch' with 'ports',
> >> we have a 'switch' with 'ethernet-ports'. Whatever.
> >
> > The rationale AFAIR was that dual Ethernet port controllers like TI's 
> > CPSW needed to describe each port as a pseudo Ethernet MAC and using 
> > 'ethernet-ports' as a contained allowed to disambiguate with the 'ports' 
> > container used in display subsystem descriptions.
> 
> Yes, that was the outcome of previous discussions.

And why would that disambiguation be necessary in the first place? My
understanding is that the whole node path provides the necessary
namespacing to avoid the confusion. For example, the 'reg' property
means 100 things to 100 buses, and no one has an issue with that. I am
not expecting an Ethernet switch to have an HDMI port, I might be wrong
though.
Florian Fainelli Oct. 22, 2020, 7:17 p.m. UTC | #7 
On 10/22/20 5:37 AM, Vladimir Oltean wrote:
> On Thu, Oct 22, 2020 at 12:54:52PM +0200, Kurt Kanzenbach wrote:
>> On Wed Oct 21 2020, Florian Fainelli wrote:
>>> On 10/21/2020 5:16 PM, Vladimir Oltean wrote:
>>>> On Wed, Oct 21, 2020 at 08:52:01AM +0200, Kurt Kanzenbach wrote:
>>>>> On Mon Oct 19 2020, Christian Eggers wrote:
>>>>> The node names should be switch. See dsa.yaml.
>>>>>
>>>>>> +            compatible = "microchip,ksz9477";
>>>>>> +            reg = <0>;
>>>>>> +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
>>>>>> +
>>>>>> +            spi-max-frequency = <44000000>;
>>>>>> +            spi-cpha;
>>>>>> +            spi-cpol;
>>>>>> +
>>>>>> +            ports {
>>>>>
>>>>> ethernet-ports are preferred.
>>>>
>>>> This is backwards to me, instead of an 'ethernet-switch' with 'ports',
>>>> we have a 'switch' with 'ethernet-ports'. Whatever.
>>>
>>> The rationale AFAIR was that dual Ethernet port controllers like TI's 
>>> CPSW needed to describe each port as a pseudo Ethernet MAC and using 
>>> 'ethernet-ports' as a contained allowed to disambiguate with the 'ports' 
>>> container used in display subsystem descriptions.
>>
>> Yes, that was the outcome of previous discussions.
> 
> And why would that disambiguation be necessary in the first place? My
> understanding is that the whole node path provides the necessary
> namespacing to avoid the confusion. For example, the 'reg' property
> means 100 things to 100 buses, and no one has an issue with that. I am
> not expecting an Ethernet switch to have an HDMI port, I might be wrong
> though.

The disambiguation is more of a hint given to DT analysis tools to
validate a given node with little to no knowledge of the containing
node. I don't really have a dog in the fight here.
Rob Herring (Arm) Oct. 26, 2020, 1:54 p.m. UTC | #8 
On Thu, Oct 22, 2020 at 12:17:26PM -0700, Florian Fainelli wrote:
> On 10/22/20 5:37 AM, Vladimir Oltean wrote:
> > On Thu, Oct 22, 2020 at 12:54:52PM +0200, Kurt Kanzenbach wrote:
> >> On Wed Oct 21 2020, Florian Fainelli wrote:
> >>> On 10/21/2020 5:16 PM, Vladimir Oltean wrote:
> >>>> On Wed, Oct 21, 2020 at 08:52:01AM +0200, Kurt Kanzenbach wrote:
> >>>>> On Mon Oct 19 2020, Christian Eggers wrote:
> >>>>> The node names should be switch. See dsa.yaml.
> >>>>>
> >>>>>> +            compatible = "microchip,ksz9477";
> >>>>>> +            reg = <0>;
> >>>>>> +            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
> >>>>>> +
> >>>>>> +            spi-max-frequency = <44000000>;
> >>>>>> +            spi-cpha;
> >>>>>> +            spi-cpol;
> >>>>>> +
> >>>>>> +            ports {
> >>>>>
> >>>>> ethernet-ports are preferred.
> >>>>
> >>>> This is backwards to me, instead of an 'ethernet-switch' with 'ports',
> >>>> we have a 'switch' with 'ethernet-ports'. Whatever.
> >>>
> >>> The rationale AFAIR was that dual Ethernet port controllers like TI's 
> >>> CPSW needed to describe each port as a pseudo Ethernet MAC and using 
> >>> 'ethernet-ports' as a contained allowed to disambiguate with the 'ports' 
> >>> container used in display subsystem descriptions.
> >>
> >> Yes, that was the outcome of previous discussions.
> > 
> > And why would that disambiguation be necessary in the first place? My
> > understanding is that the whole node path provides the necessary
> > namespacing to avoid the confusion. For example, the 'reg' property
> > means 100 things to 100 buses, and no one has an issue with that. I am
> > not expecting an Ethernet switch to have an HDMI port, I might be wrong
> > though.
> 
> The disambiguation is more of a hint given to DT analysis tools to
> validate a given node with little to no knowledge of the containing
> node. I don't really have a dog in the fight here.

A node name should mean 1 and only 1 type/class of node. 'ports' (and 
'port') is for the graph binding.

Rob
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/net/dsa/ksz.txt b/Documentation/devicetree/bindings/net/dsa/ksz.txt
deleted file mode 100644
index 95e91e84151c..000000000000
--- a/Documentation/devicetree/bindings/net/dsa/ksz.txt
+++ /dev/null
@@ -1,125 +0,0 @@ 
-Microchip KSZ Series Ethernet switches
-==================================
-
-Required properties:
-
-- compatible: For external switch chips, compatible string must be exactly one
-  of the following:
-  - "microchip,ksz8765"
-  - "microchip,ksz8794"
-  - "microchip,ksz8795"
-  - "microchip,ksz9477"
-  - "microchip,ksz9897"
-  - "microchip,ksz9896"
-  - "microchip,ksz9567"
-  - "microchip,ksz8565"
-  - "microchip,ksz9893"
-  - "microchip,ksz9563"
-  - "microchip,ksz8563"
-
-Optional properties:
-
-- reset-gpios		: Should be a gpio specifier for a reset line
-- microchip,synclko-125 : Set if the output SYNCLKO frequency should be set to
-			  125MHz instead of 25MHz.
-
-See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional
-required and optional properties.
-
-Examples:
-
-Ethernet switch connected via SPI to the host, CPU port wired to eth0:
-
-	eth0: ethernet@10001000 {
-		fixed-link {
-			speed = <1000>;
-			full-duplex;
-		};
-	};
-
-	spi1: spi@f8008000 {
-		pinctrl-0 = <&pinctrl_spi_ksz>;
-		cs-gpios = <&pioC 25 0>;
-		id = <1>;
-
-		ksz9477: ksz9477@0 {
-			compatible = "microchip,ksz9477";
-			reg = <0>;
-
-			spi-max-frequency = <44000000>;
-			spi-cpha;
-			spi-cpol;
-
-			ports {
-				#address-cells = <1>;
-				#size-cells = <0>;
-				port@0 {
-					reg = <0>;
-					label = "lan1";
-				};
-				port@1 {
-					reg = <1>;
-					label = "lan2";
-				};
-				port@2 {
-					reg = <2>;
-					label = "lan3";
-				};
-				port@3 {
-					reg = <3>;
-					label = "lan4";
-				};
-				port@4 {
-					reg = <4>;
-					label = "lan5";
-				};
-				port@5 {
-					reg = <5>;
-					label = "cpu";
-					ethernet = <&eth0>;
-					fixed-link {
-						speed = <1000>;
-						full-duplex;
-					};
-				};
-			};
-		};
-		ksz8565: ksz8565@0 {
-			compatible = "microchip,ksz8565";
-			reg = <0>;
-
-			spi-max-frequency = <44000000>;
-			spi-cpha;
-			spi-cpol;
-
-			ports {
-				#address-cells = <1>;
-				#size-cells = <0>;
-				port@0 {
-					reg = <0>;
-					label = "lan1";
-				};
-				port@1 {
-					reg = <1>;
-					label = "lan2";
-				};
-				port@2 {
-					reg = <2>;
-					label = "lan3";
-				};
-				port@3 {
-					reg = <3>;
-					label = "lan4";
-				};
-				port@6 {
-					reg = <6>;
-					label = "cpu";
-					ethernet = <&eth0>;
-					fixed-link {
-						speed = <1000>;
-						full-duplex;
-					};
-				};
-			};
-		};
-	};
diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
new file mode 100644
index 000000000000..f93c3bdd0b83
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
@@ -0,0 +1,147 @@ 
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/dsa/microchip,ksz.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip KSZ Series Ethernet switches
+
+maintainers:
+  - Marek Vasut <marex@denx.de>
+  - Woojung Huh <Woojung.Huh@microchip.com>
+
+properties:
+  # See Documentation/devicetree/bindings/net/dsa/dsa.yaml for a list of additional
+  # required and optional properties.
+  compatible:
+    enum:
+      - "microchip,ksz8765"
+      - "microchip,ksz8794"
+      - "microchip,ksz8795"
+      - "microchip,ksz9477"
+      - "microchip,ksz9897"
+      - "microchip,ksz9896"
+      - "microchip,ksz9567"
+      - "microchip,ksz8565"
+      - "microchip,ksz9893"
+      - "microchip,ksz9563"
+      - "microchip,ksz8563"
+
+  reset-gpios:
+    description:
+      Should be a gpio specifier for a reset line.
+    maxItems: 1
+
+  microchip,synclko-125:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      Set if the output SYNCLKO frequency should be set to 125MHz instead of 25MHz.
+
+required:
+  - compatible
+  - reg
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+
+    // Ethernet switch connected via SPI to the host, CPU port wired to eth0:
+    eth0 {
+        fixed-link {
+            speed = <1000>;
+            full-duplex;
+        };
+    };
+
+    spi0 {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        pinctrl-0 = <&pinctrl_spi_ksz>;
+        cs-gpios = <&pioC 25 0>;
+        id = <1>;
+
+        ksz9477: ksz9477@0 {
+            compatible = "microchip,ksz9477";
+            reg = <0>;
+            reset-gpios = <&gpio5 0 GPIO_ACTIVE_LOW>;
+
+            spi-max-frequency = <44000000>;
+            spi-cpha;
+            spi-cpol;
+
+            ports {
+                #address-cells = <1>;
+                #size-cells = <0>;
+                port@0 {
+                    reg = <0>;
+                    label = "lan1";
+                };
+                port@1 {
+                    reg = <1>;
+                    label = "lan2";
+                };
+                port@2 {
+                    reg = <2>;
+                    label = "lan3";
+                };
+                port@3 {
+                    reg = <3>;
+                    label = "lan4";
+                };
+                port@4 {
+                    reg = <4>;
+                    label = "lan5";
+                };
+                port@5 {
+                    reg = <5>;
+                    label = "cpu";
+                    ethernet = <&eth0>;
+                    fixed-link {
+                        speed = <1000>;
+                        full-duplex;
+                    };
+                };
+            };
+        };
+
+        ksz8565: ksz8565@1 {
+            compatible = "microchip,ksz8565";
+            reg = <1>;
+
+            spi-max-frequency = <44000000>;
+            spi-cpha;
+            spi-cpol;
+
+            ports {
+                #address-cells = <1>;
+                #size-cells = <0>;
+                port@0 {
+                    reg = <0>;
+                    label = "lan1";
+                };
+                port@1 {
+                    reg = <1>;
+                    label = "lan2";
+                };
+                port@2 {
+                    reg = <2>;
+                    label = "lan3";
+                };
+                port@3 {
+                    reg = <3>;
+                    label = "lan4";
+                };
+                port@6 {
+                    reg = <6>;
+                    label = "cpu";
+                    ethernet = <&eth0>;
+                    fixed-link {
+                        speed = <1000>;
+                        full-duplex;
+                    };
+                };
+            };
+        };
+    };
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index a4cba74383fa..8f56ced74cb1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11467,7 +11467,7 @@  M:	Woojung Huh <woojung.huh@microchip.com>
 M:	Microchip Linux Driver Support <UNGLinuxDriver@microchip.com>
 L:	netdev@vger.kernel.org
 S:	Maintained
-F:	Documentation/devicetree/bindings/net/dsa/ksz.txt
+F:	Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
 F:	drivers/net/dsa/microchip/*
 F:	include/linux/platform_data/microchip-ksz.h
 F:	net/dsa/tag_ksz.c