[PATCH 0/2] dt-bindings: serial: Convert generic and slave bindings to json-schema

[PATCH 0/2] dt-bindings: serial: Convert generic and slave bindings to json-schema

[Geert Uytterhoeven]

	Hi Rob, Greg,

This patch series converts the generic serial interface and slave-device
Device Tree bindings to json-schema.

This is a dependency for converting more serial DT bindings that will
refer to properties defined in serial.yaml.

Thanks for your comments!

Geert Uytterhoeven (2):
  dt-bindings: serial: Convert generic bindings to json-schema
  dt-bindings: serial: Convert slave-device bindings to json-schema

 .../devicetree/bindings/serial/serial.txt     |  56 -------
 .../devicetree/bindings/serial/serial.yaml    | 148 ++++++++++++++++++
 .../bindings/serial/slave-device.txt          |  45 ------
 MAINTAINERS                                   |   2 +-
 4 files changed, 149 insertions(+), 102 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/serial/serial.txt
 create mode 100644 Documentation/devicetree/bindings/serial/serial.yaml
 delete mode 100644 Documentation/devicetree/bindings/serial/slave-device.txt

-- 
2.17.1

Gr{oetje,eeting}s,

						Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
							    -- Linus Torvalds

[PATCH 1/2] dt-bindings: serial: Convert generic bindings to json-schema

[Geert Uytterhoeven]

Convert the generic serial interface Device Tree binding documentation
to json-schema.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 .../devicetree/bindings/serial/serial.txt     | 56 -----------
 .../devicetree/bindings/serial/serial.yaml    | 95 +++++++++++++++++++
 2 files changed, 95 insertions(+), 56 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/serial/serial.txt
 create mode 100644 Documentation/devicetree/bindings/serial/serial.yaml

diff --git a/Documentation/devicetree/bindings/serial/serial.txt b/Documentation/devicetree/bindings/serial/serial.txt
deleted file mode 100644
index 863c2893759e7151..0000000000000000
--- a/Documentation/devicetree/bindings/serial/serial.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-Generic Serial DT Bindings
-
-This document lists a set of generic properties for describing UARTs in a
-device tree.  Whether these properties apply to a particular device depends on
-the DT bindings for the actual device.
-
-Optional properties:
-  - cts-gpios: Must contain a GPIO specifier, referring to the GPIO pin to be
-    used as the UART's CTS line.
-  - dcd-gpios: Must contain a GPIO specifier, referring to the GPIO pin to be
-    used as the UART's DCD line.
-  - dsr-gpios: Must contain a GPIO specifier, referring to the GPIO pin to be
-    used as the UART's DSR line.
-  - dtr-gpios: Must contain a GPIO specifier, referring to the GPIO pin to be
-    used as the UART's DTR line.
-  - rng-gpios: Must contain a GPIO specifier, referring to the GPIO pin to be
-    used as the UART's RNG line.
-  - rts-gpios: Must contain a GPIO specifier, referring to the GPIO pin to be
-    used as the UART's RTS line.
-
-  - uart-has-rtscts: The presence of this property indicates that the
-    UART has dedicated lines for RTS/CTS hardware flow control, and that
-    they are available for use (wired and enabled by pinmux configuration).
-    This depends on both the UART hardware and the board wiring.
-    Note that this property is mutually-exclusive with "cts-gpios" and
-    "rts-gpios" above, unless support is provided to switch between modes
-    dynamically.
-
-
-Examples:
-
-	uart1: serial@48022000 {
-		compatible = "ti,am3352-uart", "ti,omap3-uart";
-		ti,hwmods = "uart2";
-		clock-frequency = <48000000>;
-		reg = <0x48022000 0x2000>;
-		interrupts = <73>;
-		dmas = <&edma 28 0>, <&edma 29 0>;
-		dma-names = "tx", "rx";
-		dtr-gpios = <&gpio2 22 GPIO_ACTIVE_LOW>;
-		dsr-gpios = <&gpio2 23 GPIO_ACTIVE_LOW>;
-		dcd-gpios = <&gpio2 24 GPIO_ACTIVE_LOW>;
-		rng-gpios = <&gpio2 25 GPIO_ACTIVE_LOW>;
-		cts-gpios = <&gpio0 12 GPIO_ACTIVE_LOW>;
-		rts-gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
-	};
-
-	scifa4: serial@e6c80000 {
-		compatible = "renesas,scifa-sh73a0", "renesas,scifa";
-		reg = <0xe6c80000 0x100>;
-		interrupts = <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>;
-		clocks = <&mstp2_clks SH73A0_CLK_SCIFA4>;
-		clock-names = "fck";
-		power-domains = <&pd_a3sp>;
-		uart-has-rtscts;
-	};
diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml
new file mode 100644
index 0000000000000000..d408335319f00215
--- /dev/null
+++ b/Documentation/devicetree/bindings/serial/serial.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/serial/serial.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Serial Interface Generic DT Bindings
+
+maintainers:
+  - Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+
+description:
+  This document lists a set of generic properties for describing UARTs in a
+  device tree.  Whether these properties apply to a particular device depends
+  on the DT bindings for the actual device.
+
+properties:
+  $nodename:
+    pattern: "^serial@[0-9a-f]+$"
+
+  cts-gpios:
+    description:
+      Must contain a GPIO specifier, referring to the GPIO pin to be used as
+      the UART's CTS line.
+
+  dcd-gpios:
+    description:
+      Must contain a GPIO specifier, referring to the GPIO pin to be used as
+      the UART's DCD line.
+
+  dsr-gpios:
+    description:
+      Must contain a GPIO specifier, referring to the GPIO pin to be used as
+      the UART's DSR line.
+
+  dtr-gpios:
+    description:
+      Must contain a GPIO specifier, referring to the GPIO pin to be used as
+      the UART's DTR line.
+
+  rng-gpios:
+    description:
+      Must contain a GPIO specifier, referring to the GPIO pin to be used as
+      the UART's RNG line.
+
+  rts-gpios:
+    description:
+      Must contain a GPIO specifier, referring to the GPIO pin to be used as
+      the UART's RTS line.
+
+  uart-has-rtscts:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      The presence of this property indicates that the UART has dedicated lines
+      for RTS/CTS hardware flow control, and that they are available for use
+      (wired and enabled by pinmux configuration).  This depends on both the
+      UART hardware and the board wiring.
+      Note that this property is mutually-exclusive with "cts-gpios" and
+      "rts-gpios" above, unless support is provided to switch between modes
+      dynamically.
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+
+    serial@48022000 {
+            compatible = "ti,am3352-uart", "ti,omap3-uart";
+            ti,hwmods = "uart2";
+            clock-frequency = <48000000>;
+            reg = <0x48022000 0x2000>;
+            interrupts = <73>;
+            dmas = <&edma 28 0>, <&edma 29 0>;
+            dma-names = "tx", "rx";
+            dtr-gpios = <&gpio2 22 GPIO_ACTIVE_LOW>;
+            dsr-gpios = <&gpio2 23 GPIO_ACTIVE_LOW>;
+            dcd-gpios = <&gpio2 24 GPIO_ACTIVE_LOW>;
+            rng-gpios = <&gpio2 25 GPIO_ACTIVE_LOW>;
+            cts-gpios = <&gpio0 12 GPIO_ACTIVE_LOW>;
+            rts-gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
+    };
+
+  - |
+    #include <dt-bindings/clock/sh73a0-clock.h>
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    serial@e6c80000 {
+            compatible = "renesas,scifa-sh73a0", "renesas,scifa";
+            reg = <0xe6c80000 0x100>;
+            interrupts = <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>;
+            clocks = <&mstp2_clks SH73A0_CLK_SCIFA4>;
+            clock-names = "fck";
+            power-domains = <&pd_a3sp>;
+            uart-has-rtscts;
+    };
-- 
2.17.1

Re: [PATCH 1/2] dt-bindings: serial: Convert generic bindings to json-schema

[Geert Uytterhoeven]

On Tue, Mar 3, 2020 at 2:44 PM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
> Convert the generic serial interface Device Tree binding documentation
> to json-schema.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  .../devicetree/bindings/serial/serial.txt     | 56 -----------
>  .../devicetree/bindings/serial/serial.yaml    | 95 +++++++++++++++++++
>  2 files changed, 95 insertions(+), 56 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/serial/serial.txt
>  create mode 100644 Documentation/devicetree/bindings/serial/serial.yaml

There are a few references to serial.txt that need to be updated.

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH 1/2] dt-bindings: serial: Convert generic bindings to json-schema

[Rob Herring]

On Tue, Mar 3, 2020 at 7:43 AM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Convert the generic serial interface Device Tree binding documentation
> to json-schema.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  .../devicetree/bindings/serial/serial.txt     | 56 -----------
>  .../devicetree/bindings/serial/serial.yaml    | 95 +++++++++++++++++++
>  2 files changed, 95 insertions(+), 56 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/serial/serial.txt
>  create mode 100644 Documentation/devicetree/bindings/serial/serial.yaml

> diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml
> new file mode 100644
> index 0000000000000000..d408335319f00215
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/serial/serial.yaml
> @@ -0,0 +1,95 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/serial/serial.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: Serial Interface Generic DT Bindings
> +
> +maintainers:
> +  - Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> +
> +description:
> +  This document lists a set of generic properties for describing UARTs in a
> +  device tree.  Whether these properties apply to a particular device depends
> +  on the DT bindings for the actual device.
> +
> +properties:
> +  $nodename:
> +    pattern: "^serial@[0-9a-f]+$"

',' is also possible in unit-address. Probably shouldn't be defining
unit-address format at all here, so:

"^serial(@.*)?$"

> +
> +  cts-gpios:
> +    description:
> +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> +      the UART's CTS line.

These all need a 'maxItems: 1'.

> +
> +  dcd-gpios:
> +    description:
> +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> +      the UART's DCD line.
> +
> +  dsr-gpios:
> +    description:
> +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> +      the UART's DSR line.
> +
> +  dtr-gpios:
> +    description:
> +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> +      the UART's DTR line.
> +
> +  rng-gpios:
> +    description:
> +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> +      the UART's RNG line.
> +
> +  rts-gpios:
> +    description:
> +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> +      the UART's RTS line.
> +
> +  uart-has-rtscts:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description:
> +      The presence of this property indicates that the UART has dedicated lines
> +      for RTS/CTS hardware flow control, and that they are available for use
> +      (wired and enabled by pinmux configuration).  This depends on both the
> +      UART hardware and the board wiring.
> +      Note that this property is mutually-exclusive with "cts-gpios" and
> +      "rts-gpios" above, unless support is provided to switch between modes
> +      dynamically.

This can be expressed as:

oneOf:
  - {} # None of the properties present
  - required:
      - uart-has-rtscts
  - anyOf:
      - required:
          - cts-gpios
      - required:
          - rts-gpios

Or probably more clearly:

if:
  required:
    - uart-has-rtscts
then:
  properties:
    rts-gpios: false
    cts-gpios: false

(Untested)

> +
> +examples:

Personally, I'd just drop examples from schemas that aren't complete.

> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    serial@48022000 {
> +            compatible = "ti,am3352-uart", "ti,omap3-uart";
> +            ti,hwmods = "uart2";
> +            clock-frequency = <48000000>;
> +            reg = <0x48022000 0x2000>;
> +            interrupts = <73>;
> +            dmas = <&edma 28 0>, <&edma 29 0>;
> +            dma-names = "tx", "rx";
> +            dtr-gpios = <&gpio2 22 GPIO_ACTIVE_LOW>;
> +            dsr-gpios = <&gpio2 23 GPIO_ACTIVE_LOW>;
> +            dcd-gpios = <&gpio2 24 GPIO_ACTIVE_LOW>;
> +            rng-gpios = <&gpio2 25 GPIO_ACTIVE_LOW>;
> +            cts-gpios = <&gpio0 12 GPIO_ACTIVE_LOW>;
> +            rts-gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
> +    };
> +
> +  - |
> +    #include <dt-bindings/clock/sh73a0-clock.h>
> +    #include <dt-bindings/gpio/gpio.h>
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    serial@e6c80000 {
> +            compatible = "renesas,scifa-sh73a0", "renesas,scifa";
> +            reg = <0xe6c80000 0x100>;
> +            interrupts = <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>;
> +            clocks = <&mstp2_clks SH73A0_CLK_SCIFA4>;
> +            clock-names = "fck";
> +            power-domains = <&pd_a3sp>;
> +            uart-has-rtscts;
> +    };
> --
> 2.17.1
>

Re: [PATCH 1/2] dt-bindings: serial: Convert generic bindings to json-schema

[Geert Uytterhoeven]

Hi Rob,

On Wed, Mar 4, 2020 at 3:03 PM Rob Herring <robh+dt@kernel.org> wrote:
> On Tue, Mar 3, 2020 at 7:43 AM Geert Uytterhoeven
> <geert+renesas@glider.be> wrote:
> > Convert the generic serial interface Device Tree binding documentation
> > to json-schema.
> >
> > Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>

> > +  cts-gpios:
> > +    description:
> > +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> > +      the UART's CTS line.

> > +  rts-gpios:
> > +    description:
> > +      Must contain a GPIO specifier, referring to the GPIO pin to be used as
> > +      the UART's RTS line.
> > +
> > +  uart-has-rtscts:
> > +    $ref: /schemas/types.yaml#/definitions/flag
> > +    description:
> > +      The presence of this property indicates that the UART has dedicated lines
> > +      for RTS/CTS hardware flow control, and that they are available for use
> > +      (wired and enabled by pinmux configuration).  This depends on both the
> > +      UART hardware and the board wiring.
> > +      Note that this property is mutually-exclusive with "cts-gpios" and
> > +      "rts-gpios" above, unless support is provided to switch between modes
> > +      dynamically.
>
> This can be expressed as:
>
> oneOf:
>   - {} # None of the properties present
>   - required:
>       - uart-has-rtscts
>   - anyOf:
>       - required:
>           - cts-gpios
>       - required:
>           - rts-gpios
>
> Or probably more clearly:
>
> if:
>   required:
>     - uart-has-rtscts
> then:
>   properties:
>     rts-gpios: false
>     cts-gpios: false
>
> (Untested)

Thanks. Note that when adding this, the note above must be removed.

>
> > +
> > +examples:
>
> Personally, I'd just drop examples from schemas that aren't complete.

OK.


Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

[PATCH 2/2] dt-bindings: serial: Convert slave-device bindings to json-schema

[Geert Uytterhoeven]

Convert the serial slave-device Device Tree binding documentation to
json-schema, and incorporate it into the generic serial bindings.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 .../devicetree/bindings/serial/serial.yaml    | 53 +++++++++++++++++++
 .../bindings/serial/slave-device.txt          | 45 ----------------
 MAINTAINERS                                   |  2 +-
 3 files changed, 54 insertions(+), 46 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/serial/slave-device.txt

diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml
index d408335319f00215..7381966449b62deb 100644
--- a/Documentation/devicetree/bindings/serial/serial.yaml
+++ b/Documentation/devicetree/bindings/serial/serial.yaml
@@ -7,6 +7,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#"
 title: Serial Interface Generic DT Bindings
 
 maintainers:
+  - Rob Herring <robh@kernel.org>
   - Greg Kroah-Hartman <gregkh@linuxfoundation.org>
 
 description:
@@ -59,6 +60,45 @@ properties:
       "rts-gpios" above, unless support is provided to switch between modes
       dynamically.
 
+patternProperties:
+  "^(bluetooth|ethernet|gnss|nfc|wifi)$":
+    type: object
+
+    description:
+      Serial attached devices shall be a child node of the host UART device the
+      slave device is attached to. It is expected that the attached device is
+      the only child node of the UART device. The slave device node name shall
+      reflect the generic type of device for the node.
+
+    properties:
+      compatible:
+        description:
+          Compatible of the device connnected to the serial port.
+
+      max-speed:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          The maximum baud rate the device operates at. This should only be
+          present if the maximum is less than the slave device can support. For
+          example, a particular board has some signal quality issue or the host
+          processor can't support higher baud rates.
+
+      current-speed:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: |
+          The current baud rate the device operates at. This should only be
+          present in case a driver has no chance to know the baud rate of the
+          slave device.
+          Examples:
+            * device supports auto-baud
+            * the rate is setup by a bootloader and there is no way to reset
+              the device
+            * device baud rate is configured by its firmware but there is no
+              way to request the actual settings
+
+    required:
+      - compatible
+
 examples:
   - |
     #include <dt-bindings/gpio/gpio.h>
@@ -93,3 +133,16 @@ examples:
             power-domains = <&pd_a3sp>;
             uart-has-rtscts;
     };
+
+  - |
+    serial@1234 {
+            compatible = "ns16550a";
+            reg = <0x1234 0x20>;
+            interrupts = <1>;
+
+            bluetooth {
+                    compatible = "brcm,bcm43341-bt";
+                    interrupt-parent = <&gpio>;
+                    interrupts = <10>;
+            };
+    };
diff --git a/Documentation/devicetree/bindings/serial/slave-device.txt b/Documentation/devicetree/bindings/serial/slave-device.txt
deleted file mode 100644
index 40110e0196209fde..0000000000000000
--- a/Documentation/devicetree/bindings/serial/slave-device.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-Serial Slave Device DT binding
-
-This documents the binding structure and common properties for serial
-attached devices. Common examples include Bluetooth, WiFi, NFC and GPS
-devices.
-
-Serial attached devices shall be a child node of the host UART device the
-slave device is attached to. It is expected that the attached device is
-the only child node of the UART device. The slave device node name shall
-reflect the generic type of device for the node.
-
-Required Properties:
-
-- compatible 	: A string reflecting the vendor and specific device the node
-		  represents.
-
-Optional Properties:
-
-- max-speed	: The maximum baud rate the device operates at. This should
-		  only be present if the maximum is less than the slave device
-		  can support. For example, a particular board has some signal
-		  quality issue or the host processor can't support higher
-		  baud rates.
-- current-speed	: The current baud rate the device operates at. This should
-		  only be present in case a driver has no chance to know
-		  the baud rate of the slave device.
-		  Examples:
-		    * device supports auto-baud
-		    * the rate is setup by a bootloader and there is no
-		      way to reset the device
-		    * device baud rate is configured by its firmware but
-		      there is no way to request the actual settings
-
-Example:
-
-serial@1234 {
-	compatible = "ns16550a";
-	interrupts = <1>;
-
-	bluetooth {
-		compatible = "brcm,bcm43341-bt";
-		interrupt-parent = <&gpio>;
-		interrupts = <10>;
-	};
-};
diff --git a/MAINTAINERS b/MAINTAINERS
index 59c14ee9a917a794..5f5d074c7b3927a5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15034,7 +15034,7 @@ SERIAL DEVICE BUS
 M:	Rob Herring <robh@kernel.org>
 L:	linux-serial@vger.kernel.org
 S:	Maintained
-F:	Documentation/devicetree/bindings/serial/slave-device.txt
+F:	Documentation/devicetree/bindings/serial/serial.yaml
 F:	drivers/tty/serdev/
 F:	include/linux/serdev.h
 
-- 
2.17.1

Re: [PATCH 2/2] dt-bindings: serial: Convert slave-device bindings to json-schema

[Geert Uytterhoeven]

On Tue, Mar 3, 2020 at 2:43 PM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
> Convert the serial slave-device Device Tree binding documentation to
> json-schema, and incorporate it into the generic serial bindings.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  .../devicetree/bindings/serial/serial.yaml    | 53 +++++++++++++++++++
>  .../bindings/serial/slave-device.txt          | 45 ----------------
>  MAINTAINERS                                   |  2 +-
>  3 files changed, 54 insertions(+), 46 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/serial/slave-device.txt

There are a few references to slave-device.txt that need to be updated.

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH 2/2] dt-bindings: serial: Convert slave-device bindings to json-schema

[Rob Herring]

On Tue, Mar 3, 2020 at 7:43 AM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Convert the serial slave-device Device Tree binding documentation to
> json-schema, and incorporate it into the generic serial bindings.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  .../devicetree/bindings/serial/serial.yaml    | 53 +++++++++++++++++++
>  .../bindings/serial/slave-device.txt          | 45 ----------------
>  MAINTAINERS                                   |  2 +-
>  3 files changed, 54 insertions(+), 46 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/serial/slave-device.txt
>
> diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml
> index d408335319f00215..7381966449b62deb 100644
> --- a/Documentation/devicetree/bindings/serial/serial.yaml
> +++ b/Documentation/devicetree/bindings/serial/serial.yaml
> @@ -7,6 +7,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#"
>  title: Serial Interface Generic DT Bindings
>
>  maintainers:
> +  - Rob Herring <robh@kernel.org>
>    - Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>
>  description:
> @@ -59,6 +60,45 @@ properties:
>        "rts-gpios" above, unless support is provided to switch between modes
>        dynamically.
>
> +patternProperties:
> +  "^(bluetooth|ethernet|gnss|nfc|wifi)$":

A bit fragile, but okay. There's also some serial attached board
control micro-controllers. See the Zodiac i.MX board "rave-sp" node.

The only other way I've come up to handle this is:

".*":
  if:
    type: object
  then:
    ...

> +    type: object
> +
> +    description:
> +      Serial attached devices shall be a child node of the host UART device the
> +      slave device is attached to. It is expected that the attached device is
> +      the only child node of the UART device. The slave device node name shall
> +      reflect the generic type of device for the node.
> +
> +    properties:
> +      compatible:
> +        description:
> +          Compatible of the device connnected to the serial port.

typo

> +
> +      max-speed:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          The maximum baud rate the device operates at. This should only be
> +          present if the maximum is less than the slave device can support. For
> +          example, a particular board has some signal quality issue or the host
> +          processor can't support higher baud rates.
> +
> +      current-speed:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: |
> +          The current baud rate the device operates at. This should only be
> +          present in case a driver has no chance to know the baud rate of the
> +          slave device.
> +          Examples:
> +            * device supports auto-baud
> +            * the rate is setup by a bootloader and there is no way to reset
> +              the device
> +            * device baud rate is configured by its firmware but there is no
> +              way to request the actual settings
> +
> +    required:
> +      - compatible
> +
>  examples:
>    - |
>      #include <dt-bindings/gpio/gpio.h>
> @@ -93,3 +133,16 @@ examples:
>              power-domains = <&pd_a3sp>;
>              uart-has-rtscts;
>      };
> +
> +  - |
> +    serial@1234 {
> +            compatible = "ns16550a";
> +            reg = <0x1234 0x20>;
> +            interrupts = <1>;
> +
> +            bluetooth {
> +                    compatible = "brcm,bcm43341-bt";
> +                    interrupt-parent = <&gpio>;
> +                    interrupts = <10>;
> +            };
> +    };
> diff --git a/Documentation/devicetree/bindings/serial/slave-device.txt b/Documentation/devicetree/bindings/serial/slave-device.txt
> deleted file mode 100644
> index 40110e0196209fde..0000000000000000
> --- a/Documentation/devicetree/bindings/serial/slave-device.txt
> +++ /dev/null
> @@ -1,45 +0,0 @@
> -Serial Slave Device DT binding
> -
> -This documents the binding structure and common properties for serial
> -attached devices. Common examples include Bluetooth, WiFi, NFC and GPS
> -devices.
> -
> -Serial attached devices shall be a child node of the host UART device the
> -slave device is attached to. It is expected that the attached device is
> -the only child node of the UART device. The slave device node name shall
> -reflect the generic type of device for the node.
> -
> -Required Properties:
> -
> -- compatible   : A string reflecting the vendor and specific device the node
> -                 represents.
> -
> -Optional Properties:
> -
> -- max-speed    : The maximum baud rate the device operates at. This should
> -                 only be present if the maximum is less than the slave device
> -                 can support. For example, a particular board has some signal
> -                 quality issue or the host processor can't support higher
> -                 baud rates.
> -- current-speed        : The current baud rate the device operates at. This should
> -                 only be present in case a driver has no chance to know
> -                 the baud rate of the slave device.
> -                 Examples:
> -                   * device supports auto-baud
> -                   * the rate is setup by a bootloader and there is no
> -                     way to reset the device
> -                   * device baud rate is configured by its firmware but
> -                     there is no way to request the actual settings
> -
> -Example:
> -
> -serial@1234 {
> -       compatible = "ns16550a";
> -       interrupts = <1>;
> -
> -       bluetooth {
> -               compatible = "brcm,bcm43341-bt";
> -               interrupt-parent = <&gpio>;
> -               interrupts = <10>;
> -       };
> -};
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 59c14ee9a917a794..5f5d074c7b3927a5 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -15034,7 +15034,7 @@ SERIAL DEVICE BUS
>  M:     Rob Herring <robh@kernel.org>
>  L:     linux-serial@vger.kernel.org
>  S:     Maintained
> -F:     Documentation/devicetree/bindings/serial/slave-device.txt
> +F:     Documentation/devicetree/bindings/serial/serial.yaml
>  F:     drivers/tty/serdev/
>  F:     include/linux/serdev.h
>
> --
> 2.17.1
>