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

[Rob Herring <robh@kernel.org>]

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
>