Re: [PATCH 7/8] sound: dt-bindings: ti,omap-twl4030: convert to DT schema

[Rob Herring <robh@kernel.org>]

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
>