[PATCH v3 1/1] dt-bindings: net: convert qca,qca7000.txt yaml format

[PATCH v3 1/1] dt-bindings: net: convert qca,qca7000.txt yaml format

[Frank Li]

Convert qca,qca7000.txt yaml format.

Additional changes:
- add refs: spi-peripheral-props.yaml, serial-peripheral-props.yaml and
  ethernet-controller.yaml.
- simple spi and uart node name.
- use low case for mac address in examples.
- add check reg choose spi-peripheral-props.yaml or
  spi-peripheral-props.yaml.

Signed-off-by: Frank Li <Frank.Li@nxp.com>
---
change in v3
- move ethernet-controller.yaml# out of if branch

change in v2
- add Ethernet over UART" description here back
- add add check reg choose spi-peripheral-props.yaml
- move spi related properties in if-then branch
- move uart related properies in if-else branch
---
 .../devicetree/bindings/net/qca,qca7000.txt   |  87 ---------------
 .../devicetree/bindings/net/qca,qca7000.yaml  | 105 ++++++++++++++++++
 MAINTAINERS                                   |   2 +-
 3 files changed, 106 insertions(+), 88 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/net/qca,qca7000.txt
 create mode 100644 Documentation/devicetree/bindings/net/qca,qca7000.yaml

diff --git a/Documentation/devicetree/bindings/net/qca,qca7000.txt b/Documentation/devicetree/bindings/net/qca,qca7000.txt
deleted file mode 100644
index 8f5ae0b84eec2..0000000000000
--- a/Documentation/devicetree/bindings/net/qca,qca7000.txt
+++ /dev/null
@@ -1,87 +0,0 @@
-* Qualcomm QCA7000
-
-The QCA7000 is a serial-to-powerline bridge with a host interface which could
-be configured either as SPI or UART slave. This configuration is done by
-the QCA7000 firmware.
-
-(a) Ethernet over SPI
-
-In order to use the QCA7000 as SPI device it must be defined as a child of a
-SPI master in the device tree.
-
-Required properties:
-- compatible	    : Should be "qca,qca7000"
-- reg		    : Should specify the SPI chip select
-- interrupts	    : The first cell should specify the index of the source
-		      interrupt and the second cell should specify the trigger
-		      type as rising edge
-- spi-cpha	    : Must be set
-- spi-cpol	    : Must be set
-
-Optional properties:
-- spi-max-frequency : Maximum frequency of the SPI bus the chip can operate at.
-		      Numbers smaller than 1000000 or greater than 16000000
-		      are invalid. Missing the property will set the SPI
-		      frequency to 8000000 Hertz.
-- qca,legacy-mode   : Set the SPI data transfer of the QCA7000 to legacy mode.
-		      In this mode the SPI master must toggle the chip select
-		      between each data word. In burst mode these gaps aren't
-		      necessary, which is faster. This setting depends on how
-		      the QCA7000 is setup via GPIO pin strapping. If the
-		      property is missing the driver defaults to burst mode.
-
-The MAC address will be determined using the optional properties
-defined in ethernet.txt.
-
-SPI Example:
-
-/* Freescale i.MX28 SPI master*/
-ssp2: spi@80014000 {
-	#address-cells = <1>;
-	#size-cells = <0>;
-	compatible = "fsl,imx28-spi";
-	pinctrl-names = "default";
-	pinctrl-0 = <&spi2_pins_a>;
-
-	qca7000: ethernet@0 {
-		compatible = "qca,qca7000";
-		reg = <0x0>;
-		interrupt-parent = <&gpio3>;      /* GPIO Bank 3 */
-		interrupts = <25 0x1>;            /* Index: 25, rising edge */
-		spi-cpha;                         /* SPI mode: CPHA=1 */
-		spi-cpol;                         /* SPI mode: CPOL=1 */
-		spi-max-frequency = <8000000>;    /* freq: 8 MHz */
-		local-mac-address = [ A0 B0 C0 D0 E0 F0 ];
-	};
-};
-
-(b) Ethernet over UART
-
-In order to use the QCA7000 as UART slave it must be defined as a child of a
-UART master in the device tree. It is possible to preconfigure the UART
-settings of the QCA7000 firmware, but it's not possible to change them during
-runtime.
-
-Required properties:
-- compatible        : Should be "qca,qca7000"
-
-Optional properties:
-- local-mac-address : see ./ethernet.txt
-- current-speed     : current baud rate of QCA7000 which defaults to 115200
-		      if absent, see also ../serial/serial.yaml
-
-UART Example:
-
-/* Freescale i.MX28 UART */
-auart0: serial@8006a000 {
-	compatible = "fsl,imx28-auart", "fsl,imx23-auart";
-	reg = <0x8006a000 0x2000>;
-	pinctrl-names = "default";
-	pinctrl-0 = <&auart0_2pins_a>;
-
-	qca7000: ethernet {
-		compatible = "qca,qca7000";
-		local-mac-address = [ A0 B0 C0 D0 E0 F0 ];
-		current-speed = <38400>;
-	};
-};
diff --git a/Documentation/devicetree/bindings/net/qca,qca7000.yaml b/Documentation/devicetree/bindings/net/qca,qca7000.yaml
new file mode 100644
index 0000000000000..1851055a86af6
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/qca,qca7000.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/qca,qca7000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm QCA7000
+
+maintainers:
+  - Frank Li <Frank.Li@nxp.com>
+
+description: |
+  The QCA7000 is a serial-to-powerline bridge with a host interface which could
+  be configured either as SPI or UART slave. This configuration is done by
+  the QCA7000 firmware.
+
+  (a) Ethernet over SPI
+
+  In order to use the QCA7000 as SPI device it must be defined as a child of a
+  SPI master in the device tree.
+
+  (b) Ethernet over UART
+
+  In order to use the QCA7000 as UART slave it must be defined as a child of a
+  UART master in the device tree. It is possible to preconfigure the UART
+  settings of the QCA7000 firmware, but it's not possible to change them during
+  runtime
+
+properties:
+  compatible:
+    const: qca,qca7000
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+if:
+  required:
+    - reg
+
+then:
+  properties:
+    spi-cpha: true
+
+    spi-cpol: true
+
+    spi-max-frequency:
+      default: 8000000
+      maximum: 16000000
+      minimum: 1000000
+
+    qca,legacy-mode:
+      $ref: /schemas/types.yaml#/definitions/flag
+      description:
+        Set the SPI data transfer of the QCA7000 to legacy mode.
+        In this mode the SPI master must toggle the chip select
+        between each data word. In burst mode these gaps aren't
+        necessary, which is faster. This setting depends on how
+        the QCA7000 is setup via GPIO pin strapping. If the
+        property is missing the driver defaults to burst mode.
+
+  allOf:
+    - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+else:
+  properties:
+    current-speed:
+      default: 115200
+
+  allOf:
+    - $ref: /schemas/serial/serial-peripheral-props.yaml#
+
+allOf:
+  - $ref: ethernet-controller.yaml#
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    spi {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ethernet@0 {
+            compatible = "qca,qca7000";
+            reg = <0x0>;
+            interrupt-parent = <&gpio3>;      /* GPIO Bank 3 */
+            interrupts = <25 0x1>;            /* Index: 25, rising edge */
+            spi-cpha;                         /* SPI mode: CPHA=1 */
+            spi-cpol;                         /* SPI mode: CPOL=1 */
+            spi-max-frequency = <8000000>;    /* freq: 8 MHz */
+            local-mac-address = [ a0 b0 c0 d0 e0 f0 ];
+        };
+    };
+
+  - |
+    serial {
+        ethernet {
+            compatible = "qca,qca7000";
+            local-mac-address = [ a0 b0 c0 d0 e0 f0 ];
+            current-speed = <38400>;
+        };
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index c14da518a214c..6416ada9900af 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20295,7 +20295,7 @@ QUALCOMM ATHEROS QCA7K ETHERNET DRIVER
 M:	Stefan Wahren <wahrenst@gmx.net>
 L:	netdev@vger.kernel.org
 S:	Maintained
-F:	Documentation/devicetree/bindings/net/qca,qca7000.txt
+F:	Documentation/devicetree/bindings/net/qca,qca7000.yaml
 F:	drivers/net/ethernet/qualcomm/qca*
 
 QUALCOMM BAM-DMUX WWAN NETWORK DRIVER
-- 
2.34.1

Re: [PATCH v3 1/1] dt-bindings: net: convert qca,qca7000.txt yaml format

[Krzysztof Kozlowski]

On Fri, Jun 06, 2025 at 11:51:17AM GMT, Frank Li wrote:
> +description: |
> +  The QCA7000 is a serial-to-powerline bridge with a host interface which could
> +  be configured either as SPI or UART slave. This configuration is done by
> +  the QCA7000 firmware.
> +
> +  (a) Ethernet over SPI
> +
> +  In order to use the QCA7000 as SPI device it must be defined as a child of a
> +  SPI master in the device tree.
> +
> +  (b) Ethernet over UART
> +
> +  In order to use the QCA7000 as UART slave it must be defined as a child of a
> +  UART master in the device tree. It is possible to preconfigure the UART
> +  settings of the QCA7000 firmware, but it's not possible to change them during
> +  runtime
> +
> +properties:
> +  compatible:
> +    const: qca,qca7000
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +if:

Please put this if: inside allOf: section, so you won't need to
re-indent it when adding one more if-clause.

> +  required:
> +    - reg
> +
> +then:
> +  properties:
> +    spi-cpha: true
> +
> +    spi-cpol: true
> +
> +    spi-max-frequency:
> +      default: 8000000
> +      maximum: 16000000
> +      minimum: 1000000
> +
> +    qca,legacy-mode:

This should be defined in top-level properties and you only do:
"foo: false" in "else:" part.

> +      $ref: /schemas/types.yaml#/definitions/flag
> +      description:
> +        Set the SPI data transfer of the QCA7000 to legacy mode.
> +        In this mode the SPI master must toggle the chip select
> +        between each data word. In burst mode these gaps aren't
> +        necessary, which is faster. This setting depends on how
> +        the QCA7000 is setup via GPIO pin strapping. If the
> +        property is missing the driver defaults to burst mode.
> +
> +  allOf:
> +    - $ref: /schemas/spi/spi-peripheral-props.yaml#

This should be part of top-level allOf.

> +
> +else:
> +  properties:
> +    current-speed:
> +      default: 115200
> +
> +  allOf:
> +    - $ref: /schemas/serial/serial-peripheral-props.yaml#

Same here.

> +
> +allOf:
> +  - $ref: ethernet-controller.yaml#
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    spi {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ethernet@0 {
> +            compatible = "qca,qca7000";
> +            reg = <0x0>;
> +            interrupt-parent = <&gpio3>;      /* GPIO Bank 3 */
> +            interrupts = <25 0x1>;            /* Index: 25, rising edge */
> +            spi-cpha;                         /* SPI mode: CPHA=1 */
> +            spi-cpol;                         /* SPI mode: CPOL=1 */
> +            spi-max-frequency = <8000000>;    /* freq: 8 MHz */
> +            local-mac-address = [ a0 b0 c0 d0 e0 f0 ];
> +        };
> +    };
> +
> +  - |
> +    serial {
> +        ethernet {
> +            compatible = "qca,qca7000";
> +            local-mac-address = [ a0 b0 c0 d0 e0 f0 ];
> +            current-speed = <38400>;
> +        };

Best regards,
Krzysztof

Re: [PATCH v3 1/1] dt-bindings: net: convert qca,qca7000.txt yaml format

[Frank Li]

On Tue, Jun 10, 2025 at 09:24:40AM +0200, Krzysztof Kozlowski wrote:
> On Fri, Jun 06, 2025 at 11:51:17AM GMT, Frank Li wrote:
> > +description: |
> > +  The QCA7000 is a serial-to-powerline bridge with a host interface which could
> > +  be configured either as SPI or UART slave. This configuration is done by
> > +  the QCA7000 firmware.
> > +
> > +  (a) Ethernet over SPI
> > +
> > +  In order to use the QCA7000 as SPI device it must be defined as a child of a
> > +  SPI master in the device tree.
> > +
> > +  (b) Ethernet over UART
> > +
> > +  In order to use the QCA7000 as UART slave it must be defined as a child of a
> > +  UART master in the device tree. It is possible to preconfigure the UART
> > +  settings of the QCA7000 firmware, but it's not possible to change them during
> > +  runtime
> > +
> > +properties:
> > +  compatible:
> > +    const: qca,qca7000
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +if:
>
> Please put this if: inside allOf: section, so you won't need to
> re-indent it when adding one more if-clause.
>
> > +  required:
> > +    - reg
> > +
> > +then:
> > +  properties:
> > +    spi-cpha: true
> > +
> > +    spi-cpol: true
> > +
> > +    spi-max-frequency:
> > +      default: 8000000
> > +      maximum: 16000000
> > +      minimum: 1000000
> > +
> > +    qca,legacy-mode:
>
> This should be defined in top-level properties and you only do:
> "foo: false" in "else:" part.
>
> > +      $ref: /schemas/types.yaml#/definitions/flag
> > +      description:
> > +        Set the SPI data transfer of the QCA7000 to legacy mode.
> > +        In this mode the SPI master must toggle the chip select
> > +        between each data word. In burst mode these gaps aren't
> > +        necessary, which is faster. This setting depends on how
> > +        the QCA7000 is setup via GPIO pin strapping. If the
> > +        property is missing the driver defaults to burst mode.
> > +
> > +  allOf:
> > +    - $ref: /schemas/spi/spi-peripheral-props.yaml#
>
> This should be part of top-level allOf.
>
> > +
> > +else:
> > +  properties:
> > +    current-speed:
> > +      default: 115200
> > +
> > +  allOf:
> > +    - $ref: /schemas/serial/serial-peripheral-props.yaml#
>
> Same here.

If it is one top, how to disable all properties in serial-peripheral-props.yaml
if it connect to spi (reg exist).

Frank

>
> > +
> > +allOf:
> > +  - $ref: ethernet-controller.yaml#
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    spi {
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        ethernet@0 {
> > +            compatible = "qca,qca7000";
> > +            reg = <0x0>;
> > +            interrupt-parent = <&gpio3>;      /* GPIO Bank 3 */
> > +            interrupts = <25 0x1>;            /* Index: 25, rising edge */
> > +            spi-cpha;                         /* SPI mode: CPHA=1 */
> > +            spi-cpol;                         /* SPI mode: CPOL=1 */
> > +            spi-max-frequency = <8000000>;    /* freq: 8 MHz */
> > +            local-mac-address = [ a0 b0 c0 d0 e0 f0 ];
> > +        };
> > +    };
> > +
> > +  - |
> > +    serial {
> > +        ethernet {
> > +            compatible = "qca,qca7000";
> > +            local-mac-address = [ a0 b0 c0 d0 e0 f0 ];
> > +            current-speed = <38400>;
> > +        };
>
> Best regards,
> Krzysztof
>

Re: [PATCH v3 1/1] dt-bindings: net: convert qca,qca7000.txt yaml format

[Krzysztof Kozlowski]

On 10/06/2025 17:29, Frank Li wrote:
>>
>>> +      $ref: /schemas/types.yaml#/definitions/flag
>>> +      description:
>>> +        Set the SPI data transfer of the QCA7000 to legacy mode.
>>> +        In this mode the SPI master must toggle the chip select
>>> +        between each data word. In burst mode these gaps aren't
>>> +        necessary, which is faster. This setting depends on how
>>> +        the QCA7000 is setup via GPIO pin strapping. If the
>>> +        property is missing the driver defaults to burst mode.
>>> +
>>> +  allOf:
>>> +    - $ref: /schemas/spi/spi-peripheral-props.yaml#
>>
>> This should be part of top-level allOf.
>>
>>> +
>>> +else:
>>> +  properties:
>>> +    current-speed:
>>> +      default: 115200
>>> +
>>> +  allOf:
>>> +    - $ref: /schemas/serial/serial-peripheral-props.yaml#
>>
>> Same here.
> 
> If it is one top, how to disable all properties in serial-peripheral-props.yaml
> if it connect to spi (reg exist).
You do not have to disallow them. If this is somehow useful, it can stay
here, although the earlier properties still need to be defined in top level.

Best regards,
Krzysztof