[PATCH] ASoC: dt-bindings: fsl-sai: Convert to YAML DT schema

[PATCH] ASoC: dt-bindings: fsl-sai: Convert to YAML DT schema

[Marek Vasut]

Convert the SAI bindings to YAML DT schema to permit validation.
Add Shengjiu as maintainer, derived from sound/soc/fsl/fsl_sai.c
get_maintainer result.

Describe existing used combinations of compatible strings, add the
missing imx7d-sai compatible string which is used on i.MX7 .

Properties lsb-first, fsl,sai-synchronous-rx, fsl,sai-asynchronous,
fsl,dataline are no longer listed as required, since those are clearly
optional, even the description says so, so does their usage.

Fix the undefined edma channel macro per arch/arm/boot/dts/vfxxx.dtsi ,
use the value itself just like in the vfxxx.dtsi .

Document interrupts property, which was previously undocumented, but
it is required property of this IP.

Document #sound-sai-cells, which should be zero for this IP.

Document fsl,imx6ul-iomuxc-gpr and its dependency on MX6UL and
fsl,sai-mclk-direction-output .

Signed-off-by: Marek Vasut <marex@denx.de>
---
Cc: Fabio Estevam <festevam@gmail.com>
Cc: Jaroslav Kysela <perex@perex.cz>
Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>
Cc: Liam Girdwood <lgirdwood@gmail.com>
Cc: Mark Brown <broonie@kernel.org>
Cc: Nicolin Chen <nicoleotsuka@gmail.com>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Shengjiu Wang <shengjiu.wang@gmail.com>
Cc: Takashi Iwai <tiwai@suse.com>
Cc: Xiubo Li <Xiubo.Lee@gmail.com>
Cc: alsa-devel@alsa-project.org
To: devicetree@vger.kernel.org
---
 .../devicetree/bindings/sound/fsl-sai.yaml    | 188 ++++++++++++++++++
 1 file changed, 188 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/fsl-sai.yaml

diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.yaml b/Documentation/devicetree/bindings/sound/fsl-sai.yaml
new file mode 100644
index 0000000000000..e6620a127f419
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/fsl-sai.yaml
@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/fsl-sai.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Synchronous Audio Interface (SAI).
+
+maintainers:
+  - Shengjiu Wang <shengjiu.wang@gmail.com>
+
+description:
+  The SAI is based on I2S module that used communicating with audio
+  codecs, which provides a synchronous audio interface that supports
+  fullduplex serial interfaces with frame synchronization such as I2S,
+  AC97, TDM, and codec/DSP interfaces.
+
+properties:
+  compatible:
+    oneOf:
+      - items:
+          - enum:
+              - fsl,imx6ul-sai
+              - fsl,imx7d-sai
+          - const: fsl,imx6sx-sai
+
+      - items:
+          - enum:
+              - fsl,imx8mm-sai
+              - fsl,imx8mn-sai
+              - fsl,imx8mp-sai
+          - const: fsl,imx8mq-sai
+
+      - items:
+          - enum:
+              - fsl,imx6sx-sai
+              - fsl,imx7ulp-sai
+              - fsl,imx8mq-sai
+              - fsl,imx8qm-sai
+              - fsl,imx8ulp-sai
+              - fsl,vf610-sai
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    minItems: 4
+    maxItems: 6
+
+  clock-names:
+    minItems: 4
+    items:
+      - const: bus
+      - const: mclk1
+      - const: mclk2
+      - const: mclk3
+      - const: pll8k
+      - const: pll11k
+
+  dmas:
+    maxItems: 2
+
+  dma-names:
+    items:
+      - const: tx
+      - const: rx
+
+  interrupts:
+    maxItems: 1
+
+  lsb-first:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      Configures whether the LSB or the MSB is transmitted first for the
+      fifo data. If this property is absent, the MSB is transmitted first
+      as default, or the LSB is transmitted first.
+
+  fsl,sai-synchronous-rx:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      This is a boolean property. If present, indicating that SAI will
+      work in the synchronous mode (sync Tx with Rx) which means both
+      the transmitter and the receiver will send and receive data by
+      following receiver's bit clocks and frame sync clocks.
+      If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are
+      absent, the default synchronous mode (sync Rx with Tx) will
+      be used, which means both transmitter and receiver will send
+      and receive data by following clocks of transmitter.
+      fsl,sai-asynchronous and fsl,sai-synchronous-rx are exclusive.
+
+  fsl,sai-asynchronous:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      If present, indicating that SAI will work in the asynchronous
+      mode, which means both transmitter and receiver will send and
+      receive data by following their own bit clocks and frame sync
+      clocks separately.
+      If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are
+      absent, the default synchronous mode (sync Rx with Tx) will
+      be used, which means both transmitter and receiver will send
+      and receive data by following clocks of transmitter.
+      fsl,sai-asynchronous and fsl,sai-synchronous-rx are exclusive.
+
+  fsl,dataline:
+    $ref: /schemas/types.yaml#/definitions/uint8-array
+    description: |
+      Configure the dataline. It has 3 values for each configuration:
+      first one means the type: I2S(1) or PDM(2)
+      second one is dataline mask for 'rx'
+      third one is dataline mask for 'tx'.
+      for example: fsl,dataline = <1 0xff 0xff 2 0xff 0x11>;
+      means I2S type rx mask is 0xff, tx mask is 0xff, PDM type
+      rx mask is 0xff, tx mask is 0x11 (dataline 1 and 4 enabled).
+
+  fsl,sai-mclk-direction-output:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      If present, indicates that SAI will output the SAI MCLK clock.
+
+  fsl,imx6ul-iomuxc-gpr:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: Phandle to MX6UL IOMUXC GPR shared register file.
+
+  big-endian:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+     Required if all the SAI registers are big-endian rather
+     than little-endian.
+
+  "#sound-dai-cells":
+    const: 0
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - dmas
+  - dma-names
+  - interrupts
+
+unevaluatedProperties: false
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - fsl,imx6ul-sai
+    then:
+      dependencies:
+        fsl,imx6ul-iomuxc-gpr: [ "fsl,sai-mclk-direction-output" ]
+
+  - if:
+      not:
+        properties:
+          compatible:
+            contains:
+              enum:
+                - fsl,imx6ul-sai
+                - fsl,imx8mm-sai
+                - fsl,imx8mn-sai
+                - fsl,imx8mp-sai
+                - fsl,imx8mq-sai
+    then:
+      properties:
+        fsl,sai-mclk-direction-output: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/vf610-clock.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    sai@40031000 {
+      compatible = "fsl,vf610-sai";
+      reg = <0x40031000 0x1000>;
+      interrupts = <86 IRQ_TYPE_LEVEL_HIGH>;
+      pinctrl-names = "default";
+      pinctrl-0 = <&pinctrl_sai2_1>;
+      clocks = <&clks VF610_CLK_PLATFORM_BUS>, <&clks VF610_CLK_SAI2>,
+               <&clks 0>, <&clks 0>;
+      clock-names = "bus", "mclk1", "mclk2", "mclk3";
+      dma-names = "tx", "rx";
+      dmas = <&edma0 0 21>, <&edma0 0 20>;
+      big-endian;
+      lsb-first;
+    };
-- 
2.35.1

Re: [PATCH] ASoC: dt-bindings: fsl-sai: Convert to YAML DT schema

[Rob Herring]

On Thu, 03 Nov 2022 19:20:16 +0100, Marek Vasut wrote:
> Convert the SAI bindings to YAML DT schema to permit validation.
> Add Shengjiu as maintainer, derived from sound/soc/fsl/fsl_sai.c
> get_maintainer result.
> 
> Describe existing used combinations of compatible strings, add the
> missing imx7d-sai compatible string which is used on i.MX7 .
> 
> Properties lsb-first, fsl,sai-synchronous-rx, fsl,sai-asynchronous,
> fsl,dataline are no longer listed as required, since those are clearly
> optional, even the description says so, so does their usage.
> 
> Fix the undefined edma channel macro per arch/arm/boot/dts/vfxxx.dtsi ,
> use the value itself just like in the vfxxx.dtsi .
> 
> Document interrupts property, which was previously undocumented, but
> it is required property of this IP.
> 
> Document #sound-sai-cells, which should be zero for this IP.
> 
> Document fsl,imx6ul-iomuxc-gpr and its dependency on MX6UL and
> fsl,sai-mclk-direction-output .
> 
> Signed-off-by: Marek Vasut <marex@denx.de>
> ---
> Cc: Fabio Estevam <festevam@gmail.com>
> Cc: Jaroslav Kysela <perex@perex.cz>
> Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>
> Cc: Liam Girdwood <lgirdwood@gmail.com>
> Cc: Mark Brown <broonie@kernel.org>
> Cc: Nicolin Chen <nicoleotsuka@gmail.com>
> Cc: Rob Herring <robh+dt@kernel.org>
> Cc: Shengjiu Wang <shengjiu.wang@gmail.com>
> Cc: Takashi Iwai <tiwai@suse.com>
> Cc: Xiubo Li <Xiubo.Lee@gmail.com>
> Cc: alsa-devel@alsa-project.org
> To: devicetree@vger.kernel.org
> ---
>  .../devicetree/bindings/sound/fsl-sai.yaml    | 188 ++++++++++++++++++
>  1 file changed, 188 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/sound/fsl-sai.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: fsl,dataline:0: [1, 255, 255, 2, 255, 17] is too long
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: clock-names:1: 'mclk1' was expected
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: clock-names:2: 'mclk2' was expected
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: clock-names:3: 'mclk3' was expected
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: clock-names:4: 'pll8k' was expected
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: dma-names:0: 'tx' was expected
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: dma-names:1: 'rx' was expected
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: fsl,dataline: size is 32, expected 8
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl,sai.example.dtb: sai@30010000: Unevaluated properties are not allowed ('clock-names', 'dma-names', 'fsl,dataline' were unexpected)
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/fsl-sai.yaml

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.

Re: [PATCH] ASoC: dt-bindings: fsl-sai: Convert to YAML DT schema

[Marek Vasut]

On 11/4/22 09:11, Shengjiu Wang wrote:
> On Fri, Nov 4, 2022 at 2:20 AM Marek Vasut <marex@denx.de> wrote:
> 
>> Convert the SAI bindings to YAML DT schema to permit validation.
>> Add Shengjiu as maintainer, derived from sound/soc/fsl/fsl_sai.c
>> get_maintainer result.
>>
>> Describe existing used combinations of compatible strings, add the
>> missing imx7d-sai compatible string which is used on i.MX7 .
>>
>> Properties lsb-first, fsl,sai-synchronous-rx, fsl,sai-asynchronous,
>> fsl,dataline are no longer listed as required, since those are clearly
>> optional, even the description says so, so does their usage.
>>
>> Fix the undefined edma channel macro per arch/arm/boot/dts/vfxxx.dtsi ,
>> use the value itself just like in the vfxxx.dtsi .
>>
>> Document interrupts property, which was previously undocumented, but
>> it is required property of this IP.
>>
>> Document #sound-sai-cells, which should be zero for this IP.
>>
>> Document fsl,imx6ul-iomuxc-gpr and its dependency on MX6UL and
>> fsl,sai-mclk-direction-output .
>>
>> Signed-off-by: Marek Vasut <marex@denx.de>
>> ---
>> Cc: Fabio Estevam <festevam@gmail.com>
>> Cc: Jaroslav Kysela <perex@perex.cz>
>> Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>
>> Cc: Liam Girdwood <lgirdwood@gmail.com>
>> Cc: Mark Brown <broonie@kernel.org>
>> Cc: Nicolin Chen <nicoleotsuka@gmail.com>
>> Cc: Rob Herring <robh+dt@kernel.org>
>> Cc: Shengjiu Wang <shengjiu.wang@gmail.com>
>> Cc: Takashi Iwai <tiwai@suse.com>
>> Cc: Xiubo Li <Xiubo.Lee@gmail.com>
>> Cc: alsa-devel@alsa-project.org
>> To: devicetree@vger.kernel.org
>> ---
>>   .../devicetree/bindings/sound/fsl-sai.yaml    | 188 ++++++++++++++++++
>>
> 
> Documentation/devicetree/bindings/sound/fsl,sai.yaml
> I have done conversion. If there is any update/change, please send patch
> base on it.

I noticed that, thanks for that. I'll see if there is anything left to do.