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

[PATCH v4 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 v4
- move if into allOf
  move qca,legacy-mode to top and use qca,legacy-mode: false to disallow it
  for uart

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  | 107 ++++++++++++++++++
 MAINTAINERS                                   |   2 +-
 3 files changed, 108 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..f786f0ab38bcf
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/qca,qca7000.yaml
@@ -0,0 +1,107 @@
+# 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
+
+  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: ethernet-controller.yaml#
+
+  - if:
+      required:
+        - reg
+
+    then:
+      properties:
+        spi-cpha: true
+
+        spi-cpol: true
+
+        spi-max-frequency:
+          default: 8000000
+          maximum: 16000000
+          minimum: 1000000
+
+      allOf:
+        - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+    else:
+      properties:
+        current-speed:
+          default: 115200
+
+        qca,legacy-mode: false
+
+      allOf:
+        - $ref: /schemas/serial/serial-peripheral-props.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 2c74753e2df41..ffc80ec9b3d6d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20383,7 +20383,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 v4 1/1] dt-bindings: net: convert qca,qca7000.txt yaml format

[Jacob Keller]

On 6/16/2025 11:48 AM, Frank Li wrote:
> 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>
> ---

I probably would have separated the additions out to their own commits,
but this is short enough it was relatively easy to read and review.

Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>

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

[Krzysztof Kozlowski]

On 16/06/2025 20:48, Frank Li wrote:
> 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>

Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Best regards,
Krzysztof

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

[Fabio Estevam]

On Mon, Jun 16, 2025 at 3:48 PM Frank Li <Frank.Li@nxp.com> wrote:

> +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 */

All of these comments are obvious and don't bring any new information.

I recommend dropping all of them.

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

[Andrew Lunn]

On Tue, Jun 17, 2025 at 01:09:21PM -0300, Fabio Estevam wrote:
> On Mon, Jun 16, 2025 at 3:48 PM Frank Li <Frank.Li@nxp.com> wrote:
> 
> > +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 */
> 
> All of these comments are obvious and don't bring any new information.
> 
> I recommend dropping all of them.

I would also suggest replacing 0x1 with IRQ_TYPE_EDGE_RISING.

  Andrew