Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Sun, 21 May 2023 17:13:38 +0800
From:   Jisheng Zhang <jszhang@kernel.org>
To:     Samuel Holland <samuel@sholland.org>
Cc:     linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org,
        devicetree@vger.kernel.org, linux-serial@vger.kernel.org,
        Palmer Dabbelt <palmer@rivosinc.com>,
        Thomas Gleixner <tglx@linutronix.de>,
        Marc Zyngier <maz@kernel.org>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Conor Dooley <conor+dt@kernel.org>,
        Palmer Dabbelt <palmer@dabbelt.com>,
        Paul Walmsley <paul.walmsley@sifive.com>,
        Albert Ou <aou@eecs.berkeley.edu>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Jiri Slaby <jirislaby@kernel.org>
Subject: Re: [PATCH v4 03/10] dt-bindings: serial: add documentation for
 Bouffalolab UART Driver
Message-ID: <ZGngwijxAKRpzmh7@xhacker>
References: <20230518152244.2178-1-jszhang@kernel.org>
 <20230518152244.2178-4-jszhang@kernel.org>
 <b5869cb0-1eab-4ab7-6dd7-16b06f91d93f@sholland.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
In-Reply-To: <b5869cb0-1eab-4ab7-6dd7-16b06f91d93f@sholland.org>
Precedence: bulk

On Thu, May 18, 2023 at 10:00:50PM -0500, Samuel Holland wrote:
> Hi Jisheng,

Hi Samuel,

> 
> On 5/18/23 10:22, Jisheng Zhang wrote:
> > Add bindings doc for Bouffalolab UART Driver
> > 
> > Signed-off-by: Jisheng Zhang <jszhang@kernel.org>
> > Acked-by: Palmer Dabbelt <palmer@rivosinc.com>
> > ---
> >  .../serial/bouffalolab,bl808-uart.yaml        | 47 +++++++++++++++++++
> >  1 file changed, 47 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/serial/bouffalolab,bl808-uart.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/serial/bouffalolab,bl808-uart.yaml b/Documentation/devicetree/bindings/serial/bouffalolab,bl808-uart.yaml
> > new file mode 100644
> > index 000000000000..0ef858e50efb
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/serial/bouffalolab,bl808-uart.yaml
> > @@ -0,0 +1,47 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +# Copyright (C) 2022 Jisheng Zhang <jszhang@kernel.org>
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/serial/bouffalolab,bl808-uart.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Bouffalolab UART Controller
> > +
> > +maintainers:
> > +  - Jisheng Zhang <jszhang@kernel.org>
> > +
> > +allOf:
> > +  - $ref: serial.yaml#
> > +
> > +properties:
> > +  compatible:
> > +    const: bouffalolab,bl808-uart
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  clocks:
> > +    maxItems: 1
> 
> This is not complete. There are separate APB and module (baud) clocks,
> as well as a peripheral reset line. If we are going to keep the binding
> stable, these need to be described up front.

IIUC, the only requirement is to keep the driver compatible with both
new dts and old dts. clk tree and reset can be added latter. I have seen
sevral such examples from other SoCs' mainline progress.

> 
> (I still don't fully understand the clock tree, and so far that has been
> the main blocker for me sending a follow-up series with additional
> bindings for hardware that's otherwise already supported, like the
> Ethernet MAC.)
> 
> Regards,
> Samuel
> 
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts
> > +  - clocks
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/irq.h>
> > +
> > +    uart0: serial@30002000 {
> > +        compatible = "bouffalolab,bl808-uart";
> > +        reg = <0x30002000 0x1000>;
> > +        interrupts = <53 IRQ_TYPE_LEVEL_HIGH>;
> > +        clocks = <&xtal>;
> > +    };
> > +...
>