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

[Rob Herring <robh+dt@xxxxxxxxxx>]

On Tue, Mar 3, 2020 at 7:43 AM Geert Uytterhoeven
<geert+renesas@xxxxxxxxx> wrote:
>
> Convert the generic serial interface Device Tree binding documentation
> to json-schema.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@xxxxxxxxx>
> ---
>  .../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@xxxxxxxxxxxxxxxxxxx>
> +
> +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
>