[PATCH v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[PATCH v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[Frank Li]

Convert fsl,esai.txt to yaml. So DTB_CHECK tools can verify dts file about
esai part.

clock-names 'spba' is optional according to description. So minItems of
clocks and clock-names is 3.

Signed-off-by: Frank Li <Frank.Li@nxp.com>
---

Notes:
    Change from v1 to v2
    - alphabetical order compatible string according to rob's suggestion
    - clock description move under 'clock' according to kryszof's suggestion
    - fix descritpion indent according to rob's suggestion
    
    Pass dt_binding check
     make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j8  dt_binding_check DT_SCHEMA_FILES=fsl,esai.yaml
      DTEX    Documentation/devicetree/bindings/sound/fsl,esai.example.dts
      LINT    Documentation/devicetree/bindings
      CHKDT   Documentation/devicetree/bindings/processed-schema.json
      SCHEMA  Documentation/devicetree/bindings/processed-schema.json
      DTC_CHK Documentation/devicetree/bindings/sound/fsl,esai.example.dtb

 .../devicetree/bindings/sound/fsl,esai.txt    |  68 ----------
 .../devicetree/bindings/sound/fsl,esai.yaml   | 116 ++++++++++++++++++
 2 files changed, 116 insertions(+), 68 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/fsl,esai.txt
 create mode 100644 Documentation/devicetree/bindings/sound/fsl,esai.yaml

diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt
deleted file mode 100644
index 90112ca1ff423..0000000000000
--- a/Documentation/devicetree/bindings/sound/fsl,esai.txt
+++ /dev/null
@@ -1,68 +0,0 @@
-Freescale Enhanced Serial Audio Interface (ESAI) Controller
-
-The Enhanced Serial Audio Interface (ESAI) provides a full-duplex serial port
-for serial communication with a variety of serial devices, including industry
-standard codecs, Sony/Phillips Digital Interface (S/PDIF) transceivers, and
-other DSPs. It has up to six transmitters and four receivers.
-
-Required properties:
-
-  - compatible		: Compatible list, should contain one of the following
-			  compatibles:
-			  "fsl,imx35-esai",
-			  "fsl,vf610-esai",
-			  "fsl,imx6ull-esai",
-			  "fsl,imx8qm-esai",
-
-  - reg			: Offset and length of the register set for the device.
-
-  - interrupts		: Contains the spdif interrupt.
-
-  - dmas		: Generic dma devicetree binding as described in
-			  Documentation/devicetree/bindings/dma/dma.txt.
-
-  - dma-names		: Two dmas have to be defined, "tx" and "rx".
-
-  - clocks		: Contains an entry for each entry in clock-names.
-
-  - clock-names		: Includes the following entries:
-	"core"		  The core clock used to access registers
-	"extal"		  The esai baud clock for esai controller used to
-			  derive HCK, SCK and FS.
-	"fsys"		  The system clock derived from ahb clock used to
-			  derive HCK, SCK and FS.
-	"spba"		  The spba clock is required when ESAI is placed as a
-			  bus slave of the Shared Peripheral Bus and when two
-			  or more bus masters (CPU, DMA or DSP) try to access
-			  it. This property is optional depending on the SoC
-			  design.
-
-  - fsl,fifo-depth	: The number of elements in the transmit and receive
-			  FIFOs. This number is the maximum allowed value for
-			  TFCR[TFWM] or RFCR[RFWM].
-
-  - fsl,esai-synchronous: This is a boolean property. If present, indicating
-			  that ESAI would work in the synchronous mode, which
-			  means all the settings for Receiving would be
-			  duplicated from Transmission related registers.
-
-Optional properties:
-
-  - big-endian		: If this property is absent, the native endian mode
-			  will be in use as default, or the big endian mode
-			  will be in use for all the device registers.
-
-Example:
-
-esai: esai@2024000 {
-	compatible = "fsl,imx35-esai";
-	reg = <0x02024000 0x4000>;
-	interrupts = <0 51 0x04>;
-	clocks = <&clks 208>, <&clks 118>, <&clks 208>;
-	clock-names = "core", "extal", "fsys";
-	dmas = <&sdma 23 21 0>, <&sdma 24 21 0>;
-	dma-names = "rx", "tx";
-	fsl,fifo-depth = <128>;
-	fsl,esai-synchronous;
-	big-endian;
-};
diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.yaml b/Documentation/devicetree/bindings/sound/fsl,esai.yaml
new file mode 100644
index 0000000000000..f167f1634d7e3
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/fsl,esai.yaml
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/fsl,esai.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Enhanced Serial Audio Interface (ESAI) Controller
+
+maintainers:
+  - Shengjiu Wang <shengjiu.wang@nxp.com>
+  - Frank Li <Frank.Li@nxp.com>
+
+description:
+  The Enhanced Serial Audio Interface (ESAI) provides a full-duplex serial port
+  for serial communication with a variety of serial devices, including industry
+  standard codecs, Sony/Phillips Digital Interface (S/PDIF) transceivers, and
+  other DSPs. It has up to six transmitters and four receivers.
+
+properties:
+  compatible:
+    enum:
+      - fsl,imx35-esai
+      - fsl,imx6ull-esai
+      - fsl,imx8qm-esai
+      - fsl,vf610-esai
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    minItems: 3
+    items:
+      - description:
+          The core clock used to access registers.
+      - description:
+          The esai baud clock for esai controller used to
+          derive HCK, SCK and FS.
+      - description:
+          The system clock derived from ahb clock used to
+          derive HCK, SCK and FS.
+      - description:
+          The spba clock is required when ESAI is placed as a
+          bus slave of the Shared Peripheral Bus and when two
+          or more bus masters (CPU, DMA or DSP) try to access
+          it. This property is optional depending on the SoC
+          design.
+
+  clock-names:
+    minItems: 3
+    items:
+      - const: core
+      - const: extal
+      - const: fsys
+      - const: spba
+
+  dmas:
+    minItems: 2
+    maxItems: 2
+
+  dma-names:
+    items:
+      - const: rx
+      - const: tx
+
+  fsl,fifo-depth:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      The number of elements in the transmit and receive
+      FIFOs. This number is the maximum allowed value for
+      TFCR[TFWM] or RFCR[RFWM].
+
+  fsl,esai-synchronous:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      This is a boolean property. If present, indicating
+      that ESAI would work in the synchronous mode, which
+      means all the settings for Receiving would be
+      duplicated from Transmission related registers.
+
+  big-endian:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      If this property is absent, the native endian mode
+      will be in use as default, or the big endian mode
+      will be in use for all the device registers.
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+  - dmas
+  - dma-names
+  - fsl,fifo-depth
+  - fsl,esai-synchronous
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    esai@2024000 {
+      compatible = "fsl,imx35-esai";
+      reg = <0x02024000 0x4000>;
+      interrupts = <0 51 0x04>;
+      clocks = <&clks 208>, <&clks 118>, <&clks 208>;
+      clock-names = "core", "extal", "fsys";
+      dmas = <&sdma 23 21 0>, <&sdma 24 21 0>;
+      dma-names = "rx", "tx";
+      fsl,fifo-depth = <128>;
+      fsl,esai-synchronous;
+      big-endian;
+    };
-- 
2.34.1

Re: [PATCH v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[Rob Herring]

On Fri, 22 Mar 2024 10:54:05 -0400, Frank Li wrote:
> Convert fsl,esai.txt to yaml. So DTB_CHECK tools can verify dts file about
> esai part.
> 
> clock-names 'spba' is optional according to description. So minItems of
> clocks and clock-names is 3.
> 
> Signed-off-by: Frank Li <Frank.Li@nxp.com>
> ---
> 
> Notes:
>     Change from v1 to v2
>     - alphabetical order compatible string according to rob's suggestion
>     - clock description move under 'clock' according to kryszof's suggestion
>     - fix descritpion indent according to rob's suggestion
> 
>     Pass dt_binding check
>      make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j8  dt_binding_check DT_SCHEMA_FILES=fsl,esai.yaml
>       DTEX    Documentation/devicetree/bindings/sound/fsl,esai.example.dts
>       LINT    Documentation/devicetree/bindings
>       CHKDT   Documentation/devicetree/bindings/processed-schema.json
>       SCHEMA  Documentation/devicetree/bindings/processed-schema.json
>       DTC_CHK Documentation/devicetree/bindings/sound/fsl,esai.example.dtb
> 
>  .../devicetree/bindings/sound/fsl,esai.txt    |  68 ----------
>  .../devicetree/bindings/sound/fsl,esai.yaml   | 116 ++++++++++++++++++
>  2 files changed, 116 insertions(+), 68 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/sound/fsl,esai.txt
>  create mode 100644 Documentation/devicetree/bindings/sound/fsl,esai.yaml
> 

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

Re: [PATCH v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[Mark Brown]

On Fri, 22 Mar 2024 10:54:05 -0400, Frank Li wrote:
> Convert fsl,esai.txt to yaml. So DTB_CHECK tools can verify dts file about
> esai part.
> 
> clock-names 'spba' is optional according to description. So minItems of
> clocks and clock-names is 3.
> 
> 
> [...]

Applied to

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

Thanks!

[1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml
      commit: 885dd75f41f9fff5b277bc6ab28ad798f98a37b4

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 v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[Rob Herring]

On Fri, Mar 22, 2024 at 9:54 AM Frank Li <Frank.Li@nxp.com> wrote:
>
> Convert fsl,esai.txt to yaml. So DTB_CHECK tools can verify dts file about
> esai part.
>
> clock-names 'spba' is optional according to description. So minItems of
> clocks and clock-names is 3.
>
> Signed-off-by: Frank Li <Frank.Li@nxp.com>
> ---
>
> Notes:
>     Change from v1 to v2
>     - alphabetical order compatible string according to rob's suggestion
>     - clock description move under 'clock' according to kryszof's suggestion
>     - fix descritpion indent according to rob's suggestion
>
>     Pass dt_binding check
>      make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j8  dt_binding_check DT_SCHEMA_FILES=fsl,esai.yaml
>       DTEX    Documentation/devicetree/bindings/sound/fsl,esai.example.dts
>       LINT    Documentation/devicetree/bindings
>       CHKDT   Documentation/devicetree/bindings/processed-schema.json
>       SCHEMA  Documentation/devicetree/bindings/processed-schema.json
>       DTC_CHK Documentation/devicetree/bindings/sound/fsl,esai.example.dtb

Did you run dtbs_check too? Probably not arm32 at least (first number
is number of warnings):

    218  esai@2024000: clocks: [[2, 208], [2, 209], [2, 118], [2,
208], [2, 156]] is too long
    218  esai@2024000: clock-names:3: 'spba' was expected
    218  esai@2024000: clock-names:2: 'fsys' was expected
    218  esai@2024000: clock-names:1: 'extal' was expected
    218  esai@2024000: clock-names: ['core', 'mem', 'extal', 'fsys',
'spba'] is too long

Conversions can leave warnings, but any you think should be fixed in
the binding should be fixed in the conversion.

Rob

Re: [PATCH v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[Frank Li]

On Tue, Apr 09, 2024 at 12:26:52PM -0500, Rob Herring wrote:
> On Fri, Mar 22, 2024 at 9:54 AM Frank Li <Frank.Li@nxp.com> wrote:
> >
> > Convert fsl,esai.txt to yaml. So DTB_CHECK tools can verify dts file about
> > esai part.
> >
> > clock-names 'spba' is optional according to description. So minItems of
> > clocks and clock-names is 3.
> >
> > Signed-off-by: Frank Li <Frank.Li@nxp.com>
> > ---
> >
> > Notes:
> >     Change from v1 to v2
> >     - alphabetical order compatible string according to rob's suggestion
> >     - clock description move under 'clock' according to kryszof's suggestion
> >     - fix descritpion indent according to rob's suggestion
> >
> >     Pass dt_binding check
> >      make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j8  dt_binding_check DT_SCHEMA_FILES=fsl,esai.yaml
> >       DTEX    Documentation/devicetree/bindings/sound/fsl,esai.example.dts
> >       LINT    Documentation/devicetree/bindings
> >       CHKDT   Documentation/devicetree/bindings/processed-schema.json
> >       SCHEMA  Documentation/devicetree/bindings/processed-schema.json
> >       DTC_CHK Documentation/devicetree/bindings/sound/fsl,esai.example.dtb
> 
> Did you run dtbs_check too? Probably not arm32 at least (first number
> is number of warnings):
> 
>     218  esai@2024000: clocks: [[2, 208], [2, 209], [2, 118], [2,
> 208], [2, 156]] is too long
>     218  esai@2024000: clock-names:3: 'spba' was expected
>     218  esai@2024000: clock-names:2: 'fsys' was expected
>     218  esai@2024000: clock-names:1: 'extal' was expected
>     218  esai@2024000: clock-names: ['core', 'mem', 'extal', 'fsys',
> 'spba'] is too long

Yes, I run dtb_check for one platform. Which dtb report this warning?

Frank

> 
> Conversions can leave warnings, but any you think should be fixed in
> the binding should be fixed in the conversion.
> 
> Rob

Re: [PATCH v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[Fabio Estevam]

On Tue, Apr 9, 2024 at 3:59 PM Frank Li <Frank.li@nxp.com> wrote:

> Yes, I run dtb_check for one platform. Which dtb report this warning?

Try imx_v6_v7_defconfig.

Re: [PATCH v2 1/1] ASoC: dt-bindings: fsl-esai: Convert fsl,esai.txt to yaml

[Frank Li]

On Tue, Apr 09, 2024 at 04:02:26PM -0300, Fabio Estevam wrote:
> On Tue, Apr 9, 2024 at 3:59 PM Frank Li <Frank.li@nxp.com> wrote:
> 
> > Yes, I run dtb_check for one platform. Which dtb report this warning?
> 
> Try imx_v6_v7_defconfig.

It is because imx6dl.dtsi use a undocumented clock-name 'mem'. According
to driver code,  clock-names 'mem' never be used. but I need double check
with driver owner before send out fix patch.

Frank