[PATCH] dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema

[PATCH] dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema

[Bhargav Joshi]

Convert the Texas Instruments Keystone Device State Control binding from
legacy text format to DT schema.

During the conversion, the following updates were made:
- Added "simple-mfd" to the allowed compatible strings.
- Enforced child bus properties (#address-cells, #size-cells, and ranges)
  to be required only when the "simple-mfd" compatible is present.
- Added patternProperties definitions to validate standard child nodes
- Updated the examples to demonstrate simple-mfd parent usage and updated
  node names to conform with standard Devicetree specifications.

Signed-off-by: Bhargav Joshi <j.bhargav.u@gmail.com>
---
Note:
Running dt_binding_check on patch will yield a warning for
'ti,keystone-reset' in the example block. The YAML conversion patch
for that child node is already in progress here:
https://lore.kernel.org/linux-devicetree/20260813-ti-keystone-reset-v1-1-189389503324@gmail.com/
---
 .../bindings/mfd/ti,keystone-devctrl.yaml          | 105 +++++++++++++++++++++
 .../bindings/mfd/ti-keystone-devctrl.txt           |  19 ----
 2 files changed, 105 insertions(+), 19 deletions(-)

diff --git a/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml b/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml
new file mode 100644
index 000000000000..33a72c290fb1
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/ti,keystone-devctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments Keystone Device State Control
+
+maintainers:
+  - Ivan Khoronzhuk <ivan.khoronzhuk@ti.com>
+
+description:
+  The Keystone II devices have a set of registers that are used to control the
+  status of its peripherals. This node is intended to allow access to this
+  functionality.
+
+properties:
+  compatible:
+    minItems: 2
+    items:
+      - const: ti,keystone-devctrl
+      - const: syscon
+      - const: simple-mfd
+
+  reg:
+    maxItems: 1
+
+  "#address-cells":
+    const: 1
+
+  "#size-cells":
+    const: 1
+
+  ranges: true
+
+patternProperties:
+  "^keystone_dsp_gpio@[0-9a-f]+$":
+    type: object
+    description: Keystone DSP GPIO controller
+
+  "^keystone_irq@[0-9a-f]+$":
+    type: object
+    description: Keystone DSP to ARM interrupt controller
+
+  "^reset-controller@[0-9a-f]+$":
+    type: object
+    description: Keystone reset controller
+
+required:
+  - compatible
+  - reg
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: simple-mfd
+    then:
+      required:
+        - "#address-cells"
+        - "#size-cells"
+        - ranges
+    else:
+      properties:
+        "#address-cells": false
+        "#size-cells": false
+        ranges: false
+
+additionalProperties: false
+
+examples:
+  - |
+    device-state-control@2620000 {
+        compatible = "ti,keystone-devctrl", "syscon";
+        reg = <0x02620000 0x1000>;
+    };
+
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    device-state-control@2620000 {
+        compatible = "ti,keystone-devctrl", "syscon", "simple-mfd";
+        reg = <0x02620000 0x1000>;
+        #address-cells = <1>;
+        #size-cells = <1>;
+        ranges = <0x0 0x02620000 0x1000>;
+
+        keystone_irq@2a0 {
+            compatible = "ti,keystone-irq";
+            reg = <0x2a0 0x4>;
+            interrupts = <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>;
+            interrupt-controller;
+            #interrupt-cells = <1>;
+            ti,syscon-dev = <&devctrl 0x2a0>;
+        };
+
+        reset-controller@328 {
+            compatible = "ti,keystone-reset";
+            reg = <0x328 0x10>;
+            ti,syscon-pll = <&pllctrl 0xe4>;
+            ti,syscon-dev = <&devctrl 0x328>;
+            ti,wdt-list = <0>;
+        };
+    };
diff --git a/Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt b/Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt
deleted file mode 100644
index 71a1f5963936..000000000000
--- a/Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-* Device tree bindings for Texas Instruments keystone device state control
-
-The Keystone II devices have a set of registers that are used to control
-the status of its peripherals. This node is intended to allow access to
-this functionality.
-
-Required properties:
-
-- compatible:		"ti,keystone-devctrl", "syscon"
-
-- reg:			contains offset/length value for device state control
-			registers space.
-
-Example:
-
-devctrl: device-state-control@02620000 {
-	compatible = "ti,keystone-devctrl", "syscon";
-	reg = <0x02620000 0x1000>;
-};

---
base-commit: 3d6d817622b0a9721e3cc404df3469171582be13
change-id: 20260813-ti-keystone-devctrl-6e49212fe35d

Best regards,
-- 
Bhargav

Re: [PATCH] dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Medium] The schema enforces non-compliant, legacy device tree node names (containing underscores) for child nodes via `patternProperties`, blocking the use of standard generic names and contradicting the commit message.
- [Low] The YAML example references undefined phandles (`&devctrl` and `&pllctrl`), which will cause a fatal `dtc` compilation error during `make dt_binding_check`.
--

--- Patch [1]: [PATCH] dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema ---
commit f59b6bface010fc243ef7f899dbb8dddf737e2c5
Author: Bhargav Joshi <j.bhargav.u@gmail.com>

dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema
    
Converts the Texas Instruments Keystone Device State Control binding from
legacy text format to DT schema. Adds "simple-mfd" support, enforces child
bus properties, and adds validations for standard child nodes.

> diff --git a/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml b/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml
> new file mode 100644
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml
[ ... ]
> +patternProperties:
> +  "^keystone_dsp_gpio@[0-9a-f]+$":
> +    type: object
> +    description: Keystone DSP GPIO controller
> +
> +  "^keystone_irq@[0-9a-f]+$":
> +    type: object
> +    description: Keystone DSP to ARM interrupt controller

[Severity: Medium]
The commit message mentions updating node names to conform with standard
Devicetree specifications. However, these patternProperties enforce names
with underscores like "keystone_dsp_gpio" and "keystone_irq". 

Does this block the use of standard generic names (like "gpio" or
"interrupt-controller")? Because additionalProperties is false, using generic
names in a DTS file would cause validation errors. Could these patterns be
updated to match generic names instead?

[ ... ]
> +examples:
[ ... ]
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    device-state-control@2620000 {
> +        compatible = "ti,keystone-devctrl", "syscon", "simple-mfd";
> +        reg = <0x02620000 0x1000>;
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        ranges = <0x0 0x02620000 0x1000>;
> +
> +        keystone_irq@2a0 {
> +            compatible = "ti,keystone-irq";
> +            reg = <0x2a0 0x4>;
> +            interrupts = <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>;
> +            interrupt-controller;
> +            #interrupt-cells = <1>;
> +            ti,syscon-dev = <&devctrl 0x2a0>;
> +        };
> +
> +        reset-controller@328 {
> +            compatible = "ti,keystone-reset";
> +            reg = <0x328 0x10>;
> +            ti,syscon-pll = <&pllctrl 0xe4>;
> +            ti,syscon-dev = <&devctrl 0x328>;
> +            ti,wdt-list = <0>;
> +        };
> +    };

[Severity: Low]
The example uses phandles for &devctrl and &pllctrl, but it appears these
labels are not defined in the example block. 

Won't this cause a fatal dtc compilation error during make dt_binding_check? 
Could we define these labels on the parent node or a dummy node in the 
example so that the build succeeds?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260813-ti-keystone-devctrl-v1-1-6f0aa87d9af8@gmail.com?part=1

Re: [PATCH] dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema

[Bhargav Joshi]

On Thu, Aug 13, 2026 at 10:11 PM <sashiko-bot@kernel.org> wrote:
>
> Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
> - [Medium] The schema enforces non-compliant, legacy device tree node names (containing underscores) for child nodes via `patternProperties`, blocking the use of standard generic names and contradicting the commit message.
Yes nodes with underscores are kept not to break older dts/dtsi files
which uses underscores
> - [Low] The YAML example references undefined phandles (`&devctrl` and `&pllctrl`), which will cause a fatal `dtc` compilation error during `make dt_binding_check`.
no this won't cause any errors related to references ( tested on version 2026.7)
> --
>
> --- Patch [1]: [PATCH] dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema ---
> commit f59b6bface010fc243ef7f899dbb8dddf737e2c5
> Author: Bhargav Joshi <j.bhargav.u@gmail.com>
>
> dt-bindings: mfd: ti,keystone-devctrl: Convert to DT schema
>
> Converts the Texas Instruments Keystone Device State Control binding from
> legacy text format to DT schema. Adds "simple-mfd" support, enforces child
> bus properties, and adds validations for standard child nodes.
>
> > diff --git a/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml b/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml
> > new file mode 100644
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/mfd/ti,keystone-devctrl.yaml
> [ ... ]
> > +patternProperties:
> > +  "^keystone_dsp_gpio@[0-9a-f]+$":
> > +    type: object
> > +    description: Keystone DSP GPIO controller
> > +
> > +  "^keystone_irq@[0-9a-f]+$":
> > +    type: object
> > +    description: Keystone DSP to ARM interrupt controller
>
> [Severity: Medium]
> The commit message mentions updating node names to conform with standard
> Devicetree specifications. However, these patternProperties enforce names
> with underscores like "keystone_dsp_gpio" and "keystone_irq".
>
> Does this block the use of standard generic names (like "gpio" or
> "interrupt-controller")? Because additionalProperties is false, using generic
> names in a DTS file would cause validation errors. Could these patterns be
> updated to match generic names instead?
>
> [ ... ]
> > +examples:
> [ ... ]
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
> > +    device-state-control@2620000 {
> > +        compatible = "ti,keystone-devctrl", "syscon", "simple-mfd";
> > +        reg = <0x02620000 0x1000>;
> > +        #address-cells = <1>;
> > +        #size-cells = <1>;
> > +        ranges = <0x0 0x02620000 0x1000>;
> > +
> > +        keystone_irq@2a0 {
> > +            compatible = "ti,keystone-irq";
> > +            reg = <0x2a0 0x4>;
> > +            interrupts = <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>;
> > +            interrupt-controller;
> > +            #interrupt-cells = <1>;
> > +            ti,syscon-dev = <&devctrl 0x2a0>;
> > +        };
> > +
> > +        reset-controller@328 {
> > +            compatible = "ti,keystone-reset";
> > +            reg = <0x328 0x10>;
> > +            ti,syscon-pll = <&pllctrl 0xe4>;
> > +            ti,syscon-dev = <&devctrl 0x328>;
> > +            ti,wdt-list = <0>;
> > +        };
> > +    };
>
> [Severity: Low]
> The example uses phandles for &devctrl and &pllctrl, but it appears these
> labels are not defined in the example block.
>
> Won't this cause a fatal dtc compilation error during make dt_binding_check?
> Could we define these labels on the parent node or a dummy node in the
> example so that the build succeeds?
>
> --
> Sashiko AI review · https://sashiko.dev/#/patchset/20260813-ti-keystone-devctrl-v1-1-6f0aa87d9af8@gmail.com?part=1