diff mbox series

[v3] dt-bindings: clock: actions,owl-cmu: convert to YAML

Message ID 20241107143431.728669-1-ivo.ivanov.ivanov1@gmail.com (mailing list archive)
State Changes Requested, archived
Headers show
Series [v3] dt-bindings: clock: actions,owl-cmu: convert to YAML | expand

Commit Message

Ivaylo Ivanov Nov. 7, 2024, 2:34 p.m. UTC 
Convert the Actions Semi Owl CMU bindings to DT schema.

Changes during conversion:
 - Since all Actions Semi Owl SoCs utilize the internal low frequency
   oscillator as a parent for some clocks, require it.

Signed-off-by: Ivaylo Ivanov <ivo.ivanov.ivanov1@gmail.com>
---
v3: list the headers in the description
v3: match properties: order with required:
v3: add clocks as a required property
v3: drop unused example node label
v3: use the preferred four-space indentation for dts example

v2: drop address and size cells from example
---
 .../bindings/clock/actions,owl-cmu.txt        | 52 ----------------
 .../bindings/clock/actions,owl-cmu.yaml       | 60 +++++++++++++++++++
 MAINTAINERS                                   |  2 +-
 3 files changed, 61 insertions(+), 53 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
 create mode 100644 Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml

Comments

Krzysztof Kozlowski Nov. 8, 2024, 12:16 p.m. UTC | #1 
On Thu, Nov 07, 2024 at 04:34:31PM +0200, Ivaylo Ivanov wrote:
> Convert the Actions Semi Owl CMU bindings to DT schema.
> 
> Changes during conversion:
>  - Since all Actions Semi Owl SoCs utilize the internal low frequency
>    oscillator as a parent for some clocks, require it.
> 
> Signed-off-by: Ivaylo Ivanov <ivo.ivanov.ivanov1@gmail.com>

<form letter>
This is a friendly reminder during the review process.

It looks like you received a tag and forgot to add it.

If you do not know the process, here is a short explanation: Please add
Acked-by/Reviewed-by/Tested-by tags when posting new versions, under
or above your Signed-off-by tag. Tag is "received", when provided
in a message replied to you on the mailing list. Tools like b4 can help
here. However, there's no need to repost patches *only* to add the tags.
The upstream maintainer will do that for tags received on the version
they apply.

https://elixir.bootlin.com/linux/v6.5-rc3/source/Documentation/process/submitting-patches.rst#L577

If a tag was not added on purpose, please state why and what changed.
</form letter>

I cannot add other people's tags - toolsets ignore it.

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

...

> +maintainers:
> +  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
> +
> +description: |
> +  The Actions Semi Owl Clock Management Unit generates and supplies clock
> +  to various controllers within the SoC.
> +
> +  See also::

Single ':'.

Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Best regards,
Krzysztof
Ivaylo Ivanov Nov. 8, 2024, 8:30 p.m. UTC | #2 
On 11/8/24 14:16, Krzysztof Kozlowski wrote:
> On Thu, Nov 07, 2024 at 04:34:31PM +0200, Ivaylo Ivanov wrote:
>> Convert the Actions Semi Owl CMU bindings to DT schema.
>>
>> Changes during conversion:
>>  - Since all Actions Semi Owl SoCs utilize the internal low frequency
>>    oscillator as a parent for some clocks, require it.
>>
>> Signed-off-by: Ivaylo Ivanov <ivo.ivanov.ivanov1@gmail.com>
> <form letter>
> This is a friendly reminder during the review process.
>
> It looks like you received a tag and forgot to add it.
>
> If you do not know the process, here is a short explanation: Please add
> Acked-by/Reviewed-by/Tested-by tags when posting new versions, under
> or above your Signed-off-by tag. Tag is "received", when provided
> in a message replied to you on the mailing list. Tools like b4 can help
> here. However, there's no need to repost patches *only* to add the tags.
> The upstream maintainer will do that for tags received on the version
> they apply.
>
> https://elixir.bootlin.com/linux/v6.5-rc3/source/Documentation/process/submitting-patches.rst#L577
>
> If a tag was not added on purpose, please state why and what changed.
> </form letter>
>
> I cannot add other people's tags - toolsets ignore it.
>
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
>
> ...
>
>> +maintainers:
>> +  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
>> +
>> +description: |
>> +  The Actions Semi Owl Clock Management Unit generates and supplies clock
>> +  to various controllers within the SoC.
>> +
>> +  See also::
> Single ':'.

$ rg --files-with-matches "See also:" | wc -l
110

$ rg --files-with-matches "See also::" | wc -l
94

Having 94 matches of that out of all 110 definitely leads me to
think that this has been done on purpose, and is still being done.

Could you elaborate a bit more? If it's wrong, then shouldn't we
clean all the other bindings from that mistake?

Best regards, Ivo.

>
> Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>
> Best regards,
> Krzysztof
>
Rob Herring (Arm) Nov. 8, 2024, 8:56 p.m. UTC | #3 
On Fri, Nov 8, 2024 at 2:31 PM Ivaylo Ivanov
<ivo.ivanov.ivanov1@gmail.com> wrote:
>
>
>
>
> On 11/8/24 14:16, Krzysztof Kozlowski wrote:
> > On Thu, Nov 07, 2024 at 04:34:31PM +0200, Ivaylo Ivanov wrote:
> >> Convert the Actions Semi Owl CMU bindings to DT schema.
> >>
> >> Changes during conversion:
> >>  - Since all Actions Semi Owl SoCs utilize the internal low frequency
> >>    oscillator as a parent for some clocks, require it.
> >>
> >> Signed-off-by: Ivaylo Ivanov <ivo.ivanov.ivanov1@gmail.com>
> > <form letter>
> > This is a friendly reminder during the review process.
> >
> > It looks like you received a tag and forgot to add it.
> >
> > If you do not know the process, here is a short explanation: Please add
> > Acked-by/Reviewed-by/Tested-by tags when posting new versions, under
> > or above your Signed-off-by tag. Tag is "received", when provided
> > in a message replied to you on the mailing list. Tools like b4 can help
> > here. However, there's no need to repost patches *only* to add the tags.
> > The upstream maintainer will do that for tags received on the version
> > they apply.
> >
> > https://elixir.bootlin.com/linux/v6.5-rc3/source/Documentation/process/submitting-patches.rst#L577
> >
> > If a tag was not added on purpose, please state why and what changed.
> > </form letter>
> >
> > I cannot add other people's tags - toolsets ignore it.
> >
> > Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> >
> > ...
> >
> >> +maintainers:
> >> +  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
> >> +
> >> +description: |
> >> +  The Actions Semi Owl Clock Management Unit generates and supplies clock
> >> +  to various controllers within the SoC.
> >> +
> >> +  See also::
> > Single ':'.
>
> $ rg --files-with-matches "See also:" | wc -l
> 110
>
> $ rg --files-with-matches "See also::" | wc -l
> 94
>
> Having 94 matches of that out of all 110 definitely leads me to
> think that this has been done on purpose, and is still being done.

91 are QCom and 82 are QCom clock bindings... They tend to be
annoyingly consistent sometimes with whatever was their downstream
coding standards.

The double colon is needed in rSt documents to escape a colon. We
don't need that in YAML though. There were some thoughts on embedding
rSt into the bindings for generating documentation from the bindings,
but that's never been more than some experiments. This just looks like
the first QCom clock binding did this and all the others just
copy-n-pasted it.

> Could you elaborate a bit more? If it's wrong, then shouldn't we
> clean all the other bindings from that mistake?

Patches welcome...

Rob
Ivaylo Ivanov Nov. 8, 2024, 9:12 p.m. UTC | #4 
On 11/8/24 22:56, Rob Herring wrote:
> On Fri, Nov 8, 2024 at 2:31 PM Ivaylo Ivanov
> <ivo.ivanov.ivanov1@gmail.com> wrote:
>>
>>
>>
>> On 11/8/24 14:16, Krzysztof Kozlowski wrote:
>>> On Thu, Nov 07, 2024 at 04:34:31PM +0200, Ivaylo Ivanov wrote:
>>>> Convert the Actions Semi Owl CMU bindings to DT schema.
>>>>
>>>> Changes during conversion:
>>>>  - Since all Actions Semi Owl SoCs utilize the internal low frequency
>>>>    oscillator as a parent for some clocks, require it.
>>>>
>>>> Signed-off-by: Ivaylo Ivanov <ivo.ivanov.ivanov1@gmail.com>
>>> <form letter>
>>> This is a friendly reminder during the review process.
>>>
>>> It looks like you received a tag and forgot to add it.
>>>
>>> If you do not know the process, here is a short explanation: Please add
>>> Acked-by/Reviewed-by/Tested-by tags when posting new versions, under
>>> or above your Signed-off-by tag. Tag is "received", when provided
>>> in a message replied to you on the mailing list. Tools like b4 can help
>>> here. However, there's no need to repost patches *only* to add the tags.
>>> The upstream maintainer will do that for tags received on the version
>>> they apply.
>>>
>>> https://elixir.bootlin.com/linux/v6.5-rc3/source/Documentation/process/submitting-patches.rst#L577
>>>
>>> If a tag was not added on purpose, please state why and what changed.
>>> </form letter>
>>>
>>> I cannot add other people's tags - toolsets ignore it.
>>>
>>> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
>>>
>>> ...
>>>
>>>> +maintainers:
>>>> +  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
>>>> +
>>>> +description: |
>>>> +  The Actions Semi Owl Clock Management Unit generates and supplies clock
>>>> +  to various controllers within the SoC.
>>>> +
>>>> +  See also::
>>> Single ':'.
>> $ rg --files-with-matches "See also:" | wc -l
>> 110
>>
>> $ rg --files-with-matches "See also::" | wc -l
>> 94
>>
>> Having 94 matches of that out of all 110 definitely leads me to
>> think that this has been done on purpose, and is still being done.
> 91 are QCom and 82 are QCom clock bindings... They tend to be
> annoyingly consistent sometimes with whatever was their downstream
> coding standards.
>
> The double colon is needed in rSt documents to escape a colon. We
> don't need that in YAML though. There were some thoughts on embedding
> rSt into the bindings for generating documentation from the bindings,
> but that's never been more than some experiments. This just looks like
> the first QCom clock binding did this and all the others just
> copy-n-pasted it.

I see, thanks for the explanation!

>> Could you elaborate a bit more? If it's wrong, then shouldn't we
>> clean all the other bindings from that mistake?
> Patches welcome...

Will look further into it the following weeks. For now I'll send a v4
of this patch with the issue fixed.

Best regards, Ivo.

>
> Rob
Manivannan Sadhasivam Nov. 12, 2024, 6:47 a.m. UTC | #5 
On Thu, Nov 07, 2024 at 04:34:31PM +0200, Ivaylo Ivanov wrote:
> Convert the Actions Semi Owl CMU bindings to DT schema.
> 
> Changes during conversion:
>  - Since all Actions Semi Owl SoCs utilize the internal low frequency
>    oscillator as a parent for some clocks, require it.
> 
> Signed-off-by: Ivaylo Ivanov <ivo.ivanov.ivanov1@gmail.com>

Acked-by: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>

Thanks!

- Mani

> ---
> v3: list the headers in the description
> v3: match properties: order with required:
> v3: add clocks as a required property
> v3: drop unused example node label
> v3: use the preferred four-space indentation for dts example
> 
> v2: drop address and size cells from example
> ---
>  .../bindings/clock/actions,owl-cmu.txt        | 52 ----------------
>  .../bindings/clock/actions,owl-cmu.yaml       | 60 +++++++++++++++++++
>  MAINTAINERS                                   |  2 +-
>  3 files changed, 61 insertions(+), 53 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
>  create mode 100644 Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml
> 
> diff --git a/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt b/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
> deleted file mode 100644
> index d19885b7c..000000000
> --- a/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
> +++ /dev/null
> @@ -1,52 +0,0 @@
> -* Actions Semi Owl Clock Management Unit (CMU)
> -
> -The Actions Semi Owl Clock Management Unit generates and supplies clock
> -to various controllers within the SoC. The clock binding described here is
> -applicable to S900, S700 and S500 SoC's.
> -
> -Required Properties:
> -
> -- compatible: should be one of the following,
> -	"actions,s900-cmu"
> -	"actions,s700-cmu"
> -	"actions,s500-cmu"
> -- reg: physical base address of the controller and length of memory mapped
> -  region.
> -- clocks: Reference to the parent clocks ("hosc", "losc")
> -- #clock-cells: should be 1.
> -- #reset-cells: should be 1.
> -
> -Each clock is assigned an identifier, and client nodes can use this identifier
> -to specify the clock which they consume.
> -
> -All available clocks are defined as preprocessor macros in corresponding
> -dt-bindings/clock/actions,s900-cmu.h or actions,s700-cmu.h or
> -actions,s500-cmu.h header and can be used in device tree sources.
> -
> -External clocks:
> -
> -The hosc clock used as input for the plls is generated outside the SoC. It is
> -expected that it is defined using standard clock bindings as "hosc".
> -
> -Actions Semi S900 CMU also requires one more clock:
> - - "losc" - internal low frequency oscillator
> -
> -Example: Clock Management Unit node:
> -
> -        cmu: clock-controller@e0160000 {
> -                compatible = "actions,s900-cmu";
> -                reg = <0x0 0xe0160000 0x0 0x1000>;
> -                clocks = <&hosc>, <&losc>;
> -                #clock-cells = <1>;
> -                #reset-cells = <1>;
> -        };
> -
> -Example: UART controller node that consumes clock generated by the clock
> -management unit:
> -
> -        uart: serial@e012a000 {
> -                compatible = "actions,s900-uart", "actions,owl-uart";
> -                reg = <0x0 0xe012a000 0x0 0x2000>;
> -                interrupts = <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>;
> -                clocks = <&cmu CLK_UART5>;
> -        };
> diff --git a/Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml b/Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml
> new file mode 100644
> index 000000000..1717099b7
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml
> @@ -0,0 +1,60 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/actions,owl-cmu.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Actions Semi Owl Clock Management Unit (CMU)
> +
> +maintainers:
> +  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
> +
> +description: |
> +  The Actions Semi Owl Clock Management Unit generates and supplies clock
> +  to various controllers within the SoC.
> +
> +  See also::
> +    include/dt-bindings/clock/actions,s500-cmu.h
> +    include/dt-bindings/clock/actions,s700-cmu.h
> +    include/dt-bindings/clock/actions,s900-cmu.h
> +
> +properties:
> +  compatible:
> +    enum:
> +      - actions,s500-cmu
> +      - actions,s700-cmu
> +      - actions,s900-cmu
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    items:
> +      - description: Host oscillator source
> +      - description: Internal low frequency oscillator source
> +
> +  "#clock-cells":
> +    const: 1
> +
> +  "#reset-cells":
> +    const: 1
> +
> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - "#clock-cells"
> +  - "#reset-cells"
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    clock-controller@e0160000 {
> +        compatible = "actions,s900-cmu";
> +        reg = <0xe0160000 0x1000>;
> +        clocks = <&hosc>, <&losc>;
> +        #clock-cells = <1>;
> +        #reset-cells = <1>;
> +    };
> +...
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 420d06d37..652c9822a 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2016,7 +2016,7 @@ L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
>  L:	linux-actions@lists.infradead.org (moderated for non-subscribers)
>  S:	Maintained
>  F:	Documentation/devicetree/bindings/arm/actions.yaml
> -F:	Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
> +F:	Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml
>  F:	Documentation/devicetree/bindings/dma/owl-dma.yaml
>  F:	Documentation/devicetree/bindings/i2c/i2c-owl.yaml
>  F:	Documentation/devicetree/bindings/interrupt-controller/actions,owl-sirq.yaml
> -- 
> 2.43.0
>
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt b/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
deleted file mode 100644
index d19885b7c..000000000
--- a/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
+++ /dev/null
@@ -1,52 +0,0 @@ 
-* Actions Semi Owl Clock Management Unit (CMU)
-
-The Actions Semi Owl Clock Management Unit generates and supplies clock
-to various controllers within the SoC. The clock binding described here is
-applicable to S900, S700 and S500 SoC's.
-
-Required Properties:
-
-- compatible: should be one of the following,
-	"actions,s900-cmu"
-	"actions,s700-cmu"
-	"actions,s500-cmu"
-- reg: physical base address of the controller and length of memory mapped
-  region.
-- clocks: Reference to the parent clocks ("hosc", "losc")
-- #clock-cells: should be 1.
-- #reset-cells: should be 1.
-
-Each clock is assigned an identifier, and client nodes can use this identifier
-to specify the clock which they consume.
-
-All available clocks are defined as preprocessor macros in corresponding
-dt-bindings/clock/actions,s900-cmu.h or actions,s700-cmu.h or
-actions,s500-cmu.h header and can be used in device tree sources.
-
-External clocks:
-
-The hosc clock used as input for the plls is generated outside the SoC. It is
-expected that it is defined using standard clock bindings as "hosc".
-
-Actions Semi S900 CMU also requires one more clock:
- - "losc" - internal low frequency oscillator
-
-Example: Clock Management Unit node:
-
-        cmu: clock-controller@e0160000 {
-                compatible = "actions,s900-cmu";
-                reg = <0x0 0xe0160000 0x0 0x1000>;
-                clocks = <&hosc>, <&losc>;
-                #clock-cells = <1>;
-                #reset-cells = <1>;
-        };
-
-Example: UART controller node that consumes clock generated by the clock
-management unit:
-
-        uart: serial@e012a000 {
-                compatible = "actions,s900-uart", "actions,owl-uart";
-                reg = <0x0 0xe012a000 0x0 0x2000>;
-                interrupts = <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>;
-                clocks = <&cmu CLK_UART5>;
-        };
diff --git a/Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml b/Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml
new file mode 100644
index 000000000..1717099b7
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml
@@ -0,0 +1,60 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/actions,owl-cmu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Actions Semi Owl Clock Management Unit (CMU)
+
+maintainers:
+  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+
+description: |
+  The Actions Semi Owl Clock Management Unit generates and supplies clock
+  to various controllers within the SoC.
+
+  See also::
+    include/dt-bindings/clock/actions,s500-cmu.h
+    include/dt-bindings/clock/actions,s700-cmu.h
+    include/dt-bindings/clock/actions,s900-cmu.h
+
+properties:
+  compatible:
+    enum:
+      - actions,s500-cmu
+      - actions,s700-cmu
+      - actions,s900-cmu
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    items:
+      - description: Host oscillator source
+      - description: Internal low frequency oscillator source
+
+  "#clock-cells":
+    const: 1
+
+  "#reset-cells":
+    const: 1
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - "#clock-cells"
+  - "#reset-cells"
+
+additionalProperties: false
+
+examples:
+  - |
+    clock-controller@e0160000 {
+        compatible = "actions,s900-cmu";
+        reg = <0xe0160000 0x1000>;
+        clocks = <&hosc>, <&losc>;
+        #clock-cells = <1>;
+        #reset-cells = <1>;
+    };
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index 420d06d37..652c9822a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2016,7 +2016,7 @@  L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
 L:	linux-actions@lists.infradead.org (moderated for non-subscribers)
 S:	Maintained
 F:	Documentation/devicetree/bindings/arm/actions.yaml
-F:	Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
+F:	Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml
 F:	Documentation/devicetree/bindings/dma/owl-dma.yaml
 F:	Documentation/devicetree/bindings/i2c/i2c-owl.yaml
 F:	Documentation/devicetree/bindings/interrupt-controller/actions,owl-sirq.yaml