Re: [PATCH 1/8] mfd: dt-bindings: ti,twl4030-audio: convert to DT schema

[Rob Herring]

On Tue, Aug 12, 2025 at 12:47:32AM +0200, Jihed Chaibi wrote:
> Convert the legacy TXT binding for the TWL4030 audio module
> to the modern YAML DT schema format. This adds formal validation
> and improves documentation.
> 
> Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@xxxxxxxxx>
> ---
>  .../bindings/mfd/ti,twl4030-audio.yaml        | 91 +++++++++++++++++++
>  .../devicetree/bindings/mfd/twl4030-audio.txt | 46 ----------

Shouldn't this move to bindings/sound/?

>  2 files changed, 91 insertions(+), 46 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/mfd/ti,twl4030-audio.yaml
>  delete mode 100644 Documentation/devicetree/bindings/mfd/twl4030-audio.txt
> 
> diff --git a/Documentation/devicetree/bindings/mfd/ti,twl4030-audio.yaml b/Documentation/devicetree/bindings/mfd/ti,twl4030-audio.yaml
> new file mode 100644
> index 000000000..16ddcf007
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/ti,twl4030-audio.yaml
> @@ -0,0 +1,91 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/ti,twl4030-audio.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments TWL4030-family Audio Module
> +
> +maintainers:
> +  - Peter Ujfalusi <peter.ujfalusi@xxxxxxxxx>
> +
> +description: |

Don't need '|' if no formatting to preserve.

> +  The audio module within the TWL4030-family of companion chips consists
> +  of an audio codec and a vibra driver. This binding describes the parent
> +  node for these functions.
> +
> +properties:
> +  compatible:
> +    const: ti,twl4030-audio
> +
> +  codec:
> +    type: object
> +    description: Node containing properties for the audio codec functionality.

       additionalProperties: false

and a blank line here.

> +    properties:
> +      ti,digimic_delay:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Delay in milliseconds after enabling digital microphones to reduce
> +          artifacts.
> +
> +      ti,ramp_delay_value:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Headset ramp delay configuration to reduce pop noise.
> +
> +      ti,hs_extmute:
> +        type: boolean
> +        description:
> +          Enable the use of an external mute for headset pop reduction.
> +
> +      ti,hs_extmute_gpio:
> +        $ref: /schemas/types.yaml#/definitions/phandle-array
> +        description:
> +          The GPIO specifier for the external mute control.
> +        maxItems: 1
> +
> +      ti,offset_cncl_path:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Offset cancellation path selection. Refer to the Technical
> +          Reference Manual for valid values.

Constraints for any of these properties?

> +
> +    # The 'codec' node itself is optional, but if it exists, it can be empty.
> +    # We don't require any of its sub-properties.
> +
> +  ti,enable-vibra:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: |
> +      Set to 1 to enable the vibra functionality, if missing
> +      or it is 0, the vibra functionality is disabled.

Sounds like constraints. Don't write constraints in prose.

> +
> +additionalProperties: false
> +
> +required:
> +  - compatible
> +
> +examples:
> +  - |
> +    i2c {
> +
> +      clock-frequency = <2600000>;

Drop. Not relevant to this binding.

> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      twl: twl@48 {
> +        reg = <0x48>;
> +        interrupts = <7>; /* SYS_NIRQ cascaded to intc */
> +        interrupt-parent = <&intc>;
> +
> +        twl_audio: audio {
> +          compatible = "ti,twl4030-audio";
> +
> +          ti,enable-vibra = <1>;
> +
> +          codec {
> +            ti,ramp_delay_value = <3>;
> +          };
> +
> +        };
> +      };
> +    };