ASoC: dt-bindings: Document routing strings for various codecs
Subsystems (4)
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
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
@@ -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
PATCH 2/3 ASoC: dt-bindings: nau8825: Document routing strings
In reply to Jihed ChaibiThe 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
@@ -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
PATCH 3/3 ASoC: dt-bindings: wlf,wm8960: Document routing strings (pin names)
In reply to Jihed ChaibiThe 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
@@ -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
Re: [PATCH 1/3] ASoC: dt-bindings: everest,es8316: Document routing strings
In reply to Jihed ChaibiQuoted 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.
Signed-off-by Jihed Chaibi <[email protected]>--- .../devicetree/bindings/sound/everest,es8316.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+)Documentation/devicetree/bindings/sound/everest,es8316.yaml +0
-0
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
Re: [PATCH 2/3] ASoC: dt-bindings: nau8825: Document routing strings
In reply to Jihed ChaibiQuoted 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.
Signed-off-by Jihed Chaibi <[email protected]>--- .../devicetree/bindings/sound/nuvoton,nau8825.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+)Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml +0
-0
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
Mark Brown
maintainerRe: [PATCH 1/3] ASoC: dt-bindings: everest,es8316: Document routing strings
In reply to Krzysztof KozlowskiQuoted 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.
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