Convert the legacy TXT binding for the OMAP TWL4030 sound card
to the modern YAML DT schema format. This adds formal validation
and improves documentation.

Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
---
 .../bindings/sound/omap-twl4030.txt           |  62 -----------
 .../bindings/sound/ti,omap-twl4030.yaml       | 101 ++++++++++++++++++
 2 files changed, 101 insertions(+), 62 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/omap-twl4030.txt
 create mode 100644 Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml

diff --git a/Documentation/devicetree/bindings/sound/omap-twl4030.txt b/Documentation/devicetree/bindings/sound/omap-twl4030.txt
deleted file mode 100644
index f6a715e4e..000000000
--- a/Documentation/devicetree/bindings/sound/omap-twl4030.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-* Texas Instruments SoC with twl4030 based audio setups
-
-Required properties:
-- compatible: "ti,omap-twl4030"
-- ti,model: Name of the sound card (for example "omap3beagle")
-- ti,mcbsp: phandle for the McBSP node
-
-Optional properties:
-- ti,codec: phandle for the twl4030 audio node
-- ti,mcbsp-voice: phandle for the McBSP node connected to the voice port of twl
-- ti, jack-det-gpio: Jack detect GPIO
-- ti,audio-routing: List of connections between audio components.
-  Each entry is a pair of strings, the first being the connection's sink,
-  the second being the connection's source.
-  If the routing is not provided all possible connection will be available
-
-Available audio endpoints for the audio-routing table:
-
-Board connectors:
- * Headset Stereophone
- * Earpiece Spk
- * Handsfree Spk
- * Ext Spk
- * Main Mic
- * Sub Mic
- * Headset Mic
- * Carkit Mic
- * Digital0 Mic
- * Digital1 Mic
- * Line In
-
-twl4030 pins:
- * HSOL
- * HSOR
- * EARPIECE
- * HFL
- * HFR
- * PREDRIVEL
- * PREDRIVER
- * CARKITL
- * CARKITR
- * MAINMIC
- * SUBMIC
- * HSMIC
- * DIGIMIC0
- * DIGIMIC1
- * CARKITMIC
- * AUXL
- * AUXR
-
- * Headset Mic Bias
- * Mic Bias 1 /* Used for Main Mic or Digimic0 */
- * Mic Bias 2 /* Used for Sub Mic or Digimic1 */
-
-Example:
-
-sound {
-	compatible = "ti,omap-twl4030";
-	ti,model = "omap3beagle";
-
-	ti,mcbsp = <&mcbsp2>;
-};
diff --git a/Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml b/Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml
new file mode 100644
index 000000000..3124320d6
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ti,omap-twl4030.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments SoC with twl4030 based audio setups
+
+maintainers:
+  - Peter Ujfalusi <peter.ujfalusi@gmail.com>
+
+description:
+  Bindings for audio setups on TI OMAP SoCs using TWL4030-family audio codec connected via a McBSP port.
+
+properties:
+  compatible:
+    const: ti,omap-twl4030
+
+  ti,model:
+    $ref: /schemas/types.yaml#/definitions/string
+    description: Name of the sound card (for example "omap3beagle").
+
+  ti,mcbsp:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: phandle for the McBSP node.
+
+  ti,codec:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: phandle for the twl4030 audio node.
+
+  ti,mcbsp-voice:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: phandle to the McBSP node connected to the voice port.
+
+  ti,jack-det-gpio:
+    description: GPIO specifier for jack detection.
+    maxItems: 1
+
+  ti,audio-routing:
+    description: |
+      A list of audio routing connections. Each entry is a pair of strings,
+      with the first being the connection's sink and the second being the
+      source. If not provided, all possible connections are available.
+
+      Available TWL4030 Pins:  "HFL", "HFR",
+        "PREDRIVEL", "PREDRIVER", "CARKITL", "CARKITR", "MAINMIC", "SUBMIC",
+        "HSMIC", "DIGIMIC0", "DIGIMIC1", "CARKITMIC", "AUXL", "AUXR",
+        "Headset Mic Bias", "Mic Bias 1", "Mic Bias 2"
+    $ref: /schemas/types.yaml#/definitions/non-unique-string-array
+    items:
+      enum:
+        # Board Connectors
+        - Headset Stereophone
+        - Earpiece Spk
+        - Handsfree Spk
+        - Ext Spk
+        - Main Mic
+        - Sub Mic
+        - Headset Mic
+        - Carkit Mic
+        - Digital0 Mic
+        - Digital1 Mic
+        - Line In
+
+        # CODEC Pins
+        - HSOL
+        - HSOR
+        - EARPIECE
+        - HFL
+        - HFR
+        - PREDRIVEL
+        - PREDRIVER
+        - CARKITL
+        - CARKITR
+        - MAINMIC
+        - SUBMIC
+        - HSMIC
+        - DIGIMIC0
+        - DIGIMIC1
+        - CARKITMIC
+        - AUXL
+        - AUXR
+
+        # Headset Mic Bias
+        - Mic Bias 1 # Used for Main Mic or Digimic0
+        - Mic Bias 2 # Used for Sub Mic or Digimic1
+
+required:
+  - compatible
+  - ti,model
+  - ti,mcbsp
+
+additionalProperties: false
+
+examples:
+  - |
+    sound {
+        compatible = "ti,omap-twl4030";
+        ti,model = "omap3beagle";
+        ti,mcbsp = <&mcbsp2>;
+    };
-- 
2.39.5

On Tue, Aug 12, 2025 at 12:47:38AM +0200, Jihed Chaibi wrote:
> Convert the legacy TXT binding for the OMAP TWL4030 sound card
> to the modern YAML DT schema format. This adds formal validation
> and improves documentation.
> 
> Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
> ---
>  .../bindings/sound/omap-twl4030.txt           |  62 -----------
>  .../bindings/sound/ti,omap-twl4030.yaml       | 101 ++++++++++++++++++
>  2 files changed, 101 insertions(+), 62 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/sound/omap-twl4030.txt
>  create mode 100644 Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml
> 
> diff --git a/Documentation/devicetree/bindings/sound/omap-twl4030.txt b/Documentation/devicetree/bindings/sound/omap-twl4030.txt
> deleted file mode 100644
> index f6a715e4e..000000000
> --- a/Documentation/devicetree/bindings/sound/omap-twl4030.txt
> +++ /dev/null
> @@ -1,62 +0,0 @@
> -* Texas Instruments SoC with twl4030 based audio setups
> -
> -Required properties:
> -- compatible: "ti,omap-twl4030"
> -- ti,model: Name of the sound card (for example "omap3beagle")
> -- ti,mcbsp: phandle for the McBSP node
> -
> -Optional properties:
> -- ti,codec: phandle for the twl4030 audio node
> -- ti,mcbsp-voice: phandle for the McBSP node connected to the voice port of twl
> -- ti, jack-det-gpio: Jack detect GPIO
> -- ti,audio-routing: List of connections between audio components.
> -  Each entry is a pair of strings, the first being the connection's sink,
> -  the second being the connection's source.
> -  If the routing is not provided all possible connection will be available
> -
> -Available audio endpoints for the audio-routing table:
> -
> -Board connectors:
> - * Headset Stereophone
> - * Earpiece Spk
> - * Handsfree Spk
> - * Ext Spk
> - * Main Mic
> - * Sub Mic
> - * Headset Mic
> - * Carkit Mic
> - * Digital0 Mic
> - * Digital1 Mic
> - * Line In
> -
> -twl4030 pins:
> - * HSOL
> - * HSOR
> - * EARPIECE
> - * HFL
> - * HFR
> - * PREDRIVEL
> - * PREDRIVER
> - * CARKITL
> - * CARKITR
> - * MAINMIC
> - * SUBMIC
> - * HSMIC
> - * DIGIMIC0
> - * DIGIMIC1
> - * CARKITMIC
> - * AUXL
> - * AUXR
> -
> - * Headset Mic Bias
> - * Mic Bias 1 /* Used for Main Mic or Digimic0 */
> - * Mic Bias 2 /* Used for Sub Mic or Digimic1 */
> -
> -Example:
> -
> -sound {
> -	compatible = "ti,omap-twl4030";
> -	ti,model = "omap3beagle";
> -
> -	ti,mcbsp = <&mcbsp2>;
> -};
> diff --git a/Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml b/Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml
> new file mode 100644
> index 000000000..3124320d6
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml
> @@ -0,0 +1,101 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/sound/ti,omap-twl4030.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments SoC with twl4030 based audio setups
> +
> +maintainers:
> +  - Peter Ujfalusi <peter.ujfalusi@gmail.com>
> +
> +description:
> +  Bindings for audio setups on TI OMAP SoCs using TWL4030-family audio codec connected via a McBSP port.

Wrap lines at 80. Drop 'Bindings for'.

> +
> +properties:
> +  compatible:
> +    const: ti,omap-twl4030
> +
> +  ti,model:
> +    $ref: /schemas/types.yaml#/definitions/string
> +    description: Name of the sound card (for example "omap3beagle").
> +
> +  ti,mcbsp:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: phandle for the McBSP node.
> +
> +  ti,codec:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: phandle for the twl4030 audio node.
> +
> +  ti,mcbsp-voice:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: phandle to the McBSP node connected to the voice port.
> +
> +  ti,jack-det-gpio:
> +    description: GPIO specifier for jack detection.
> +    maxItems: 1
> +
> +  ti,audio-routing:
> +    description: |
> +      A list of audio routing connections. Each entry is a pair of strings,
> +      with the first being the connection's sink and the second being the
> +      source. If not provided, all possible connections are available.
> +
> +      Available TWL4030 Pins:  "HFL", "HFR",
> +        "PREDRIVEL", "PREDRIVER", "CARKITL", "CARKITR", "MAINMIC", "SUBMIC",
> +        "HSMIC", "DIGIMIC0", "DIGIMIC1", "CARKITMIC", "AUXL", "AUXR",
> +        "Headset Mic Bias", "Mic Bias 1", "Mic Bias 2"

Is this list supposed to match the below 'CODEC Pins'? If so, then don't 
duplicate it here. If not, then I'm confused.

> +    $ref: /schemas/types.yaml#/definitions/non-unique-string-array
> +    items:
> +      enum:
> +        # Board Connectors
> +        - Headset Stereophone
> +        - Earpiece Spk
> +        - Handsfree Spk
> +        - Ext Spk
> +        - Main Mic
> +        - Sub Mic
> +        - Headset Mic
> +        - Carkit Mic
> +        - Digital0 Mic
> +        - Digital1 Mic
> +        - Line In
> +
> +        # CODEC Pins
> +        - HSOL
> +        - HSOR
> +        - EARPIECE
> +        - HFL
> +        - HFR
> +        - PREDRIVEL
> +        - PREDRIVER
> +        - CARKITL
> +        - CARKITR
> +        - MAINMIC
> +        - SUBMIC
> +        - HSMIC
> +        - DIGIMIC0
> +        - DIGIMIC1
> +        - CARKITMIC
> +        - AUXL
> +        - AUXR
> +
> +        # Headset Mic Bias
> +        - Mic Bias 1 # Used for Main Mic or Digimic0
> +        - Mic Bias 2 # Used for Sub Mic or Digimic1
> +
> +required:
> +  - compatible
> +  - ti,model
> +  - ti,mcbsp
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    sound {
> +        compatible = "ti,omap-twl4030";
> +        ti,model = "omap3beagle";
> +        ti,mcbsp = <&mcbsp2>;
> +    };
> -- 
> 2.39.5
>

On Tue, Aug 12, 2025 at 12:47:38AM +0200, Jihed Chaibi wrote:

> Convert the legacy TXT binding for the OMAP TWL4030 sound card
> to the modern YAML DT schema format. This adds formal validation
> and improves documentation.

Acked-by: Mark Brown <broonie@kernel.org>

Please submit patches using subject lines reflecting the style for the
subsystem, this makes it easier for people to identify relevant patches.
Look at what existing commits in the area you're changing are doing and
make sure your subject lines visually resemble what they're doing.
There's no need to resubmit to fix this alone.