diff mbox series

[1/2] dt-bindings: sound: ti,pcm3168a: Convert to json-schema

Message ID 9f2a2474ec71dcc2a76e868295202a8c425a5d41.1669980383.git.geert+renesas@glider.be (mailing list archive)
State New, archived
Headers show
Series dt-bindings: sound: ti, pcm3168a: json-schema conversion and fixes | expand

Commit Message

Geert Uytterhoeven Dec. 2, 2022, 12:55 p.m. UTC 
Convert the Texas Instruments PCM3168A Audio Codec Device Tree binding
documentation to json-schema.

Add missing properties.
Drop unneeded pinctrl properties from example.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 .../devicetree/bindings/sound/ti,pcm3168a.txt |  56 ----------
 .../bindings/sound/ti,pcm3168a.yaml           | 105 ++++++++++++++++++
 2 files changed, 105 insertions(+), 56 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/ti,pcm3168a.txt
 create mode 100644 Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml

Comments

Krzysztof Kozlowski Dec. 3, 2022, 12:13 p.m. UTC | #1 
On 02/12/2022 13:55, Geert Uytterhoeven wrote:
> Convert the Texas Instruments PCM3168A Audio Codec Device Tree binding
> documentation to json-schema.
> 
> Add missing properties.
> Drop unneeded pinctrl properties from example.

Thank you for your patch. There is something to discuss/improve.

> +description:
> +  The Texas Instruments PCM3168A is a 24-bit Multi-channel Audio CODEC with
> +  96/192kHz sampling rate, supporting both SPI and I2C bus access.
> +
> +properties:
> +  compatible:
> +    const: ti,pcm3168a
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    items:
> +      - description: System clock input
> +
> +  clock-names:
> +    items:
> +      - const: scki
> +
> +  reset-gpios:
> +    items:
> +      - description: |
> +          GPIO line connected to the active-low RST pin of the codec.
> +            RST = low: device power-down
> +            RST = high: device is enabled
> +
> +  "#sound-dai-cells":
> +    enum: [0, 1]

This is a bit unexpected. Looking at DTSes:
1. I see in ulcb-kf.dtsi with cells==0, but two endpoints. The dai cells
seem unused? In such case shall dai-cells be skipped if we have endpoints?

2. in k3-j721e-common-proc-board.dts has cells=1, but user's phandle
does not have an argument, so practically it is ==0? The user -
sound/soc/ti/j721e-evm.c - just gets the node and does not use cells,
right? So even though dai-cells==1, it does not matter, because user
gets its own parsing?

3. The pcm3168a driver also does not have any xlate function, but it
registers to DAIs, so all uses should be with cells==1 to select proper
DAI...


> +
> +  VDD1-supply:
> +    description: Digital power supply regulator 1 (+3.3V)
> +
> +  VDD2-supply:
> +    description: Digital power supply regulator 2 (+3.3V)
> +
> +  VCCAD1-supply:
> +    description: ADC power supply regulator 1 (+5V)
> +
> +  VCCAD2-supply:
> +    description: ADC power supply regulator 2 (+5V)
> +
> +  VCCDA1-supply:
> +    description: DAC power supply regulator 1 (+5V)
> +
> +  VCCDA2-supply:
> +    description: DAC power supply regulator 2 (+5V)
> +
> +  ports:
> +    $ref: /schemas/graph.yaml#/properties/ports
> +    properties:
> +      port@0:
> +        $ref: audio-graph-port.yaml#
> +        description: Audio input port.

unevaluatedProperties: false

> +
> +      port@1:
> +        $ref: audio-graph-port.yaml#
> +        description: Audio output port.

unevaluatedProperties: false


> +
> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - clock-names
> +  - VDD1-supply
> +  - VDD2-supply
> +  - VCCAD1-supply
> +  - VCCAD2-supply
> +  - VCCDA1-supply
> +  - VCCDA2-supply
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        pcm3168a: audio-codec@44 {
> +            compatible = "ti,pcm3168a";
> +            reg = <0x44>;
> +            reset-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>;
> +            clocks = <&clk_core 42>;
> +            clock-names = "scki";
> +            VDD1-supply = <&supply3v3>;
> +            VDD2-supply = <&supply3v3>;
> +            VCCAD1-supply = <&supply5v0>;
> +            VCCAD2-supply = <&supply5v0>;
> +            VCCDA1-supply = <&supply5v0>;
> +            VCCDA2-supply = <&supply5v0>;

Can you extend the example with dai cells or with endpoints (or both,
depending on my previous comment...)

> +        };
> +    };

Best regards,
Krzysztof
Geert Uytterhoeven Dec. 5, 2022, 8 a.m. UTC | #2 
Hi Krzysztof,

Thanks for your comments!

On Sat, Dec 3, 2022 at 1:13 PM Krzysztof Kozlowski
<krzysztof.kozlowski@linaro.org> wrote:
> On 02/12/2022 13:55, Geert Uytterhoeven wrote:
> > Convert the Texas Instruments PCM3168A Audio Codec Device Tree binding
> > documentation to json-schema.
> >
> > Add missing properties.
> > Drop unneeded pinctrl properties from example.
>
> Thank you for your patch. There is something to discuss/improve.
>
> > +description:
> > +  The Texas Instruments PCM3168A is a 24-bit Multi-channel Audio CODEC with
> > +  96/192kHz sampling rate, supporting both SPI and I2C bus access.
> > +
> > +properties:
> > +  compatible:
> > +    const: ti,pcm3168a
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  clocks:
> > +    items:
> > +      - description: System clock input
> > +
> > +  clock-names:
> > +    items:
> > +      - const: scki
> > +
> > +  reset-gpios:
> > +    items:
> > +      - description: |
> > +          GPIO line connected to the active-low RST pin of the codec.
> > +            RST = low: device power-down
> > +            RST = high: device is enabled
> > +
> > +  "#sound-dai-cells":
> > +    enum: [0, 1]
>
> This is a bit unexpected. Looking at DTSes:
> 1. I see in ulcb-kf.dtsi with cells==0, but two endpoints. The dai cells
> seem unused? In such case shall dai-cells be skipped if we have endpoints?
>
> 2. in k3-j721e-common-proc-board.dts has cells=1, but user's phandle
> does not have an argument, so practically it is ==0? The user -
> sound/soc/ti/j721e-evm.c - just gets the node and does not use cells,
> right? So even though dai-cells==1, it does not matter, because user
> gets its own parsing?
>
> 3. The pcm3168a driver also does not have any xlate function, but it
> registers to DAIs, so all uses should be with cells==1 to select proper
> DAI...

I have no idea (DAI is magic to me), and hope the audio experts
can provide some input...
Thanks!

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds
Krzysztof Kozlowski Dec. 6, 2022, 9:16 a.m. UTC | #3 
On 05/12/2022 09:00, Geert Uytterhoeven wrote:
> Hi Krzysztof,
> 
> Thanks for your comments!
> 
> On Sat, Dec 3, 2022 at 1:13 PM Krzysztof Kozlowski
> <krzysztof.kozlowski@linaro.org> wrote:
>> On 02/12/2022 13:55, Geert Uytterhoeven wrote:
>>> Convert the Texas Instruments PCM3168A Audio Codec Device Tree binding
>>> documentation to json-schema.
>>>
>>> Add missing properties.
>>> Drop unneeded pinctrl properties from example.
>>
>> Thank you for your patch. There is something to discuss/improve.
>>
>>> +description:
>>> +  The Texas Instruments PCM3168A is a 24-bit Multi-channel Audio CODEC with
>>> +  96/192kHz sampling rate, supporting both SPI and I2C bus access.
>>> +
>>> +properties:
>>> +  compatible:
>>> +    const: ti,pcm3168a
>>> +
>>> +  reg:
>>> +    maxItems: 1
>>> +
>>> +  clocks:
>>> +    items:
>>> +      - description: System clock input
>>> +
>>> +  clock-names:
>>> +    items:
>>> +      - const: scki
>>> +
>>> +  reset-gpios:
>>> +    items:
>>> +      - description: |
>>> +          GPIO line connected to the active-low RST pin of the codec.
>>> +            RST = low: device power-down
>>> +            RST = high: device is enabled
>>> +
>>> +  "#sound-dai-cells":
>>> +    enum: [0, 1]
>>
>> This is a bit unexpected. Looking at DTSes:
>> 1. I see in ulcb-kf.dtsi with cells==0, but two endpoints. The dai cells
>> seem unused? In such case shall dai-cells be skipped if we have endpoints?
>>
>> 2. in k3-j721e-common-proc-board.dts has cells=1, but user's phandle
>> does not have an argument, so practically it is ==0? The user -
>> sound/soc/ti/j721e-evm.c - just gets the node and does not use cells,
>> right? So even though dai-cells==1, it does not matter, because user
>> gets its own parsing?
>>
>> 3. The pcm3168a driver also does not have any xlate function, but it
>> registers to DAIs, so all uses should be with cells==1 to select proper
>> DAI...
> 
> I have no idea (DAI is magic to me), and hope the audio experts
> can provide some input...

It is a bit of magic to me too. Yet I think the correct usage of this is
with dai-cells=1. I think we can skip the choice here between
sound-dai-cells and endpoints (to allow only one) and only fix the value
here to =1.

This would also require changing
arch/arm64/boot/dts/renesas/ulcb-kf.dtsi to dai-cells=1.

Best regards,
Krzysztof
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt b/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt
deleted file mode 100644
index a02ecaab518327d5..0000000000000000
--- a/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt
+++ /dev/null
@@ -1,56 +0,0 @@ 
-Texas Instruments pcm3168a DT bindings
-
-This driver supports both SPI and I2C bus access for this codec
-
-Required properties:
-
-  - compatible: "ti,pcm3168a"
-
-  - clocks : Contains an entry for each entry in clock-names
-
-  - clock-names : Includes the following entries:
-	"scki"	The system clock
-
-  - VDD1-supply : Digital power supply regulator 1 (+3.3V)
-
-  - VDD2-supply : Digital power supply regulator 2 (+3.3V)
-
-  - VCCAD1-supply : ADC power supply regulator 1 (+5V)
-
-  - VCCAD2-supply : ADC power supply regulator 2 (+5V)
-
-  - VCCDA1-supply : DAC power supply regulator 1 (+5V)
-
-  - VCCDA2-supply : DAC power supply regulator 2 (+5V)
-
-For required properties on SPI/I2C, consult SPI/I2C device tree documentation
-
-Optional properties:
-
-  - reset-gpios : Optional reset gpio line connected to RST pin of the codec.
-		  The RST line is low active:
-		  RST = low: device power-down
-		  RST = high: device is enabled
-
-Examples:
-
-i2c0: i2c0@0 {
-
-	...
-
-	pcm3168a: audio-codec@44 {
-		compatible = "ti,pcm3168a";
-		reg = <0x44>;
-		reset-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>;
-		clocks = <&clk_core CLK_AUDIO>;
-		clock-names = "scki";
-		VDD1-supply = <&supply3v3>;
-		VDD2-supply = <&supply3v3>;
-		VCCAD1-supply = <&supply5v0>;
-		VCCAD2-supply = <&supply5v0>;
-		VCCDA1-supply = <&supply5v0>;
-		VCCDA2-supply = <&supply5v0>;
-		pinctrl-names = "default";
-		pinctrl-0 = <&dac_clk_pin>;
-	};
-};
diff --git a/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml
new file mode 100644
index 0000000000000000..a977507c52b05aed
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml
@@ -0,0 +1,105 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ti,pcm3168a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments PCM3168A Audio Codec
+
+maintainers:
+  - Damien Horsley <Damien.Horsley@imgtec.com>
+
+description:
+  The Texas Instruments PCM3168A is a 24-bit Multi-channel Audio CODEC with
+  96/192kHz sampling rate, supporting both SPI and I2C bus access.
+
+properties:
+  compatible:
+    const: ti,pcm3168a
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    items:
+      - description: System clock input
+
+  clock-names:
+    items:
+      - const: scki
+
+  reset-gpios:
+    items:
+      - description: |
+          GPIO line connected to the active-low RST pin of the codec.
+            RST = low: device power-down
+            RST = high: device is enabled
+
+  "#sound-dai-cells":
+    enum: [0, 1]
+
+  VDD1-supply:
+    description: Digital power supply regulator 1 (+3.3V)
+
+  VDD2-supply:
+    description: Digital power supply regulator 2 (+3.3V)
+
+  VCCAD1-supply:
+    description: ADC power supply regulator 1 (+5V)
+
+  VCCAD2-supply:
+    description: ADC power supply regulator 2 (+5V)
+
+  VCCDA1-supply:
+    description: DAC power supply regulator 1 (+5V)
+
+  VCCDA2-supply:
+    description: DAC power supply regulator 2 (+5V)
+
+  ports:
+    $ref: /schemas/graph.yaml#/properties/ports
+    properties:
+      port@0:
+        $ref: audio-graph-port.yaml#
+        description: Audio input port.
+
+      port@1:
+        $ref: audio-graph-port.yaml#
+        description: Audio output port.
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - VDD1-supply
+  - VDD2-supply
+  - VCCAD1-supply
+  - VCCAD2-supply
+  - VCCDA1-supply
+  - VCCDA2-supply
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        pcm3168a: audio-codec@44 {
+            compatible = "ti,pcm3168a";
+            reg = <0x44>;
+            reset-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>;
+            clocks = <&clk_core 42>;
+            clock-names = "scki";
+            VDD1-supply = <&supply3v3>;
+            VDD2-supply = <&supply3v3>;
+            VCCAD1-supply = <&supply5v0>;
+            VCCAD2-supply = <&supply5v0>;
+            VCCDA1-supply = <&supply5v0>;
+            VCCDA2-supply = <&supply5v0>;
+        };
+    };