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
>
