2022-08-02 21:50:10

by Jai Luthra

Subject: [PATCH] dt-bindings: sound: tlv320aic3x: Convert to dtschema

Convert bindings for TI's TLV320AIC3x audio codecs to dtschema.

Signed-off-by: Jai Luthra <[email protected]>
---
.../devicetree/bindings/sound/tlv320aic3x.txt | 97 ------------
.../bindings/sound/tlv320aic3x.yaml | 145 ++++++++++++++++++
2 files changed, 145 insertions(+), 97 deletions(-)
delete mode 100644 Documentation/devicetree/bindings/sound/tlv320aic3x.txt
create mode 100644 Documentation/devicetree/bindings/sound/tlv320aic3x.yaml

diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt
deleted file mode 100644
index 20931a63fd64..000000000000
--- a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt
+++ /dev/null
@@ -1,97 +0,0 @@
-Texas Instruments - tlv320aic3x Codec module
-
-The tlv320aic3x serial control bus communicates through both I2C and SPI bus protocols
-
-Required properties:
-
-- compatible - "string" - One of:
- "ti,tlv320aic3x" - Generic TLV320AIC3x device
- "ti,tlv320aic33" - TLV320AIC33
- "ti,tlv320aic3007" - TLV320AIC3007
- "ti,tlv320aic3106" - TLV320AIC3106
- "ti,tlv320aic3104" - TLV320AIC3104
-
-
-- reg - <int> - I2C slave address
-
-
-Optional properties:
-
-- reset-gpios - GPIO specification for the active low RESET input.
-- ai3x-gpio-func - <array of 2 int> - AIC3X_GPIO1 & AIC3X_GPIO2 Functionality
- - Not supported on tlv320aic3104
-- ai3x-micbias-vg - MicBias Voltage required.
- 1 - MICBIAS output is powered to 2.0V,
- 2 - MICBIAS output is powered to 2.5V,
- 3 - MICBIAS output is connected to AVDD,
- If this node is not mentioned or if the value is incorrect, then MicBias
- is powered down.
-- ai3x-ocmv - Output Common-Mode Voltage selection:
- 0 - 1.35V,
- 1 - 1.5V,
- 2 - 1.65V,
- 3 - 1.8V
-- AVDD-supply, IOVDD-supply, DRVDD-supply, DVDD-supply : power supplies for the
- device as covered in Documentation/devicetree/bindings/regulator/regulator.txt
-
-Deprecated properties:
-
-- gpio-reset - gpio pin number used for codec reset
-
-CODEC output pins:
- * LLOUT
- * RLOUT
- * MONO_LOUT
- * HPLOUT
- * HPROUT
- * HPLCOM
- * HPRCOM
-
-CODEC input pins for TLV320AIC3104:
- * MIC2L
- * MIC2R
- * LINE1L
- * LINE1R
-
-CODEC input pins for other compatible codecs:
- * MIC3L
- * MIC3R
- * LINE1L
- * LINE2L
- * LINE1R
- * LINE2R
-
-The pins can be used in referring sound node's audio-routing property.
-
-I2C example:
-
-#include <dt-bindings/gpio/gpio.h>
-
-tlv320aic3x: tlv320aic3x@1b {
- compatible = "ti,tlv320aic3x";
- reg = <0x1b>;
-
- reset-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>;
-
- AVDD-supply = <&regulator>;
- IOVDD-supply = <&regulator>;
- DRVDD-supply = <&regulator>;
- DVDD-supply = <&regulator>;
-};
-
-SPI example:
-
-spi0: spi@f0000000 {
- tlv320aic3x: codec@0 {
- compatible = "ti,tlv320aic3x";
- reg = <0>; /* CS number */
- #sound-dai-cells = <0>;
- spi-max-frequency = <1000000>;
-
- AVDD-supply = <&regulator>;
- IOVDD-supply = <&regulator>;
- DRVDD-supply = <&regulator>;
- DVDD-supply = <&regulator>;
- ai3x-ocmv = <0>;
- };
-};
diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml b/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml
new file mode 100644
index 000000000000..6efb1d459543
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/tlv320aic3x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TLV320AIC3x Codec Device Tree Bindings
+
+maintainers:
+ - Jai Luthra <[email protected]>
+
+properties:
+ compatible:
+ enum:
+ - ti,tlv320aic3x
+ - ti,tlv320aic33
+ - ti,tlv320aic3007
+ - ti,tlv320aic3106
+ - ti,tlv320aic3104
+
+ reg:
+ maxItems: 1
+ description: i2c slave address
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ GPIO specification for the active low RESET input.
+
+ ai3x-gpio-func:
+ description: AIC3X_GPIO1 & AIC3X_GPIO2 Functionality
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minItems: 3
+ maxItems: 3
+
+ ai3x-micbias-vg:
+ description: MicBias required voltage. If node is omitted then MicBias is powered down.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ oneOf:
+ - const: 1
+ description: MICBIAS output is powered to 2.0V.
+ - const: 2
+ description: MICBIAS output is powered to 2.5V.
+ - const: 3
+ description: MICBIAS output is connected to AVDD.
+
+ ai3x-ocmv:
+ description: Output Common-Mode Voltage selection.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ oneOf:
+ - const: 0
+ description: 1.35V
+ - const: 1
+ description: 1.5V
+ - const: 2
+ description: 1.65V
+ - const: 3
+ description: 1.8V
+
+ AVDD-supply:
+ description: Analog DAC voltage.
+
+ IOVDD-supply:
+ description: I/O voltage.
+
+ DRVDD-supply:
+ description: ADC analog and output driver voltage.
+
+ DVDD-supply:
+ description: Digital core voltage.
+
+ '#sound-dai-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+#The pins can be used in referring sound node's audio-routing property.
+
+#CODEC output pins:
+ # LLOUT
+ # RLOUT
+ # MONO_LOUT
+ # HPLOUT
+ # HPROUT
+ # HPLCOM
+ # HPRCOM
+
+#CODEC input pins for TLV320AIC3104:
+ # MIC2L
+ # MIC2R
+ # LINE1L
+ # LINE1R
+
+#CODEC input pins for other compatible codecs:
+ # MIC3L
+ # MIC3R
+ # LINE1L
+ # LINE2L
+ # LINE1R
+ # LINE2R
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ tlv320aic3x_i2c: tlv320aic3x@1b {
+ compatible = "ti,tlv320aic3x";
+ reg = <0x1b>;
+
+ reset-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>;
+
+ AVDD-supply = <&regulator>;
+ IOVDD-supply = <&regulator>;
+ DRVDD-supply = <&regulator>;
+ DVDD-supply = <&regulator>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ tlv320aic3x_spi: codec@0 {
+ compatible = "ti,tlv320aic3x";
+ reg = <0>; /* CS number */
+ #sound-dai-cells = <0>;
+
+ AVDD-supply = <&regulator>;
+ IOVDD-supply = <&regulator>;
+ DRVDD-supply = <&regulator>;
+ DVDD-supply = <&regulator>;
+ ai3x-ocmv = <0>;
+ };
+ };
+
+...
--
2.17.1

2022-08-02 22:45:39

by Rob Herring (Arm)

Subject: Re: [PATCH] dt-bindings: sound: tlv320aic3x: Convert to dtschema

On Tue, 02 Aug 2022 16:48:11 -0500, Jai Luthra wrote:
> Convert bindings for TI's TLV320AIC3x audio codecs to dtschema.
>
> Signed-off-by: Jai Luthra <[email protected]>
> ---
> .../devicetree/bindings/sound/tlv320aic3x.txt | 97 ------------
> .../bindings/sound/tlv320aic3x.yaml | 145 ++++++++++++++++++
> 2 files changed, 145 insertions(+), 97 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/sound/tlv320aic3x.txt
> create mode 100644 Documentation/devicetree/bindings/sound/tlv320aic3x.yaml
>

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/linux-dt-review/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml: properties:ai3x-gpio-func:maxItems: False schema does not allow 3
hint: Scalar properties should not have array keywords
from schema $id: http://devicetree.org/meta-schemas/keywords.yaml#
/builds/robherring/linux-dt-review/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml: properties:ai3x-gpio-func:minItems: False schema does not allow 3
hint: Scalar properties should not have array keywords
from schema $id: http://devicetree.org/meta-schemas/keywords.yaml#
/builds/robherring/linux-dt-review/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml: ignoring, error in schema: properties: ai3x-gpio-func: maxItems
Documentation/devicetree/bindings/sound/tlv320aic3x.example.dtb:0:0: /example-0/i2c/tlv320aic3x@1b: failed to match any schema with compatible: ['ti,tlv320aic3x']
Documentation/devicetree/bindings/sound/tlv320aic3x.example.dtb:0:0: /example-1/spi/codec@0: failed to match any schema with compatible: ['ti,tlv320aic3x']

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.

2022-08-03 06:58:03

by Krzysztof Kozlowski

Subject: Re: [PATCH] dt-bindings: sound: tlv320aic3x: Convert to dtschema

On 02/08/2022 23:48, Jai Luthra wrote:
> Convert bindings for TI's TLV320AIC3x audio codecs to dtschema.
>
> Signed-off-by: Jai Luthra <[email protected]>
> ---


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

> diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml b/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml
> new file mode 100644
> index 000000000000..6efb1d459543
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml
> @@ -0,0 +1,145 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/sound/tlv320aic3x.yaml#

Filename with vendor prefix, so ti,tlv320aic3x.yaml

> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments TLV320AIC3x Codec Device Tree Bindings

s/Device Tree Bindings//

> +
> +maintainers:
> + - Jai Luthra <[email protected]>
> +
> +properties:
> + compatible:
> + enum:
> + - ti,tlv320aic3x
> + - ti,tlv320aic33
> + - ti,tlv320aic3007
> + - ti,tlv320aic3106
> + - ti,tlv320aic3104
> +
> + reg:
> + maxItems: 1
> + description: i2c slave address

Skip description.

> +
> + reset-gpios:
> + maxItems: 1
> + description:
> + GPIO specification for the active low RESET input.
> +
> + ai3x-gpio-func:
> + description: AIC3X_GPIO1 & AIC3X_GPIO2 Functionality
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minItems: 3

uint32-array. Old bindings say about two items only. Mention any changes
to binding in cover letter.

> + maxItems: 3
> +

You lost gpio-reset property. Also not explained in commit msg.

> + ai3x-micbias-vg:
> + description: MicBias required voltage. If node is omitted then MicBias is powered down.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + oneOf:
> + - const: 1
> + description: MICBIAS output is powered to 2.0V.
> + - const: 2
> + description: MICBIAS output is powered to 2.5V.
> + - const: 3
> + description: MICBIAS output is connected to AVDD.
> +
> + ai3x-ocmv:
> + description: Output Common-Mode Voltage selection.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + oneOf:
> + - const: 0
> + description: 1.35V
> + - const: 1
> + description: 1.5V
> + - const: 2
> + description: 1.65V
> + - const: 3
> + description: 1.8V
> +
> + AVDD-supply:
> + description: Analog DAC voltage.

New properties?

> +
> + IOVDD-supply:
> + description: I/O voltage.
> +
> + DRVDD-supply:
> + description: ADC analog and output driver voltage.
> +
> + DVDD-supply:
> + description: Digital core voltage.
> +
> + '#sound-dai-cells':
> + const: 0
> +
> +required:
> + - compatible
> + - reg
> +
> +#The pins can be used in referring sound node's audio-routing property.
> +
> +#CODEC output pins:
> + # LLOUT
> + # RLOUT
> + # MONO_LOUT
> + # HPLOUT
> + # HPROUT
> + # HPLCOM
> + # HPRCOM
> +
> +#CODEC input pins for TLV320AIC3104:
> + # MIC2L
> + # MIC2R
> + # LINE1L
> + # LINE1R
> +
> +#CODEC input pins for other compatible codecs:
> + # MIC3L
> + # MIC3R
> + # LINE1L
> + # LINE2L
> + # LINE1R
> + # LINE2R

All this goes to top level description.


Best regards,
Krzysztof

2022-08-03 15:32:22

by Jai Luthra

Subject: Re: [PATCH] dt-bindings: sound: tlv320aic3x: Convert to dtschema

Hi Krzysztof,

Thanks for the review.

On 08:29-20220803, Krzysztof Kozlowski wrote:
> On 02/08/2022 23:48, Jai Luthra wrote:
> > Convert bindings for TI's TLV320AIC3x audio codecs to dtschema.
> >
> > Signed-off-by: Jai Luthra <[email protected]>
> > ---
>
>
> Thank you for your patch. There is something to discuss/improve.
>
> > diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml b/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml
> > new file mode 100644
> > index 000000000000..6efb1d459543
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/sound/tlv320aic3x.yaml
> > @@ -0,0 +1,145 @@
> > +# SPDX-License-Identifier: GPL-2.0
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/sound/tlv320aic3x.yaml#
>
> Filename with vendor prefix, so ti,tlv320aic3x.yaml
>
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Texas Instruments TLV320AIC3x Codec Device Tree Bindings
>
> s/Device Tree Bindings//
>
> > +
> > +maintainers:
> > + - Jai Luthra <[email protected]>
> > +
> > +properties:
> > + compatible:
> > + enum:
> > + - ti,tlv320aic3x
> > + - ti,tlv320aic33
> > + - ti,tlv320aic3007
> > + - ti,tlv320aic3106
> > + - ti,tlv320aic3104
> > +
> > + reg:
> > + maxItems: 1
> > + description: i2c slave address
>
> Skip description.
>
> > +
> > + reset-gpios:
> > + maxItems: 1
> > + description:
> > + GPIO specification for the active low RESET input.
> > +
> > + ai3x-gpio-func:
> > + description: AIC3X_GPIO1 & AIC3X_GPIO2 Functionality
> > + $ref: /schemas/types.yaml#/definitions/uint32
> > + minItems: 3
>
> uint32-array. Old bindings say about two items only. Mention any changes
> to binding in cover letter.

My bad, that should still be 2 items.

>
> > + maxItems: 3
> > +
>
> You lost gpio-reset property. Also not explained in commit msg.
>
> > + ai3x-micbias-vg:
> > + description: MicBias required voltage. If node is omitted then MicBias is powered down.
> > + $ref: /schemas/types.yaml#/definitions/uint32
> > + oneOf:
> > + - const: 1
> > + description: MICBIAS output is powered to 2.0V.
> > + - const: 2
> > + description: MICBIAS output is powered to 2.5V.
> > + - const: 3
> > + description: MICBIAS output is connected to AVDD.
> > +
> > + ai3x-ocmv:
> > + description: Output Common-Mode Voltage selection.
> > + $ref: /schemas/types.yaml#/definitions/uint32
> > + oneOf:
> > + - const: 0
> > + description: 1.35V
> > + - const: 1
> > + description: 1.5V
> > + - const: 2
> > + description: 1.65V
> > + - const: 3
> > + description: 1.8V
> > +
> > + AVDD-supply:
> > + description: Analog DAC voltage.
>
> New properties?
>

These regulator properties were mentioned in the txt as well.

> > +
> > + IOVDD-supply:
> > + description: I/O voltage.
> > +
> > + DRVDD-supply:
> > + description: ADC analog and output driver voltage.
> > +
> > + DVDD-supply:
> > + description: Digital core voltage.
> > +
> > + '#sound-dai-cells':
> > + const: 0
> > +
> > +required:
> > + - compatible
> > + - reg
> > +
> > +#The pins can be used in referring sound node's audio-routing property.
> > +
> > +#CODEC output pins:
> > + # LLOUT
> > + # RLOUT
> > + # MONO_LOUT
> > + # HPLOUT
> > + # HPROUT
> > + # HPLCOM
> > + # HPRCOM
> > +
> > +#CODEC input pins for TLV320AIC3104:
> > + # MIC2L
> > + # MIC2R
> > + # LINE1L
> > + # LINE1R
> > +
> > +#CODEC input pins for other compatible codecs:
> > + # MIC3L
> > + # MIC3R
> > + # LINE1L
> > + # LINE2L
> > + # LINE1R
> > + # LINE2R
>
> All this goes to top level description.
>
>
> Best regards,
> Krzysztof

Fixed rest of the comments in v2.

Thanks,
Jai