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

[Frank Li <Frank.li@nxp.com>]

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@nxp.com>
> > ---
> > 
> > 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@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,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
> >