linux-kernel - Re: [PATCH v2 1/2] dt-bindings: serial: add documentation for the SiFive UART driver

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAL_JsqJBSqaxnETdJg1Mdp+H2ay+WKT0JaxLe6D4Fwo_99qUkw@mail.gmail.com>
Date:   Fri, 19 Oct 2018 15:45:57 -0500
From:   Rob Herring <robh+dt@...nel.org>
To:     Paul Walmsley <paul.walmsley@...ive.com>
Cc:     "open list:SERIAL DRIVERS" <linux-serial@...r.kernel.org>,
        devicetree@...r.kernel.org, linux-riscv@...ts.infradead.org,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Mark Rutland <mark.rutland@....com>,
        Palmer Dabbelt <palmer@...ive.com>,
        Paul Walmsley <paul@...an.com>
Subject: Re: [PATCH v2 1/2] dt-bindings: serial: add documentation for the
 SiFive UART driver

On Fri, Oct 19, 2018 at 1:48 PM Paul Walmsley <paul.walmsley@...ive.com> wrote:
>
> Add DT binding documentation for the Linux driver for the SiFive
> asynchronous serial IP block.  Nothing too exotic.
>
> Cc: linux-serial@...r.kernel.org
> Cc: devicetree@...r.kernel.org
> Cc: linux-riscv@...ts.infradead.org
> Cc: linux-kernel@...r.kernel.org
> Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
> Cc: Rob Herring <robh+dt@...nel.org>
> Cc: Mark Rutland <mark.rutland@....com>
> Cc: Palmer Dabbelt <palmer@...ive.com>
> Reviewed-by: Palmer Dabbelt <palmer@...ive.com>
> Signed-off-by: Paul Walmsley <paul.walmsley@...ive.com>
> Signed-off-by: Paul Walmsley <paul@...an.com>
> ---
>  .../bindings/serial/sifive-serial.txt         | 21 +++++++++++++++++++
>  1 file changed, 21 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/serial/sifive-serial.txt
>
> diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.txt b/Documentation/devicetree/bindings/serial/sifive-serial.txt
> new file mode 100644
> index 000000000000..8982338512f5
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/serial/sifive-serial.txt
> @@ -0,0 +1,21 @@
> +SiFive asynchronous serial interface (UART)
> +
> +Required properties:
> +
> +- compatible: should be "sifive,fu540-c000-uart0" or "sifive,uart0"

I assume once again, the last '0' is a version? As I mentioned for the
intc and now the pwm block bindings, if you are going to do version
numbers please document the versioning scheme. Palmer mentioned the
compatible string is part of the IP block repository? Where does the
number come from? What's the next version? Major vs. minor versions?
ECO fixes? Is the version s/w readable? How do you ensure it gets
updated? All that should be addressed.

Otherwise, don't do version numbers because we have no visibility to
what they mean.

> +- reg: address and length of the register space
> +- interrupt-parent: should contain a phandle pointing to the SoC interrupt
> +    controller device node that the UART interrupts are connected to

Don't need to document interrupt-parent here.

> +- interrupts: Should contain the UART interrupt identifier
> +- clocks: Should contain a clock identifier for the UART's parent clock
> +
> +
> +Example:
> +
> +uart0: serial@...10000 {
> +       compatible = "sifive,uart0";
> +       interrupt-parent = <&plic0>;
> +       interrupts = <80>;
> +       reg = <0x0 0x10010000 0x0 0x1000>;
> +       clocks = <&prci PRCI_CLK_TLCLK>;
> +};
> --
> 2.19.1
>