Re: [PATCH] ASoC: dt-bindings: fsl, sai: Convert format to json-schema

On Tue, Jul 26, 2022 at 4:25 AM Rob Herring robh@kernel.org wrote:

On Mon, Jul 25, 2022 at 05:31:07PM +0800, Shengjiu Wang wrote:

...

Convert the NXP SAI binding to DT schema format using json-schema.

The Synchronous Audio Interface (SAI) provides an interface that supports full-duplex serial interfaces with frame synchronization formats such as I2S, AC97, TDM, and codec/DSP interfaces.

Signed-off-by: Shengjiu Wang shengjiu.wang@nxp.com

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

diff --git a/Documentation/devicetree/bindings/sound/fsl,sai.yaml

b/Documentation/devicetree/bindings/sound/fsl,sai.yaml

...

new file mode 100644 index 000000000000..adcd77531eba --- /dev/null +++ b/Documentation/devicetree/bindings/sound/fsl,sai.yaml @@ -0,0 +1,175 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/fsl,sai.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml#

+title: Freescale Synchronous Audio Interface (SAI).

+maintainers:

• • Shengjiu Wang shengjiu.wang@nxp.com

+description: |

• The SAI is based on I2S module that used communicating with audio

codecs,

...

• which provides a synchronous audio interface that supports fullduplex
• serial interfaces with frame synchronization such as I2S, AC97, TDM,

and

...

• codec/DSP interfaces.

+properties:

• compatible:
• minItems: 1
• maxItems: 2
• items:

•  enum:
  

•    - fsl,vf610-sai
  

•    - fsl,imx6sx-sai
  

•    - fsl,imx6ul-sai
  

•    - fsl,imx7ulp-sai
  

•    - fsl,imx8mq-sai
  

•    - fsl,imx8qm-sai
  

•    - fsl,imx8mm-sai
  

•    - fsl,imx8mn-sai
  

•    - fsl,imx8mp-sai
  

•    - fsl,imx8ulp-sai
  

You need to define the order and combinations which are valid.

ok, I will modify it.

...

• reg:
• maxItems: 1
• interrupts:
• items:

•  - description: receive and transmit interrupt
  

• dmas:
• minItems: 2
• maxItems: 2
• description:

•  Must contain a list of pairs of references to DMA specifiers, one
  

for

...

•  transmission, and one for reception.
  

No need for generic descriptions.

ok, will remove the description.

...

• dma-names:
• minItems: 2
• maxItems: 2
• items:

•  enum:
  

•    - tx
  

•    - rx
  

We really need to support either order?

yes, some dts use "tx", "rx", some dts use "rx", "tx". legacy issue.

...

• clocks:
• minItems: 4
• items:

•  - description: The ipg clock for register access
  

•  - description: master clock source 0 (obsoleted, compatible for
  

old dts)

...

•  - description: master clock source 1
  

•  - description: master clock source 2
  

•  - description: master clock source 3
  

•  - description: PLL clock source for 8kHz series
  

•  - description: PLL clock source for 11kHz series
  

• clock-names:
• minItems: 4
• maxItems: 7
• items:

•  enum:
  

•    - bus
  

•    - mclk0
  

•    - mclk1
  

•    - mclk2
  

•    - mclk3
  

•    - pll8k
  

•    - pll11k
  

Again, need to define the order.

some dts already add "mclk0", but some dts no "mclk0". Is there a way to handle this?

...

• lsb-first:
• $ref: /schemas/types.yaml#/definitions/flag
• description: |

•  Configures whether the LSB or the MSB is transmitted
  

•  first for the fifo data. If this property is absent,
  

•  the MSB is transmitted first as default, or the LSB
  

•  is transmitted first.
  

• big-endian:
• $ref: /schemas/types.yaml#/definitions/flag

Common property, already has a type and description.

ok, will remove this $ref.

...

• description: |

•  Boolean property, required if all the SAI
  

•  registers are big-endian rather than little-endian.
  

• fsl,sai-synchronous-rx:
• $ref: /schemas/types.yaml#/definitions/flag
• description: |

•  This is a boolean property. If present, indicating
  

•  that SAI will work in the synchronous mode (sync Tx
  

•  with Rx) which means both the transmitter and the
  

•  receiver will send and receive data by following
  

•  receiver's bit clocks and frame sync clocks.
  

•  fsl,sai-asynchronous and fsl,sai-synchronous-rx are exclusive.
  

• fsl,sai-asynchronous:
• $ref: /schemas/types.yaml#/definitions/flag
• description: |

•  This is a boolean property. If present, indicating
  

Schema already says it is boolean property, don't need that in plain text.

ok, will update

...

•  that SAI will work in the asynchronous mode, which
  

•  means both transmitter and receiver will send and
  

•  receive data by following their own bit clocks and
  

•  frame sync clocks separately.
  

•  If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are
  

absent, the

...

•  default synchronous mode (sync Rx with Tx) will be used, which
  

means both

...

•  transmitter and receiver will send and receive data by following
  

clocks

...

•  of transmitter.
  

•  fsl,sai-asynchronous and fsl,sai-synchronous-rx are exclusive.
  

• fsl,dataline:
• $ref: /schemas/types.yaml#/definitions/uint32-matrix
• description: |

•  configure the dataline. it has 3 value for each configuration
  

•  first one means the type: I2S(1) or PDM(2)
  

Looks like constraints:

items: items: - description: ... enum: [ 1, 2 ] - ... - ...

ok, I will add it.

...

•  second one is dataline mask for 'rx'
  

•  third one is dataline mask for 'tx'.
  

•  for example: fsl,dataline = <1 0xff 0xff 2 0xff 0x11>;
  

Perhaps add to the actual example.

ok.

best regards wang shengjiu

...

•  it means I2S type rx mask is 0xff, tx mask is 0xff, PDM type
  

•  rx mask is 0xff, tx mask is 0x11 (dataline 1 and 5 enabled).
  

• fsl,sai-mclk-direction-output:
• $ref: /schemas/types.yaml#/definitions/flag
• description: |

•  This is a boolean property. If present,
  

•  indicates that SAI will output the SAI MCLK clock.
  

• fsl,shared-interrupt:
• $ref: /schemas/types.yaml#/definitions/flag
• description: |

•  This is a boolean property. If present,
  

•  indicates that interrupt is shared with other modules.
  

• "#sound-dai-cells":
• const: 0

+required:

• • compatible
• • reg
• • interrupts
• • dmas
• • dma-names
• • clocks
• • clock-names

+additionalProperties: false

+examples:

• • |
• #include <dt-bindings/interrupt-controller/arm-gic.h>
• #include <dt-bindings/clock/vf610-clock.h>
• sai2: sai@40031000 {

•    compatible = "fsl,vf610-sai";
  

•    reg = <0x40031000 0x1000>;
  

•    interrupts = <86 IRQ_TYPE_LEVEL_HIGH>;
  

•    pinctrl-names = "default";
  

•    pinctrl-0 = <&pinctrl_sai2_1>;
  

•    clocks = <&clks VF610_CLK_PLATFORM_BUS>,
  

•             <&clks VF610_CLK_SAI2>,
  

•             <&clks 0>, <&clks 0>;
  

•    clock-names = "bus", "mclk1", "mclk2", "mclk3";
  

•    dma-names = "rx", "tx";
  

•    dmas = <&edma0 0 20>,
  

•           <&edma0 0 21>;
  

•    big-endian;
  

•    lsb-first;
  

• };