diff mbox series

[03/13] dt-bindings: a2b: Analog Devices AD24xx devices

Message ID 20240517-a2b-v1-3-b8647554c67b@bang-olufsen.dk
State Not Applicable
Headers show
Series Analog Devices Inc. Automotive Audio Bus (A2B) support | expand

Commit Message

Alvin Šipraga May 17, 2024, 12:58 p.m. UTC
From: Alvin Šipraga <alsi@bang-olufsen.dk>

Add device tree bindings for the AD24xx series A2B transceiver chips,
including their functional blocks.

Signed-off-by: Alvin Šipraga <alsi@bang-olufsen.dk>
---
 .../devicetree/bindings/a2b/adi,ad24xx-clk.yaml    |  53 +++++
 .../devicetree/bindings/a2b/adi,ad24xx-codec.yaml  |  52 +++++
 .../devicetree/bindings/a2b/adi,ad24xx-gpio.yaml   |  76 +++++++
 .../devicetree/bindings/a2b/adi,ad24xx-i2c.yaml    |  55 +++++
 .../devicetree/bindings/a2b/adi,ad24xx.yaml        | 253 +++++++++++++++++++++
 5 files changed, 489 insertions(+)

Comments

Krzysztof Kozlowski May 19, 2024, 11:40 a.m. UTC | #1
On 17/05/2024 14:58, Alvin Šipraga wrote:
> From: Alvin Šipraga <alsi@bang-olufsen.dk>
> 
> Add device tree bindings for the AD24xx series A2B transceiver chips,
> including their functional blocks.
> 
> Signed-off-by: Alvin Šipraga <alsi@bang-olufsen.dk>
> ---
>  .../devicetree/bindings/a2b/adi,ad24xx-clk.yaml    |  53 +++++

What is a2b and why clock bindings are not in clock?

>  .../devicetree/bindings/a2b/adi,ad24xx-codec.yaml  |  52 +++++
>  .../devicetree/bindings/a2b/adi,ad24xx-gpio.yaml   |  76 +++++++
>  .../devicetree/bindings/a2b/adi,ad24xx-i2c.yaml    |  55 +++++
>  .../devicetree/bindings/a2b/adi,ad24xx.yaml        | 253 +++++++++++++++++++++

Sorry, all this looks weirdly placed.

>  5 files changed, 489 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml
> new file mode 100644
> index 000000000000..819efaa6a3f9
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml
> @@ -0,0 +1,53 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/a2b/adi,ad24xx-clk.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices Inc. AD24xx clock functional block
> +
> +maintainers:
> +  - Alvin Šipraga <alsi@bang-olufsen.dk>
> +
> +allOf:
> +  - $ref: /schemas/clock/clock.yaml

Drop. There is no single binding doing this, which is usually a hint you
do something not correct.

> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,ad2420-clk
> +      - adi,ad2421-clk
> +      - adi,ad2422-clk
> +      - adi,ad2425-clk
> +      - adi,ad2426-clk
> +      - adi,ad2427-clk
> +      - adi,ad2428-clk
> +      - adi,ad2429-clk
> +

This is just incomplete. See other bindings how clock controller is written.

> +required:
> +  - compatible
> +  - clock-output-names
> +
> +unevaluatedProperties: false

additionalProperties: false
> +
> +examples:
> +  - |
> +    a2b {
> +      #address-cells = <1>;
> +      #size-cells = <0>;

Not related, drop entire node.

> +
> +      node@1 {
> +        compatible = "adi,ad2425-node";

Not related, drop entire node.

> +        reg = <1>;
> +        interrupts = <1>;
> +        adi,tdm-mode = <16>;
> +        adi,tdm-slot-size = <32>;
> +
> +        clock {
> +          compatible = "adi,ad2425-clk";
> +          #clock-cells = <1>;
> +          clock-indices = <1>;
> +          clock-output-names = "A2B1 CLKOUT2";
> +        };
> +      };
> +    };
> diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml
> new file mode 100644
> index 000000000000..eee12f1c810e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml
> @@ -0,0 +1,52 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/a2b/adi,ad24xx-codec.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices Inc. AD24xx I2S/TDM functional block
> +
> +maintainers:
> +  - Alvin Šipraga <alsi@bang-olufsen.dk>
> +
> +allOf:
> +  - $ref: /schemas/sound/dai-common.yaml#

Why full path? It's the same directory, isn't it?

> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,ad2403-codec
> +      - adi,ad2410-codec
> +      - adi,ad2425-codec
> +      - adi,ad2428-codec
> +      - adi,ad2429-codec
> +
> +  '#sound-dai-cells':
> +    const: 0
> +
> +required:
> +  - compatible
> +  - '#sound-dai-cells'
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    a2b {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      node@2 {
> +        compatible = "adi,ad2428-node";
> +        reg = <2>;
> +        interrupts = <2>;
> +        adi,tdm-mode = <8>;
> +        adi,tdm-slot-size = <32>;

Same comments. Limited review follows.


...


> +
> +required:
> +  - compatible
> +
> +unevaluatedProperties: false

Sorry, but not. No resources, nothing here. Do not create bindings just
to instantiate drivers.


...

> diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml
> new file mode 100644
> index 000000000000..dcda15e8032a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml
> @@ -0,0 +1,253 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/a2b/adi,ad24xx.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices Inc. AD24xx Automotive Audio Bus A2B Transceiver
> +
> +description: |
> +  AD24xx chips provide A2B bus functionality together with several peripheral

What is A2B?

> +  functions, including GPIO, I2S/TDM, an I2C controller interface, and
> +  programmable clock outputs.
> +
> +maintainers:
> +  - Alvin Šipraga <alsi@bang-olufsen.dk>
> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,ad2403
> +      - adi,ad2410
> +      - adi,ad2425
> +      - adi,ad2428
> +      - adi,ad2429
> +

reg: is second property.

> +  reg-names:
> +    items:
> +      - const: base
> +      - const: bus
> +
> +  reg:
> +    items:
> +      - description: Normal I2C address of the chip
> +      - description: Auxiliary BUS_ADDR I2C address of the chip
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +  clock-names:
> +    items:
> +      - const: sync

Again misordered. -names always follow main entry. Anyway, clock-names
for just one entry is not really useful.

> +
> +  clocks:
> +    items:
> +      - description: SYNC input pin clock source
> +
> +  vin-supply:
> +    description: Optional regulator for supply voltage to VIN pin
> +
> +  bus-supply:
> +    description: Optional regulator for out-of-band supply voltage to
> +      subodrinate nodes' VIN pins
> +
> +  interrupts: true

??? This must be specific.

> +
> +  interrupt-controller: true
> +
> +  '#interrupt-cells':
> +    const: 1
> +
> +patternProperties:
> +  '^node@[0-9]+$':
> +    type: object
> +    unevaluatedProperties: false

Why? This must be additionalProperties: false, or I miss something...

> +
> +    properties:
> +      compatible:
> +        enum:
> +          - adi,ad2401-node
> +          - adi,ad2402-node
> +          - adi,ad2403-node
> +          - adi,ad2410-node
> +          - adi,ad2420-node
> +          - adi,ad2421-node
> +          - adi,ad2422-node
> +          - adi,ad2425-node
> +          - adi,ad2426-node
> +          - adi,ad2427-node
> +          - adi,ad2428-node
> +          - adi,ad2429-node
> +
> +      reg:
> +        maxItems: 1
> +
> +      interrupts:
> +        maxItems: 1
> +
> +      interrupt-controller: true
> +
> +      '#interrupt-cells':
> +        const: 1
> +
> +      gpio:
> +        $ref: adi,ad24xx-gpio.yaml#
> +
> +      codec:
> +        $ref: adi,ad24xx-codec.yaml#
> +
> +      i2c:
> +        $ref: adi,ad24xx-i2c.yaml#
> +
> +      clock:
> +        $ref: adi,ad24xx-clk.yaml#
> +
> +      adi,tdm-mode:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: TDM mode

Please do not add descriptions which are copies of property name. You
basically said ZERO here. Say something useful...

> +        enum: [2, 4, 8, 12, 16, 20, 24, 32]
> +
> +      adi,tdm-slot-size:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: TDM slot size
> +        enum: [16, 32]
> +
> +      adi,invert-sync:
> +        description: Falling edge of SYNC pin indicates the start of an audio
> +          frame, as opposed to rising edge.
> +        type: boolean
> +
> +      adi,early-sync:
> +        description: The SYNC pin changes one cycle before the MSB of the first
> +          data slot.
> +        type: boolean
> +
> +      adi,alternating-sync:
> +        description: Drive SYNC pin during first half of I2S/TDM data
> +          transmission rather than just pulsing it for once cycle.
> +        type: boolean
> +
> +      adi,rx-on-dtx1:
> +        description: Use the DTX1 pin for I2S/TDM RX in place of the DRX1 pin.
> +        type: boolean
> +
> +      adi,a2b-external-switch-mode-1:
> +        description: Use external switch mode 1 instead of 0 on the assumption
> +          that the downstream node is not using A2B bus power.
> +        type: boolean
> +
> +      adi,drive-strength:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: Configures drive strength low (0) or high (1, default).
> +        enum: [0, 1]
> +        default: 1
> +
> +      adi,invert-interrupt:
> +        description: Invert polarity of IRQ pin, making it active low.
> +        type: boolean
> +
> +      adi,tristate-interrupt:
> +        description: Rather than always actively driving the IRQ pin, only drive
> +          when the interrupt is active and otherwise set to tristate (high-Z).
> +        type: boolean

It looks you put all children properties into parent node... With so
little explanation tricky to judge.

> +
> +    required:
> +      - compatible
> +      - reg
> +      - adi,tdm-mode
> +      - adi,tdm-slot-size
> +
> +    dependencies:
> +      interrupt-controller: [ '#interrupt-cells' ]
> +      '#interrupt-cells': [ interrupt-controller ]
> +
> +required:
> +  - compatible
> +  - reg-names
> +  - reg
> +  - clock-names
> +  - clocks
> +  - '#address-cells'
> +  - '#size-cells'
> +  - interrupts
> +  - interrupt-controller
> +  - '#interrupt-cells'
> +  - node@0
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    sync_clk: sync-clock {

Drop, not related.

> +          compatible = "fixed-clock";
> +          #clock-cells = <0>;
> +          clock-frequency = <48000>;
> +    };
> +
> +    i2c {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      a2b@68 {
> +        compatible = "adi,ad2428";
> +        reg-names = "base", "bus";
> +        reg = <0x68>, <0x69>;


Please follow DTS coding style. Do not introduce entire different style
and order of properties. reg-names IS NEVER the second property.



Best regards,
Krzysztof
Krzysztof Kozlowski May 19, 2024, 11:44 a.m. UTC | #2
On 19/05/2024 13:40, Krzysztof Kozlowski wrote:
> On 17/05/2024 14:58, Alvin Šipraga wrote:
>> From: Alvin Šipraga <alsi@bang-olufsen.dk>
>>
>> Add device tree bindings for the AD24xx series A2B transceiver chips,
>> including their functional blocks.
>>
>> Signed-off-by: Alvin Šipraga <alsi@bang-olufsen.dk>
>> ---
>>  .../devicetree/bindings/a2b/adi,ad24xx-clk.yaml    |  53 +++++
> 
> What is a2b and why clock bindings are not in clock?

Just in case you reply "but I have cover letter", so no, it does not
matter really. This is the patch describing hardware, so here you
describe hardware. Not in cover letter which often is ignored. Many
people, including myself, skip cover letters.

Provide *hardware* description here.

Best regards,
Krzysztof
Alvin Šipraga May 21, 2024, 7:24 a.m. UTC | #3
On Sun, May 19, 2024 at 01:40:25PM GMT, Krzysztof Kozlowski wrote:
> On 17/05/2024 14:58, Alvin Šipraga wrote:
> > From: Alvin Šipraga <alsi@bang-olufsen.dk>
> > 
> > Add device tree bindings for the AD24xx series A2B transceiver chips,
> > including their functional blocks.
> > 
> > Signed-off-by: Alvin Šipraga <alsi@bang-olufsen.dk>
> > ---
> >  .../devicetree/bindings/a2b/adi,ad24xx-clk.yaml    |  53 +++++
> 
> What is a2b and why clock bindings are not in clock?
> 
> >  .../devicetree/bindings/a2b/adi,ad24xx-codec.yaml  |  52 +++++
> >  .../devicetree/bindings/a2b/adi,ad24xx-gpio.yaml   |  76 +++++++
> >  .../devicetree/bindings/a2b/adi,ad24xx-i2c.yaml    |  55 +++++
> >  .../devicetree/bindings/a2b/adi,ad24xx.yaml        | 253 +++++++++++++++++++++
> 
> Sorry, all this looks weirdly placed.

Alright, I'll move the bindings to their respective directories. Wasn't
sure what is preferred.

> 
> >  5 files changed, 489 insertions(+)
> > 
> > diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml
> > new file mode 100644
> > index 000000000000..819efaa6a3f9
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml
> > @@ -0,0 +1,53 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/a2b/adi,ad24xx-clk.yaml
> > +$schema: http://devicetree.org/meta-schemas/core.yaml
> > +
> > +title: Analog Devices Inc. AD24xx clock functional block
> > +
> > +maintainers:
> > +  - Alvin Šipraga <alsi@bang-olufsen.dk>
> > +
> > +allOf:
> > +  - $ref: /schemas/clock/clock.yaml
> 
> Drop. There is no single binding doing this, which is usually a hint you
> do something not correct.
> 
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - adi,ad2420-clk
> > +      - adi,ad2421-clk
> > +      - adi,ad2422-clk
> > +      - adi,ad2425-clk
> > +      - adi,ad2426-clk
> > +      - adi,ad2427-clk
> > +      - adi,ad2428-clk
> > +      - adi,ad2429-clk
> > +
> 
> This is just incomplete. See other bindings how clock controller is written.

OK, will review.

> 
> > +required:
> > +  - compatible
> > +  - clock-output-names
> > +
> > +unevaluatedProperties: false
> 
> additionalProperties: false

OK

> > +
> > +examples:
> > +  - |
> > +    a2b {
> > +      #address-cells = <1>;
> > +      #size-cells = <0>;
> 
> Not related, drop entire node.

OK

> 
> > +
> > +      node@1 {
> > +        compatible = "adi,ad2425-node";
> 
> Not related, drop entire node.

OK

> 
> > +        reg = <1>;
> > +        interrupts = <1>;
> > +        adi,tdm-mode = <16>;
> > +        adi,tdm-slot-size = <32>;
> > +
> > +        clock {
> > +          compatible = "adi,ad2425-clk";
> > +          #clock-cells = <1>;
> > +          clock-indices = <1>;
> > +          clock-output-names = "A2B1 CLKOUT2";
> > +        };
> > +      };
> > +    };
> > diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml
> > new file mode 100644
> > index 000000000000..eee12f1c810e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml
> > @@ -0,0 +1,52 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/a2b/adi,ad24xx-codec.yaml
> > +$schema: http://devicetree.org/meta-schemas/core.yaml
> > +
> > +title: Analog Devices Inc. AD24xx I2S/TDM functional block
> > +
> > +maintainers:
> > +  - Alvin Šipraga <alsi@bang-olufsen.dk>
> > +
> > +allOf:
> > +  - $ref: /schemas/sound/dai-common.yaml#
> 
> Why full path? It's the same directory, isn't it?

In this case no, but when I move it into sound, yes. So your comment is
acknowledged and will be addressed in v2.

> 
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - adi,ad2403-codec
> > +      - adi,ad2410-codec
> > +      - adi,ad2425-codec
> > +      - adi,ad2428-codec
> > +      - adi,ad2429-codec
> > +
> > +  '#sound-dai-cells':
> > +    const: 0
> > +
> > +required:
> > +  - compatible
> > +  - '#sound-dai-cells'
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    a2b {
> > +      #address-cells = <1>;
> > +      #size-cells = <0>;
> > +
> > +      node@2 {
> > +        compatible = "adi,ad2428-node";
> > +        reg = <2>;
> > +        interrupts = <2>;
> > +        adi,tdm-mode = <8>;
> > +        adi,tdm-slot-size = <32>;
> 
> Same comments. Limited review follows.

Ack

> 
> 
> ...
> 
> 
> > +
> > +required:
> > +  - compatible
> > +
> > +unevaluatedProperties: false
> 
> Sorry, but not. No resources, nothing here. Do not create bindings just
> to instantiate drivers.

Do you mean that there is no need to introduce a binding for this codec
if it has the same bindings as dai-common.yaml?

Basically that is the case, but #sound-dai-cells should be <0>. Is that
not enough?

I am OK to just drop the binding if you think so, but I would think that
the compatible string should be somewhere in the bindings. Could you
explain a little more what you mean?

> 
> 
> ...
> 
> > diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml
> > new file mode 100644
> > index 000000000000..dcda15e8032a
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml
> > @@ -0,0 +1,253 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/a2b/adi,ad24xx.yaml
> > +$schema: http://devicetree.org/meta-schemas/core.yaml
> > +
> > +title: Analog Devices Inc. AD24xx Automotive Audio Bus A2B Transceiver
> > +
> > +description: |
> > +  AD24xx chips provide A2B bus functionality together with several peripheral
> 
> What is A2B?

I will improve the description per your review comments.

> 
> > +  functions, including GPIO, I2S/TDM, an I2C controller interface, and
> > +  programmable clock outputs.
> > +
> > +maintainers:
> > +  - Alvin Šipraga <alsi@bang-olufsen.dk>
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - adi,ad2403
> > +      - adi,ad2410
> > +      - adi,ad2425
> > +      - adi,ad2428
> > +      - adi,ad2429
> > +
> 
> reg: is second property.

Ack

> 
> > +  reg-names:
> > +    items:
> > +      - const: base
> > +      - const: bus
> > +
> > +  reg:
> > +    items:
> > +      - description: Normal I2C address of the chip
> > +      - description: Auxiliary BUS_ADDR I2C address of the chip
> > +
> > +  '#address-cells':
> > +    const: 1
> > +
> > +  '#size-cells':
> > +    const: 0
> > +
> > +  clock-names:
> > +    items:
> > +      - const: sync
> 
> Again misordered. -names always follow main entry. Anyway, clock-names
> for just one entry is not really useful.

Ack

> 
> > +
> > +  clocks:
> > +    items:
> > +      - description: SYNC input pin clock source
> > +
> > +  vin-supply:
> > +    description: Optional regulator for supply voltage to VIN pin
> > +
> > +  bus-supply:
> > +    description: Optional regulator for out-of-band supply voltage to
> > +      subodrinate nodes' VIN pins
> > +
> > +  interrupts: true
> 
> ??? This must be specific.

Right, it should be:

maxItems: 1

That's specific, right?

> 
> > +
> > +  interrupt-controller: true
> > +
> > +  '#interrupt-cells':
> > +    const: 1
> > +
> > +patternProperties:
> > +  '^node@[0-9]+$':
> > +    type: object
> > +    unevaluatedProperties: false
> 
> Why? This must be additionalProperties: false, or I miss something...

I think you are right, but I will review this before sending v2. Thanks.

> 
> > +
> > +    properties:
> > +      compatible:
> > +        enum:
> > +          - adi,ad2401-node
> > +          - adi,ad2402-node
> > +          - adi,ad2403-node
> > +          - adi,ad2410-node
> > +          - adi,ad2420-node
> > +          - adi,ad2421-node
> > +          - adi,ad2422-node
> > +          - adi,ad2425-node
> > +          - adi,ad2426-node
> > +          - adi,ad2427-node
> > +          - adi,ad2428-node
> > +          - adi,ad2429-node
> > +
> > +      reg:
> > +        maxItems: 1
> > +
> > +      interrupts:
> > +        maxItems: 1
> > +
> > +      interrupt-controller: true
> > +
> > +      '#interrupt-cells':
> > +        const: 1
> > +
> > +      gpio:
> > +        $ref: adi,ad24xx-gpio.yaml#
> > +
> > +      codec:
> > +        $ref: adi,ad24xx-codec.yaml#
> > +
> > +      i2c:
> > +        $ref: adi,ad24xx-i2c.yaml#
> > +
> > +      clock:
> > +        $ref: adi,ad24xx-clk.yaml#
> > +
> > +      adi,tdm-mode:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description: TDM mode
> 
> Please do not add descriptions which are copies of property name. You
> basically said ZERO here. Say something useful...

Ack

> 
> > +        enum: [2, 4, 8, 12, 16, 20, 24, 32]
> > +
> > +      adi,tdm-slot-size:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description: TDM slot size
> > +        enum: [16, 32]
> > +
> > +      adi,invert-sync:
> > +        description: Falling edge of SYNC pin indicates the start of an audio
> > +          frame, as opposed to rising edge.
> > +        type: boolean
> > +
> > +      adi,early-sync:
> > +        description: The SYNC pin changes one cycle before the MSB of the first
> > +          data slot.
> > +        type: boolean
> > +
> > +      adi,alternating-sync:
> > +        description: Drive SYNC pin during first half of I2S/TDM data
> > +          transmission rather than just pulsing it for once cycle.
> > +        type: boolean
> > +
> > +      adi,rx-on-dtx1:
> > +        description: Use the DTX1 pin for I2S/TDM RX in place of the DRX1 pin.
> > +        type: boolean
> > +
> > +      adi,a2b-external-switch-mode-1:
> > +        description: Use external switch mode 1 instead of 0 on the assumption
> > +          that the downstream node is not using A2B bus power.
> > +        type: boolean
> > +
> > +      adi,drive-strength:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description: Configures drive strength low (0) or high (1, default).
> > +        enum: [0, 1]
> > +        default: 1
> > +
> > +      adi,invert-interrupt:
> > +        description: Invert polarity of IRQ pin, making it active low.
> > +        type: boolean
> > +
> > +      adi,tristate-interrupt:
> > +        description: Rather than always actively driving the IRQ pin, only drive
> > +          when the interrupt is active and otherwise set to tristate (high-Z).
> > +        type: boolean
> 
> It looks you put all children properties into parent node... With so
> little explanation tricky to judge.

I will put some more information into the binding so that it is more
understandable without reading the cover letter. Hopefully things will
be clearer for the next review and you can reconsider.

> 
> > +
> > +    required:
> > +      - compatible
> > +      - reg
> > +      - adi,tdm-mode
> > +      - adi,tdm-slot-size
> > +
> > +    dependencies:
> > +      interrupt-controller: [ '#interrupt-cells' ]
> > +      '#interrupt-cells': [ interrupt-controller ]
> > +
> > +required:
> > +  - compatible
> > +  - reg-names
> > +  - reg
> > +  - clock-names
> > +  - clocks
> > +  - '#address-cells'
> > +  - '#size-cells'
> > +  - interrupts
> > +  - interrupt-controller
> > +  - '#interrupt-cells'
> > +  - node@0
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    sync_clk: sync-clock {
> 
> Drop, not related.

If the clock is required (as it is) then I have to reference some
phandle in the example, else the example will fail the check (missing
required property 'clocks'). That's why I put it here. Please advise.

> 
> > +          compatible = "fixed-clock";
> > +          #clock-cells = <0>;
> > +          clock-frequency = <48000>;
> > +    };
> > +
> > +    i2c {
> > +      #address-cells = <1>;
> > +      #size-cells = <0>;
> > +
> > +      a2b@68 {
> > +        compatible = "adi,ad2428";
> > +        reg-names = "base", "bus";
> > +        reg = <0x68>, <0x69>;
> 
> 
> Please follow DTS coding style. Do not introduce entire different style
> and order of properties. reg-names IS NEVER the second property.

OK
Krzysztof Kozlowski May 21, 2024, 7:47 a.m. UTC | #4
On 21/05/2024 09:24, Alvin Šipraga wrote:

>>> +
>>> +required:
>>> +  - compatible
>>> +
>>> +unevaluatedProperties: false
>>
>> Sorry, but not. No resources, nothing here. Do not create bindings just
>> to instantiate drivers.
> 
> Do you mean that there is no need to introduce a binding for this codec
> if it has the same bindings as dai-common.yaml?

No, I said you do not have absolutely any resources here, so your
binding is empty. There is no need for such binding. You just want to
treat DT as way to instantiate drivers, which is a no-go.

> 
> Basically that is the case, but #sound-dai-cells should be <0>. Is that
> not enough?
> 
> I am OK to just drop the binding if you think so, but I would think that
> the compatible string should be somewhere in the bindings. Could you
> explain a little more what you mean?

Why do you need compatible? Which piece of hardware, with its own
resources, is being described here?

Just put dai-cells in parent node.


...


>>> +
>>> +examples:
>>> +  - |
>>> +    sync_clk: sync-clock {
>>
>> Drop, not related.
> 
> If the clock is required (as it is) then I have to reference some
> phandle in the example, 

Why?

> else the example will fail the check (missing
> required property 'clocks'). That's why I put it here. Please advise.

Let me answer indirectly: do you see any binding doing this? No. There
is almost none, so this should be a hint that it is not needed.



Best regards,
Krzysztof
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml
new file mode 100644
index 000000000000..819efaa6a3f9
--- /dev/null
+++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-clk.yaml
@@ -0,0 +1,53 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/a2b/adi,ad24xx-clk.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Inc. AD24xx clock functional block
+
+maintainers:
+  - Alvin Šipraga <alsi@bang-olufsen.dk>
+
+allOf:
+  - $ref: /schemas/clock/clock.yaml
+
+properties:
+  compatible:
+    enum:
+      - adi,ad2420-clk
+      - adi,ad2421-clk
+      - adi,ad2422-clk
+      - adi,ad2425-clk
+      - adi,ad2426-clk
+      - adi,ad2427-clk
+      - adi,ad2428-clk
+      - adi,ad2429-clk
+
+required:
+  - compatible
+  - clock-output-names
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    a2b {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      node@1 {
+        compatible = "adi,ad2425-node";
+        reg = <1>;
+        interrupts = <1>;
+        adi,tdm-mode = <16>;
+        adi,tdm-slot-size = <32>;
+
+        clock {
+          compatible = "adi,ad2425-clk";
+          #clock-cells = <1>;
+          clock-indices = <1>;
+          clock-output-names = "A2B1 CLKOUT2";
+        };
+      };
+    };
diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml
new file mode 100644
index 000000000000..eee12f1c810e
--- /dev/null
+++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-codec.yaml
@@ -0,0 +1,52 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/a2b/adi,ad24xx-codec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Inc. AD24xx I2S/TDM functional block
+
+maintainers:
+  - Alvin Šipraga <alsi@bang-olufsen.dk>
+
+allOf:
+  - $ref: /schemas/sound/dai-common.yaml#
+
+properties:
+  compatible:
+    enum:
+      - adi,ad2403-codec
+      - adi,ad2410-codec
+      - adi,ad2425-codec
+      - adi,ad2428-codec
+      - adi,ad2429-codec
+
+  '#sound-dai-cells':
+    const: 0
+
+required:
+  - compatible
+  - '#sound-dai-cells'
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    a2b {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      node@2 {
+        compatible = "adi,ad2428-node";
+        reg = <2>;
+        interrupts = <2>;
+        adi,tdm-mode = <8>;
+        adi,tdm-slot-size = <32>;
+
+        codec {
+          compatible = "adi,ad2428-codec";
+          #sound-dai-cells = <0>;
+          sound-name-prefix = "A2B Sub2";
+        };
+      };
+    };
diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-gpio.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-gpio.yaml
new file mode 100644
index 000000000000..e2b99c711a47
--- /dev/null
+++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-gpio.yaml
@@ -0,0 +1,76 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/a2b/adi,ad24xx-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Inc. AD24xx GPIO functional block
+
+maintainers:
+  - Alvin Šipraga <alsi@bang-olufsen.dk>
+
+properties:
+  compatible:
+    enum:
+      - adi,ad2401-gpio
+      - adi,ad2402-gpio
+      - adi,ad2403-gpio
+      - adi,ad2410-gpio
+      - adi,ad2420-gpio
+      - adi,ad2421-gpio
+      - adi,ad2422-gpio
+      - adi,ad2425-gpio
+      - adi,ad2426-gpio
+      - adi,ad2427-gpio
+      - adi,ad2428-gpio
+      - adi,ad2429-gpio
+
+  gpio-controller: true
+
+  '#gpio-cells':
+    const: 2
+
+  interrupt-controller: true
+
+  '#interrupt-cells':
+    const: 2
+
+  gpio-line-names: true
+  gpio-reserved-ranges: true
+
+required:
+  - compatible
+  - gpio-controller
+  - '#gpio-cells'
+
+dependencies:
+  interrupt-controller: [ '#interrupt-cells' ]
+  '#interrupt-cells': [ interrupt-controller ]
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    a2b {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      node@0 {
+        compatible = "adi,ad2428-node";
+        reg = <0>;
+        interrupts = <0>;
+        interrupt-controller;
+        #interrupt-cells = <1>;
+        adi,tdm-mode = <16>;
+        adi,tdm-slot-size = <32>;
+
+        gpio {
+          compatible = "adi,ad2428-gpio";
+          interrupt-controller;
+          #interrupt-cells = <2>;
+          gpio-controller;
+          #gpio-cells = <2>;
+          gpio-reserved-ranges = <0 1>;
+        };
+      };
+    };
diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx-i2c.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx-i2c.yaml
new file mode 100644
index 000000000000..ac52f184004d
--- /dev/null
+++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx-i2c.yaml
@@ -0,0 +1,55 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/a2b/adi,ad24xx-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Inc. AD24xx I2C controller functional block
+
+maintainers:
+  - Alvin Šipraga <alsi@bang-olufsen.dk>
+
+allOf:
+  - $ref: /schemas/i2c/i2c-controller.yaml
+
+properties:
+  compatible:
+    enum:
+      - adi,ad2401-i2c
+      - adi,ad2402-i2c
+      - adi,ad2403-i2c
+      - adi,ad2410-i2c
+      - adi,ad2420-i2c
+      - adi,ad2421-i2c
+      - adi,ad2422-i2c
+      - adi,ad2425-i2c
+      - adi,ad2426-i2c
+      - adi,ad2427-i2c
+      - adi,ad2428-i2c
+
+required:
+  - compatible
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    a2b {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      node@1 {
+        compatible = "adi,ad2425-node";
+        reg = <1>;
+        interrupts = <1>;
+        adi,tdm-mode = <16>;
+        adi,tdm-slot-size = <32>;
+
+        i2c {
+          compatible = "adi,ad2425-i2c";
+          #address-cells = <1>;
+          #size-cells = <0>;
+          clock-frequency = <400000>;
+        };
+      };
+    };
diff --git a/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml b/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml
new file mode 100644
index 000000000000..dcda15e8032a
--- /dev/null
+++ b/Documentation/devicetree/bindings/a2b/adi,ad24xx.yaml
@@ -0,0 +1,253 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/a2b/adi,ad24xx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Inc. AD24xx Automotive Audio Bus A2B Transceiver
+
+description: |
+  AD24xx chips provide A2B bus functionality together with several peripheral
+  functions, including GPIO, I2S/TDM, an I2C controller interface, and
+  programmable clock outputs.
+
+maintainers:
+  - Alvin Šipraga <alsi@bang-olufsen.dk>
+
+properties:
+  compatible:
+    enum:
+      - adi,ad2403
+      - adi,ad2410
+      - adi,ad2425
+      - adi,ad2428
+      - adi,ad2429
+
+  reg-names:
+    items:
+      - const: base
+      - const: bus
+
+  reg:
+    items:
+      - description: Normal I2C address of the chip
+      - description: Auxiliary BUS_ADDR I2C address of the chip
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+  clock-names:
+    items:
+      - const: sync
+
+  clocks:
+    items:
+      - description: SYNC input pin clock source
+
+  vin-supply:
+    description: Optional regulator for supply voltage to VIN pin
+
+  bus-supply:
+    description: Optional regulator for out-of-band supply voltage to
+      subodrinate nodes' VIN pins
+
+  interrupts: true
+
+  interrupt-controller: true
+
+  '#interrupt-cells':
+    const: 1
+
+patternProperties:
+  '^node@[0-9]+$':
+    type: object
+    unevaluatedProperties: false
+
+    properties:
+      compatible:
+        enum:
+          - adi,ad2401-node
+          - adi,ad2402-node
+          - adi,ad2403-node
+          - adi,ad2410-node
+          - adi,ad2420-node
+          - adi,ad2421-node
+          - adi,ad2422-node
+          - adi,ad2425-node
+          - adi,ad2426-node
+          - adi,ad2427-node
+          - adi,ad2428-node
+          - adi,ad2429-node
+
+      reg:
+        maxItems: 1
+
+      interrupts:
+        maxItems: 1
+
+      interrupt-controller: true
+
+      '#interrupt-cells':
+        const: 1
+
+      gpio:
+        $ref: adi,ad24xx-gpio.yaml#
+
+      codec:
+        $ref: adi,ad24xx-codec.yaml#
+
+      i2c:
+        $ref: adi,ad24xx-i2c.yaml#
+
+      clock:
+        $ref: adi,ad24xx-clk.yaml#
+
+      adi,tdm-mode:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: TDM mode
+        enum: [2, 4, 8, 12, 16, 20, 24, 32]
+
+      adi,tdm-slot-size:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: TDM slot size
+        enum: [16, 32]
+
+      adi,invert-sync:
+        description: Falling edge of SYNC pin indicates the start of an audio
+          frame, as opposed to rising edge.
+        type: boolean
+
+      adi,early-sync:
+        description: The SYNC pin changes one cycle before the MSB of the first
+          data slot.
+        type: boolean
+
+      adi,alternating-sync:
+        description: Drive SYNC pin during first half of I2S/TDM data
+          transmission rather than just pulsing it for once cycle.
+        type: boolean
+
+      adi,rx-on-dtx1:
+        description: Use the DTX1 pin for I2S/TDM RX in place of the DRX1 pin.
+        type: boolean
+
+      adi,a2b-external-switch-mode-1:
+        description: Use external switch mode 1 instead of 0 on the assumption
+          that the downstream node is not using A2B bus power.
+        type: boolean
+
+      adi,drive-strength:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: Configures drive strength low (0) or high (1, default).
+        enum: [0, 1]
+        default: 1
+
+      adi,invert-interrupt:
+        description: Invert polarity of IRQ pin, making it active low.
+        type: boolean
+
+      adi,tristate-interrupt:
+        description: Rather than always actively driving the IRQ pin, only drive
+          when the interrupt is active and otherwise set to tristate (high-Z).
+        type: boolean
+
+    required:
+      - compatible
+      - reg
+      - adi,tdm-mode
+      - adi,tdm-slot-size
+
+    dependencies:
+      interrupt-controller: [ '#interrupt-cells' ]
+      '#interrupt-cells': [ interrupt-controller ]
+
+required:
+  - compatible
+  - reg-names
+  - reg
+  - clock-names
+  - clocks
+  - '#address-cells'
+  - '#size-cells'
+  - interrupts
+  - interrupt-controller
+  - '#interrupt-cells'
+  - node@0
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    sync_clk: sync-clock {
+          compatible = "fixed-clock";
+          #clock-cells = <0>;
+          clock-frequency = <48000>;
+    };
+
+    i2c {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      a2b@68 {
+        compatible = "adi,ad2428";
+        reg-names = "base", "bus";
+        reg = <0x68>, <0x69>;
+        clock-names = "sync";
+        clocks = <&sync_clk>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+        interrupts = <42>;
+        interrupt-controller;
+        #interrupt-cells = <1>;
+
+        node@0 {
+          compatible = "adi,ad2428-node";
+          reg = <0>;
+          interrupts = <0>;
+          adi,tdm-mode = <16>;
+          adi,tdm-slot-size = <32>;
+
+          codec {
+            compatible = "adi,ad2428-codec";
+            #sound-dai-cells = <0>;
+            sound-name-prefix = "A2B Main";
+          };
+        };
+
+        node@1 {
+          compatible = "adi,ad2425-node";
+          reg = <1>;
+          interrupts = <1>;
+          adi,tdm-mode = <8>;
+          adi,tdm-slot-size = <32>;
+
+          gpio {
+            compatible = "adi,ad2425-gpio";
+            interrupt-controller;
+            #interrupt-cells = <2>;
+            gpio-controller;
+            #gpio-cells = <2>;
+          };
+
+          codec {
+            compatible = "adi,ad2425-codec";
+            #sound-dai-cells = <0>;
+            sound-name-prefix = "A2B Sub1";
+          };
+
+          i2c {
+            compatible = "adi,ad2425-i2c";
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            eeprom@50 {
+              compatible = "atmel,24c64";
+              reg = <0x50>;
+            };
+          };
+        };
+      };
+    };