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

From: Frank Li
Date: Thu Mar 21 2024 - 12:20:20 EST

On Wed, Mar 20, 2024 at 10:24:35AM -0500, Rob Herring wrote:
> 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.

I am not sure how to do that.

items:
- descripton: abc
- const: core
....

I get below error.
properties:clock-names:items: 'oneOf' conditional failed, one must be fixed:
[{'description': 'abcd', 'const': 'core'}, {'description': 'abcd', 'const': 'extal'}, {'description': 'abcd', 'const': 'fsys'}, {'description': 'abcd', 'const': 'spba'}] is not of type 'object'
Additional properties are not allowed ('description' was unexpected)
from schema $id: http://devicetree.org/meta-schemas/string-array.yaml#


snps,dw-pcie.yaml give example

items:
oneOf
- desecirpt: abc
const: core

allOf
contain:
- const: core


but it lost clock-names order restriction.

Could you please give me example about how to add description for const
under items?

Frank


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