Skip to contentSkip to conversation

ASoC: dt-bindings: Document routing strings for various codecs

PATCH Superseded Jihed Chaibi 3 participants 8 messages Aug 9, 2025 – Sep 2, 2025

Subsystems (4)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover ASoC: dt-bindings: Document routing strings for various codecs

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(+)
Signature · 1 line
2.39.5
#1 lore raw

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

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.

---
 .../devicetree/bindings/sound/everest,es8316.yaml  | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
Documentation/devicetree/bindings/sound/everest,es8316.yaml +14 -0
index e4b2eb5fa..cd073dd0c 100644
@@ -12,6 +12,20 @@ maintainers:
   - Matteo Martelli <[email protected]>
   - Binbin Zhou <[email protected]>
 
+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#
 
Signature · 1 line
2.39.5
#2 lore raw

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

Quoted 6 lines · 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.

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

Quoted 15 lines

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.

---
 .../devicetree/bindings/sound/everest,es8316.yaml  | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
Documentation/devicetree/bindings/sound/everest,es8316.yaml +0 -0
index e4b2eb5fa..cd073dd0c 100644

Documentation/devicetree/bindings/sound/everest,es8316.yaml maintainers: · line 18

Quoted 7 lines
Documentation/devicetree/bindings/sound/everest,es8316.yaml +4 -0
@@ -12,6 +12,20 @@ maintainers:
   - Matteo Martelli <[email protected]>
   - Binbin Zhou <[email protected]>
 
+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

maintainer
#3 lore raw

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

Quoted 10 lines · Krzysztof Kozlowski
Quoted 6 lines · 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.

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.

#4 lore raw

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

Quoted 9 lines · Mark Brown
Quoted 7 lines · Krzysztof Kozlowski
Quoted 6 lines · 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.

Quoted 6 lines
Quoted 2 lines

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

#5 lore raw

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

In reply to 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.

---
 .../devicetree/bindings/sound/nuvoton,nau8825.yaml   | 12 ++++++++++++
 1 file changed, 12 insertions(+)
Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml +12 -0
index a54f194a0..cb1c82aa3 100644
@@ -9,6 +9,18 @@ title: NAU8825 audio CODEC
 maintainers:
   - John Hsu <[email protected]>
 
+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#
 
Signature · 1 line
2.39.5
#6 lore raw

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

Quoted 6 lines · 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.

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.

Quoted 15 lines

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.

---
 .../devicetree/bindings/sound/nuvoton,nau8825.yaml   | 12 ++++++++++++
 1 file changed, 12 insertions(+)
Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml +0 -0
index a54f194a0..cb1c82aa3 100644

Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml title: NAU8825 audio CODEC · line 15

Quoted 7 lines
Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml +4 -0
@@ -9,6 +9,18 @@ title: NAU8825 audio CODEC
 maintainers:
   - John Hsu <[email protected]>
 
+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

#7 lore raw

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

In reply to 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.

---
 .../devicetree/bindings/sound/wlf,wm8960.yaml | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
Documentation/devicetree/bindings/sound/wlf,wm8960.yaml +22 -0
index 3c2b9790f..c8c786cb6 100644
@@ -9,6 +9,28 @@ title: Wolfson WM8960 audio codec
 maintainers:
   - [email protected]
 
+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
Signature · 1 line
2.39.5