[0/2] clk: Add basic register clock controller

These clocks were provided in `include/linux/clk-provider.h`, but lacks DT
bindings. Add a clock controller to avoid operation conflict on same
register.

*** BLURB HERE ***

David Yang (2):
  dt-bindings: clock: Add reg-clock-controller
  clk: Add basic register clock controller

 .../bindings/clock/reg-clock-controller.yaml  | 245 +++++++
 drivers/clk/Makefile                          |   1 +
 drivers/clk/clk-reg.c                         | 638 ++++++++++++++++++
 3 files changed, 884 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
 create mode 100644 drivers/clk/clk-reg.c


base-commit: 7a934f4bd7d6f9da84c8812da3ba42ee10f5778e

On 14/04/2023 20:12, David Yang wrote:
> Add DT bindings documentation for reg-clock-controller, collection of
> basic clocks common to many platforms.
> 
> Signed-off-by: David Yang <mmyangfl@gmail.com>
> ---
>  .../bindings/clock/reg-clock-controller.yaml  | 245 ++++++++++++++++++
>  1 file changed, 245 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> 
> diff --git a/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> new file mode 100644
> index 000000000000..a6a7e0b05821
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> @@ -0,0 +1,245 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/reg-clock-controller.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Simple straight-forward register-based clocks
> +
> +maintainers:
> +  - David Yang <mmyangfl@gmail.com>
> +
> +description: |
> +  Basic clocks common to many platforms.
> +
> +  If your clocks don't fit into these catagories, simply create your clock

typo: categories

> +  controller. This driver normally work well with other controllers as long as
> +  they operate on different registers.
> +
> +  See linux/clk-provider.h for details about properties for each type of clock.

Describe here what is this device, what such simple clock controller
represents.

> +
> +properties:
> +  compatible:
> +    enum:
> +      - reg-clock-controller
> +
> +  ranges: true
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 1
> +
> +required:
> +  - compatible
> +  - ranges
> +  - '#address-cells'
> +  - '#size-cells'

required goes after patternProperties.

> +
> +patternProperties:
> +  ".*gate-clock@.*":

"gate-clock@" should be equivalent. However this should be just "clock".

> +    type: object
> +
> +    description: |

Do not need '|' unless you need to preserve formatting.

> +      Clock which can gate its output.
> +
> +    properties:
> +      compatible:
> +        const: gate-clock
> +
> +      reg:
> +        maxItems: 1
> +
> +      '#clock-cells':
> +        const: 0
> +
> +      clocks:
> +        maxItems: 1
> +        description:
> +          Parent clock.
> +
> +      clock-output-name:

names

Don't create your own properties.

> +        maxItems: 1
> +
> +      bit-index:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Bit index which controls the output.

I suggest to use same property as nvme, so bits.

> +
> +    required:
> +      - compatible
> +      - reg
> +      - '#clock-cells'
> +      - bit-index
> +
> +    additionalProperties: false
> +
> +  ".*divider-clock@.*":
> +    type: object
> +
> +    description: |
> +      Clock with an adjustable divider affecting its output frequency.
> +
> +    properties:
> +      compatible:
> +        const: divider-clock
> +
> +      reg:
> +        maxItems: 1
> +
> +      '#clock-cells':
> +        const: 0
> +
> +      clocks:
> +        description:
> +          Parent clocks.
> +
> +      clock-output-name:
> +        maxItems: 1
> +
> +      shift:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Shift to the divider bit field.
> +
> +      width:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Width of the divider bit field.
> +
> +      dividers:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          Array of value/divider pairs.

Then it looks like matrix.

> +
> +    required:
> +      - compatible
> +      - reg
> +      - '#clock-cells'
> +      - shift
> +      - width
> +
> +    additionalProperties: false
> +
> +  ".*mux-clock@.*":
> +    type: object
> +
> +    description: |
> +      Clock with multiple selectable parents.
> +
> +    properties:
> +      compatible:
> +        const: mux-clock
> +
> +      reg:
> +        maxItems: 1
> +
> +      '#clock-cells':
> +        const: 0
> +
> +      clocks:
> +        minItems: 1
> +        description:
> +          Parent clock.
> +
> +      clock-output-name:
> +        maxItems: 1
> +
> +      shift:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Shift to multiplexer bit field.
> +
> +      mask:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Mask of mutliplexer bit field.
> +
> +      table:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          Array of register values corresponding to the parent index.
> +
> +    required:
> +      - compatible
> +      - reg
> +      - '#clock-cells'
> +      - shift
> +      - mask
> +
> +    additionalProperties: false
> +
> +  ".*fractional-divider-clock@.*":
> +    type: object
> +
> +    description: |
> +      Clock with adjustable fractional divider affecting its output frequency.
> +
> +    properties:
> +      compatible:
> +        const: fractional_divider-clock
> +
> +      reg:
> +        maxItems: 1
> +
> +      '#clock-cells':
> +        const: 0
> +
> +      clocks:
> +        maxItems: 1
> +        description:
> +          Parent clock.
> +
> +      clock-output-name:
> +        maxItems: 1
> +
> +      numerator-shift:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Shift to the numerator bit field.
> +
> +      numerator-width:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Width of the numerator bit field.
> +
> +      denominator-shift:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Shift to the denominator bit field.
> +
> +      denominator-width:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Width of the denominator bit field.
> +
> +    required:
> +      - compatible
> +      - reg
> +      - '#clock-cells'
> +      - numerator-shift
> +      - numerator-width
> +      - denominator-shift
> +      - denominator-width
> +
> +    additionalProperties: false
> +
> +additionalProperties: true

No, come on. This must be false.

> +
> +examples:
> +  - |
> +    clks: reg-clk-ctrl@ffff0000 {

Names should be generic, so clock-controller

Drop the label.

> +      compatible = "reg-clock-controller";
> +      #address-cells = <1>;
> +      #size-cells = <1>;
> +      ranges = <0 0xffff0000 0x1000>;
> +
> +      my_clk: gate-clock@cc-3 {

Drop label.

That's a new unit address to me. Did I miss a change in DT spec?

> +        compatible = "gate-clock";
> +        #clock-cells = <0>;
> +        reg = <0xcc 4>;

reg is after compatible.

> +        bit-index = <3>;
> +        clock-output-name = "my-clk";

Plus, test your patches. This fails testing...

> +      };
> +    };

Best regards,
Krzysztof

Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> 于2023年4月15日周六 05:08写道：
>
> On 14/04/2023 20:12, David Yang wrote:
> > Add DT bindings documentation for reg-clock-controller, collection of
> > basic clocks common to many platforms.
> >
> > Signed-off-by: David Yang <mmyangfl@gmail.com>
> > ---
> >  .../bindings/clock/reg-clock-controller.yaml  | 245 ++++++++++++++++++
> >  1 file changed, 245 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> > new file mode 100644
> > index 000000000000..a6a7e0b05821
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> > @@ -0,0 +1,245 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/clock/reg-clock-controller.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Simple straight-forward register-based clocks
> > +
> > +maintainers:
> > +  - David Yang <mmyangfl@gmail.com>
> > +
> > +description: |
> > +  Basic clocks common to many platforms.
> > +
> > +  If your clocks don't fit into these catagories, simply create your clock
>
> typo: categories

Fixed in v2.

>
> > +  controller. This driver normally work well with other controllers as long as
> > +  they operate on different registers.
> > +
> > +  See linux/clk-provider.h for details about properties for each type of clock.
>
> Describe here what is this device, what such simple clock controller
> represents.

Description has been rewritten in v3, to describe the device.

>
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - reg-clock-controller
> > +
> > +  ranges: true
> > +
> > +  '#address-cells':
> > +    const: 1
> > +
> > +  '#size-cells':
> > +    const: 1
> > +
> > +required:
> > +  - compatible
> > +  - ranges
> > +  - '#address-cells'
> > +  - '#size-cells'
>
> required goes after patternProperties.

Fixed in v2.

>
> > +
> > +patternProperties:
> > +  ".*gate-clock@.*":
>
> "gate-clock@" should be equivalent. However this should be just "clock".

Fixed in v3.

>
> > +    type: object
> > +
> > +    description: |
>
> Do not need '|' unless you need to preserve formatting.

Fixed in v2.

>
> > +      Clock which can gate its output.
> > +
> > +    properties:
> > +      compatible:
> > +        const: gate-clock
> > +
> > +      reg:
> > +        maxItems: 1
> > +
> > +      '#clock-cells':
> > +        const: 0
> > +
> > +      clocks:
> > +        maxItems: 1
> > +        description:
> > +          Parent clock.
> > +
> > +      clock-output-name:
>
> names
>
> Don't create your own properties.

Fixed in v2, "clock-output-names".

>
> > +        maxItems: 1
> > +
> > +      bit-index:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Bit index which controls the output.
>
> I suggest to use same property as nvme, so bits.

Replaced with "bits" in v2.

>
> > +
> > +    required:
> > +      - compatible
> > +      - reg
> > +      - '#clock-cells'
> > +      - bit-index
> > +
> > +    additionalProperties: false
> > +
> > +  ".*divider-clock@.*":
> > +    type: object
> > +
> > +    description: |
> > +      Clock with an adjustable divider affecting its output frequency.
> > +
> > +    properties:
> > +      compatible:
> > +        const: divider-clock
> > +
> > +      reg:
> > +        maxItems: 1
> > +
> > +      '#clock-cells':
> > +        const: 0
> > +
> > +      clocks:
> > +        description:
> > +          Parent clocks.
> > +
> > +      clock-output-name:
> > +        maxItems: 1
> > +
> > +      shift:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Shift to the divider bit field.
> > +
> > +      width:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Width of the divider bit field.
> > +
> > +      dividers:
> > +        $ref: /schemas/types.yaml#/definitions/uint32-array
> > +        description:
> > +          Array of value/divider pairs.
>
> Then it looks like matrix.

This part of bindings has been (temporarily) removed from this series
since v2, to make it simpler.

>
> > +
> > +    required:
> > +      - compatible
> > +      - reg
> > +      - '#clock-cells'
> > +      - shift
> > +      - width
> > +
> > +    additionalProperties: false
> > +
> > +  ".*mux-clock@.*":
> > +    type: object
> > +
> > +    description: |
> > +      Clock with multiple selectable parents.
> > +
> > +    properties:
> > +      compatible:
> > +        const: mux-clock
> > +
> > +      reg:
> > +        maxItems: 1
> > +
> > +      '#clock-cells':
> > +        const: 0
> > +
> > +      clocks:
> > +        minItems: 1
> > +        description:
> > +          Parent clock.
> > +
> > +      clock-output-name:
> > +        maxItems: 1
> > +
> > +      shift:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Shift to multiplexer bit field.
> > +
> > +      mask:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Mask of mutliplexer bit field.
> > +
> > +      table:
> > +        $ref: /schemas/types.yaml#/definitions/uint32-array
> > +        description:
> > +          Array of register values corresponding to the parent index.
> > +
> > +    required:
> > +      - compatible
> > +      - reg
> > +      - '#clock-cells'
> > +      - shift
> > +      - mask
> > +
> > +    additionalProperties: false
> > +
> > +  ".*fractional-divider-clock@.*":
> > +    type: object
> > +
> > +    description: |
> > +      Clock with adjustable fractional divider affecting its output frequency.
> > +
> > +    properties:
> > +      compatible:
> > +        const: fractional_divider-clock
> > +
> > +      reg:
> > +        maxItems: 1
> > +
> > +      '#clock-cells':
> > +        const: 0
> > +
> > +      clocks:
> > +        maxItems: 1
> > +        description:
> > +          Parent clock.
> > +
> > +      clock-output-name:
> > +        maxItems: 1
> > +
> > +      numerator-shift:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Shift to the numerator bit field.
> > +
> > +      numerator-width:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Width of the numerator bit field.
> > +
> > +      denominator-shift:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Shift to the denominator bit field.
> > +
> > +      denominator-width:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          Width of the denominator bit field.
> > +
> > +    required:
> > +      - compatible
> > +      - reg
> > +      - '#clock-cells'
> > +      - numerator-shift
> > +      - numerator-width
> > +      - denominator-shift
> > +      - denominator-width
> > +
> > +    additionalProperties: false
> > +
> > +additionalProperties: true
>
> No, come on. This must be false.

Fixed with "false" in v2.

>
> > +
> > +examples:
> > +  - |
> > +    clks: reg-clk-ctrl@ffff0000 {
>
> Names should be generic, so clock-controller
>
> Drop the label.

Dropped in v2.

>
> > +      compatible = "reg-clock-controller";
> > +      #address-cells = <1>;
> > +      #size-cells = <1>;
> > +      ranges = <0 0xffff0000 0x1000>;
> > +
> > +      my_clk: gate-clock@cc-3 {
>
> Drop label.
>
> That's a new unit address to me. Did I miss a change in DT spec?

Dropped label in v2.

>
> > +        compatible = "gate-clock";
> > +        #clock-cells = <0>;
> > +        reg = <0xcc 4>;
>
> reg is after compatible.
>
> > +        bit-index = <3>;
> > +        clock-output-name = "my-clk";
>
> Plus, test your patches. This fails testing...

Fix name error in v3.

>
> > +      };
> > +    };
>
> Best regards,
> Krzysztof
>

Rob Herring <robh@kernel.org> 于2023年4月18日周二 04:49写道：
>
> On Sat, Apr 15, 2023 at 02:12:59AM +0800, David Yang wrote:
> > Add DT bindings documentation for reg-clock-controller, collection of
> > basic clocks common to many platforms.
> >
> > Signed-off-by: David Yang <mmyangfl@gmail.com>
> > ---
> >  .../bindings/clock/reg-clock-controller.yaml  | 245 ++++++++++++++++++
> >  1 file changed, 245 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> > new file mode 100644
> > index 000000000000..a6a7e0b05821
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> > @@ -0,0 +1,245 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/clock/reg-clock-controller.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Simple straight-forward register-based clocks
>
> 'simple' means extended one property at a time with little foresight. In
> the end, 'simple' bindings are never simple. s/simple/generic/ as well.
>
> When we first started the clock binding, we had exactly this. There's
> still bindings for at least some of it. It turned out to be a bad
> idea because it was difficult to get correct and complete. So this
> binding is exactly what we don't want.
>
> Rob

Thanks. So in the next version v2, clock-controller are made merely
container of clocks. The real jobs are done by sub clock nodes, so
that clocks, with or without hardware-specific clock types
"compatible", can be declared independently and individually as dt
nodes, instead of hardware clock "controllers" with quite arbitrary
clock identifiers listed under include/dt-bindings/clock/.

Quoting Yangfl (2023-04-17 14:39:23)
> Rob Herring <robh@kernel.org> 于2023年4月18日周二 04:49写道：
> >
> > On Sat, Apr 15, 2023 at 02:12:59AM +0800, David Yang wrote:
> > > Add DT bindings documentation for reg-clock-controller, collection of
> > > basic clocks common to many platforms.
> > >
> > > Signed-off-by: David Yang <mmyangfl@gmail.com>
> > > ---
> > >  .../bindings/clock/reg-clock-controller.yaml  | 245 ++++++++++++++++++
> > >  1 file changed, 245 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> > >
> > > diff --git a/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> > > new file mode 100644
> > > index 000000000000..a6a7e0b05821
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
> > > @@ -0,0 +1,245 @@
> > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/clock/reg-clock-controller.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: Simple straight-forward register-based clocks
> >
> > 'simple' means extended one property at a time with little foresight. In
> > the end, 'simple' bindings are never simple. s/simple/generic/ as well.
> >
> > When we first started the clock binding, we had exactly this. There's
> > still bindings for at least some of it. It turned out to be a bad
> > idea because it was difficult to get correct and complete. So this
> > binding is exactly what we don't want.
> >
> > Rob
> 
> Thanks. So in the next version v2, clock-controller are made merely
> container of clocks. The real jobs are done by sub clock nodes, so
> that clocks, with or without hardware-specific clock types
> "compatible", can be declared independently and individually as dt
> nodes, instead of hardware clock "controllers" with quite arbitrary
> clock identifiers listed under include/dt-bindings/clock/.

No. Write actual drivers and actual bindings for real devices.