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

[Rob Herring]

On Mon, Mar 18, 2024 at 03:45:34PM -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@xxxxxxx>
> ---
> 
> Notes:
>     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   | 110 ++++++++++++++++++
>  2 files changed, 110 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..9e31283933d1b
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/fsl,esai.yaml
> @@ -0,0 +1,110 @@
> +# 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@xxxxxxx>
> +  - Frank Li <Frank.Li@xxxxxxx>
> +
> +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,vf610-esai

Alphabetical order

> +      - fsl,imx6ull-esai
> +      - fsl,imx8qm-esai
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    minItems: 3
> +    maxItems: 4
> +
> +  clock-names:
> +    minItems: 3
> +    description: |
> +      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.

This description should be split into each items entry below.

> +    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].

Not the normal indentation. Should be just indent 2 more spaces than 
'description'.

> +
> +  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
>