[PATCH v3 0/3] Convert name-prefix doc to json-schema

[PATCH v3 0/3] Convert name-prefix doc to json-schema

[Sameer Pujar]

Following are the changes:
  - Add json-schema for 'sound-name-prefix' documentation under
    'name-perfix.yaml'
  - Use schema references wherever needed.
  - Remove txt based doc


Changelog
=========

v2 -> v3
--------
 * Removed examples in patch 1/3 as suggested by Rob
 * Added reviewed tag from Jerome for the series
 * Added reviewed tag from Rob for patch 2/3

v1 -> v2
--------
 * Provide top reference to name-prefix.yaml as suggested by Rob
   for patch 2/3
 * Dropped couple of unreachable email ids from Cc list in commit
   message of patch 2/3
 * No changes in remaining patches

Sameer Pujar (3):
  ASoC: Add json-schema documentation for sound-name-prefix
  ASoC: Use schema reference for sound-name-prefix
  ASoC: Remove name-prefix.txt

 .../devicetree/bindings/sound/name-prefix.txt      | 24 ----------------------
 .../devicetree/bindings/sound/name-prefix.yaml     | 21 +++++++++++++++++++
 .../bindings/sound/nvidia,tegra186-dspk.yaml       |  9 +++-----
 .../bindings/sound/nvidia,tegra210-dmic.yaml       |  9 +++-----
 .../bindings/sound/nvidia,tegra210-i2s.yaml        |  9 +++-----
 .../devicetree/bindings/sound/nxp,tfa989x.yaml     |  9 +++-----
 Documentation/devicetree/bindings/sound/rt5659.txt |  2 +-
 .../bindings/sound/simple-audio-mux.yaml           |  9 +++-----
 8 files changed, 37 insertions(+), 55 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/name-prefix.txt
 create mode 100644 Documentation/devicetree/bindings/sound/name-prefix.yaml

-- 
2.7.4

[PATCH v3 1/3] ASoC: Add json-schema documentation for sound-name-prefix

[Sameer Pujar]

The 'sound-name-prefix' is used to prepend suitable strings to a
component widgets or controls. This is helpful when there are
multiple instances of the same component. Add relevant json-schema
and is inspired from sound-name-prefix.txt documentation.

Signed-off-by: Sameer Pujar <spujar@nvidia.com>
Cc: Jerome Brunet <jbrunet@baylibre.com>
Cc: Rob Herring <robh+dt@kernel.org>
Reviewed-by: Jerome Brunet <jbrunet@baylibre.com>
---
 .../devicetree/bindings/sound/name-prefix.yaml      | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/name-prefix.yaml

diff --git a/Documentation/devicetree/bindings/sound/name-prefix.yaml b/Documentation/devicetree/bindings/sound/name-prefix.yaml
new file mode 100644
index 00000000..2fe57f8
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/name-prefix.yaml
@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/name-prefix.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Component sound name prefix
+
+maintainers:
+  - Jerome Brunet <jbrunet@baylibre.com>
+
+properties:
+  sound-name-prefix:
+    $ref: /schemas/types.yaml#/definitions/string
+    description: |
+      Card implementing the routing property define the connection between
+      audio components as list of string pair. Component using the same
+      sink/source names may use this property to prepend the name of their
+      sinks/sources with the provided string.
+
+additionalProperties: true
-- 
2.7.4

[PATCH v3 2/3] ASoC: Use schema reference for sound-name-prefix

[Sameer Pujar]

Use schema reference for 'sound-name-prefix' property wherever
necessary.

Signed-off-by: Sameer Pujar <spujar@nvidia.com>
Cc: Jerome Brunet <jbrunet@baylibre.com>
Cc: Stephan Gerhold <stephan@gerhold.net>
Cc: Rob Herring <robh+dt@kernel.org>
Reviewed-by: Jerome Brunet <jbrunet@baylibre.com>
Reviewed-by: Rob Herring <robh@kernel.org>
---
 .../devicetree/bindings/sound/nvidia,tegra186-dspk.yaml          | 9 +++------
 .../devicetree/bindings/sound/nvidia,tegra210-dmic.yaml          | 9 +++------
 Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml | 9 +++------
 Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml         | 9 +++------
 Documentation/devicetree/bindings/sound/rt5659.txt               | 2 +-
 Documentation/devicetree/bindings/sound/simple-audio-mux.yaml    | 9 +++------
 6 files changed, 16 insertions(+), 31 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml
index 5f6b37c..0912d3e 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml
@@ -17,6 +17,9 @@ maintainers:
   - Jon Hunter <jonathanh@nvidia.com>
   - Sameer Pujar <spujar@nvidia.com>
 
+allOf:
+  - $ref: name-prefix.yaml#
+
 properties:
   $nodename:
     pattern: "^dspk@[0-9a-f]*$"
@@ -48,12 +51,6 @@ properties:
 
   sound-name-prefix:
     pattern: "^DSPK[1-9]$"
-    $ref: /schemas/types.yaml#/definitions/string
-    description:
-      Used as prefix for sink/source names of the component. Must be a
-      unique string among multiple instances of the same component.
-      The name can be "DSPK1" or "DSPKx", where x depends on the maximum
-      available instances on a Tegra SoC.
 
   ports:
     $ref: /schemas/graph.yaml#/properties/ports
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml
index fd275a5..62db982 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml
@@ -16,6 +16,9 @@ maintainers:
   - Jon Hunter <jonathanh@nvidia.com>
   - Sameer Pujar <spujar@nvidia.com>
 
+allOf:
+  - $ref: name-prefix.yaml#
+
 properties:
   $nodename:
     pattern: "^dmic@[0-9a-f]*$"
@@ -49,12 +52,6 @@ properties:
 
   sound-name-prefix:
     pattern: "^DMIC[1-9]$"
-    $ref: /schemas/types.yaml#/definitions/string
-    description:
-      used as prefix for sink/source names of the component. Must be a
-      unique string among multiple instances of the same component.
-      The name can be "DMIC1" or "DMIC2" ... "DMICx", where x depends
-      on the maximum available instances on a Tegra SoC.
 
   ports:
     $ref: /schemas/graph.yaml#/properties/ports
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml
index 6337070..f954be6 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml
@@ -16,6 +16,9 @@ maintainers:
   - Jon Hunter <jonathanh@nvidia.com>
   - Sameer Pujar <spujar@nvidia.com>
 
+allOf:
+  - $ref: name-prefix.yaml#
+
 properties:
   $nodename:
     pattern: "^i2s@[0-9a-f]*$"
@@ -65,12 +68,6 @@ properties:
 
   sound-name-prefix:
     pattern: "^I2S[1-9]$"
-    $ref: /schemas/types.yaml#/definitions/string
-    description:
-      Used as prefix for sink/source names of the component. Must be a
-      unique string among multiple instances of the same component.
-      The name can be "I2S1" or "I2S2" ... "I2Sx", where x depends
-      on the maximum available instances on a Tegra SoC.
 
   ports:
     $ref: /schemas/graph.yaml#/properties/ports
diff --git a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
index ffb8fcf..68e5ad2 100644
--- a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
+++ b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
@@ -9,6 +9,9 @@ title: NXP/Goodix TFA989X (TFA1) Audio Amplifiers
 maintainers:
   - Stephan Gerhold <stephan@gerhold.net>
 
+allOf:
+  - $ref: name-prefix.yaml#
+
 properties:
   compatible:
     enum:
@@ -21,12 +24,6 @@ properties:
   '#sound-dai-cells':
     const: 0
 
-  sound-name-prefix:
-    $ref: /schemas/types.yaml#/definitions/string
-    description:
-      Used as prefix for sink/source names of the component. Must be a
-      unique string among multiple instances of the same component.
-
   vddd-supply:
     description: regulator phandle for the VDDD power supply.
 
diff --git a/Documentation/devicetree/bindings/sound/rt5659.txt b/Documentation/devicetree/bindings/sound/rt5659.txt
index c473df5..013f534 100644
--- a/Documentation/devicetree/bindings/sound/rt5659.txt
+++ b/Documentation/devicetree/bindings/sound/rt5659.txt
@@ -42,7 +42,7 @@ Optional properties:
 - realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin.
 - realtek,reset-gpios : The GPIO that controls the CODEC's RESET pin.
 
-- sound-name-prefix: Please refer to name-prefix.txt
+- sound-name-prefix: Please refer to name-prefix.yaml
 
 - ports: A Codec may have a single or multiple I2S interfaces. These
   interfaces on Codec side can be described under 'ports' or 'port'.
diff --git a/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml b/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml
index 5986d1f..c597d9d 100644
--- a/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml
+++ b/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml
@@ -13,6 +13,9 @@ description: |
   Simple audio multiplexers are driven using gpios, allowing to select which of
   their input line is connected to the output line.
 
+allOf:
+  - $ref: name-prefix.yaml#
+
 properties:
   compatible:
     const: simple-audio-mux
@@ -21,12 +24,6 @@ properties:
     description: |
       GPIOs used to select the input line.
 
-  sound-name-prefix:
-    $ref: /schemas/types.yaml#/definitions/string
-    description:
-      Used as prefix for sink/source names of the component. Must be a
-      unique string among multiple instances of the same component.
-
 required:
   - compatible
   - mux-gpios
-- 
2.7.4

[PATCH v3 3/3] ASoC: Remove name-prefix.txt

[Sameer Pujar]

Since schema name-prefix.yaml is available and references are updated,
remove txt based doc.

Signed-off-by: Sameer Pujar <spujar@nvidia.com>
Cc: Jerome Brunet <jbrunet@baylibre.com>
Cc: Rob Herring <robh+dt@kernel.org>
Reviewed-by: Jerome Brunet <jbrunet@baylibre.com>
---
 .../devicetree/bindings/sound/name-prefix.txt      | 24 ----------------------
 1 file changed, 24 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/name-prefix.txt

diff --git a/Documentation/devicetree/bindings/sound/name-prefix.txt b/Documentation/devicetree/bindings/sound/name-prefix.txt
deleted file mode 100644
index 6457759..00000000
--- a/Documentation/devicetree/bindings/sound/name-prefix.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-Name prefix:
-
-Card implementing the routing property define the connection between
-audio components as list of string pair. Component using the same
-sink/source names may use the name prefix property to prepend the
-name of their sinks/sources with the provided string.
-
-Optional name prefix property:
-- sound-name-prefix : string using as prefix for the sink/source names of
-		      the component.
-
-Example: Two instances of the same component.
-
-amp0: analog-amplifier@0 {
-	compatible = "simple-audio-amplifier";
-	enable-gpios = <&gpio GPIOH_3 0>;
-	sound-name-prefix = "FRONT";
-};
-
-amp1: analog-amplifier@1 {
-	compatible = "simple-audio-amplifier";
-	enable-gpios = <&gpio GPIOH_4 0>;
-	sound-name-prefix = "BACK";
-};
-- 
2.7.4

Re: [PATCH v3 1/3] ASoC: Add json-schema documentation for sound-name-prefix

[Rob Herring]

On Fri, 03 Sep 2021 22:05:17 +0530, Sameer Pujar wrote:
> The 'sound-name-prefix' is used to prepend suitable strings to a
> component widgets or controls. This is helpful when there are
> multiple instances of the same component. Add relevant json-schema
> and is inspired from sound-name-prefix.txt documentation.
> 
> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
> Cc: Jerome Brunet <jbrunet@baylibre.com>
> Cc: Rob Herring <robh+dt@kernel.org>
> Reviewed-by: Jerome Brunet <jbrunet@baylibre.com>
> ---
>  .../devicetree/bindings/sound/name-prefix.yaml      | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/sound/name-prefix.yaml
> 

Reviewed-by: Rob Herring <robh@kernel.org>

Re: [PATCH v3 3/3] ASoC: Remove name-prefix.txt

[Rob Herring]

On Fri, 03 Sep 2021 22:05:19 +0530, Sameer Pujar wrote:
> Since schema name-prefix.yaml is available and references are updated,
> remove txt based doc.
> 
> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
> Cc: Jerome Brunet <jbrunet@baylibre.com>
> Cc: Rob Herring <robh+dt@kernel.org>
> Reviewed-by: Jerome Brunet <jbrunet@baylibre.com>
> ---
>  .../devicetree/bindings/sound/name-prefix.txt      | 24 ----------------------
>  1 file changed, 24 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/sound/name-prefix.txt
> 

Acked-by: Rob Herring <robh@kernel.org>

Re: [PATCH v3 0/3] Convert name-prefix doc to json-schema

[Mark Brown]

On Fri, 3 Sep 2021 22:05:16 +0530, Sameer Pujar wrote:
> Following are the changes:
>   - Add json-schema for 'sound-name-prefix' documentation under
>     'name-perfix.yaml'
>   - Use schema references wherever needed.
>   - Remove txt based doc
> 
> 
> [...]

Applied to

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

Thanks!

[1/3] ASoC: Add json-schema documentation for sound-name-prefix
      commit: 7f826da8e924bae7dd56b99e3760514017ca51a3
[2/3] ASoC: Use schema reference for sound-name-prefix
      commit: 82d3ec1d89fa2750fdc74e2f29c6c7ff673a2768
[3/3] ASoC: Remove name-prefix.txt
      commit: 955cc3488e6d407bac3883be630cabbead0892f4

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 v3 2/3] ASoC: Use schema reference for sound-name-prefix

[Rob Herring]

On Fri, Sep 3, 2021 at 11:36 AM Sameer Pujar <spujar@nvidia.com> wrote:
>
> Use schema reference for 'sound-name-prefix' property wherever
> necessary.
>
> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
> Cc: Jerome Brunet <jbrunet@baylibre.com>
> Cc: Stephan Gerhold <stephan@gerhold.net>
> Cc: Rob Herring <robh+dt@kernel.org>
> Reviewed-by: Jerome Brunet <jbrunet@baylibre.com>
> Reviewed-by: Rob Herring <robh@kernel.org>
> ---

[...]

> diff --git a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
> index ffb8fcf..68e5ad2 100644
> --- a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
> +++ b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
> @@ -9,6 +9,9 @@ title: NXP/Goodix TFA989X (TFA1) Audio Amplifiers
>  maintainers:
>    - Stephan Gerhold <stephan@gerhold.net>
>
> +allOf:
> +  - $ref: name-prefix.yaml#
> +
>  properties:
>    compatible:
>      enum:
> @@ -21,12 +24,6 @@ properties:
>    '#sound-dai-cells':
>      const: 0
>
> -  sound-name-prefix:

You can't remove the property. This is now a warning in linux-next:

Documentation/devicetree/bindings/sound/nxp,tfa989x.example.dt.yaml:
audio-codec@34: 'sound-name-prefix' does not match any of the regexes:
'pinctrl-[0-9]+'
 From schema: /builds/robherring/linux-dt/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
Documentation/devicetree/bindings/sound/nxp,tfa989x.example.dt.yaml:
audio-codec@36: 'sound-name-prefix' does not match any of the regexes:
'pinctrl-[0-9]+'
 From schema: /builds/robherring/linux-dt/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml


Just 'sound-name-prefix: true' is fine

> -    $ref: /schemas/types.yaml#/definitions/string
> -    description:
> -      Used as prefix for sink/source names of the component. Must be a
> -      unique string among multiple instances of the same component.
> -
>    vddd-supply:
>      description: regulator phandle for the VDDD power supply.
>
> diff --git a/Documentation/devicetree/bindings/sound/rt5659.txt b/Documentation/devicetree/bindings/sound/rt5659.txt
> index c473df5..013f534 100644
> --- a/Documentation/devicetree/bindings/sound/rt5659.txt
> +++ b/Documentation/devicetree/bindings/sound/rt5659.txt
> @@ -42,7 +42,7 @@ Optional properties:
>  - realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin.
>  - realtek,reset-gpios : The GPIO that controls the CODEC's RESET pin.
>
> -- sound-name-prefix: Please refer to name-prefix.txt
> +- sound-name-prefix: Please refer to name-prefix.yaml
>
>  - ports: A Codec may have a single or multiple I2S interfaces. These
>    interfaces on Codec side can be described under 'ports' or 'port'.
> diff --git a/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml b/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml
> index 5986d1f..c597d9d 100644
> --- a/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml
> +++ b/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml
> @@ -13,6 +13,9 @@ description: |
>    Simple audio multiplexers are driven using gpios, allowing to select which of
>    their input line is connected to the output line.
>
> +allOf:
> +  - $ref: name-prefix.yaml#
> +
>  properties:
>    compatible:
>      const: simple-audio-mux
> @@ -21,12 +24,6 @@ properties:
>      description: |
>        GPIOs used to select the input line.
>
> -  sound-name-prefix:

Here too, but I guess we don't have any example to throw a warning?

Re: [PATCH v3 2/3] ASoC: Use schema reference for sound-name-prefix

[Sameer Pujar]

On 9/20/2021 6:27 PM, Rob Herring wrote:
> External email: Use caution opening links or attachments
>
>
> On Fri, Sep 3, 2021 at 11:36 AM Sameer Pujar <spujar@nvidia.com> wrote:
>> Use schema reference for 'sound-name-prefix' property wherever
>> necessary.
>>
>> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
>> Cc: Jerome Brunet <jbrunet@baylibre.com>
>> Cc: Stephan Gerhold <stephan@gerhold.net>
>> Cc: Rob Herring <robh+dt@kernel.org>
>> Reviewed-by: Jerome Brunet <jbrunet@baylibre.com>
>> Reviewed-by: Rob Herring <robh@kernel.org>
>> ---
> [...]
>
>> diff --git a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
>> index ffb8fcf..68e5ad2 100644
>> --- a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
>> +++ b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
>> @@ -9,6 +9,9 @@ title: NXP/Goodix TFA989X (TFA1) Audio Amplifiers
>>   maintainers:
>>     - Stephan Gerhold <stephan@gerhold.net>
>>
>> +allOf:
>> +  - $ref: name-prefix.yaml#
>> +
>>   properties:
>>     compatible:
>>       enum:
>> @@ -21,12 +24,6 @@ properties:
>>     '#sound-dai-cells':
>>       const: 0
>>
>> -  sound-name-prefix:
> You can't remove the property. This is now a warning in linux-next:
>
> Documentation/devicetree/bindings/sound/nxp,tfa989x.example.dt.yaml:
> audio-codec@34: 'sound-name-prefix' does not match any of the regexes:
> 'pinctrl-[0-9]+'
>   From schema: /builds/robherring/linux-dt/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
> Documentation/devicetree/bindings/sound/nxp,tfa989x.example.dt.yaml:
> audio-codec@36: 'sound-name-prefix' does not match any of the regexes:
> 'pinctrl-[0-9]+'
>   From schema: /builds/robherring/linux-dt/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml
>
>
> Just 'sound-name-prefix: true' is fine

I will push a fix for this.