[PATCH] ASoC: dt-bindings: audio-graph-card: Expand 'widgets' documentation

[PATCH] ASoC: dt-bindings: audio-graph-card: Expand 'widgets' documentation

[Marek Vasut]

Document the encoding of 'widgets' property to avoid confusion.

Signed-off-by: Marek Vasut <marex@denx.de>
---
Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>
Cc: Kuninori Morimoto <kuninori.morimoto.gx@renesas.com>
Cc: Liam Girdwood <lgirdwood@gmail.com>
Cc: Mark Brown <broonie@kernel.org>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: alsa-devel@alsa-project.org
Cc: devicetree@vger.kernel.org
---
 Documentation/devicetree/bindings/sound/audio-graph.yaml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/sound/audio-graph.yaml b/Documentation/devicetree/bindings/sound/audio-graph.yaml
index c87eb91de1593..ed31e04ff6a68 100644
--- a/Documentation/devicetree/bindings/sound/audio-graph.yaml
+++ b/Documentation/devicetree/bindings/sound/audio-graph.yaml
@@ -24,7 +24,11 @@ properties:
       connection's sink, the second being the connection's source.
     $ref: /schemas/types.yaml#/definitions/non-unique-string-array
   widgets:
-    description: User specified audio sound widgets.
+    description: |
+      User specified audio sound widgets.
+      Each entry is a pair of strings, the first being the type of
+      widget ("Microphone", "Line", "Headphone", "Speaker"), the
+      second being the machine specific name for the widget.
     $ref: /schemas/types.yaml#/definitions/non-unique-string-array
   convert-rate:
     $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate
-- 
2.39.2

Re: [PATCH] ASoC: dt-bindings: audio-graph-card: Expand 'widgets' documentation

[Mark Brown]

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

On Tue, Jun 06, 2023 at 07:59:51PM +0200, Marek Vasut wrote:

> Document the encoding of 'widgets' property to avoid confusion.

>    widgets:
> -    description: User specified audio sound widgets.
> +    description: |
> +      User specified audio sound widgets.
> +      Each entry is a pair of strings, the first being the type of
> +      widget ("Microphone", "Line", "Headphone", "Speaker"), the
> +      second being the machine specific name for the widget.

This looks sensible to me, I don't know if there's a way we can get the
tooling to validate either the length or (ideally) the widget type
strings?

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

Re: [PATCH] ASoC: dt-bindings: audio-graph-card: Expand 'widgets' documentation

[Mark Brown]

On Tue, 06 Jun 2023 19:59:51 +0200, Marek Vasut wrote:
> Document the encoding of 'widgets' property to avoid confusion.
> 
> 

Applied to

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git for-next

Thanks!

[1/1] ASoC: dt-bindings: audio-graph-card: Expand 'widgets' documentation
      commit: 7077b1864ca8f0d616c497b3ee890d72d1da0a26

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark

Re: [PATCH] ASoC: dt-bindings: audio-graph-card: Expand 'widgets' documentation

[Marek Vasut]

On 6/6/23 20:25, Mark Brown wrote:
> On Tue, Jun 06, 2023 at 07:59:51PM +0200, Marek Vasut wrote:
> 
>> Document the encoding of 'widgets' property to avoid confusion.
> 
>>     widgets:
>> -    description: User specified audio sound widgets.
>> +    description: |
>> +      User specified audio sound widgets.
>> +      Each entry is a pair of strings, the first being the type of
>> +      widget ("Microphone", "Line", "Headphone", "Speaker"), the
>> +      second being the machine specific name for the widget.
> 
> This looks sensible to me, I don't know if there's a way we can get the
> tooling to validate either the length or (ideally) the widget type
> strings?

It seems there is no way to do validation of every two elements for 
lists with variable number of elements.