[v4,11/15] ASoC: dt-bindings: tegra: Add json-schema for Tegra audio graph card

Add YAML schema for Tegra audio graph sound card DT bindings. It uses the
same DT bindings provided by generic audio graph driver. Along with this
few standard clock DT bindings are added which are specifically required
for Tegra audio.

Signed-off-by: Sameer Pujar <spujar@nvidia.com>
---
 .../sound/nvidia,tegra-audio-graph-card.yaml       | 158 +++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml

On Fri, Oct 16, 2020 at 08:12:58PM +0530, Sameer Pujar wrote:
> Add YAML schema for Tegra audio graph sound card DT bindings. It uses the
> same DT bindings provided by generic audio graph driver. Along with this
> few standard clock DT bindings are added which are specifically required
> for Tegra audio.
> 
> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
> ---
>  .../sound/nvidia,tegra-audio-graph-card.yaml       | 158 +++++++++++++++++++++
>  1 file changed, 158 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
> 
> diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
> new file mode 100644
> index 0000000..284d185
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
> @@ -0,0 +1,158 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-graph-card.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Audio Graph based Tegra sound card driver
> +
> +description: |
> +  This is based on generic audio graph card driver along with additional
> +  customizations for Tegra platforms. It uses the same bindings with
> +  additional standard clock DT bindings required for Tegra.
> +
> +  See{LINUX}/Documentation/devicetree/bindings/sound/audio-graph-card.yaml

You should be able to just $ref this at the top level.

> +
> +maintainers:
> +  - Jon Hunter <jonathanh@nvidia.com>
> +  - Sameer Pujar <spujar@nvidia.com>
> +
> +properties:
> +  compatible:
> +    items:
> +      - enum:
> +          - nvidia,tegra210-audio-graph-card
> +          - nvidia,tegra186-audio-graph-card
> +

> +  dais:
> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/dais
> +
> +  label:
> +    $ref: /schemas/sound/simple-card.yaml#/properties/label
> +
> +  pa-gpios:
> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/pa-gpios
> +
> +  widgets:
> +    $ref: /schemas/sound/simple-card.yaml#/definitions/widgets
> +
> +  routing:
> +    $ref: /schemas/sound/simple-card.yaml#/definitions/routing
> +
> +  mclk-fs:
> +    $ref: /schemas/sound/simple-card.yaml#/definitions/mclk-fs
> +
> +  prefix:
> +    $ref: /schemas/sound/simple-card.yaml#/definitions/prefix

And drop all of these.

> +
> +  clocks:
> +   minItems: 2
> +
> +  clock-names:
> +   minItems: 2

Don't need this.

> +   items:
> +     - const: pll_a
> +     - const: plla_out0
> +
> +  assigned-clocks:
> +    minItems: 1
> +    maxItems: 3
> +
> +  assigned-clock-parents:
> +    minItems: 1
> +    maxItems: 3
> +
> +  assigned-clock-rates:
> +    minItems: 1
> +    maxItems: 3
> +
> +  ports:
> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/ports
> +
> +patternProperties:
> +  "^port(@[0-9a-f]+)?$":
> +    $ref: /schemas/sound/audio-graph-card.yaml#/definitions/port

And these can be dropped. Unless what each port is is Tegra specific.

> +
> +additionalProperties: false
> +
> +required:
> +  - compatible
> +  - dais
> +  - clocks
> +  - clock-names
> +  - assigned-clocks
> +  - assigned-clock-parents
> +
> +examples:
> +  - |
> +    #include<dt-bindings/clock/tegra210-car.h>
> +
> +    tegra_sound {
> +        compatible = "nvidia,tegra210-audio-graph-card";
> +
> +        clocks = <&tegra_car TEGRA210_CLK_PLL_A>,
> +                 <&tegra_car TEGRA210_CLK_PLL_A_OUT0>;
> +        clock-names = "pll_a", "plla_out0";
> +
> +        assigned-clocks = <&tegra_car TEGRA210_CLK_PLL_A>,
> +                          <&tegra_car TEGRA210_CLK_PLL_A_OUT0>,
> +                          <&tegra_car TEGRA210_CLK_EXTERN1>;
> +        assigned-clock-parents = <0>, <0>, <&tegra_car TEGRA210_CLK_PLL_A_OUT0>;
> +        assigned-clock-rates = <368640000>, <49152000>, <12288000>;
> +
> +        dais = /* FE */
> +               <&admaif1_port>,
> +               /* Router */
> +               <&xbar_i2s1_port>,
> +               /* I/O DAP Ports */
> +               <&i2s1_port>;
> +
> +        label = "jetson-tx1-ape";
> +    };
> +
> +    tegra_ahub: ahub@702d0800 {
> +        // ...
> +
> +        reg = <0x702d0800 0x800>;
> +
> +        ports {
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            xbar_i2s1_port: port@a {
> +                reg = <0xa>;
> +                xbar_i2s1_ep: endpoint {
> +                    remote-endpoint = <&i2s1_cif_ep>;
> +                };
> +            };
> +        };
> +    };
> +
> +    tegra_i2s1: i2s@702d1000 {
> +        // ...
> +
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        reg = <0x702d1000 0x100>;
> +
> +        port@0 {
> +            reg = <0>;
> +
> +            i2s1_cif_ep: endpoint {
> +                remote-endpoint = <&xbar_i2s1_ep>;
> +            };
> +        };
> +
> +        i2s1_port: port@1 {
> +            reg = <1>;
> +
> +            i2s1_dap: endpoint {
> +                dai-format = "i2s";
> +
> +                // ...
> +            };
> +        };
> +    };
> +
> +...
> -- 
> 2.7.4
>

>> Add YAML schema for Tegra audio graph sound card DT bindings. It uses the
>> same DT bindings provided by generic audio graph driver. Along with this
>> few standard clock DT bindings are added which are specifically required
>> for Tegra audio.
>>
>> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
>> ---
>>   .../sound/nvidia,tegra-audio-graph-card.yaml       | 158 +++++++++++++++++++++
>>   1 file changed, 158 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
>> new file mode 100644
>> index 0000000..284d185
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
>> @@ -0,0 +1,158 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-graph-card.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Audio Graph based Tegra sound card driver
>> +
>> +description: |
>> +  This is based on generic audio graph card driver along with additional
>> +  customizations for Tegra platforms. It uses the same bindings with
>> +  additional standard clock DT bindings required for Tegra.
>> +
>> +  See{LINUX}/Documentation/devicetree/bindings/sound/audio-graph-card.yaml
> You should be able to just $ref this at the top level.

I am seeing one problem while using $ref like below.
allOf:
   - $ref: /schemas/sound/audio-graph-card.yaml

I see below while running doc validator.
"Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.example.dt.yaml: 
tegra_sound: compatible:0: 'audio-graph-card' was expected"

Is there a way to avoid this?

>
>> +
>> +maintainers:
>> +  - Jon Hunter <jonathanh@nvidia.com>
>> +  - Sameer Pujar <spujar@nvidia.com>
>> +
>> +properties:
>> +  compatible:
>> +    items:
>> +      - enum:
>> +          - nvidia,tegra210-audio-graph-card
>> +          - nvidia,tegra186-audio-graph-card
>> +

>> +  dais:
>> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/dais
>> +
>> +  label:
>> +    $ref: /schemas/sound/simple-card.yaml#/properties/label
>> +
>> +  pa-gpios:
>> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/pa-gpios
>> +
>> +  widgets:
>> +    $ref: /schemas/sound/simple-card.yaml#/definitions/widgets
>> +
>> +  routing:
>> +    $ref: /schemas/sound/simple-card.yaml#/definitions/routing
>> +
>> +  mclk-fs:
>> +    $ref: /schemas/sound/simple-card.yaml#/definitions/mclk-fs
>> +
>> +  prefix:
>> +    $ref: /schemas/sound/simple-card.yaml#/definitions/prefix
> And drop all of these.

Could not re-use because of above compatible problem. Also require some 
additional properties for Tegra.

>> +
>> +  clocks:
>> +   minItems: 2
>> +
>> +  clock-names:
>> +   minItems: 2
> Don't need this.

This is required for Tegra audio graph card to update clock rates at 
runtime.

>
>> +   items:
>> +     - const: pll_a
>> +     - const: plla_out0
>> +
>> +  assigned-clocks:
>> +    minItems: 1
>> +    maxItems: 3
>> +
>> +  assigned-clock-parents:
>> +    minItems: 1
>> +    maxItems: 3
>> +
>> +  assigned-clock-rates:
>> +    minItems: 1
>> +    maxItems: 3
>> +

It is required for initialisation of above clocks with specific rates.

>> +  ports:
>> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/ports
>> +
>> +patternProperties:
>> +  "^port(@[0-9a-f]+)?$":
>> +    $ref: /schemas/sound/audio-graph-card.yaml#/definitions/port
> And these can be dropped. Unless what each port is is Tegra specific.

May be I can drop this if I could just directly include 
audio-graph-card.yaml and extend required properties for Tegra.

On Tue, Oct 20, 2020 at 1:16 AM Sameer Pujar <spujar@nvidia.com> wrote:
>
>
> >> Add YAML schema for Tegra audio graph sound card DT bindings. It uses the
> >> same DT bindings provided by generic audio graph driver. Along with this
> >> few standard clock DT bindings are added which are specifically required
> >> for Tegra audio.
> >>
> >> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
> >> ---
> >>   .../sound/nvidia,tegra-audio-graph-card.yaml       | 158 +++++++++++++++++++++
> >>   1 file changed, 158 insertions(+)
> >>   create mode 100644 Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
> >>
> >> diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
> >> new file mode 100644
> >> index 0000000..284d185
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml
> >> @@ -0,0 +1,158 @@
> >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> +%YAML 1.2
> >> +---
> >> +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-graph-card.yaml#
> >> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> +
> >> +title: Audio Graph based Tegra sound card driver
> >> +
> >> +description: |
> >> +  This is based on generic audio graph card driver along with additional
> >> +  customizations for Tegra platforms. It uses the same bindings with
> >> +  additional standard clock DT bindings required for Tegra.
> >> +
> >> +  See{LINUX}/Documentation/devicetree/bindings/sound/audio-graph-card.yaml
> > You should be able to just $ref this at the top level.
>
> I am seeing one problem while using $ref like below.
> allOf:
>    - $ref: /schemas/sound/audio-graph-card.yaml
>
> I see below while running doc validator.
> "Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.example.dt.yaml:
> tegra_sound: compatible:0: 'audio-graph-card' was expected"
>
> Is there a way to avoid this?

Adjust the schemas so the constraints match. You can't say it must be
one thing in one place and something else here. Your choices are:

- Drop compatible from audio-graph-card.yaml. You can define a 2nd
schema that references audio-graph-card.yaml and defines the
compatible.
- Use 'contains' in audio-graph-card.yaml and then make
'audio-graph-card' a fallback here.

The best option depends on what existing users have.

> >> +maintainers:
> >> +  - Jon Hunter <jonathanh@nvidia.com>
> >> +  - Sameer Pujar <spujar@nvidia.com>
> >> +
> >> +properties:
> >> +  compatible:
> >> +    items:
> >> +      - enum:
> >> +          - nvidia,tegra210-audio-graph-card
> >> +          - nvidia,tegra186-audio-graph-card
> >> +
>
> >> +  dais:
> >> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/dais
> >> +
> >> +  label:
> >> +    $ref: /schemas/sound/simple-card.yaml#/properties/label
> >> +
> >> +  pa-gpios:
> >> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/pa-gpios
> >> +
> >> +  widgets:
> >> +    $ref: /schemas/sound/simple-card.yaml#/definitions/widgets
> >> +
> >> +  routing:
> >> +    $ref: /schemas/sound/simple-card.yaml#/definitions/routing
> >> +
> >> +  mclk-fs:
> >> +    $ref: /schemas/sound/simple-card.yaml#/definitions/mclk-fs
> >> +
> >> +  prefix:
> >> +    $ref: /schemas/sound/simple-card.yaml#/definitions/prefix
> > And drop all of these.
>
> Could not re-use because of above compatible problem. Also require some
> additional properties for Tegra.
>
> >> +
> >> +  clocks:
> >> +   minItems: 2
> >> +
> >> +  clock-names:
> >> +   minItems: 2
> > Don't need this.
>
> This is required for Tegra audio graph card to update clock rates at
> runtime.

I mean you can drop 'minItems: 2' as it is redundant. The 'items' list
size implies the size.

> >> +   items:
> >> +     - const: pll_a
> >> +     - const: plla_out0
> >> +
> >> +  assigned-clocks:
> >> +    minItems: 1
> >> +    maxItems: 3
> >> +
> >> +  assigned-clock-parents:
> >> +    minItems: 1
> >> +    maxItems: 3
> >> +
> >> +  assigned-clock-rates:
> >> +    minItems: 1
> >> +    maxItems: 3
> >> +
>
> It is required for initialisation of above clocks with specific rates.
>
> >> +  ports:
> >> +    $ref: /schemas/sound/audio-graph-card.yaml#/properties/ports
> >> +
> >> +patternProperties:
> >> +  "^port(@[0-9a-f]+)?$":
> >> +    $ref: /schemas/sound/audio-graph-card.yaml#/definitions/port
> > And these can be dropped. Unless what each port is is Tegra specific.
>
> May be I can drop this if I could just directly include
> audio-graph-card.yaml and extend required properties for Tegra.

There are numerous examples of doing that.

Rob