[PATCH v2] dt-bindings: mfd: Convert TI TWL6040 to DT schema

[PATCH v2] dt-bindings: mfd: Convert TI TWL6040 to DT schema

[Eduard Bostina]

Convert the Texas Instruments TWL6040 audio codecs family bindings to DT
schema.

During the conversion, the following updates were made:
- Changed 'twl6040,audpwron-gpio' to 'ti,audpwron-gpio', which was
  misnamed in the old txt binding.
- Made 'gpio-controller', '#gpio-cells', and 'ti,audpwron-gpio' optional
  because modern platforms do not require them.
- Renamed the vibra 'vddvibl_uV'/'vddvibr_uV' properties to
  'ti,vddvibl-uV'/'ti,vddvibr-uV', the names actually read by the
  twl6040-vibra driver.

Signed-off-by: Eduard Bostina <egbostina@gmail.com>
---
Changes in v2:
- Renamed the vibra 'vddvibl_uV'/'vddvibr_uV' properties to 
  'ti,vddvibl-uV'/'ti,vddvibr-uV', the names actually read by the
  twl6040-vibra driver.

Link to v1: https://lore.kernel.org/all/20260815083451.2147129-1-egbostina@gmail.com/

 .../devicetree/bindings/mfd/ti,twl6040.yaml   | 142 ++++++++++++++++++
 .../devicetree/bindings/mfd/twl6040.txt       |  67 ---------
 2 files changed, 142 insertions(+), 67 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/mfd/ti,twl6040.yaml
 delete mode 100644 Documentation/devicetree/bindings/mfd/twl6040.txt

diff --git a/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml b/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml
new file mode 100644
index 000000000000..011a1a58615a
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml
@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/ti,twl6040.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TWL6040 family audio codec
+
+maintainers:
+  - Eduard Bostina <egbostina@gmail.com>
+
+description:
+  The TWL6040s are 8-channel high quality low-power audio codecs providing
+  audio, vibra and GPO functionality on OMAP4+ platforms. They are connected
+  to the host processor via i2c for commands, McPDM for audio data and
+  commands.
+
+properties:
+  compatible:
+    enum:
+      - ti,twl6040
+      - ti,twl6041
+
+  reg:
+    const: 0x4b
+
+  interrupts:
+    maxItems: 1
+
+  gpio-controller: true
+
+  "#gpio-cells":
+    const: 1
+
+  "#clock-cells":
+    const: 0
+
+  ti,audpwron-gpio:
+    maxItems: 1
+    description: Power on GPIO line for the twl6040
+
+  vio-supply:
+    description: Regulator for the twl6040 VIO supply
+
+  v2v1-supply:
+    description: Regulator for the twl6040 V2V1 supply
+
+  enable-active-high:
+    type: boolean
+    description: To power on the twl6040 during boot.
+
+  clocks:
+    minItems: 1
+    maxItems: 2
+
+  clock-names:
+    minItems: 1
+    maxItems: 2
+    items:
+      enum:
+        - clk32k
+        - mclk
+
+  vddvibl-supply:
+    description: Regulator for the left vibra motor
+
+  vddvibr-supply:
+    description: Regulator for the right vibra motor
+
+  vibra:
+    type: object
+    additionalProperties: false
+    properties:
+      ti,vibldrv-res:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: Resistance parameter for left driver
+      ti,vibrdrv-res:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: Resistance parameter for right driver
+      ti,viblmotor-res:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: Resistance parameter for left motor
+      ti,vibrmotor-res:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: Resistance parameter for right motor
+      ti,vddvibl-uV:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: vddvibl default voltage if it needs to be changed
+      ti,vddvibr-uV:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: vddvibr default voltage if it needs to be changed
+
+    required:
+      - ti,vibldrv-res
+      - ti,vibrdrv-res
+      - ti,viblmotor-res
+      - ti,vibrmotor-res
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - "#clock-cells"
+  - vio-supply
+  - v2v1-supply
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        audio-codec@4b {
+            compatible = "ti,twl6040";
+            reg = <0x4b>;
+            interrupts = <0 119 IRQ_TYPE_LEVEL_HIGH>;
+            interrupt-parent = <&gic>;
+            gpio-controller;
+            #gpio-cells = <1>;
+            #clock-cells = <0>;
+            ti,audpwron-gpio = <&gpio4 31 0>;
+
+            vio-supply = <&v1v8>;
+            v2v1-supply = <&v2v1>;
+            enable-active-high;
+
+            /* regulators for vibra motor */
+            vddvibl-supply = <&vbat>;
+            vddvibr-supply = <&vbat>;
+
+            vibra {
+                ti,vibldrv-res = <8>;
+                ti,vibrdrv-res = <3>;
+                ti,viblmotor-res = <10>;
+                ti,vibrmotor-res = <10>;
+            };
+        };
+    };
diff --git a/Documentation/devicetree/bindings/mfd/twl6040.txt b/Documentation/devicetree/bindings/mfd/twl6040.txt
deleted file mode 100644
index dfd8683ede0c..000000000000
--- a/Documentation/devicetree/bindings/mfd/twl6040.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-Texas Instruments TWL6040 family
-
-The TWL6040s are 8-channel high quality low-power audio codecs providing audio,
-vibra and GPO functionality on OMAP4+ platforms.
-They are connected to the host processor via i2c for commands, McPDM for audio
-data and commands.
-
-Required properties:
-- compatible : "ti,twl6040" for twl6040, "ti,twl6041" for twl6041
-- reg: must be 0x4b for i2c address
-- interrupts: twl6040 has one interrupt line connecteded to the main SoC
-- gpio-controller:
-- #gpio-cells = <1>: twl6040 provides GPO lines.
-- #clock-cells = <0>; twl6040 is a provider of pdmclk which is used by McPDM
-- twl6040,audpwron-gpio: Power on GPIO line for the twl6040
-
-- vio-supply: Regulator for the twl6040 VIO supply
-- v2v1-supply: Regulator for the twl6040 V2V1 supply
-
-Optional properties, nodes:
-- enable-active-high: To power on the twl6040 during boot.
-- clocks: phandle to the clk32k and/or to mclk clock provider
-- clock-names: Must be "clk32k" for the 32K clock and "mclk" for the MCLK.
-
-Vibra functionality
-Required properties:
-- vddvibl-supply: Regulator for the left vibra motor
-- vddvibr-supply: Regulator for the right vibra motor
-- vibra { }: Configuration section for vibra parameters containing the following
-	     properties:
-- ti,vibldrv-res: Resistance parameter for left driver
-- ti,vibrdrv-res: Resistance parameter for right driver
-- ti,viblmotor-res: Resistance parameter for left motor
-- ti,viblmotor-res: Resistance parameter for right motor
-
-Optional properties within vibra { } section:
-- vddvibl_uV: If the vddvibl default voltage need to be changed
-- vddvibr_uV: If the vddvibr default voltage need to be changed
-
-Example:
-&i2c1 {
-	twl6040: twl@4b {
-		compatible = "ti,twl6040";
-
-		interrupts = <0 119 4>;
-		interrupt-parent = <&gic>;
-		twl6040,audpwron-gpio = <&gpio4 31 0>;
-
-		vio-supply = <&v1v8>;
-		v2v1-supply = <&v2v1>;
-		enable-active-high;
-
-		/* regulators for vibra motor */
-		vddvibl-supply = <&vbat>;
-		vddvibr-supply = <&vbat>;
-
-		vibra {
-			/* Vibra driver, motor resistance parameters */
-			ti,vibldrv-res = <8>;
-			ti,vibrdrv-res = <3>;
-			ti,viblmotor-res = <10>;
-			ti,vibrmotor-res = <10>;
-		};
-	};
-};
-
-/include/ "twl6040.dtsi"
-- 
2.43.0

Re: [PATCH v2] dt-bindings: mfd: Convert TI TWL6040 to DT schema

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 3 potential issue(s) to consider:

New issues:
- [Medium] Missing dependency enforcement for the 'vibra' node power supplies ('vddvibl-supply' and 'vddvibr-supply').

Pre-existing issues:
- [High] The twl6040 driver constructs its mfd_cell array dynamically at runtime and mutates a global static resource array, violating MFD static reference rules.
- [High] Hardcoded cell indexing via PLATFORM_DEVID_NONE creates sysfs naming collisions.
--

--- Patch [1]: [PATCH v2] dt-bindings: mfd: Convert TI TWL6040 to DT schema ---
commit 940b493f232639b743b8f6ddfb4feba28f32a8ab
Author: Eduard Bostina <egbostina@gmail.com>

dt-bindings: mfd: Convert TI TWL6040 to DT schema

Convert the Texas Instruments TWL6040 audio codecs family bindings to DT
schema. During the conversion, ti,audpwron-gpio was renamed and made
optional along with gpio-controller. The vibra voltage properties were also
renamed to match what the driver actually reads.

Link: https://lore.kernel.org/all/20260815083451.2147129-1-egbostina@gmail.com/

While reviewing this binding conversion, I noticed a couple of pre-existing
issues in the corresponding driver.

[Severity: High]
This isn't a bug introduced by this patch, but does the dynamic mutation of
mfd_cell resources in twl6040_probe() cause a data race?

drivers/mfd/twl6040.c:twl6040_probe() {
    ...
    twl6040_codec_rsrc[0].start = irq;
    twl6040_codec_rsrc[0].end = irq;
    cell->resources = twl6040_codec_rsrc;
    cell->num_resources = ARRAY_SIZE(twl6040_codec_rsrc);
    ...
}

If two TWL6040 devices probe concurrently, could they race to overwrite these
globally shared arrays, resulting in incorrect IRQ assignments for the child
devices?

[Severity: High]
This is a pre-existing issue, but does using the hardcoded value of -1
instead of PLATFORM_DEVID_AUTO prevent multiple TWL6040 chips from being
used in the same system?

drivers/mfd/twl6040.c:twl6040_probe() {
    ...
    ret = mfd_add_devices(&client->dev, -1, twl6040->cells, children,
                          NULL, 0, NULL);
    ...
}

If a system integrates more than one TWL6040 device, would the second
instance fail to probe its child devices due to identical sysfs device names?

> diff --git a/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml b/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml
> new file mode 100644
> index 0000000000000..011a1a58615a6
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml
[ ... ]
> +  vibra:
> +    type: object
> +    additionalProperties: false
> +    properties:
> +      ti,vibldrv-res:

[Severity: Medium]
Should the vibra configuration object include a dependencies constraint to
ensure vddvibl-supply and vddvibr-supply are present?

The previous twl6040.txt binding explicitly marked vddvibl-supply and
vddvibr-supply as required when the vibra functionality is present.

Without this constraint, would an incomplete device tree missing these
regulators silently pass dt_binding_check validation but fail in
twl6040-vibra.c at runtime?

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

Re: [PATCH v2] dt-bindings: mfd: Convert TI TWL6040 to DT schema

[Dhruva G]

Hi Eduard,

On 16-08-2026 14:58, Eduard Bostina wrote:
> Convert the Texas Instruments TWL6040 audio codecs family bindings to DT
> schema.
> 
> During the conversion, the following updates were made:
> - Changed 'twl6040,audpwron-gpio' to 'ti,audpwron-gpio', which was
>   misnamed in the old txt binding.
> - Made 'gpio-controller', '#gpio-cells', and 'ti,audpwron-gpio' optional
>   because modern platforms do not require them.
> - Renamed the vibra 'vddvibl_uV'/'vddvibr_uV' properties to
>   'ti,vddvibl-uV'/'ti,vddvibr-uV', the names actually read by the
>   twl6040-vibra driver.
> 
> Signed-off-by: Eduard Bostina <egbostina@gmail.com>
> ---
> Changes in v2:
> - Renamed the vibra 'vddvibl_uV'/'vddvibr_uV' properties to 
>   'ti,vddvibl-uV'/'ti,vddvibr-uV', the names actually read by the
>   twl6040-vibra driver.
> 
> Link to v1: https://lore.kernel.org/all/20260815083451.2147129-1-egbostina@gmail.com/
> 
>  .../devicetree/bindings/mfd/ti,twl6040.yaml   | 142 ++++++++++++++++++
>  .../devicetree/bindings/mfd/twl6040.txt       |  67 ---------
>  2 files changed, 142 insertions(+), 67 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/mfd/ti,twl6040.yaml
>  delete mode 100644 Documentation/devicetree/bindings/mfd/twl6040.txt
> 
> diff --git a/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml b/Documentation/devicetree/bindings/mfd/ti,twl6040.yaml
> new file mode 100644
[..snip..]
> +
> +  vddvibl-supply:
> +    description: Regulator for the left vibra motor
> +
> +  vddvibr-supply:
> +    description: Regulator for the right vibra motor
> +
> +  vibra:
> +    type: object
> +    additionalProperties: false
> +    properties:
> +      ti,vibldrv-res:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: Resistance parameter for left driver
> +      ti,vibrdrv-res:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: Resistance parameter for right driver
> +      ti,viblmotor-res:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: Resistance parameter for left motor
> +      ti,vibrmotor-res:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: Resistance parameter for right motor
> +      ti,vddvibl-uV:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: vddvibl default voltage if it needs to be changed
> +      ti,vddvibr-uV:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: vddvibr default voltage if it needs to be changed
> +
> +    required:
> +      - ti,vibldrv-res
> +      - ti,vibrdrv-res
> +      - ti,viblmotor-res
> +      - ti,vibrmotor-res
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - "#clock-cells"
> +  - vio-supply
> +  - v2v1-supply

I think the vibra supplies need to be conditionally required when the vibra child is present. 
twl6040_has_vibra() uses the presence of this child to instantiate twl6040-vibra, whose probe
then unconditionally gets both vddvibl and vddvibr.

Would something like this make sense?

allOf:
  - if:
      required:
        - vibra
    then:
      required:
        - vddvibl-supply
        - vddvibr-supply

This would still allow TWL6040 users without vibra, while retaining the dependency for users which enable it.

> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        audio-codec@4b {
> +            compatible = "ti,twl6040";
> +            reg = <0x4b>;
> +            interrupts = <0 119 IRQ_TYPE_LEVEL_HIGH>;
> +            interrupt-parent = <&gic>;
> +            gpio-controller;
> +            #gpio-cells = <1>;
> +            #clock-cells = <0>;
> +            ti,audpwron-gpio = <&gpio4 31 0>;
> +
> +            vio-supply = <&v1v8>;
> +            v2v1-supply = <&v2v1>;
> +            enable-active-high;
> +
> +            /* regulators for vibra motor */
> +            vddvibl-supply = <&vbat>;
> +            vddvibr-supply = <&vbat>;
> +
> +            vibra {
> +                ti,vibldrv-res = <8>;
> +                ti,vibrdrv-res = <3>;
> +                ti,viblmotor-res = <10>;
> +                ti,vibrmotor-res = <10>;
> +            };
> +        };
> +    };
> diff --git a/Documentation/devicetree/bindings/mfd/twl6040.txt b/Documentation/devicetree/bindings/mfd/twl6040.txt
> deleted file mode 100644

[..snip..]