[PATCH] dt-bindings: clock: ti: Convert APLL clock to DT schema

[PATCH] dt-bindings: clock: ti: Convert APLL clock to DT schema

[Eduard Bostina]

Convert the Texas Instruments APLL clock bindings to DT schema.

Signed-off-by: Eduard Bostina <egbostina@gmail.com>
---
 .../devicetree/bindings/clock/ti/apll.txt     | 43 ---------
 .../bindings/clock/ti/ti,apll-clock.yaml      | 89 +++++++++++++++++++
 2 files changed, 89 insertions(+), 43 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/clock/ti/apll.txt
 create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,apll-clock.yaml

diff --git a/Documentation/devicetree/bindings/clock/ti/apll.txt b/Documentation/devicetree/bindings/clock/ti/apll.txt
deleted file mode 100644
index bbd505c11..000000000
--- a/Documentation/devicetree/bindings/clock/ti/apll.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-Binding for Texas Instruments APLL clock.
-
-This binding uses the common clock binding[1].  It assumes a
-register-mapped APLL with usually two selectable input clocks
-(reference clock and bypass clock), with analog phase locked
-loop logic for multiplying the input clock to a desired output
-clock. This clock also typically supports different operation
-modes (locked, low power stop etc.) APLL mostly behaves like
-a subtype of a DPLL [2], although a simplified one at that.
-
-[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
-[2] Documentation/devicetree/bindings/clock/ti/dpll.txt
-
-Required properties:
-- compatible : shall be "ti,dra7-apll-clock" or "ti,omap2-apll-clock"
-- #clock-cells : from common clock binding; shall be set to 0.
-- clocks : link phandles of parent clocks (clk-ref and clk-bypass)
-- reg : address and length of the register set for controlling the APLL.
-  It contains the information of registers in the following order:
-	"control" - contains the control register offset
-	"idlest" - contains the idlest register offset
-	"autoidle" - contains the autoidle register offset (OMAP2 only)
-- ti,clock-frequency : static clock frequency for the clock (OMAP2 only)
-- ti,idlest-shift : bit-shift for the idlest field (OMAP2 only)
-- ti,bit-shift : bit-shift for enable and autoidle fields (OMAP2 only)
-
-Examples:
-	apll_pcie_ck: apll_pcie_ck {
-		#clock-cells = <0>;
-		clocks = <&apll_pcie_in_clk_mux>, <&dpll_pcie_ref_ck>;
-		reg = <0x021c>, <0x0220>;
-		compatible = "ti,dra7-apll-clock";
-	};
-
-	apll96_ck: apll96_ck {
-		#clock-cells = <0>;
-		compatible = "ti,omap2-apll-clock";
-		clocks = <&sys_ck>;
-		ti,bit-shift = <2>;
-		ti,idlest-shift = <8>;
-		ti,clock-frequency = <96000000>;
-		reg = <0x0500>, <0x0530>, <0x0520>;
-	};
diff --git a/Documentation/devicetree/bindings/clock/ti/ti,apll-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,apll-clock.yaml
new file mode 100644
index 000000000..e14a76254
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/ti/ti,apll-clock.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/ti/ti,apll-clock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments APLL clock
+
+maintainers:
+  - Eduard Bostina <egbostina@gmail.com>
+
+allOf:
+  - $ref: /schemas/clock/clock.yaml#
+
+description:
+  This binding assumes a register-mapped APLL with usually two selectable
+  input clocks (reference clock and bypass clock), with analog phase locked
+  loop logic for multiplying the input clock to a desired output clock.
+  This clock also typically supports different operation modes (locked, low
+  power stop etc.) APLL mostly behaves like a subtype of a DPLL, although
+  a simplified one at that.
+
+properties:
+  compatible:
+    enum:
+      - ti,dra7-apll-clock
+      - ti,omap2-apll-clock
+
+  "#clock-cells":
+    const: 0
+
+  clocks:
+    minItems: 1
+    maxItems: 2
+    description: Link phandles of parent clocks (clk-ref and clk-bypass)
+
+  reg:
+    minItems: 2
+    maxItems: 3
+    description: |
+      Address and length of the register set for controlling the APLL.
+      It contains the information of registers in the following order:
+      "control" - contains the control register offset
+      "idlest" - contains the idlest register offset
+      "autoidle" - contains the autoidle register offset (OMAP2 only)
+
+  ti,clock-frequency:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: static clock frequency for the clock (OMAP2 only)
+
+  ti,idlest-shift:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: bit-shift for the idlest field (OMAP2 only)
+
+  ti,bit-shift:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: bit-shift for enable and autoidle fields (OMAP2 only)
+
+required:
+  - compatible
+  - "#clock-cells"
+  - clocks
+  - reg
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    bus {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        clock@21c {
+            #clock-cells = <0>;
+            compatible = "ti,dra7-apll-clock";
+            clocks = <&apll_pcie_in_clk_mux>, <&dpll_pcie_ref_ck>;
+            reg = <0x021c>, <0x0220>;
+        };
+
+        clock@500 {
+            #clock-cells = <0>;
+            compatible = "ti,omap2-apll-clock";
+            clocks = <&sys_ck>;
+            ti,bit-shift = <2>;
+            ti,idlest-shift = <8>;
+            ti,clock-frequency = <96000000>;
+            reg = <0x0500>, <0x0530>, <0x0520>;
+        };
+    };
-- 
2.54.0

Re: [PATCH] dt-bindings: clock: ti: Convert APLL clock to DT schema

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] The YAML conversion fails to conditionally enforce variant-specific requirements for OMAP2 vs DRA7 hardware variants.
--

--- Patch [1]: [PATCH] dt-bindings: clock: ti: Convert APLL clock to DT schema ---
commit ae216da14737ed29efd003eb0159b573f9308b0f
Author: Eduard Bostina <egbostina@gmail.com>

dt-bindings: clock: ti: Convert APLL clock to DT schema

This commit converts the Texas Instruments APLL clock bindings from a plain
text file to a DT schema.

> diff --git a/Documentation/devicetree/bindings/clock/ti/ti,apll-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,apll-clock.yaml
> new file mode 100644
> index 0000000000000..e14a76254ce77
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/ti/ti,apll-clock.yaml
[ ... ]
> +  clocks:
> +    minItems: 1
> +    maxItems: 2
> +    description: Link phandles of parent clocks (clk-ref and clk-bypass)
> +
> +  reg:
> +    minItems: 2
> +    maxItems: 3
[ ... ]
> +  ti,clock-frequency:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: static clock frequency for the clock (OMAP2 only)
> +
> +  ti,idlest-shift:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: bit-shift for the idlest field (OMAP2 only)
> +
> +  ti,bit-shift:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: bit-shift for enable and autoidle fields (OMAP2 only)
> +
> +required:
> +  - compatible
> +  - "#clock-cells"
> +  - clocks
> +  - reg
> +
> +unevaluatedProperties: false

[Severity: Medium]
Does this YAML conversion fail to enforce the OMAP2-specific required
properties that were described in the original text binding?

The original text binding indicated that ti,clock-frequency, ti,idlest-shift,
and ti,bit-shift were required for the OMAP2 hardware variant. By dropping
these properties from the required list entirely and leaving clocks and reg
with loose bounds, device trees with incomplete OMAP2 configurations will
now silently pass schema validation.

Should this schema include an allOf conditional block matching the
ti,omap2-apll-clock compatible string to properly enforce these properties
and the specific minItems/maxItems constraints for each generation?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260730083019.29998-1-egbostina@gmail.com?part=1