[PATCH v6 0/2] usb: dt-bindings: ti,twlxxxx-usb: convert to DT schema

[PATCH v6 0/2] usb: dt-bindings: ti,twlxxxx-usb: convert to DT schema

[Jihed Chaibi]

Hello,

This series converts the legacy TXT bindings for the TI TWL4030
and TWL6030 USB modules to the modern YAML DT schema format.

This version (v6) addresses maintainer feedback by defining the
'interrupts' property with a list of 'items' for better clarity and
validation.

With the conversion complete, the second patch in this series removes
the now-obsolete .txt binding file.

Thank you,
Jihed

---
Changes in v6:
 - Reworked 'interrupts' property in both patches to use a list of
   items with descriptions, per reviewer feedback.

Changes in v5:
 - Split combined twlxxxx-usb binding into two dedicated files
   for TWL4030 and TWL6030 per maintainer feedback.
 - Used more accurate header file for interrupt macros.
 - Improved formatting in the examples.
 - Patch 2/2 removes the old .txt file.

Changes in v4:
 - This patch is split from larger series per maintainer feedback.
 - v3 link:
    https://lore.kernel.org/all/20250816021523.167049-1-jihed.chaibi.dev@gmail.com/
 - Removed i2c node as it wasn't required by the old binding file.
 - Updated node names to 'usb' and 'usb-phy' in the examples to follow
   generic naming conventions per the Device Tree specification.
 - Replaced raw interrupt values with standard defines for clarity.
 - Improved formatting in the examples for clarity and consistency.

Changes in v3:
 - No changes.

Changes in v2:
 - Added '#phy-cells' property to support PHY framework integration.

Jihed Chaibi (2):
  usb: dt-bindings: ti,twl4030-usb: convert to DT schema
  usb: dt-bindings: ti,twl6030-usb: convert to DT schema

 .../bindings/usb/ti,twl4030-usb.yaml          | 74 +++++++++++++++++++
 .../bindings/usb/ti,twl6030-usb.yaml          | 48 ++++++++++++
 .../devicetree/bindings/usb/twlxxxx-usb.txt   | 43 -----------
 3 files changed, 122 insertions(+), 43 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/usb/ti,twl4030-usb.yaml
 create mode 100644 Documentation/devicetree/bindings/usb/ti,twl6030-usb.yaml
 delete mode 100644 Documentation/devicetree/bindings/usb/twlxxxx-usb.txt

-- 
2.39.5

[PATCH v6 1/2] usb: dt-bindings: ti,twl4030-usb: convert to DT schema

[Jihed Chaibi]

Convert the legacy TXT binding for the TWL4030 USB module
to the modern YAML DT schema format. This adds formal validation
and improves documentation using a conditional schema.

Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>

---
Changes in v6:
 - Reworked 'interrupts' property to use a list of items with
   descriptions instead of a single free-form text block.

Changes in v5:
 - Split combined twlxxxx-usb binding into a dedicated file for
   twl4030-usb per maintainer feedback.
 - Used more accurate header for interrupt macros.
 - Improved formatting in the examples.

Changes in v4:
 - This patch is split from larger series per maintainer feedback.
 - v3 link:
    https://lore.kernel.org/all/20250816021523.167049-1-jihed.chaibi.dev@gmail.com/
 - Removed i2c node as it wasn't required by the old binding file.
 - Updated node names to 'usb' and 'usb-phy' in the examples to follow
   generic naming conventions per the Device Tree specification.
 - Replaced raw interrupt values with standard defines for clarity.
 - Improved formatting in the examples for clarity and consistency.

Changes in v3:
 - No changes.

Changes in v2:
 - Added '#phy-cells' property to support PHY framework integration.
---
 .../bindings/usb/ti,twl4030-usb.yaml          | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/usb/ti,twl4030-usb.yaml

diff --git a/Documentation/devicetree/bindings/usb/ti,twl4030-usb.yaml b/Documentation/devicetree/bindings/usb/ti,twl4030-usb.yaml
new file mode 100644
index 000000000..6ef337507
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/ti,twl4030-usb.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/ti,twl4030-usb.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TWL4030 USB PHY and Comparator
+
+maintainers:
+  - Peter Ujfalusi <peter.ujfalusi@gmail.com>
+
+description:
+  Bindings for the USB PHY and comparator module found within the
+  TWL4030 family of companion chips. If a sibling node is compatible with
+  "ti,twl4030-bci", the driver for that node will query this device for
+  USB power status.
+
+properties:
+  compatible:
+    const: ti,twl4030-usb
+
+  interrupts:
+    minItems: 1
+    items:
+      - description: OTG interrupt number for ID events.
+      - description: USB interrupt number for VBUS events.
+
+  usb1v5-supply:
+    description: Phandle to the vusb1v5 regulator.
+
+  usb1v8-supply:
+    description: Phandle to the vusb1v8 regulator.
+
+  usb3v1-supply:
+    description: Phandle to the vusb3v1 regulator.
+
+  usb_mode:
+    description: |
+      The mode used by the PHY to connect to the controller:
+        1: ULPI mode
+        2: CEA2011_3PIN mode
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [1, 2]
+
+  '#phy-cells':
+    const: 0
+
+required:
+  - compatible
+  - interrupts
+  - usb1v5-supply
+  - usb1v8-supply
+  - usb3v1-supply
+  - usb_mode
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    usb-phy {
+        compatible = "ti,twl4030-usb";
+
+        interrupts = <10 IRQ_TYPE_LEVEL_HIGH>;
+        interrupt-parent = <&gic>;
+
+        usb1v5-supply = <&reg_vusb1v5>;
+        usb1v8-supply = <&reg_vusb1v8>;
+        usb3v1-supply  = <&reg_vusb3v1>;
+        usb_mode = <1>;
+
+        #phy-cells = <0>;
+    };
-- 
2.39.5

Re: [PATCH v6 1/2] usb: dt-bindings: ti,twl4030-usb: convert to DT schema

[Krzysztof Kozlowski]

On Fri, Aug 22, 2025 at 10:17:26PM +0200, Jihed Chaibi wrote:
> Convert the legacy TXT binding for the TWL4030 USB module
> to the modern YAML DT schema format. This adds formal validation
> and improves documentation using a conditional schema.
> 
> Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
> 
> ---
> Changes in v6:
>  - Reworked 'interrupts' property to use a list of items with
>    descriptions instead of a single free-form text block.
> 
> Changes in v5:
>  - Split combined twlxxxx-usb binding into a dedicated file for
>    twl4030-usb per maintainer feedback.
>  - Used more accurate header for interrupt macros.
>  - Improved formatting in the examples.
> 
> Changes in v4:
>  - This patch is split from larger series per maintainer feedback.
>  - v3 link:
>     https://lore.kernel.org/all/20250816021523.167049-1-jihed.chaibi.dev@gmail.com/
>  - Removed i2c node as it wasn't required by the old binding file.
>  - Updated node names to 'usb' and 'usb-phy' in the examples to follow
>    generic naming conventions per the Device Tree specification.
>  - Replaced raw interrupt values with standard defines for clarity.
>  - Improved formatting in the examples for clarity and consistency.
> 
> Changes in v3:
>  - No changes.
> 
> Changes in v2:
>  - Added '#phy-cells' property to support PHY framework integration.
> ---
>  .../bindings/usb/ti,twl4030-usb.yaml          | 74 +++++++++++++++++++

I asked to drop here parts of converted binding.

Best regards,
Krzysztof

[PATCH v6 2/2] usb: dt-bindings: ti,twl6030-usb: convert to DT schema

[Jihed Chaibi]

Convert the legacy TXT binding for the TWL6030 USB module
to the modern YAML DT schema format. This adds formal validation
and improves documentation using a conditional schema.

With the conversion of both devices complete, the legacy twlxxxx-usb.txt
file is no longer needed and is removed.

Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>

---
Changes in v6:
 - Reworked 'interrupts' property to use a list of items with
   descriptions per reviewer feedback.

Changes in v5:
 - Split combined twlxxxx-usb binding into a dedicated file for
   twl6030-usb per maintainer feedback.
 - Used more accurate header for interrupt macros.
 - Improved formatting in the examples.
 - This patch also removes the old .txt file.

Changes in v4:
 - This patch is split from larger series per maintainer feedback.
 - v3 link:
    https://lore.kernel.org/all/20250816021523.167049-1-jihed.chaibi.dev@gmail.com/
 - Removed i2c node as it wasn't required by the old binding file.
 - Updated node names to 'usb' and 'usb-phy' in the examples to follow
   generic naming conventions per the Device Tree specification.
 - Replaced raw interrupt values with standard defines for clarity.
 - Improved formatting in the examples for clarity and consistency.

Changes in v3:
 - No changes.

Changes in v2:
 - Added '#phy-cells' property to support PHY framework integration.
---
 .../bindings/usb/ti,twl6030-usb.yaml          | 48 +++++++++++++++++++
 .../devicetree/bindings/usb/twlxxxx-usb.txt   | 43 -----------------
 2 files changed, 48 insertions(+), 43 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/usb/ti,twl6030-usb.yaml
 delete mode 100644 Documentation/devicetree/bindings/usb/twlxxxx-usb.txt

diff --git a/Documentation/devicetree/bindings/usb/ti,twl6030-usb.yaml b/Documentation/devicetree/bindings/usb/ti,twl6030-usb.yaml
new file mode 100644
index 000000000..bf737fa9e
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/ti,twl6030-usb.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/ti,twl6030-usb.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TWL6030 USB Comparator
+
+maintainers:
+  - Peter Ujfalusi <peter.ujfalusi@gmail.com>
+
+description:
+  Bindings for the USB comparator module found within the TWL6030
+  family of companion chips.
+
+properties:
+  compatible:
+    const: ti,twl6030-usb
+
+  interrupts:
+    items:
+      - description: OTG interrupt for ID events in host mode.
+      - description: USB interrupt for VBUS events in device mode.
+
+  usb-supply:
+    description:
+      Phandle to the VUSB regulator. For TWL6030, this should be the 'vusb'
+      regulator. For TWL6032 subclass, it should be the 'ldousb' regulator.
+
+required:
+  - compatible
+  - interrupts
+  - usb-supply
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    usb {
+        compatible = "ti,twl6030-usb";
+
+        interrupts = <4 IRQ_TYPE_LEVEL_HIGH>, <10 IRQ_TYPE_LEVEL_HIGH>;
+        interrupt-parent = <&gic>;
+
+        usb-supply = <&reg_vusb>;
+    };
diff --git a/Documentation/devicetree/bindings/usb/twlxxxx-usb.txt b/Documentation/devicetree/bindings/usb/twlxxxx-usb.txt
deleted file mode 100644
index 17327a296..000000000
--- a/Documentation/devicetree/bindings/usb/twlxxxx-usb.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-USB COMPARATOR OF TWL CHIPS
-
-TWL6030 USB COMPARATOR
- - compatible : Should be "ti,twl6030-usb"
- - interrupts : Two interrupt numbers to the cpu should be specified. First
-   interrupt number is the otg interrupt number that raises ID interrupts when
-   the controller has to act as host and the second interrupt number is the
-   usb interrupt number that raises VBUS interrupts when the controller has to
-   act as device
- - usb-supply : phandle to the regulator device tree node. It should be vusb
-   if it is twl6030 or ldousb if it is twl6032 subclass.
-
-twl6030-usb {
-	compatible = "ti,twl6030-usb";
-	interrupts = < 4 10 >;
-};
-
-Board specific device node entry
-&twl6030-usb {
-	usb-supply = <&vusb>;
-};
-
-TWL4030 USB PHY AND COMPARATOR
- - compatible : Should be "ti,twl4030-usb"
- - interrupts : The interrupt numbers to the cpu should be specified. First
-   interrupt number is the otg interrupt number that raises ID interrupts
-   and VBUS interrupts. The second interrupt number is optional.
- - <supply-name>-supply : phandle to the regulator device tree node.
-   <supply-name> should be vusb1v5, vusb1v8 and vusb3v1
- - usb_mode : The mode used by the phy to connect to the controller. "1"
-   specifies "ULPI" mode and "2" specifies "CEA2011_3PIN" mode.
-
-If a sibling node is compatible "ti,twl4030-bci", then it will find
-this device and query it for USB power status.
-
-twl4030-usb {
-	compatible = "ti,twl4030-usb";
-	interrupts = < 10 4 >;
-	usb1v5-supply = <&vusb1v5>;
-	usb1v8-supply = <&vusb1v8>;
-	usb3v1-supply = <&vusb3v1>;
-	usb_mode = <1>;
-};
-- 
2.39.5

Re: [PATCH v6 2/2] usb: dt-bindings: ti,twl6030-usb: convert to DT schema

[Krzysztof Kozlowski]

On Fri, Aug 22, 2025 at 10:17:27PM +0200, Jihed Chaibi wrote:
> -TWL4030 USB PHY AND COMPARATOR
> - - compatible : Should be "ti,twl4030-usb"

All this should be in previous commit.

> - - interrupts : The interrupt numbers to the cpu should be specified. First
> -   interrupt number is the otg interrupt number that raises ID interrupts
> -   and VBUS interrupts. The second interrupt number is optional.
> - - <supply-name>-supply : phandle to the regulator device tree node.
> -   <supply-name> should be vusb1v5, vusb1v8 and vusb3v1
> - - usb_mode : The mode used by the phy to connect to the controller. "1"
> -   specifies "ULPI" mode and "2" specifies "CEA2011_3PIN" mode.
> -
> -If a sibling node is compatible "ti,twl4030-bci", then it will find
> -this device and query it for USB power status.

Best regards,
Krzysztof