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

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

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.

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