[PATCH 0/3] ASoC: dt-bindings: Document routing strings for various codecs

[PATCH 0/3] ASoC: dt-bindings: Document routing strings for various codecs

[Jihed Chaibi]

This patch series addresses a challenge for developers configuring ASoC
audio cards in the device tree. Discovering the valid routing strings for
a codec often requires reading the C driver source, which is inefficient,
error-prone, and creates a high barrier to entry.

To improve this, this series adds the lists of these strings (which
correspond to the driver's DAPM widget names) to the descriptions of
three popular audio codec bindings. This makes the documentation more
self-contained and improves the user experience for anyone doing board
bring-up.

While this series adds the documentation as plain text, a potential
future enhancement could be defining these strings as a formal enum
in the binding. This would allow for automated checking and further
improve robustness.

Jihed Chaibi (3):
  ASoC: dt-bindings: everest,es8316: Document routing strings
  ASoC: dt-bindings: nau8825: Document routing strings
  ASoC: dt-bindings: wlf,wm8960: Document routing strings (pin names)

 .../bindings/sound/everest,es8316.yaml        | 14 ++++++++++++
 .../bindings/sound/nuvoton,nau8825.yaml       | 12 ++++++++++
 .../devicetree/bindings/sound/wlf,wm8960.yaml | 22 +++++++++++++++++++
 3 files changed, 48 insertions(+)

-- 
2.39.5

[PATCH 1/3] ASoC: dt-bindings: everest,es8316: Document routing strings

[Jihed Chaibi]

The es8316 driver defines several DAPM widget names that are used for
audio routing in the device tree. However, these strings are not
documented in the binding file.

This forces developers to read the C source to discover the valid
names, which can be inefficient and error-prone.

Add a list of the input and output widget names to the binding's
description to make it self-contained and improve the user
experience for board bring-up.

Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
---
 .../devicetree/bindings/sound/everest,es8316.yaml  | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.yaml b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
index e4b2eb5fa..cd073dd0c 100644
--- a/Documentation/devicetree/bindings/sound/everest,es8316.yaml
+++ b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
@@ -12,6 +12,20 @@ maintainers:
   - Matteo Martelli <matteomartelli3@gmail.com>
   - Binbin Zhou <zhoubinbin@loongson.cn>
 
+description: |
+  Everest ES8311, ES8316 and ES8323 audio CODECs
+
+  Valid routing names defined in the driver for this codec include:
+
+    Outputs:
+      * HPOL: Left Headphone Output
+      * HPOR: Right Headphone Output
+
+    Inputs:
+      * DMIC: Digital Microphone Input
+      * MIC1: Analog Microphone Input 1
+      * MIC2: Analog Microphone Input 2
+
 allOf:
   - $ref: dai-common.yaml#
 
-- 
2.39.5

Re: [PATCH 1/3] ASoC: dt-bindings: everest,es8316: Document routing strings

[Krzysztof Kozlowski]

On 09/08/2025 17:18, Jihed Chaibi wrote:
> The es8316 driver defines several DAPM widget names that are used for
> audio routing in the device tree. However, these strings are not
> documented in the binding file.
> 
> This forces developers to read the C source to discover the valid
> names, which can be inefficient and error-prone.

Reading free form text is as inefficient and error-prone as reading the
driver.

> 
> Add a list of the input and output widget names to the binding's
> description to make it self-contained and improve the user
> experience for board bring-up.
> 
> Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
> ---
>  .../devicetree/bindings/sound/everest,es8316.yaml  | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.yaml b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
> index e4b2eb5fa..cd073dd0c 100644
> --- a/Documentation/devicetree/bindings/sound/everest,es8316.yaml
> +++ b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
> @@ -12,6 +12,20 @@ maintainers:
>    - Matteo Martelli <matteomartelli3@gmail.com>
>    - Binbin Zhou <zhoubinbin@loongson.cn>
>  
> +description: |
> +  Everest ES8311, ES8316 and ES8323 audio CODECs
> +
> +  Valid routing names defined in the driver for this codec include:

Anyway, don't describe drivers but hardware.

Best regards,
Krzysztof

Re: [PATCH 1/3] ASoC: dt-bindings: everest,es8316: Document routing strings

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 697 bytes --]

On Tue, Aug 12, 2025 at 09:40:20AM +0200, Krzysztof Kozlowski wrote:
> On 09/08/2025 17:18, Jihed Chaibi wrote:
> > The es8316 driver defines several DAPM widget names that are used for
> > audio routing in the device tree. However, these strings are not
> > documented in the binding file.

> > This forces developers to read the C source to discover the valid
> > names, which can be inefficient and error-prone.

> Reading free form text is as inefficient and error-prone as reading the
> driver.

On the one hand, yes.  On the other hand this is better than what we had
before so seems useful.  Ideally at some point someone will add a
binding for this but that's a much bigger piece of work.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH 1/3] ASoC: dt-bindings: everest,es8316: Document routing strings

[Krzysztof Kozlowski]

On Tue, Aug 12, 2025 at 12:05:55PM +0100, Mark Brown wrote:
> On Tue, Aug 12, 2025 at 09:40:20AM +0200, Krzysztof Kozlowski wrote:
> > On 09/08/2025 17:18, Jihed Chaibi wrote:
> > > The es8316 driver defines several DAPM widget names that are used for
> > > audio routing in the device tree. However, these strings are not
> > > documented in the binding file.
> 
> > > This forces developers to read the C source to discover the valid
> > > names, which can be inefficient and error-prone.
> 
> > Reading free form text is as inefficient and error-prone as reading the
> > driver.
> 
> On the one hand, yes.  On the other hand this is better than what we had
> before so seems useful.  Ideally at some point someone will add a
> binding for this but that's a much bigger piece of work.

Fair enough. Jihed, please send v2 with descriptions referring rather to
pins or device, instead of the driver. Even though you took them from
driver, people would just copy-paste this description later for their
new drivers...

Best regards,
Krzysztof

[PATCH 2/3] ASoC: dt-bindings: nau8825: Document routing strings

[Jihed Chaibi]

The nau8825 driver defines several DAPM widget names that are used for
audio routing in the Device Tree. However, these strings are not
documented in the binding file.

This forces developers to read the C source to discover the valid
names, which can be inefficient and error-prone.

Add a list of the input and output widget names to the binding's
description to make it self-contained and improve the user
experience for board bring-up.

Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
---
 .../devicetree/bindings/sound/nuvoton,nau8825.yaml   | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
index a54f194a0..cb1c82aa3 100644
--- a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
+++ b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
@@ -9,6 +9,18 @@ title: NAU8825 audio CODEC
 maintainers:
   - John Hsu <KCHSU0@nuvoton.com>
 
+description: |
+  NAU8825 audio CODEC
+
+  Valid routing names defined in the driver for this codec include:
+
+    Outputs:
+      * HPOL : Left Headphone Output
+      * HPOR : Right Headphone Output
+
+    Inputs:
+      * MIC : Microphone Input
+
 allOf:
   - $ref: dai-common.yaml#
 
-- 
2.39.5

Re: [PATCH 2/3] ASoC: dt-bindings: nau8825: Document routing strings

[Krzysztof Kozlowski]

On 09/08/2025 17:18, Jihed Chaibi wrote:
> The nau8825 driver defines several DAPM widget names that are used for
> audio routing in the Device Tree. However, these strings are not
> documented in the binding file.
> 
> This forces developers to read the C source to discover the valid
> names, which can be inefficient and error-prone.

Reading snd_soc_dapm_route can be automatize/scripted, so I don't
consider it error prone or difficult, comparing to reading free form
text in any documentation.

> 
> Add a list of the input and output widget names to the binding's
> description to make it self-contained and improve the user
> experience for board bring-up.
> 
> Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
> ---
>  .../devicetree/bindings/sound/nuvoton,nau8825.yaml   | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> index a54f194a0..cb1c82aa3 100644
> --- a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> +++ b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> @@ -9,6 +9,18 @@ title: NAU8825 audio CODEC
>  maintainers:
>    - John Hsu <KCHSU0@nuvoton.com>
>  
> +description: |
> +  NAU8825 audio CODEC
> +
> +  Valid routing names defined in the driver for this codec include:
Describe pins on the device or device properties instead.

Best regards,
Krzysztof

[PATCH 3/3] ASoC: dt-bindings: wlf,wm8960: Document routing strings (pin names)

[Jihed Chaibi]

The wm8960 driver defines several DAPM widget names that are used for
audio routing in the Device Tree. However, these strings are not
documented in the binding file.

This forces developers to read the C source to discover the valid
names, which can be inefficient and error-prone.

Add a list of the input and output widget names to the binding's
description to make it self-contained and improve the user
experience for board bring-up.

Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
---
 .../devicetree/bindings/sound/wlf,wm8960.yaml | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml
index 3c2b9790f..c8c786cb6 100644
--- a/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml
@@ -9,6 +9,28 @@ title: Wolfson WM8960 audio codec
 maintainers:
   - patches@opensource.cirrus.com
 
+description: |
+  Wolfson WM8960 audio codec
+
+  Pins on the device (for linking into audio routes):
+
+    Outputs:
+      * HP_L    : Left Headphone/Line Output
+      * HP_R    : Right Headphone/Line Output
+      * SPK_LP  : Left Speaker Output (Positive)
+      * SPK_LN  : Left Speaker Output (Negative)
+      * SPK_RP  : Right Speaker Output (Positive)
+      * SPK_RN  : Right Speaker Output (Negative)
+      * OUT3    : Mono, Left, Right or buffered midrail output for capless mode
+
+    Inputs:
+      * LINPUT1 : Left single-ended or negative differential microphone input
+      * RINPUT1 : Right single-ended or negative differential microphone input
+      * LINPUT2 : Left line input or positive differential microphone input
+      * RINPUT2 : Right line input or positive differential microphone input
+      * LINPUT3 : Left line input, positive differential microphone, or Jack Detect 2
+      * RINPUT3 : Right line input, positive differential microphone, or Jack Detect 3
+
 properties:
   compatible:
     const: wlf,wm8960
-- 
2.39.5