[08/15] dt-bindings: clock: Document ma35d1 clock controller bindings

  From: Jacky Huang <ychuang3@nuvoton.com>

Add documentation to describe nuvoton ma35d1 clock driver bindings.

Signed-off-by: Jacky Huang <ychuang3@nuvoton.com>
---
 .../bindings/clock/nuvoton,ma35d1-clk.yaml    | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
  

Quoting Jacky Huang (2023-03-15 00:28:55)
> diff --git a/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
> new file mode 100644
> index 000000000000..5c2dea071b38
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
> @@ -0,0 +1,83 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/nuvoton,ma35d1-clk.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Nuvoton MA35D1 Clock Controller Module Binding

Binding is redundant.

> +
> +maintainers:
> +  - Chi-Fang Li <cfli0@nuvoton.com>
> +  - Jacky Huang <ychuang3@nuvoton.com>
> +
> +description: |
> +  The MA35D1 clock controller generates clocks for the whole chip,
> +  including system clocks and all peripheral clocks.
> +
> +  See also:
> +    include/dt-bindings/clock/ma35d1-clk.h
> +
> +properties:
> +  compatible:
> +    items:
> +      - const: nuvoton,ma35d1-clk
> +      - const: syscon

Does it really need to be a syscon?

> +
> +  reg:
> +    maxItems: 1
> +
> +  "#clock-cells":
> +    const: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: clk_hxt
> +
> +  assigned-clocks:
> +    maxItems: 5
> +
> +  assigned-clock-rates:
> +    maxItems: 5

I hope the assigned clocks properties can be left out of this doc.

> +
> +  nuvoton,pll-mode:
> +    description:
> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
> +      integer mode, 1 is for fractional mode, and 2 is for spread
> +      spectrum mode.
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    maxItems: 5
> +    items:
> +      minimum: 0
> +      maximum: 2

Why not use a string?

> +
> +  nuvoton,sys:
> +    description:
> +      Phandle to the system management controller.
> +    $ref: "/schemas/types.yaml#/definitions/phandle-array"
> +
> +required:
> +  - compatible
> +  - reg
> +  - "#clock-cells"
> +  - clocks
> +  - clock-names
> +  - nuvoton,sys
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/nuvoton,ma35d1-clk.h>

No need to include this header right?

> +
> +    clk: clock-controller@40460200 {

Drop the label?

> +        compatible = "nuvoton,ma35d1-clk", "syscon";
> +        reg = <0x40460200 0x100>;
> +        #clock-cells = <1>;
> +        clocks = <&clk_hxt>;
> +        clock-names = "clk_hxt";
> +        nuvoton,sys = <&sys>;
> +    };
  

Dear Stephen,


Thanks for your review.


On 2023/3/16 上午 05:59, Stephen Boyd wrote:
> Quoting Jacky Huang (2023-03-15 00:28:55)
>> diff --git a/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
>> new file mode 100644
>> index 000000000000..5c2dea071b38
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
>> @@ -0,0 +1,83 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/clock/nuvoton,ma35d1-clk.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Nuvoton MA35D1 Clock Controller Module Binding
> Binding is redundant.

I will remove this word.

>> +
>> +maintainers:
>> +  - Chi-Fang Li <cfli0@nuvoton.com>
>> +  - Jacky Huang <ychuang3@nuvoton.com>
>> +
>> +description: |
>> +  The MA35D1 clock controller generates clocks for the whole chip,
>> +  including system clocks and all peripheral clocks.
>> +
>> +  See also:
>> +    include/dt-bindings/clock/ma35d1-clk.h
>> +
>> +properties:
>> +  compatible:
>> +    items:
>> +      - const: nuvoton,ma35d1-clk
>> +      - const: syscon
> Does it really need to be a syscon?

Some registers of the clock controller are locked against writing.
Before writing, the lock must be unlocked through the system controller.
So syscon is needed.

>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  "#clock-cells":
>> +    const: 1
>> +
>> +  clocks:
>> +    maxItems: 1
>> +
>> +  clock-names:
>> +    const: clk_hxt
>> +
>> +  assigned-clocks:
>> +    maxItems: 5
>> +
>> +  assigned-clock-rates:
>> +    maxItems: 5
> I hope the assigned clocks properties can be left out of this doc.

Sure, we will remove it.

>> +
>> +  nuvoton,pll-mode:
>> +    description:
>> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
>> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
>> +      integer mode, 1 is for fractional mode, and 2 is for spread
>> +      spectrum mode.
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    maxItems: 5
>> +    items:
>> +      minimum: 0
>> +      maximum: 2
> Why not use a string?

OK, we'll use strings instead.

>> +
>> +  nuvoton,sys:
>> +    description:
>> +      Phandle to the system management controller.
>> +    $ref: "/schemas/types.yaml#/definitions/phandle-array"
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - "#clock-cells"
>> +  - clocks
>> +  - clock-names
>> +  - nuvoton,sys
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/clock/nuvoton,ma35d1-clk.h>
> No need to include this header right?

Yes, I will remove this header in the next version.

>
>> +
>> +    clk: clock-controller@40460200 {
> Drop the label?

OK, I will drop this label in the next version.

>
>> +        compatible = "nuvoton,ma35d1-clk", "syscon";
>> +        reg = <0x40460200 0x100>;
>> +        #clock-cells = <1>;
>> +        clocks = <&clk_hxt>;
>> +        clock-names = "clk_hxt";
>> +        nuvoton,sys = <&sys>;
>> +    };


Best Regards,

Jacky Huang
  

On 15/03/2023 08:28, Jacky Huang wrote:
> From: Jacky Huang <ychuang3@nuvoton.com>
> 
> Add documentation to describe nuvoton ma35d1 clock driver bindings.

Subject: drop second/last, redundant "bindings". The "dt-bindings"
prefix is already stating that these are bindings.

> 
> Signed-off-by: Jacky Huang <ychuang3@nuvoton.com>
> ---
>  .../bindings/clock/nuvoton,ma35d1-clk.yaml    | 83 +++++++++++++++++++
>  1 file changed, 83 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
> 
> diff --git a/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
> new file mode 100644
> index 000000000000..5c2dea071b38
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
> @@ -0,0 +1,83 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/nuvoton,ma35d1-clk.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Nuvoton MA35D1 Clock Controller Module Binding
> +
> +maintainers:
> +  - Chi-Fang Li <cfli0@nuvoton.com>
> +  - Jacky Huang <ychuang3@nuvoton.com>
> +
> +description: |
> +  The MA35D1 clock controller generates clocks for the whole chip,
> +  including system clocks and all peripheral clocks.
> +
> +  See also:
> +    include/dt-bindings/clock/ma35d1-clk.h
> +
> +properties:
> +  compatible:
> +    items:
> +      - const: nuvoton,ma35d1-clk
> +      - const: syscon
> +
> +  reg:
> +    maxItems: 1
> +
> +  "#clock-cells":
> +    const: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: clk_hxt

Drop clock-names. You do not need it for one clock.


> +
> +  assigned-clocks:
> +    maxItems: 5
> +
> +  assigned-clock-rates:
> +    maxItems: 5

Drop both properties, you do not need them in the binding.

> +
> +  nuvoton,pll-mode:
> +    description:
> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
> +      integer mode, 1 is for fractional mode, and 2 is for spread
> +      spectrum mode.
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    maxItems: 5
> +    items:
> +      minimum: 0
> +      maximum: 2

Why exactly this is suitable for DT?

> +
> +  nuvoton,sys:
> +    description:
> +      Phandle to the system management controller.
> +    $ref: "/schemas/types.yaml#/definitions/phandle-array"

Drop quotes.

You need here constraints, look for existing examples.



Best regards,
Krzysztof
  

Dear Krzysztof,

Thanks for your advice.


On 2023/3/16 下午 03:35, Krzysztof Kozlowski wrote:
> On 15/03/2023 08:28, Jacky Huang wrote:
>> From: Jacky Huang <ychuang3@nuvoton.com>
>>
>> Add documentation to describe nuvoton ma35d1 clock driver bindings.
> Subject: drop second/last, redundant "bindings". The "dt-bindings"
> prefix is already stating that these are bindings.

Got it, thanks.

>> Signed-off-by: Jacky Huang <ychuang3@nuvoton.com>
>> ---
>>   .../bindings/clock/nuvoton,ma35d1-clk.yaml    | 83 +++++++++++++++++++
>>   1 file changed, 83 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
>> new file mode 100644
>> index 000000000000..5c2dea071b38
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml
>> @@ -0,0 +1,83 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/clock/nuvoton,ma35d1-clk.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Nuvoton MA35D1 Clock Controller Module Binding
>> +
>> +maintainers:
>> +  - Chi-Fang Li <cfli0@nuvoton.com>
>> +  - Jacky Huang <ychuang3@nuvoton.com>
>> +
>> +description: |
>> +  The MA35D1 clock controller generates clocks for the whole chip,
>> +  including system clocks and all peripheral clocks.
>> +
>> +  See also:
>> +    include/dt-bindings/clock/ma35d1-clk.h
>> +
>> +properties:
>> +  compatible:
>> +    items:
>> +      - const: nuvoton,ma35d1-clk
>> +      - const: syscon
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  "#clock-cells":
>> +    const: 1
>> +
>> +  clocks:
>> +    maxItems: 1
>> +
>> +  clock-names:
>> +    const: clk_hxt
> Drop clock-names. You do not need it for one clock.

I will remove it.

>
>
>> +
>> +  assigned-clocks:
>> +    maxItems: 5
>> +
>> +  assigned-clock-rates:
>> +    maxItems: 5
> Drop both properties, you do not need them in the binding.

I will drop them.

>
>> +
>> +  nuvoton,pll-mode:
>> +    description:
>> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
>> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
>> +      integer mode, 1 is for fractional mode, and 2 is for spread
>> +      spectrum mode.
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    maxItems: 5
>> +    items:
>> +      minimum: 0
>> +      maximum: 2
> Why exactly this is suitable for DT?

I will use strings instead.

>
>> +
>> +  nuvoton,sys:
>> +    description:
>> +      Phandle to the system management controller.
>> +    $ref: "/schemas/types.yaml#/definitions/phandle-array"
> Drop quotes.
>
> You need here constraints, look for existing examples.
>

I would like to modify this as:


   nuvoton,sys:
     description:
       Use to unlock and lock some clock controller registers. The lock
       control register is in system controller.
     $ref: /schemas/types.yaml#/definitions/phandle-array
     items:
       - items:
           - description: phandle to the system controller.


>
> Best regards,
> Krzysztof
>

Best regards,

Jacky Huang
  

On 17/03/2023 04:47, Jacky Huang wrote:
> 
>>
>>> +
>>> +  nuvoton,pll-mode:
>>> +    description:
>>> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
>>> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
>>> +      integer mode, 1 is for fractional mode, and 2 is for spread
>>> +      spectrum mode.
>>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>>> +    maxItems: 5
>>> +    items:
>>> +      minimum: 0
>>> +      maximum: 2
>> Why exactly this is suitable for DT?
> 
> I will use strings instead.

I have doubts why PLL mode is a property of DT. Is this a board-specific
property?

> 
>>
>>> +
>>> +  nuvoton,sys:
>>> +    description:
>>> +      Phandle to the system management controller.
>>> +    $ref: "/schemas/types.yaml#/definitions/phandle-array"
>> Drop quotes.
>>
>> You need here constraints, look for existing examples.
>>
> 
> I would like to modify this as:
> 
> 
>    nuvoton,sys:
>      description:
>        Use to unlock and lock some clock controller registers. The lock
>        control register is in system controller.
>      $ref: /schemas/types.yaml#/definitions/phandle-array
>      items:
>        - items:
>            - description: phandle to the system controller.

In such case you do not have array. Just make it phandle and drop the items.



Best regards,
Krzysztof
  

Dear Krzysztof,

Thanks for your advice.

On 2023/3/17 下午 05:13, Krzysztof Kozlowski wrote:
> On 17/03/2023 04:47, Jacky Huang wrote:
>>>> +
>>>> +  nuvoton,pll-mode:
>>>> +    description:
>>>> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
>>>> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
>>>> +      integer mode, 1 is for fractional mode, and 2 is for spread
>>>> +      spectrum mode.
>>>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>>>> +    maxItems: 5
>>>> +    items:
>>>> +      minimum: 0
>>>> +      maximum: 2
>>> Why exactly this is suitable for DT?
>> I will use strings instead.
> I have doubts why PLL mode is a property of DT. Is this a board-specific
> property?

CA-PLL has mode 0 only.
DDRPLL, APLL, EPLL, and VPLL have the same PLL design that supports
integer mode, fractional mode, and spread spctrum mode. The PLL mode
is controlled by clock controller register. I think it's not board-specific.

>>>> +
>>>> +  nuvoton,sys:
>>>> +    description:
>>>> +      Phandle to the system management controller.
>>>> +    $ref: "/schemas/types.yaml#/definitions/phandle-array"
>>> Drop quotes.
>>>
>>> You need here constraints, look for existing examples.
>>>
>> I would like to modify this as:
>>
>>
>>     nuvoton,sys:
>>       description:
>>         Use to unlock and lock some clock controller registers. The lock
>>         control register is in system controller.
>>       $ref: /schemas/types.yaml#/definitions/phandle-array
>>       items:
>>         - items:
>>             - description: phandle to the system controller.
> In such case you do not have array. Just make it phandle and drop the items.
>

Thank you.
So, I will rewrite it as

   nuvoton,sys:
     description:
       Use to unlock and lock some clock controller registers. The lock
       control register is in system controller.
     $ref: /schemas/types.yaml#/definitions/phandle


>
> Best regards,
> Krzysztof
>

Best regards,

Jacky Huang
  

On 17/03/2023 10:52, Jacky Huang wrote:
> Dear Krzysztof,
> 
> Thanks for your advice.
> 
> On 2023/3/17 下午 05:13, Krzysztof Kozlowski wrote:
>> On 17/03/2023 04:47, Jacky Huang wrote:
>>>>> +
>>>>> +  nuvoton,pll-mode:
>>>>> +    description:
>>>>> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
>>>>> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
>>>>> +      integer mode, 1 is for fractional mode, and 2 is for spread
>>>>> +      spectrum mode.
>>>>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>>>>> +    maxItems: 5
>>>>> +    items:
>>>>> +      minimum: 0
>>>>> +      maximum: 2
>>>> Why exactly this is suitable for DT?
>>> I will use strings instead.
>> I have doubts why PLL mode is a property of DT. Is this a board-specific
>> property?
> 
> CA-PLL has mode 0 only.
> DDRPLL, APLL, EPLL, and VPLL have the same PLL design that supports
> integer mode, fractional mode, and spread spctrum mode. The PLL mode
> is controlled by clock controller register. I think it's not board-specific.

You described the feature but that does not answer why this is suitable
in DT. If this is not board-specific, then it is implied by compatible,
right? Or it does not have to be in DT at all.


Best regards,
Krzysztof
  

Dear Krzysztof,


Thanks for your advice.


On 2023/3/18 上午 12:03, Krzysztof Kozlowski wrote:
> On 17/03/2023 10:52, Jacky Huang wrote:
>> Dear Krzysztof,
>>
>> Thanks for your advice.
>>
>> On 2023/3/17 下午 05:13, Krzysztof Kozlowski wrote:
>>> On 17/03/2023 04:47, Jacky Huang wrote:
>>>>>> +
>>>>>> +  nuvoton,pll-mode:
>>>>>> +    description:
>>>>>> +      A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL,
>>>>>> +      EPLL, and VPLL in sequential. The operation mode value 0 is for
>>>>>> +      integer mode, 1 is for fractional mode, and 2 is for spread
>>>>>> +      spectrum mode.
>>>>>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>>>>>> +    maxItems: 5
>>>>>> +    items:
>>>>>> +      minimum: 0
>>>>>> +      maximum: 2
>>>>> Why exactly this is suitable for DT?
>>>> I will use strings instead.
>>> I have doubts why PLL mode is a property of DT. Is this a board-specific
>>> property?
>> CA-PLL has mode 0 only.
>> DDRPLL, APLL, EPLL, and VPLL have the same PLL design that supports
>> integer mode, fractional mode, and spread spctrum mode. The PLL mode
>> is controlled by clock controller register. I think it's not board-specific.
> You described the feature but that does not answer why this is suitable
> in DT. If this is not board-specific, then it is implied by compatible,
> right? Or it does not have to be in DT at all.
>
>
> Best regards,
> Krzysztof


I got it now. Yes, at least DDR PLL and VPLL (video pixel clock) can be 
different on

different boards. You're right, it should be board specific. Thank you.

In the next version, I will move PLL property to board dts.


Best regards,

Jacky Huang