Re: [PATCH 19/22] ASoC: dt-bindings: mt8192: Document audio-routing and dai-link subnode

[Rob Herring <robh@kernel.org>]

On Tue, Feb 27, 2024 at 01:09:36PM +0100, AngeloGioacchino Del Regno wrote:
> Document the dai-link subnodes and the audio-routing property, allowing
> to describe machine specific audio hardware and links in device tree.
> 
> While at it, also deprecate the old properties which were previously
> used with the driver's partially hardcoded configuration.
> 
> Signed-off-by: AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
> ---
>  .../sound/mt8192-mt6359-rt1015-rt5682.yaml    | 129 ++++++++++++++++--
>  1 file changed, 121 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml
> index 7e50f5d65c8f..78e221003750 100644
> --- a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml
> +++ b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml
> @@ -20,6 +20,15 @@ properties:
>        - mediatek,mt8192_mt6359_rt1015p_rt5682
>        - mediatek,mt8192_mt6359_rt1015p_rt5682s
>  
> +  audio-routing:
> +    $ref: /schemas/types.yaml#/definitions/non-unique-string-array

Already defined in sound-card-common.yaml. Add a $ref.

> +    description:
> +      A list of the 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.
> +      Valid names could be the input or output widgets of audio components,
> +      power supplies, MicBias of codec and the software switch.

Generally the names are defined here.

> +
>    mediatek,platform:
>      $ref: /schemas/types.yaml#/definitions/phandle
>      description: The phandle of MT8192 ASoC platform.
> @@ -27,10 +36,12 @@ properties:
>    mediatek,hdmi-codec:
>      $ref: /schemas/types.yaml#/definitions/phandle
>      description: The phandle of HDMI codec.
> +    deprecated: true
>  
>    headset-codec:
>      type: object
>      additionalProperties: false
> +    deprecated: true
>  
>      properties:
>        sound-dai:
> @@ -41,6 +52,7 @@ properties:
>    speaker-codecs:
>      type: object
>      additionalProperties: false
> +    deprecated: true
>  
>      properties:
>        sound-dai:
> @@ -51,13 +63,83 @@ properties:
>      required:
>        - sound-dai
>  
> +patternProperties:
> +  ".*-dai-link$":
> +    type: object
> +    description:
> +      Container for dai-link level properties and CODEC sub-nodes.
> +
> +    properties:
> +      link-name:
> +        description: Indicates dai-link name and PCM stream name
> +        items:
> +          enum:
> +            - I2S0
> +            - I2S1
> +            - I2S2
> +            - I2S3
> +            - I2S4
> +            - I2S5
> +            - I2S6
> +            - I2S7
> +            - I2S8
> +            - I2S9
> +            - TDM
> +
> +      codec:
> +        description: Holds subnode which indicates codec dai.
> +        type: object
> +        additionalProperties: false
> +        properties:
> +          sound-dai:
> +            minItems: 1
> +            maxItems: 2
> +        required:
> +          - sound-dai
> +
> +      dai-format:
> +        description: audio format
> +        items:
> +          enum:
> +            - i2s
> +            - right_j
> +            - left_j
> +            - dsp_a
> +            - dsp_b
> +
> +      mediatek,clk-provider:
> +        $ref: /schemas/types.yaml#/definitions/string
> +        description: Indicates dai-link clock master.
> +        items:
> +          enum:
> +            - cpu
> +            - codec
> +
> +    additionalProperties: false

Move this before properties.

> +
> +    required:
> +      - link-name
> +
>  additionalProperties: false
>  
>  required:
>    - compatible
>    - mediatek,platform
> -  - headset-codec
> -  - speaker-codecs
> +
> +allOf:
> +  # Disallow dai-link-xxx nodes if the legacy properties are specified

xxx-dai-link?

> +  - if:
> +      patternProperties:
> +        ".*-dai-link$": false
> +    then:
> +      required:
> +        - headset-codec
> +        - speaker-codecs
> +    else:
> +      properties:
> +        headset-codec: false
> +        speaker-codecs: false
> +        mediatek,hdmi-codec: false

Allowing both would preserve compatibility. That's not needed? If so, 
say why in the commit msg.

>  
>  examples:
>    - |
> @@ -65,19 +147,50 @@ examples:
>      sound: mt8192-sound {
>          compatible = "mediatek,mt8192_mt6359_rt1015_rt5682";
>          mediatek,platform = <&afe>;
> -        mediatek,hdmi-codec = <&anx_bridge_dp>;
>          pinctrl-names = "aud_clk_mosi_off",
>                          "aud_clk_mosi_on";
>          pinctrl-0 = <&aud_clk_mosi_off>;
>          pinctrl-1 = <&aud_clk_mosi_on>;
>  
> -        headset-codec {
> -            sound-dai = <&rt5682>;
> +        audio-routing =
> +                "Headphone Jack", "HPOL",
> +                "Headphone Jack", "HPOR",
> +                "IN1P", "Headset Mic",
> +                "Speakers", "Speaker";
> +
> +        spk-playback-dai-link {
> +                link-name = "I2S3";
> +                dai-format = "i2s";
> +                mediatek,clk-provider = "cpu";
> +                codec {
> +                        sound-dai = <&rt1015p>;
> +                };
> +        };
> +
> +        hs-playback-dai-link {
> +                link-name = "I2S8";
> +                dai-format = "i2s";
> +                mediatek,clk-provider = "cpu";
> +                codec {
> +                        sound-dai = <&rt5682 0>;
> +                };
> +        };
> +
> +        hs-capture-dai-link {
> +                link-name = "I2S9";
> +                dai-format = "i2s";
> +                mediatek,clk-provider = "cpu";
> +                codec {
> +                        sound-dai = <&rt5682 0>;
> +                };
>          };
>  
> -        speaker-codecs {
> -            sound-dai = <&rt1015_l>,
> -                        <&rt1015_r>;
> +        displayport-dai-link {
> +                link-name = "TDM";
> +                dai-format = "dsp_a";
> +                codec {
> +                        sound-dai = <&anx_bridge_dp>;
> +                };
>          };
>      };
>  
> -- 
> 2.44.0
>