[PATCH RFC v2 0/2] dt-bindings: clock: ti: convert to yaml

[PATCH RFC v2 0/2] dt-bindings: clock: ti: convert to yaml

[Andreas Kemnade]

Convert some clock schemas to yaml. These are one of the most used non-yaml
compatibles.

All can appear under a ti,clksel or without a ti,clksel

Reason for being RFC. In the comments for the first version, it was said that
everything which can be below a ti,clksel should be converted at the same
time. But I want to know whether I am on the right track.
I plan to convert the clock things from time to time.
So enforcing certain compatibles below ti,clksel i not there yet.

Open question: I set license to GPL-2 only because the .txt bindings the
yaml binding was derived from were
GPL-2. I personally have no problem with dual-licensing the binding.
No idea about the legal side wether that is possible or who must agree.

Changes in v2:
- added conversion of divider
- require reg now, makes sense after
  https://lore.kernel.org/linux-omap/20240213105730.5287-1-tony@atomide.com/
- clean up of examples
- improvement of documentation

v1 is at https://lore.kernel.org/linux-omap/20231127202359.145778-1-andreas@kemnade.info/

Andreas Kemnade (2):
  dt-bindings: clock: ti: Convert interface.txt to json-schema
  dt-bindings: clock: ti: Convert divider.txt to json-schema

 .../devicetree/bindings/clock/ti/divider.txt  | 115 ------------
 .../bindings/clock/ti/interface.txt           |  55 ------
 .../bindings/clock/ti/ti,divider-clock.yaml   | 175 ++++++++++++++++++
 .../bindings/clock/ti/ti,interface-clock.yaml |  70 +++++++
 4 files changed, 245 insertions(+), 170 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/clock/ti/divider.txt
 delete mode 100644 Documentation/devicetree/bindings/clock/ti/interface.txt
 create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
 create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml

-- 
2.39.5

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

[Andreas Kemnade]

Convert the OMAP interface 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>
---
 .../bindings/clock/ti/interface.txt           | 55 ---------------
 .../bindings/clock/ti/ti,interface-clock.yaml | 70 +++++++++++++++++++
 2 files changed, 70 insertions(+), 55 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/clock/ti/interface.txt
 create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml

diff --git a/Documentation/devicetree/bindings/clock/ti/interface.txt b/Documentation/devicetree/bindings/clock/ti/interface.txt
deleted file mode 100644
index 85fb1f2d2d28..000000000000
--- a/Documentation/devicetree/bindings/clock/ti/interface.txt
+++ /dev/null
@@ -1,55 +0,0 @@
-Binding for Texas Instruments interface clock.
-
-This binding uses the common clock binding[1]. This clock is
-quite much similar to the basic gate-clock [2], however,
-it supports a number of additional features, including
-companion clock finding (match corresponding functional gate
-clock) and hardware autoidle enable / disable.
-
-[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
-[2] Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
-
-Required properties:
-- compatible : shall be one of:
-  "ti,omap3-interface-clock" - basic OMAP3 interface clock
-  "ti,omap3-no-wait-interface-clock" - interface clock which has no hardware
-				       capability for waiting clock to be ready
-  "ti,omap3-hsotgusb-interface-clock" - interface clock with USB specific HW
-					handling
-  "ti,omap3-dss-interface-clock" - interface clock with DSS specific HW handling
-  "ti,omap3-ssi-interface-clock" - interface clock with SSI specific HW handling
-  "ti,am35xx-interface-clock" - interface clock with AM35xx specific HW handling
-  "ti,omap2430-interface-clock" - interface clock with OMAP2430 specific HW
-				  handling
-- #clock-cells : from common clock binding; shall be set to 0
-- clocks : link to phandle of parent clock
-- reg : base address for the control register
-
-Optional properties:
-- clock-output-names : from common clock binding.
-- ti,bit-shift : bit shift for the bit enabling/disabling the clock (default 0)
-
-Examples:
-	aes1_ick: aes1_ick@48004a14 {
-		#clock-cells = <0>;
-		compatible = "ti,omap3-interface-clock";
-		clocks = <&security_l4_ick2>;
-		reg = <0x48004a14 0x4>;
-		ti,bit-shift = <3>;
-	};
-
-	cam_ick: cam_ick@48004f10 {
-		#clock-cells = <0>;
-		compatible = "ti,omap3-no-wait-interface-clock";
-		clocks = <&l4_ick>;
-		reg = <0x48004f10 0x4>;
-		ti,bit-shift = <0>;
-	};
-
-	ssi_ick_3430es2: ssi_ick_3430es2@48004a10 {
-		#clock-cells = <0>;
-		compatible = "ti,omap3-ssi-interface-clock";
-		clocks = <&ssi_l4_ick>;
-		reg = <0x48004a10 0x4>;
-		ti,bit-shift = <0>;
-	};
diff --git a/Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml
new file mode 100644
index 000000000000..0e9542ed381f
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/ti/ti,interface-clock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments interface clock.
+
+maintainers:
+  - Tero Kristo <kristo@kernel.org>
+
+description: |
+  This clock is quite much similar to the basic gate-clock[1], however,
+  it supports a number of additional features, including
+  companion clock finding (match corresponding functional gate
+  clock) and hardware autoidle enable / disable.
+
+  [1] Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
+
+properties:
+  compatible:
+    enum:
+      - ti,omap3-interface-clock           # basic OMAP3 interface clock
+      - ti,omap3-no-wait-interface-clock   # interface clock which has no hardware
+                                           # capability for waiting clock to be ready
+      - ti,omap3-hsotgusb-interface-clock  # interface clock with USB specific HW handling
+      - ti,omap3-dss-interface-clock       # interface clock with DSS specific HW handling
+      - ti,omap3-ssi-interface-clock       # interface clock with SSI specific HW handling
+      - ti,am35xx-interface-clock          # interface clock with AM35xx specific HW handling
+      - ti,omap2430-interface-clock        # interface clock with OMAP2430 specific HW handling
+
+  "#clock-cells":
+    const: 0
+
+  clocks:
+    maxItems: 1
+
+  clock-output-names:
+    maxItems: 1
+
+  reg:
+    maxItems: 1
+
+  ti,bit-shift:
+    description:
+      bit shift for the bit enabling/disabling the clock
+    $ref: /schemas/types.yaml#/definitions/uint32
+    default: 0
+
+required:
+  - compatible
+  - clocks
+  - '#clock-cells'
+  - reg
+
+additionalProperties: false
+
+examples:
+  - |
+    bus {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      aes1_ick: clock-controller@3 {
+        #clock-cells = <0>;
+        compatible = "ti,omap3-interface-clock";
+        clocks = <&security_l4_ick2>;
+        reg = <3>;
+      };
+    };
-- 
2.39.5

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

[Rob Herring]

On Wed, Oct 09, 2024 at 10:56:18PM +0200, Andreas Kemnade wrote:
> Convert the OMAP interface clock device tree binding to json-schema.
> Specify the creator of the original binding as a maintainer.

Nice to see this! These are the top occurring undocumented (by schema) 
warnings for arm32.

> 
> Signed-off-by: Andreas Kemnade <andreas@kemnade.info>
> ---
>  .../bindings/clock/ti/interface.txt           | 55 ---------------
>  .../bindings/clock/ti/ti,interface-clock.yaml | 70 +++++++++++++++++++
>  2 files changed, 70 insertions(+), 55 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/clock/ti/interface.txt
>  create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml
> 
> diff --git a/Documentation/devicetree/bindings/clock/ti/interface.txt b/Documentation/devicetree/bindings/clock/ti/interface.txt
> deleted file mode 100644
> index 85fb1f2d2d28..000000000000
> --- a/Documentation/devicetree/bindings/clock/ti/interface.txt
> +++ /dev/null
> @@ -1,55 +0,0 @@
> -Binding for Texas Instruments interface clock.
> -
> -This binding uses the common clock binding[1]. This clock is
> -quite much similar to the basic gate-clock [2], however,
> -it supports a number of additional features, including
> -companion clock finding (match corresponding functional gate
> -clock) and hardware autoidle enable / disable.
> -
> -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
> -[2] Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
> -
> -Required properties:
> -- compatible : shall be one of:
> -  "ti,omap3-interface-clock" - basic OMAP3 interface clock
> -  "ti,omap3-no-wait-interface-clock" - interface clock which has no hardware
> -				       capability for waiting clock to be ready
> -  "ti,omap3-hsotgusb-interface-clock" - interface clock with USB specific HW
> -					handling
> -  "ti,omap3-dss-interface-clock" - interface clock with DSS specific HW handling
> -  "ti,omap3-ssi-interface-clock" - interface clock with SSI specific HW handling
> -  "ti,am35xx-interface-clock" - interface clock with AM35xx specific HW handling
> -  "ti,omap2430-interface-clock" - interface clock with OMAP2430 specific HW
> -				  handling
> -- #clock-cells : from common clock binding; shall be set to 0
> -- clocks : link to phandle of parent clock
> -- reg : base address for the control register
> -
> -Optional properties:
> -- clock-output-names : from common clock binding.
> -- ti,bit-shift : bit shift for the bit enabling/disabling the clock (default 0)
> -
> -Examples:
> -	aes1_ick: aes1_ick@48004a14 {
> -		#clock-cells = <0>;
> -		compatible = "ti,omap3-interface-clock";
> -		clocks = <&security_l4_ick2>;
> -		reg = <0x48004a14 0x4>;
> -		ti,bit-shift = <3>;
> -	};
> -
> -	cam_ick: cam_ick@48004f10 {
> -		#clock-cells = <0>;
> -		compatible = "ti,omap3-no-wait-interface-clock";
> -		clocks = <&l4_ick>;
> -		reg = <0x48004f10 0x4>;
> -		ti,bit-shift = <0>;
> -	};
> -
> -	ssi_ick_3430es2: ssi_ick_3430es2@48004a10 {
> -		#clock-cells = <0>;
> -		compatible = "ti,omap3-ssi-interface-clock";
> -		clocks = <&ssi_l4_ick>;
> -		reg = <0x48004a10 0x4>;
> -		ti,bit-shift = <0>;
> -	};
> diff --git a/Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml
> new file mode 100644
> index 000000000000..0e9542ed381f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml
> @@ -0,0 +1,70 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/ti/ti,interface-clock.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments interface clock.
> +
> +maintainers:
> +  - Tero Kristo <kristo@kernel.org>
> +
> +description: |
> +  This clock is quite much similar to the basic gate-clock[1], however,
> +  it supports a number of additional features, including
> +  companion clock finding (match corresponding functional gate
> +  clock) and hardware autoidle enable / disable.
> +
> +  [1] Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
> +
> +properties:
> +  compatible:
> +    enum:
> +      - ti,omap3-interface-clock           # basic OMAP3 interface clock
> +      - ti,omap3-no-wait-interface-clock   # interface clock which has no hardware
> +                                           # capability for waiting clock to be ready
> +      - ti,omap3-hsotgusb-interface-clock  # interface clock with USB specific HW handling
> +      - ti,omap3-dss-interface-clock       # interface clock with DSS specific HW handling
> +      - ti,omap3-ssi-interface-clock       # interface clock with SSI specific HW handling
> +      - ti,am35xx-interface-clock          # interface clock with AM35xx specific HW handling
> +      - ti,omap2430-interface-clock        # interface clock with OMAP2430 specific HW handling
> +
> +  "#clock-cells":
> +    const: 0
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-output-names:
> +    maxItems: 1
> +
> +  reg:
> +    maxItems: 1
> +
> +  ti,bit-shift:
> +    description:
> +      bit shift for the bit enabling/disabling the clock
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    default: 0

maximum: 31 ?

Otherwise,

Reviewed-by: Rob Herring (Arm) <robh@kernel.org>

> +
> +required:
> +  - compatible
> +  - clocks
> +  - '#clock-cells'
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    bus {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      aes1_ick: clock-controller@3 {
> +        #clock-cells = <0>;
> +        compatible = "ti,omap3-interface-clock";
> +        clocks = <&security_l4_ick2>;
> +        reg = <3>;
> +      };
> +    };
> -- 
> 2.39.5
> 

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

[Andreas Kemnade]

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
+
+  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)
+
+  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.
+
+  ti,autoidle-shift:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      bit shift of the autoidle enable bit for the clock,
+      see [1].
+
+  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 {
+        #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

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

[Rob Herring (Arm)]

On Wed, 09 Oct 2024 22:56:19 +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
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml: ti,dividers: missing type definition

doc reference errors (make refcheckdocs):
Warning: Documentation/devicetree/bindings/clock/ti/composite.txt references a file that doesn't exist: Documentation/devicetree/bindings/clock/ti/divider.txt
Documentation/devicetree/bindings/clock/ti/composite.txt: Documentation/devicetree/bindings/clock/ti/divider.txt

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20241009205619.16250-3-andreas@kemnade.info

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.

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

[Rob Herring]

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
> 

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

[Andreas Kemnade]

Am Wed, 9 Oct 2024 22:44:34 -0500
schrieb Rob Herring <robh@kernel.org>:

> > +
> > +  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

maximum is complex: there is one place in the code where this runs
through a u8 (_get_val). although it it read from the devicetree as a
uint32.
So, if we do not care about a specific implementation, then
in the power-of-two case, the theoretical maximum would be 1 << (1 <<
(32-bitshift) - 1) clipped to UINT32_MAX due to type constraints. And
also the maximum lifetime of electronics and elementary elements and
pieces, probably even with the proposed decay time of protons.
In the index-starts-at-case, we would have (1 << (32-bitshift)) - 1.
otherwise 1 << (32-bitshift).

I would propose not to define a maximum here.

Regards,
Andreas