Re: [PATCH RFC v2 2/2] dt-bindings: clock: ti: Convert divider.txt to json-schema

Rob Herring
2024-10-10T03:44:35Z

On Wed, Oct 09, 2024 at 10:56:19PM +0200, Andreas Kemnade wrote:
> Convert the OMAP divider clock device tree binding to json-schema.
> Specify the creator of the original binding as a maintainer.
>
> Signed-off-by: Andreas Kemnade <andreas@kemnade.info>
> ---
> .../devicetree/bindings/clock/ti/divider.txt | 115 ------------
> .../bindings/clock/ti/ti,divider-clock.yaml | 175 ++++++++++++++++++
> 2 files changed, 175 insertions(+), 115 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/clock/ti/divider.txt
> create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
>
> diff --git a/Documentation/devicetree/bindings/clock/ti/divider.txt b/Documentation/devicetree/bindings/clock/ti/divider.txt
> deleted file mode 100644
> index 4d7c76f0b356..000000000000
> --- a/Documentation/devicetree/bindings/clock/ti/divider.txt
> +++ /dev/null
> @@ -1,115 +0,0 @@
> -Binding for TI divider clock
> -
> -This binding uses the common clock binding[1]. It assumes a
> -register-mapped adjustable clock rate divider that does not gate and has
> -only one input clock or parent. By default the value programmed into
> -the register is one less than the actual divisor value. E.g:
> -
> -register value actual divisor value
> -0 1
> -1 2
> -2 3
> -
> -This assumption may be modified by the following optional properties:
> -
> -ti,index-starts-at-one - valid divisor values start at 1, not the default
> -of 0. E.g:
> -register value actual divisor value
> -1 1
> -2 2
> -3 3
> -
> -ti,index-power-of-two - valid divisor values are powers of two. E.g:
> -register value actual divisor value
> -0 1
> -1 2
> -2 4
> -
> -Additionally an array of valid dividers may be supplied like so:
> -
> - ti,dividers = <4>, <8>, <0>, <16>;
> -
> -Which will map the resulting values to a divisor table by their index:
> -register value actual divisor value
> -0 4
> -1 8
> -2 <invalid divisor, skipped>
> -3 16
> -
> -Any zero value in this array means the corresponding bit-value is invalid
> -and must not be used.
> -
> -The binding must also provide the register to control the divider and
> -unless the divider array is provided, min and max dividers. Optionally
> -the number of bits to shift that mask, if necessary. If the shift value
> -is missing it is the same as supplying a zero shift.
> -
> -This binding can also optionally provide support to the hardware autoidle
> -feature, see [2].
> -
> -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
> -[2] Documentation/devicetree/bindings/clock/ti/autoidle.txt
> -
> -Required properties:
> -- compatible : shall be "ti,divider-clock" or "ti,composite-divider-clock".
> -- #clock-cells : from common clock binding; shall be set to 0.
> -- clocks : link to phandle of parent clock
> -- reg : offset for register controlling adjustable divider
> -
> -Optional properties:
> -- clock-output-names : from common clock binding.
> -- ti,dividers : array of integers defining divisors
> -- ti,bit-shift : number of bits to shift the divider value, defaults to 0
> -- ti,min-div : min divisor for dividing the input clock rate, only
> - needed if the first divisor is offset from the default value (1)
> -- ti,max-div : max divisor for dividing the input clock rate, only needed
> - if ti,dividers is not defined.
> -- ti,index-starts-at-one : valid divisor programming starts at 1, not zero,
> - only valid if ti,dividers is not defined.
> -- ti,index-power-of-two : valid divisor programming must be a power of two,
> - only valid if ti,dividers is not defined.
> -- ti,autoidle-shift : bit shift of the autoidle enable bit for the clock,
> - see [2]
> -- ti,invert-autoidle-bit : autoidle is enabled by setting the bit to 0,
> - see [2]
> -- ti,set-rate-parent : clk_set_rate is propagated to parent
> -- ti,latch-bit : latch the divider value to HW, only needed if the register
> - access requires this. As an example dra76x DPLL_GMAC H14 divider implements
> - such behavior.
> -
> -Examples:
> -dpll_usb_m2_ck: dpll_usb_m2_ck@4a008190 {
> - #clock-cells = <0>;
> - compatible = "ti,divider-clock";
> - clocks = <&dpll_usb_ck>;
> - ti,max-div = <127>;
> - reg = <0x190>;
> - ti,index-starts-at-one;
> -};
> -
> -aess_fclk: aess_fclk@4a004528 {
> - #clock-cells = <0>;
> - compatible = "ti,divider-clock";
> - clocks = <&abe_clk>;
> - ti,bit-shift = <24>;
> - reg = <0x528>;
> - ti,max-div = <2>;
> -};
> -
> -dpll_core_m3x2_div_ck: dpll_core_m3x2_div_ck {
> - #clock-cells = <0>;
> - compatible = "ti,composite-divider-clock";
> - clocks = <&dpll_core_x2_ck>;
> - ti,max-div = <31>;
> - reg = <0x0134>;
> - ti,index-starts-at-one;
> -};
> -
> -ssi_ssr_div_fck_3430es2: ssi_ssr_div_fck_3430es2 {
> - #clock-cells = <0>;
> - compatible = "ti,composite-divider-clock";
> - clocks = <&corex2_fck>;
> - ti,bit-shift = <8>;
> - reg = <0x0a40>;
> - ti,dividers = <0>, <1>, <2>, <3>, <4>, <0>, <6>, <0>, <8>;
> -};
> diff --git a/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
> new file mode 100644
> index 000000000000..31fe876fb40b
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
> @@ -0,0 +1,175 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/ti/ti,divider-clock.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments divider clock
> +
> +maintainers:
> + - Tero Kristo <kristo@kernel.org>
> +
> +description: |
> + This clock It assumes a register-mapped adjustable clock rate divider
> + that does not gate and has only one input clock or parent. By default the
> + value programmed into the register is one less than the actual divisor value.
> + E.g:
> +
> + register value actual divisor value
> + 0 1
> + 1 2
> + 2 3
> +
> + This assumption may be modified by the following optional properties:
> +
> + ti,index-starts-at-one - valid divisor values start at 1, not the default
> + of 0. E.g:
> + register value actual divisor value
> + 1 1
> + 2 2
> + 3 3
> +
> + ti,index-power-of-two - valid divisor values are powers of two. E.g:
> + register value actual divisor value
> + 0 1
> + 1 2
> + 2 4
> +
> + Additionally an array of valid dividers may be supplied like so:
> +
> + ti,dividers = <4>, <8>, <0>, <16>;
> +
> + Which will map the resulting values to a divisor table by their index:
> + register value actual divisor value
> + 0 4
> + 1 8
> + 2 <invalid divisor, skipped>
> + 3 16
> +
> + Any zero value in this array means the corresponding bit-value is invalid
> + and must not be used.
> +
> + The binding must also provide the register to control the divider and
> + unless the divider array is provided, min and max dividers. Optionally
> + the number of bits to shift that mask, if necessary. If the shift value
> + is missing it is the same as supplying a zero shift.
> +
> + This binding can also optionally provide support to the hardware autoidle
> + feature, see [1].
> +
> + [1] Documentation/devicetree/bindings/clock/ti/autoidle.txt
> +
> +properties:
> + compatible:
> + enum:
> + - ti,divider-clock
> + - ti,composite-divider-clock
> +
> + "#clock-cells":
> + const: 0
> +
> + clocks:
> + maxItems: 1
> +
> + clock-output-names:
> + maxItems: 1
> +
> + reg:
> + maxItems: 1
> +
> + ti,dividers: true
> +
> + ti,bit-shift:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + number of bits to shift the divider value

maximum: 31 ?
default: 0

> +
> + ti,min-div:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + min divisor for dividing the input clock rate, only
> + needed if the first divisor is offset from the default value (1)

minimum: 1
maximum: ?
default: 1

> +
> + ti,max-div:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + max divisor for dividing the input clock rate, only needed
> + if ti,dividers is not defined.
> +
> + ti,index-starts-at-one:
> + type: boolean
> + description:
> + valid divisor programming starts at 1, not zero,
> + only valid if ti,dividers is not defined
> +
> + ti,index-power-of-two:
> + type: boolean
> + description:
> + valid divisor programming must be a power of two,
> + only valid if ti,dividers is not defined.

This can be expressed as:

dependentSchemas:
ti,dividers:
properties:
ti,min-div: false
ti,max-div: false
ti,index-power-of-two: false
ti,index-starts-at-one: false

> +
> + ti,autoidle-shift:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + bit shift of the autoidle enable bit for the clock,
> + see [1].

maximum: 31
default: 0

> +
> + ti,invert-autoidle-bit:
> + type: boolean
> + description:
> + autoidle is enabled by setting the bit to 0,
> + see [1]
> +
> + ti,set-rate-parent:
> + type: boolean
> + description:
> + clk_set_rate is propagated to parent |
> +
> + ti,latch-bit:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + latch the divider value to HW, only needed if the register
> + compatible access requires this. As an example dra76x DPLL_GMAC
> + H14 divider implements such behavior.
> +
> +required:
> + - compatible
> + - "#clock-cells"
> + - clocks
> + - reg
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + bus {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + dpll_usb_m2_ck: clock-controller@190 {

Drop unused labels.

> + #clock-cells = <0>;
> + compatible = "ti,divider-clock";
> + clocks = <&dpll_usb_ck>;
> + ti,max-div = <127>;
> + reg = <0x190>;
> + ti,index-starts-at-one;
> + };
> +
> + aess_fclk: clock-controller@528 {
> + #clock-cells = <0>;
> + compatible = "ti,divider-clock";
> + clocks = <&abe_clk>;
> + ti,bit-shift = <24>;
> + reg = <0x528>;
> + ti,max-div = <2>;
> + };
> +
> + ssi_ssr_div_fck_3430es2: clock-controller@a40 {
> + #clock-cells = <0>;
> + compatible = "ti,composite-divider-clock";
> + clocks = <&corex2_fck>;
> + ti,bit-shift = <8>;
> + reg = <0x0a40>;
> + ti,dividers = <0>, <1>, <2>, <3>, <4>, <0>, <6>, <0>, <8>;
> + };
> + };
> --
> 2.39.5
>