[2/3] dt-bindings: rtc: Add Mstar SSD20xD RTC devicetree bindings documentation

This adds the documentation for the devicetree bindings of the Mstar
SSD20xD RTC driver.

Signed-off-by: Romain Perier <romain.perier@gmail.com>
---
 .../bindings/rtc/mstar,ssd20xd-rtc.yaml       | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml

Hey Romain,

On Wed, May 17, 2023 at 04:41:43PM +0200, Romain Perier wrote:
> This adds the documentation for the devicetree bindings of the Mstar
> SSD20xD RTC driver.

Bindings describe hardware, not the driver ;)

> 
> Signed-off-by: Romain Perier <romain.perier@gmail.com>
> ---
>  .../bindings/rtc/mstar,ssd20xd-rtc.yaml       | 37 +++++++++++++++++++
>  1 file changed, 37 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> new file mode 100644
> index 000000000000..2acd86cce69f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> @@ -0,0 +1,37 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/rtc/mstar,ssd20xd-rtc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Mstar SSD20xD RTC
> +
> +allOf:
> +  - $ref: rtc.yaml#
> +
> +maintainers:
> +  - Daniel Palmer <daniel@0x0f.com>
> +  - Romain Perier <romain.perier@gmail.com>
> +
> +properties:
> +  compatible:
> +    enum:
> +      - mstar,ssd20xd-rtc

Is this x a wildcard?
In general, having a specific compatible is preferred, and if there are
other models that are compatible we can list several "fall back" to the
most specific one implemented in a driver.

Thanks,
Conor.

On 17/05/2023 16:41, Romain Perier wrote:
> This adds the documentation for the devicetree bindings of the Mstar
> SSD20xD RTC driver.
> 

Please use scripts/get_maintainers.pl to get a list of necessary people
and lists to CC.  It might happen, that command when run on an older
kernel, gives you outdated entries.  Therefore please be sure you base
your patches on recent Linux kernel.

A nit, subject: drop second/last, redundant "devicetree bindings
documentation". The "dt-bindings" prefix is already stating that these
are bindings. You actually repeated everything...

> Signed-off-by: Romain Perier <romain.perier@gmail.com>
> ---
>  .../bindings/rtc/mstar,ssd20xd-rtc.yaml       | 37 +++++++++++++++++++
>  1 file changed, 37 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> new file mode 100644
> index 000000000000..2acd86cce69f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> @@ -0,0 +1,37 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/rtc/mstar,ssd20xd-rtc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Mstar SSD20xD RTC
> +
> +allOf:
> +  - $ref: rtc.yaml#

This goes just above properties:

> +
> +maintainers:
> +  - Daniel Palmer <daniel@0x0f.com>
> +  - Romain Perier <romain.perier@gmail.com>
> +
> +properties:
> +  compatible:
> +    enum:
> +      - mstar,ssd20xd-rtc

Why rtc suffix? Can it be anything else?

Missing blank line

> +  reg:
> +    maxItems: 1
> +
> +  start-year: true

Drop

What about interrupt line?

> +
> +required:
> +  - compatible
> +  - reg
> +
> +additionalProperties: false

instead
unevaluatedProperties: false

> +
> +examples:
> +  - |
> +    rtc@6800 {
> +        compatible = "mstar,ssd20xd-rtc";
> +        reg = <0x6800 0x200>;
> +    };
> +...

Best regards,
Krzysztof

Le mer. 17 mai 2023 à 19:44, Conor Dooley <conor@kernel.org> a écrit :
>
> Hey Romain,
>
> On Wed, May 17, 2023 at 04:41:43PM +0200, Romain Perier wrote:
> > This adds the documentation for the devicetree bindings of the Mstar
> > SSD20xD RTC driver.
>
> Bindings describe hardware, not the driver ;)

Hi,

Yep, I just copied and pasted the message of a previous merged-commit,
I will fix it.

>
> >
> > Signed-off-by: Romain Perier <romain.perier@gmail.com>
> > ---
> >  .../bindings/rtc/mstar,ssd20xd-rtc.yaml       | 37 +++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> > new file mode 100644
> > index 000000000000..2acd86cce69f
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> > @@ -0,0 +1,37 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/rtc/mstar,ssd20xd-rtc.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Mstar SSD20xD RTC
> > +
> > +allOf:
> > +  - $ref: rtc.yaml#
> > +
> > +maintainers:
> > +  - Daniel Palmer <daniel@0x0f.com>
> > +  - Romain Perier <romain.perier@gmail.com>
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - mstar,ssd20xd-rtc
>
> Is this x a wildcard?
> In general, having a specific compatible is preferred, and if there are
> other models that are compatible we can list several "fall back" to the
> most specific one implemented in a driver.


The first SoC being concerned is SSD202D, so  "mstar,ssd202d-rtc" ?

Thanks,
Romain

On Mon, May 22, 2023 at 08:47:08AM +0200, Romain Perier wrote:
> Le mer. 17 mai 2023 à 19:44, Conor Dooley <conor@kernel.org> a écrit :

> > > +properties:
> > > +  compatible:
> > > +    enum:
> > > +      - mstar,ssd20xd-rtc
> >
> > Is this x a wildcard?
> > In general, having a specific compatible is preferred, and if there are
> > other models that are compatible we can list several "fall back" to the
> > most specific one implemented in a driver.
> 
> 
> The first SoC being concerned is SSD202D, so  "mstar,ssd202d-rtc" ?

Sounds good to me, thanks.

Le jeu. 18 mai 2023 à 10:24, Krzysztof Kozlowski <krzk@kernel.org> a écrit :
>
> On 17/05/2023 16:41, Romain Perier wrote:
> > This adds the documentation for the devicetree bindings of the Mstar
> > SSD20xD RTC driver.
> >
>
> Please use scripts/get_maintainers.pl to get a list of necessary people
> and lists to CC.  It might happen, that command when run on an older
> kernel, gives you outdated entries.  Therefore please be sure you base
> your patches on recent Linux kernel.

Hi,

This is usually what I do for all patches series, but possible I have
missed some person

>
> A nit, subject: drop second/last, redundant "devicetree bindings
> documentation". The "dt-bindings" prefix is already stating that these
> are bindings. You actually repeated everything...

Originally, it was just to write a simple sentence with words... it
gives context, you know...

Like here:   https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=7647204c2e81b28b4a7c4eec7d539f998d48eaf0
or here:  https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=dd49cbedde8a0f1e0d09698f9cad791d37a8e03e

But honestly, I don't want to debate about this, yes I can remove
redundant "devicetree bindings documentation" ^^


>
> > Signed-off-by: Romain Perier <romain.perier@gmail.com>
> > ---
> >  .../bindings/rtc/mstar,ssd20xd-rtc.yaml       | 37 +++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> > new file mode 100644
> > index 000000000000..2acd86cce69f
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/rtc/mstar,ssd20xd-rtc.yaml
> > @@ -0,0 +1,37 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/rtc/mstar,ssd20xd-rtc.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Mstar SSD20xD RTC
> > +
> > +allOf:
> > +  - $ref: rtc.yaml#
>
> This goes just above properties:
>

ack

> > +
> > +maintainers:
> > +  - Daniel Palmer <daniel@0x0f.com>
> > +  - Romain Perier <romain.perier@gmail.com>
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - mstar,ssd20xd-rtc
>
> Why rtc suffix? Can it be anything else?

Well, it is the dt-bindings for an RTC block ? suppose tomorrow we
have an ethernet block specific to the SoC SSD202D, it should be
"mstar,ssd202d-ethernet" , how do you make
the difference if you just put "mstar,sd202d" ? Plus a lot of rtc
dt-bindings have this suffix (when it is not an IP name). This is
exactly the case for rtc-msc313e and it was not an issue.

>
> Missing blank line

ack

>
> > +  reg:
> > +    maxItems: 1
> > +
> > +  start-year: true
>
> Drop
>
> What about interrupt line?

There is currently no interrupt right now, we have not yet the irqchip
code for handling the alarm irq of this rtc block.


>
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +
> > +additionalProperties: false
>
> instead
> unevaluatedProperties: false

ack

Thanks,
Romain

On 22/05/2023 13:27, Romain Perier wrote:
>>> +properties:
>>> +  compatible:
>>> +    enum:
>>> +      - mstar,ssd20xd-rtc
>>
>> Why rtc suffix? Can it be anything else?
> 
> Well, it is the dt-bindings for an RTC block ? suppose tomorrow we
> have an ethernet block specific to the SoC SSD202D, it should be
> "mstar,ssd202d-ethernet" , how do you make
> the difference if you just put "mstar,sd202d" ? Plus a lot of rtc
> dt-bindings have this suffix (when it is not an IP name).

There are a lot of bad design choices or bugs - are you going to
implement the same mistakes because someone did it?

> This is
> exactly the case for rtc-msc313e and it was not an issue.

So that was my question - can it be anything else? There is literally no
description of the hardware... Neither in commit msg nor in description:
field in bindings.

What is SSD202D? SoC? RTC?


> 
>>
>> Missing blank line
> 
> ack
> 
>>
>>> +  reg:
>>> +    maxItems: 1
>>> +
>>> +  start-year: true
>>
>> Drop
>>
>> What about interrupt line?
> 
> There is currently no interrupt right now, we have not yet the irqchip
> code for handling the alarm irq of this rtc block.

So you are going to change the hardware and add the interrupt line? We
do not talk about drivers, but hardware. Whether your driver handles it
or not, matters less.

Describe the hardware, not the current implementation of one driver.


Best regards,
Krzysztof

Hi Krzysztof,

On Tue, 30 May 2023 at 17:01, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> > This is
> > exactly the case for rtc-msc313e and it was not an issue.
>
> So that was my question - can it be anything else? There is literally no
> description of the hardware... Neither in commit msg nor in description:
> field in bindings.

This RTC block is a block inside of the SSD201/SSD202D (they are the
same die with different memory attached) and is only found there.
The documentation we have for this is literally one page in a PDF that
says "RTC registers".
It could be an IP block licensed from somewhere and technically have a
better name but right now all we know is this RTC block is the one in
that chip and that chip is the first known instance of it.

Say we manage to get the ethernet mainlined at some point: That's a
lot easier as we know already it's a hacked up version of the cadence
macb so the compatible can be "macb something".

> >> What about interrupt line?
> >
> > There is currently no interrupt right now, we have not yet the irqchip
> > code for handling the alarm irq of this rtc block.
>
> So you are going to change the hardware and add the interrupt line? We
> do not talk about drivers, but hardware. Whether your driver handles it
> or not, matters less.
>
> Describe the hardware, not the current implementation of one driver.

We don't really know how the interrupt is wired up in the hardware properly yet.

Cheers,

Daniel

On 31/05/2023 01:12, Daniel Palmer wrote:
> Hi Krzysztof,
> 
> On Tue, 30 May 2023 at 17:01, Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>> This is
>>> exactly the case for rtc-msc313e and it was not an issue.
>>
>> So that was my question - can it be anything else? There is literally no
>> description of the hardware... Neither in commit msg nor in description:
>> field in bindings.
> 
> This RTC block is a block inside of the SSD201/SSD202D (they are the

But what is SSD201?

> same die with different memory attached) and is only found there.
> The documentation we have for this is literally one page in a PDF that
> says "RTC registers".
> It could be an IP block licensed from somewhere and technically have a
> better name but right now all we know is this RTC block is the one in
> that chip and that chip is the first known instance of it.
> 
> Say we manage to get the ethernet mainlined at some point: That's a
> lot easier as we know already it's a hacked up version of the cadence
> macb so the compatible can be "macb something".
> 
>>>> What about interrupt line?
>>>
>>> There is currently no interrupt right now, we have not yet the irqchip
>>> code for handling the alarm irq of this rtc block.
>>
>> So you are going to change the hardware and add the interrupt line? We
>> do not talk about drivers, but hardware. Whether your driver handles it
>> or not, matters less.
>>
>> Describe the hardware, not the current implementation of one driver.
> 
> We don't really know how the interrupt is wired up in the hardware properly yet.

OK

Best regards,
Krzysztof

Hi Krzysztof,

On Wed, 31 May 2023 at 15:49, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> > This RTC block is a block inside of the SSD201/SSD202D (they are the
>
> But what is SSD201?

Dual Cortex A7 SoC with integrated memory (SSD201 == 64MB, SSD202D ==
128MB) that happens to have an RTC.

Cheers,

Daniel