[PATCH v7 1/3] dt-bindings: mfd: twl: Add missing sub-nodes for TWL4030 & TWL603x
From: Jihed Chaibi <hidden>
Date: 2025-09-10 16:07:24
Also in:
linux-omap, linux-pwm, lkml
Subsystem:
multifunction devices (mfd), open firmware and flattened device tree bindings, pwm subsystem, the rest · Maintainers:
Lee Jones, Rob Herring, Krzysztof Kozlowski, Conor Dooley, Uwe Kleine-König, Linus Torvalds
Update the main TI TWL-family binding to be self-contained and to fix
pre-existing validation errors.
To ensure future patches are bisectable, child nodes whose bindings
are in other patches (audio, keypad, usb, etc.) are now defined using
a flexible 'additionalProperties: true' pattern. This removes hard
dependencies between the MFD and subsystem bindings.
The complete dtbs_check for this binding is clean except for two
warnings originating from pre-existing bugs in the OMAP DTS files,
for which fixes have already been submitted separately [1][2].
Signed-off-by: Jihed Chaibi <redacted>
---
Changes in v7:
- Moved twl4030/twl6030-specific child node definitions (audio, usb..)
into the conditional 'if/then' block to improve schema accuracy.
Changes in v6:
- Refactored the ti,twl4030-power compatible schema to be much stricter,
removing obsolete board-specific compatibles (-n900, -beagleboard-xm),
that were added in v5. The schema now only permits specific, valid
fallback combinations. This change is supported by subsequent patches
in the same series (2/3) & (3/3), which update the affected DTS files.
- Enforced the presence of the compatible property on all relevant
sub-nodes by adding 'required: - compatible', closing a key validation
loophole.
- Applied various formatting cleanups for readability and correctness.
Changes in v5:
- Restructured the entire binding to define properties at the top
level instead of if/then blocks, per maintainer feedback.
- Added specific compatible enums for new child nodes instead of a
generic 'compatible: true'.
- Set 'unevaluatedProperties: false' for 'pwm' and 'pwmled' nodes to
enforce strict validation.
- Expanded 'power' node compatible enum to include all board-specific
compatible strings (used in existing device trees, e.g. OMAP3-based
boards) for more complete coverage.
- Corrected the schema for the 'power' node compatible to properly
handle single and fallback entries.
Changes in v4:
- Reworked binding to be independent and bisectable per maintainer
feedback by using 'additionalProperties: true' for child nodes.
- Added board-specific compatibles to the 'power' node enum.
- Added definitions for 'clocks' and 'clock-names' properties.
- Renamed 'twl6030-usb' child node to 'usb-comparator' to match
existing Device Tree usage (twl6030.dtsi).
- Fixed some spelling/grammar erros in the description.
Changes in v3:
- New patch to consolidate simple bindings (power, pwm) and add
definitions for all child nodes to fix dtbs_check validation
errors found in v2.
Changes in v2:
- This patch is split from larger series [3] per maintainer feedback.
- Added missing sub-node definitions, resolving dtbs_check errors.
[1] https://lore.kernel.org/all/20250822222530.113520-1-jihed.chaibi.dev@gmail.com/ (local)
[2] https://lore.kernel.org/all/20250822225052.136919-1-jihed.chaibi.dev@gmail.com/ (local)
[3] https://lore.kernel.org/all/20250816021523.167049-1-jihed.chaibi.dev@gmail.com/ (local)
---
.../devicetree/bindings/mfd/ti,twl.yaml | 232 +++++++++++++++++-
.../devicetree/bindings/mfd/twl4030-power.txt | 48 ----
.../devicetree/bindings/pwm/ti,twl-pwm.txt | 17 --
.../devicetree/bindings/pwm/ti,twl-pwmled.txt | 17 --
4 files changed, 221 insertions(+), 93 deletions(-)
delete mode 100644 Documentation/devicetree/bindings/mfd/twl4030-power.txt
delete mode 100644 Documentation/devicetree/bindings/pwm/ti,twl-pwm.txt
delete mode 100644 Documentation/devicetree/bindings/pwm/ti,twl-pwmled.txt
diff --git a/Documentation/devicetree/bindings/mfd/ti,twl.yaml b/Documentation/devicetree/bindings/mfd/ti,twl.yaml
index f162ab60c09b..95238a10ecda 100644
--- a/Documentation/devicetree/bindings/mfd/ti,twl.yaml
+++ b/Documentation/devicetree/bindings/mfd/ti,twl.yaml@@ -9,11 +9,13 @@ title: Texas Instruments TWL family maintainers: - Andreas Kemnade <andreas@kemnade.info> -description: | +description: > The TWLs are Integrated Power Management Chips. - Some version might contain much more analog function like + + Some versions might contain much more analog functionality like USB transceiver or Audio amplifier. - These chips are connected to an i2c bus. + + These chips are connected to an I2C bus. allOf: - if:
@@ -62,6 +64,7 @@ allOf: pwrbutton: type: object additionalProperties: false + properties: compatible: const: ti,twl4030-pwrbutton
@@ -73,9 +76,109 @@ allOf: watchdog: type: object additionalProperties: false + properties: compatible: const: ti,twl4030-wdt + + audio: + type: object + additionalProperties: true + + properties: + compatible: + const: ti,twl4030-audio + + required: + - compatible + + keypad: + type: object + additionalProperties: true + + properties: + compatible: + const: ti,twl4030-keypad + + required: + - compatible + + twl4030-usb: + type: object + additionalProperties: true + + properties: + compatible: + const: ti,twl4030-usb + + required: + - compatible + + gpio: + type: object + additionalProperties: true + + properties: + compatible: + const: ti,twl4030-gpio + + required: + - compatible + + power: + type: object + additionalProperties: false + description: > + The power management module inside the TWL4030 provides several + facilities to control the power resources, including power scripts. + + For now, the binding only supports the complete shutdown of the + system after poweroff. + + Board-specific compatible strings may be used for platform-specific + power configurations. + + A board-specific compatible string (e.g., ti,twl4030-power-omap3-evm) + may be paired with a generic fallback (generally for power saving mode). + + properties: + compatible: + oneOf: + # Case 1: A single compatible string is provided. + - enum: + - ti,twl4030-power + - ti,twl4030-power-reset + - ti,twl4030-power-idle + - ti,twl4030-power-idle-osc-off + - ti,twl4030-power-omap3-sdp + - ti,twl4030-power-omap3-ldp + - ti,twl4030-power-omap3-evm + + # Case 2: The specific, valid fallback for 'idle-osc-off'. + - items: + - const: ti,twl4030-power-idle-osc-off + - const: ti,twl4030-power-idle + + # Case 3: The specific, valid fallback for 'omap3-evm'. + - items: + - const: ti,twl4030-power-omap3-evm + - const: ti,twl4030-power-idle + + ti,system-power-controller: + type: boolean + deprecated: true + description: > + DEPRECATED. The standard 'system-power-controller' + property on the parent node should be used instead. + + ti,use_poweroff: + type: boolean + deprecated: true + description: DEPRECATED, to be removed. + + required: + - compatible + - if: properties: compatible:
@@ -107,14 +210,29 @@ allOf: properties: charger: type: object + properties: compatible: const: ti,twl6030-charger + gpadc: type: object + properties: compatible: const: ti,twl6030-gpadc + + usb-comparator: + type: object + additionalProperties: true + + properties: + compatible: + const: ti,twl6030-usb + + required: + - compatible + - if: properties: compatible:
@@ -143,22 +261,37 @@ allOf: properties: charger: type: object + properties: compatible: items: - const: ti,twl6032-charger - const: ti,twl6030-charger + gpadc: type: object + properties: compatible: const: ti,twl6032-gpadc + usb-comparator: + type: object + additionalProperties: true + + properties: + compatible: + const: ti,twl6030-usb + + required: + - compatible + properties: compatible: - description: - TWL4030 for integrated power-management/audio CODEC device used in OMAP3 - based boards + description: > + TWL4030 for integrated power-management/audio CODEC device used in + OMAP3 based boards. + TWL6030/32 for integrated power-management used in OMAP4 based boards enum: - ti,twl4030
@@ -181,28 +314,80 @@ properties: "#clock-cells": const: 1 + clocks: + maxItems: 1 + + clock-names: + const: fck + charger: type: object additionalProperties: true + properties: compatible: true + required: - compatible rtc: type: object additionalProperties: false + properties: compatible: const: ti,twl4030-rtc interrupts: maxItems: 1 + pwm: + type: object + $ref: /schemas/pwm/pwm.yaml# + unevaluatedProperties: false + description: + PWM controllers (PWM1 and PWM2 on TWL4030, PWM0 and PWM1 on TWL6030/32). + + properties: + compatible: + enum: + - ti,twl4030-pwm + - ti,twl6030-pwm + + '#pwm-cells': + const: 2 + + required: + - compatible + - '#pwm-cells' + + pwmled: + type: object + $ref: /schemas/pwm/pwm.yaml# + unevaluatedProperties: false + description: > + PWM controllers connected to LED terminals (PWMA and PWMB on TWL4030. + + LED PWM on TWL6030/32, mainly used as charging indicator LED). + + properties: + compatible: + enum: + - ti,twl4030-pwmled + - ti,twl6030-pwmled + + '#pwm-cells': + const: 2 + + required: + - compatible + - '#pwm-cells' + patternProperties: "^regulator-": type: object unevaluatedProperties: false $ref: /schemas/regulator/regulator.yaml + properties: compatible: true regulator-initial-mode:
@@ -211,12 +396,13 @@ patternProperties: # with low power consumption with low load current capability - 0x0e # Active mode, the regulator can deliver its nominal output # voltage with full-load current capability + ti,retain-on-reset: - description: - Does not turn off the supplies during warm - reset. Could be needed for VMMC, as TWL6030 - reset sequence for this signal does not comply - with the SD specification. + description: > + Does not turn off the supplies during warm reset. + + Could be needed for VMMC, as TWL6030 reset sequence for + this signal does not comply with the SD specification. type: boolean unevaluatedProperties: false
@@ -271,6 +457,16 @@ examples: compatible = "ti,twl6030-vmmc"; ti,retain-on-reset; }; + + pwm { + compatible = "ti,twl6030-pwm"; + #pwm-cells = <2>; + }; + + pwmled { + compatible = "ti,twl6030-pwmled"; + #pwm-cells = <2>; + }; }; };
@@ -325,6 +521,20 @@ examples: watchdog { compatible = "ti,twl4030-wdt"; }; + + power { + compatible = "ti,twl4030-power"; + }; + + pwm { + compatible = "ti,twl4030-pwm"; + #pwm-cells = <2>; + }; + + pwmled { + compatible = "ti,twl4030-pwmled"; + #pwm-cells = <2>; + }; }; }; ...
diff --git a/Documentation/devicetree/bindings/mfd/twl4030-power.txt b/Documentation/devicetree/bindings/mfd/twl4030-power.txt
deleted file mode 100644
index 3d19963312ce..000000000000
--- a/Documentation/devicetree/bindings/mfd/twl4030-power.txt
+++ /dev/null@@ -1,48 +0,0 @@ -Texas Instruments TWL family (twl4030) reset and power management module - -The power management module inside the TWL family provides several facilities -to control the power resources, including power scripts. For now, the -binding only supports the complete shutdown of the system after poweroff. - -Required properties: -- compatible : must be one of the following - "ti,twl4030-power" - "ti,twl4030-power-reset" - "ti,twl4030-power-idle" - "ti,twl4030-power-idle-osc-off" - -The use of ti,twl4030-power-reset is recommended at least on -3530 that needs a special configuration for warm reset to work. - -When using ti,twl4030-power-idle, the TI recommended configuration -for idle modes is loaded to the tlw4030 PMIC. - -When using ti,twl4030-power-idle-osc-off, the TI recommended -configuration is used with the external oscillator being shut -down during off-idle. Note that this does not work on all boards -depending on how the external oscillator is wired. - -Optional properties: - -- ti,system-power-controller: This indicates that TWL4030 is the - power supply master of the system. With this flag, the chip will - initiate an ACTIVE-to-OFF or SLEEP-to-OFF transition when the - system poweroffs. - -- ti,use_poweroff: Deprecated name for ti,system-power-controller - -Example: -&i2c1 { - clock-frequency = <2600000>; - - twl: twl@48 { - reg = <0x48>; - interrupts = <7>; /* SYS_NIRQ cascaded to intc */ - interrupt-parent = <&intc>; - - twl_power: power { - compatible = "ti,twl4030-power"; - ti,use_poweroff; - }; - }; -};
diff --git a/Documentation/devicetree/bindings/pwm/ti,twl-pwm.txt b/Documentation/devicetree/bindings/pwm/ti,twl-pwm.txt
deleted file mode 100644
index d97ca1964e94..000000000000
--- a/Documentation/devicetree/bindings/pwm/ti,twl-pwm.txt
+++ /dev/null@@ -1,17 +0,0 @@ -Texas Instruments TWL series PWM drivers - -Supported PWMs: -On TWL4030 series: PWM1 and PWM2 -On TWL6030 series: PWM0 and PWM1 - -Required properties: -- compatible: "ti,twl4030-pwm" or "ti,twl6030-pwm" -- #pwm-cells: should be 2. See pwm.yaml in this directory for a description of - the cells format. - -Example: - -twl_pwm: pwm { - compatible = "ti,twl6030-pwm"; - #pwm-cells = <2>; -};
diff --git a/Documentation/devicetree/bindings/pwm/ti,twl-pwmled.txt b/Documentation/devicetree/bindings/pwm/ti,twl-pwmled.txt
deleted file mode 100644
index 31ca1b032ef0..000000000000
--- a/Documentation/devicetree/bindings/pwm/ti,twl-pwmled.txt
+++ /dev/null@@ -1,17 +0,0 @@ -Texas Instruments TWL series PWM drivers connected to LED terminals - -Supported PWMs: -On TWL4030 series: PWMA and PWMB (connected to LEDA and LEDB terminals) -On TWL6030 series: LED PWM (mainly used as charging indicator LED) - -Required properties: -- compatible: "ti,twl4030-pwmled" or "ti,twl6030-pwmled" -- #pwm-cells: should be 2. See pwm.yaml in this directory for a description of - the cells format. - -Example: - -twl_pwmled: pwmled { - compatible = "ti,twl6030-pwmled"; - #pwm-cells = <2>; -};
--
2.39.5