[1/4] dt-bindings: clock: renesas: Document RZ/V2H(P) SoC CPG driver

From: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>

Document the device tree bindings of the Renesas RZ/V2H(P) SoC
Clock Pulse Generator (CPG).

CPG block handles the below operations:
- Handles the generation and control of clock signals for the IP modules
- The generation and control of resets
- Control over booting
- Low power consumption and the power supply domains

Signed-off-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
---
 .../bindings/clock/renesas,rzv2h-cpg.yaml     | 78 +++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml

On Fri, May 24, 2024 at 09:27:57AM +0100, Prabhakar wrote:
> From: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> 
> Document the device tree bindings of the Renesas RZ/V2H(P) SoC
> Clock Pulse Generator (CPG).
> 
> CPG block handles the below operations:
> - Handles the generation and control of clock signals for the IP modules
> - The generation and control of resets
> - Control over booting
> - Low power consumption and the power supply domains
> 
> Signed-off-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> ---
>  .../bindings/clock/renesas,rzv2h-cpg.yaml     | 78 +++++++++++++++++++
>  1 file changed, 78 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml
> 
> diff --git a/Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml b/Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml
> new file mode 100644
> index 000000000000..baa0f2a5b6f9
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml
> @@ -0,0 +1,78 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/renesas,rzv2h-cpg.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Renesas RZ/V2H(P) Clock Pulse Generator (CPG)
> +
> +maintainers:
> +  - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> +
> +description: |
> +  On Renesas RZ/V2H(P) SoC's, the CPG (Clock Pulse Generator) handles the generation
> +  and control of clock signals for the IP modules, the generation and control of resets,
> +  and control over booting, low power consumption and the power supply domains.
> +
> +properties:
> +  compatible:
> +    const: renesas,r9a09g057-cpg
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    description:
> +      Clock source to CPG can be either from external clock input (EXCLK) or
> +      crystal oscillator (XIN/XOUT).

I think this description should be in clocks, not clock names.

> +    const: extal
> +
> +  '#clock-cells':
> +    description: |
> +      - For CPG core clocks, the two clock specifier cells must be "CPG_CORE"
> +        and a core clock reference, as defined in
> +        <dt-bindings/clock/r9a09g057-cpg.h>,
> +      - For module clocks, the two clock specifier cells must be "CPG_MOD" and
> +        a module number, as defined in <dt-bindings/clock/r9a09g057-cpg.h>.

Can you please explain the difference and why it matters? Why isn't the
unique number for a given clock sufficient?

Thanks,
Conor.

> +    const: 2
> +
> +  '#power-domain-cells':
> +    description:
> +      SoC devices that are part of the CPG/Module Standby Mode Clock Domain and
> +      can be power-managed through Module Standby should refer to the CPG device
> +      node in their "power-domains" property, as documented by the generic PM
> +      Domain bindings in Documentation/devicetree/bindings/power/power-domain.yaml.
> +      The power domain specifiers defined in <dt-bindings/clock/r9a09g057-cpg.h> could
> +      be used to reference individual CPG power domains.
> +
> +  '#reset-cells':
> +    description:
> +      The single reset specifier cell must be the module number, as defined in
> +      <dt-bindings/clock/r9a09g057-cpg.h>.
> +    const: 1
> +
> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - clock-names
> +  - '#clock-cells'
> +  - '#power-domain-cells'
> +  - '#reset-cells'
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    cpg: clock-controller@10420000 {
> +            compatible = "renesas,r9a09g057-cpg";
> +            reg = <0x10420000 0x10000>;
> +            clocks = <&extal_clk>;
> +            clock-names = "extal";
> +            #clock-cells = <2>;
> +            #power-domain-cells = <0>;
> +            #reset-cells = <1>;
> +    };
> -- 
> 2.34.1
>

Hi Prabhakar,

Thanks for your patch!

Please drop "driver" from the one-line summary.

On Fri, May 24, 2024 at 10:29 AM Prabhakar <prabhakar.csengg@gmail.com> wrote:
> From: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
>
> Document the device tree bindings of the Renesas RZ/V2H(P) SoC

s/of/for/

> Clock Pulse Generator (CPG).
>
> CPG block handles the below operations:
> - Handles the generation and control of clock signals for the IP modules

Please drop "Handles the"

> - The generation and control of resets

Please drop "The".

> - Control over booting
> - Low power consumption and the power supply domains

Please drop "the".

>
> Signed-off-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>

> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml
> @@ -0,0 +1,78 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/renesas,rzv2h-cpg.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Renesas RZ/V2H(P) Clock Pulse Generator (CPG)
> +
> +maintainers:
> +  - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> +
> +description: |
> +  On Renesas RZ/V2H(P) SoC's, the CPG (Clock Pulse Generator) handles the generation

SoCs

> +  and control of clock signals for the IP modules, the generation and control of resets,
> +  and control over booting, low power consumption and the power supply domains.

Please drop "the".

> +
> +properties:
> +  compatible:
> +    const: renesas,r9a09g057-cpg
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    description:
> +      Clock source to CPG can be either from external clock input (EXCLK) or
> +      crystal oscillator (XIN/XOUT).
> +    const: extal

According to Figure 4.4-1 ("CPG Functional Block Diagram"), there are 3
(RTC, audio, main).

> +
> +  '#clock-cells':
> +    description: |
> +      - For CPG core clocks, the two clock specifier cells must be "CPG_CORE"
> +        and a core clock reference, as defined in
> +        <dt-bindings/clock/r9a09g057-cpg.h>,
> +      - For module clocks, the two clock specifier cells must be "CPG_MOD" and
> +        a module number, as defined in <dt-bindings/clock/r9a09g057-cpg.h>.
> +    const: 2

I understand this will be changed to 1, the clock number?

> +  '#power-domain-cells':
> +    description:
> +      SoC devices that are part of the CPG/Module Standby Mode Clock Domain and
> +      can be power-managed through Module Standby should refer to the CPG device
> +      node in their "power-domains" property, as documented by the generic PM
> +      Domain bindings in Documentation/devicetree/bindings/power/power-domain.yaml.
> +      The power domain specifiers defined in <dt-bindings/clock/r9a09g057-cpg.h> could
> +      be used to reference individual CPG power domains.

The latter suggests "const: 1".
But the example below uses zero, as does the code?

> +
> +  '#reset-cells':
> +    description:
> +      The single reset specifier cell must be the module number, as defined in

reset number (or index).

> +      <dt-bindings/clock/r9a09g057-cpg.h>.
> +    const: 1
> +
> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - clock-names
> +  - '#clock-cells'
> +  - '#power-domain-cells'
> +  - '#reset-cells'
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    cpg: clock-controller@10420000 {
> +            compatible = "renesas,r9a09g057-cpg";
> +            reg = <0x10420000 0x10000>;
> +            clocks = <&extal_clk>;
> +            clock-names = "extal";
> +            #clock-cells = <2>;
> +            #power-domain-cells = <0>;
> +            #reset-cells = <1>;
> +    };

Gr{oetje,eeting}s,

                        Geert


--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Hi Prabhakar,

On Tue, Jun 4, 2024 at 5:49 PM Geert Uytterhoeven <geert@linux-m68k.org> wrote:
> On Fri, May 24, 2024 at 10:29 AM Prabhakar <prabhakar.csengg@gmail.com> wrote:
> > From: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> >
> > Document the device tree bindings of the Renesas RZ/V2H(P) SoC
> > Clock Pulse Generator (CPG).
> >
> > CPG block handles the below operations:
> > - Handles the generation and control of clock signals for the IP modules
> > - The generation and control of resets
> > - Control over booting
> > - Low power consumption and the power supply domains
> >
> > Signed-off-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
>
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml
> > +
> > +  '#clock-cells':
> > +    description: |
> > +      - For CPG core clocks, the two clock specifier cells must be "CPG_CORE"
> > +        and a core clock reference, as defined in
> > +        <dt-bindings/clock/r9a09g057-cpg.h>,
> > +      - For module clocks, the two clock specifier cells must be "CPG_MOD" and
> > +        a module number, as defined in <dt-bindings/clock/r9a09g057-cpg.h>.
> > +    const: 2
>
> I understand this will be changed to 1, the clock number?

We typically come up with our own definitions in header files if there
are no suitable module numbers listed in the hardware documentation.

For RZ/V2H, you could use a combination (e.g. concatenation) of the
column (register) and row (bit) numbers from Tables 4.4-14-19
("Specifications of the CPG_CLKON_m Registers") and Tables 4.4-22-25
("Specifications of the CPG_RST_m Registers") as the clock resp. reset
number, like is done on R-Car Gen2+ SoCs (see MOD_CLK_PACK() for
conversion from sparse to packed module numbers).

Gr{oetje,eeting}s,

                        Geert

Hi Geert,

Thank you for the review.

On Tue, Jun 4, 2024 at 4:50 PM Geert Uytterhoeven <geert@linux-m68k.org> wrote:
>
> Hi Prabhakar,
>
> Thanks for your patch!
>
> Please drop "driver" from the one-line summary.
>
OK, I will drop it.

> On Fri, May 24, 2024 at 10:29 AM Prabhakar <prabhakar.csengg@gmail.com> wrote:
> > From: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> >
> > Document the device tree bindings of the Renesas RZ/V2H(P) SoC
>
> s/of/for/
>
OK.

> > Clock Pulse Generator (CPG).
> >
> > CPG block handles the below operations:
> > - Handles the generation and control of clock signals for the IP modules
>
> Please drop "Handles the"
>
OK.

> > - The generation and control of resets
>
> Please drop "The".
>
OK.

> > - Control over booting
> > - Low power consumption and the power supply domains
>
> Please drop "the".
>
OK.

> >
> > Signed-off-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
>
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml
> > @@ -0,0 +1,78 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/clock/renesas,rzv2h-cpg.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Renesas RZ/V2H(P) Clock Pulse Generator (CPG)
> > +
> > +maintainers:
> > +  - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> > +
> > +description: |
> > +  On Renesas RZ/V2H(P) SoC's, the CPG (Clock Pulse Generator) handles the generation
>
> SoCs
>
OK.

> > +  and control of clock signals for the IP modules, the generation and control of resets,
> > +  and control over booting, low power consumption and the power supply domains.
>
> Please drop "the".
>
OK.

> > +
> > +properties:
> > +  compatible:
> > +    const: renesas,r9a09g057-cpg
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  clocks:
> > +    maxItems: 1
> > +
> > +  clock-names:
> > +    description:
> > +      Clock source to CPG can be either from external clock input (EXCLK) or
> > +      crystal oscillator (XIN/XOUT).
> > +    const: extal
>
> According to Figure 4.4-1 ("CPG Functional Block Diagram"), there are 3
> (RTC, audio, main).
>
Agreed, I will add the below:
- QEXTAL
- RTXIN
- AUDIO_EXTAL
- AUDIO_CLKB
- AUDIO_CLKC

> > +
> > +  '#clock-cells':
> > +    description: |
> > +      - For CPG core clocks, the two clock specifier cells must be "CPG_CORE"
> > +        and a core clock reference, as defined in
> > +        <dt-bindings/clock/r9a09g057-cpg.h>,
> > +      - For module clocks, the two clock specifier cells must be "CPG_MOD" and
> > +        a module number, as defined in <dt-bindings/clock/r9a09g057-cpg.h>.
> > +    const: 2
>
> I understand this will be changed to 1, the clock number?
>
I'll keep this '2'. I will introduce core clocks (clocks which cannot
be controlled by  CLKON_m register) for example,
- SYS_0_PCLK
- CA55_0_CORE_CLK[x]
- IOTOP_0_SHCLK.

> > +  '#power-domain-cells':
> > +    description:
> > +      SoC devices that are part of the CPG/Module Standby Mode Clock Domain and
> > +      can be power-managed through Module Standby should refer to the CPG device
> > +      node in their "power-domains" property, as documented by the generic PM
> > +      Domain bindings in Documentation/devicetree/bindings/power/power-domain.yaml.
> > +      The power domain specifiers defined in <dt-bindings/clock/r9a09g057-cpg.h> could
> > +      be used to reference individual CPG power domains.
>
> The latter suggests "const: 1".
> But the example below uses zero, as does the code?
>
This should be '0' indeed.

> > +
> > +  '#reset-cells':
> > +    description:
> > +      The single reset specifier cell must be the module number, as defined in
>
> reset number (or index).
>
OK.

Cheers,
Prabhakar

Hi Geert,

Thank you for the review.

On Wed, Jun 5, 2024 at 10:42 AM Geert Uytterhoeven <geert@linux-m68k.org> wrote:
>
> Hi Prabhakar,
>
> On Tue, Jun 4, 2024 at 5:49 PM Geert Uytterhoeven <geert@linux-m68k.org> wrote:
> > On Fri, May 24, 2024 at 10:29 AM Prabhakar <prabhakar.csengg@gmail.com> wrote:
> > > From: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> > >
> > > Document the device tree bindings of the Renesas RZ/V2H(P) SoC
> > > Clock Pulse Generator (CPG).
> > >
> > > CPG block handles the below operations:
> > > - Handles the generation and control of clock signals for the IP modules
> > > - The generation and control of resets
> > > - Control over booting
> > > - Low power consumption and the power supply domains
> > >
> > > Signed-off-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> >
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml
> > > +
> > > +  '#clock-cells':
> > > +    description: |
> > > +      - For CPG core clocks, the two clock specifier cells must be "CPG_CORE"
> > > +        and a core clock reference, as defined in
> > > +        <dt-bindings/clock/r9a09g057-cpg.h>,
> > > +      - For module clocks, the two clock specifier cells must be "CPG_MOD" and
> > > +        a module number, as defined in <dt-bindings/clock/r9a09g057-cpg.h>.
> > > +    const: 2
> >
> > I understand this will be changed to 1, the clock number?
>
> We typically come up with our own definitions in header files if there
> are no suitable module numbers listed in the hardware documentation.
>
Agreed.

> For RZ/V2H, you could use a combination (e.g. concatenation) of the
> column (register) and row (bit) numbers from Tables 4.4-14-19
> ("Specifications of the CPG_CLKON_m Registers") and Tables 4.4-22-25
> ("Specifications of the CPG_RST_m Registers") as the clock resp. reset
> number, like is done on R-Car Gen2+ SoCs (see MOD_CLK_PACK() for
> conversion from sparse to packed module numbers).
>
Thanks for the pointer.

I'll model as per your suggestion (this way we can avoid adding any
macros for module clocks) and dont have to worry about reserved bits.

Cheers,
Prabhakar