[PATCH] dt-bindings: convert ac97 controller child node codec to dtschema

[PATCH] dt-bindings: convert ac97 controller child node codec to dtschema

[Archana]

Convert codec bindings of an ac97 controller child node describing ac97 codecs to DT schema.
Update example during conversion.

Signed-off-by: Archana <craechal@gmail.com>
---
 .../devicetree/bindings/sound/ac97-bus.txt    | 32 ----------
 .../devicetree/bindings/sound/ac97-bus.yaml   | 60 +++++++++++++++++++
 2 files changed, 60 insertions(+), 32 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.txt
 create mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.yaml

diff --git a/Documentation/devicetree/bindings/sound/ac97-bus.txt b/Documentation/devicetree/bindings/sound/ac97-bus.txt
deleted file mode 100644
index 103c428f2595..000000000000
--- a/Documentation/devicetree/bindings/sound/ac97-bus.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-Generic AC97 Device Properties
-
-This documents describes the devicetree bindings for an ac97 controller child
-node describing ac97 codecs.
-
-Required properties:
--compatible : Must be "ac97,vendor_id1,vendor_id2
-	      The ids shall be the 4 characters hexadecimal encoding, such as
-	      given by "%04x" formatting of printf
--reg	    : Must be the ac97 codec number, between 0 and 3
-
-Example:
-ac97: sound@40500000 {
-	compatible = "marvell,pxa270-ac97";
-	reg = < 0x40500000 0x1000 >;
-	interrupts = <14>;
-	reset-gpios = <&gpio 95 GPIO_ACTIVE_HIGH>;
-	#sound-dai-cells = <1>;
-	pinctrl-names = "default";
-	pinctrl-0 = < &pinctrl_ac97_default >;
-	clocks = <&clks CLK_AC97>, <&clks CLK_AC97CONF>;
-	clock-names = "AC97CLK", "AC97CONFCLK";
-
-	#address-cells = <1>;
-	#size-cells = <0>;
-	audio-codec@0 {
-		reg = <0>;
-		compatible = "ac97,574d,4c13";
-		clocks = <&fixed_wm9713_clock>;
-		clock-names = "ac97_clk";
-	}
-};
diff --git a/Documentation/devicetree/bindings/sound/ac97-bus.yaml b/Documentation/devicetree/bindings/sound/ac97-bus.yaml
new file mode 100644
index 000000000000..469fd88ff729
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ac97-bus.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ac97-bus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic AC97 Device Properties
+
+maintainers:
+  - Archana <craechal@gmail.com>
+
+description: |
+  This documents describes the devicetree bindings for an ac97 controller child 
+  node describing ac97 codecs.
+
+allOf:
+  - $ref: dai-common.yaml#
+
+properties:
+  compatible:
+    description:
+      Must be "ac97,vendor_id1,vendor_id2". The ids shall be the 4 characters hexadecimal encoding, such as
+      given by "%04x" formatting of printf
+    pattern: "^ac97,[A-Fa-f0-9]{4},[A-Fa-f0-9]{4}$"
+
+  reg:
+    description: Must be the ac97 codec number, between 0 and 3
+    minimum: 0
+    maximum: 3
+    
+required:
+  - compatible
+  - reg
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/clock/pxa-clock.h>
+    ac97: sound@40500000 {
+      compatible = "marvell,pxa270-ac97";
+      reg = < 0x40500000 0x1000 >;
+      interrupts = <14>;
+      reset-gpios = <&gpio 95 GPIO_ACTIVE_HIGH>;
+      #sound-dai-cells = <1>;
+      pinctrl-names = "default";
+      pinctrl-0 = < &pinctrl_ac97_default >;
+      clocks = <&clks CLK_AC97>, <&clks CLK_AC97CONF>;
+      clock-names = "AC97CLK", "AC97CONFCLK";
+
+      #address-cells = <1>;
+      #size-cells = <0>;
+      audio-codec@0 {
+        reg = <0>;
+        compatible = "ac97,574d,4c13";
+        clocks = <&fixed_wm9713_clock>;
+        clock-names = "ac97_clk";
+      };
+    };
\ No newline at end of file
-- 
2.34.1

[PATCH v2] dt-bindings: convert ac97 controller child node codec to dtschema

[Archana]

Convert codec bindings of an ac97 controller child node describing ac97 codecs to DT schema.
Update example during conversion.

Signed-off-by: Archana <craechal@gmail.com>
---
v1->v2:
1. Add newline at end of file

 .../devicetree/bindings/sound/ac97-bus.txt    | 32 ----------
 .../devicetree/bindings/sound/ac97-bus.yaml   | 60 +++++++++++++++++++
 2 files changed, 60 insertions(+), 32 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.txt
 create mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.yaml

diff --git a/Documentation/devicetree/bindings/sound/ac97-bus.txt b/Documentation/devicetree/bindings/sound/ac97-bus.txt
deleted file mode 100644
index 103c428f2595..000000000000
--- a/Documentation/devicetree/bindings/sound/ac97-bus.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-Generic AC97 Device Properties
-
-This documents describes the devicetree bindings for an ac97 controller child
-node describing ac97 codecs.
-
-Required properties:
--compatible : Must be "ac97,vendor_id1,vendor_id2
-	      The ids shall be the 4 characters hexadecimal encoding, such as
-	      given by "%04x" formatting of printf
--reg	    : Must be the ac97 codec number, between 0 and 3
-
-Example:
-ac97: sound@40500000 {
-	compatible = "marvell,pxa270-ac97";
-	reg = < 0x40500000 0x1000 >;
-	interrupts = <14>;
-	reset-gpios = <&gpio 95 GPIO_ACTIVE_HIGH>;
-	#sound-dai-cells = <1>;
-	pinctrl-names = "default";
-	pinctrl-0 = < &pinctrl_ac97_default >;
-	clocks = <&clks CLK_AC97>, <&clks CLK_AC97CONF>;
-	clock-names = "AC97CLK", "AC97CONFCLK";
-
-	#address-cells = <1>;
-	#size-cells = <0>;
-	audio-codec@0 {
-		reg = <0>;
-		compatible = "ac97,574d,4c13";
-		clocks = <&fixed_wm9713_clock>;
-		clock-names = "ac97_clk";
-	}
-};
diff --git a/Documentation/devicetree/bindings/sound/ac97-bus.yaml b/Documentation/devicetree/bindings/sound/ac97-bus.yaml
new file mode 100644
index 000000000000..4d86d557c303
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ac97-bus.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ac97-bus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic AC97 Device Properties
+
+maintainers:
+  - Archana <craechal@gmail.com>
+
+description: |
+  This documents describes the devicetree bindings for an ac97 controller child 
+  node describing ac97 codecs.
+
+allOf:
+  - $ref: dai-common.yaml#
+
+properties:
+  compatible:
+    description:
+      Must be "ac97,vendor_id1,vendor_id2". The ids shall be the 4 characters hexadecimal encoding, such as
+      given by "%04x" formatting of printf
+    pattern: "^ac97,[A-Fa-f0-9]{4},[A-Fa-f0-9]{4}$"
+
+  reg:
+    description: Must be the ac97 codec number, between 0 and 3
+    minimum: 0
+    maximum: 3
+
+required:
+  - compatible
+  - reg
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/clock/pxa-clock.h>
+    ac97: sound@40500000 {
+      compatible = "marvell,pxa270-ac97";
+      reg = < 0x40500000 0x1000 >;
+      interrupts = <14>;
+      reset-gpios = <&gpio 95 GPIO_ACTIVE_HIGH>;
+      #sound-dai-cells = <1>;
+      pinctrl-names = "default";
+      pinctrl-0 = < &pinctrl_ac97_default >;
+      clocks = <&clks CLK_AC97>, <&clks CLK_AC97CONF>;
+      clock-names = "AC97CLK", "AC97CONFCLK";
+
+      #address-cells = <1>;
+      #size-cells = <0>;
+      audio-codec@0 {
+        reg = <0>;
+        compatible = "ac97,574d,4c13";
+        clocks = <&fixed_wm9713_clock>;
+        clock-names = "ac97_clk";
+      };
+    };
-- 
2.34.1

Re: [PATCH v2] dt-bindings: convert ac97 controller child node codec to dtschema

[Krzysztof Kozlowski]

On 25/03/2023 21:49, Archana wrote:

If you are sending it as part of GSoC or other mentorship programme,
please follow exactly the instructions you got. This way we will avoid
trivial mistakes.

> Convert codec bindings of an ac97 controller child node describing ac97 codecs to DT schema.
> Update example during conversion.

Use subject prefixes matching the subsystem (which you can get for
example with `git log --oneline -- DIRECTORY_OR_FILE` on the directory
your patch is touching).

> 
> Signed-off-by: Archana <craechal@gmail.com>

Usually we expect someones full used name and pseudonyms are not
allowed. Are you sure this is your full used name?

> ---
> v1->v2:
> 1. Add newline at end of file
> 
>  .../devicetree/bindings/sound/ac97-bus.txt    | 32 ----------
>  .../devicetree/bindings/sound/ac97-bus.yaml   | 60 +++++++++++++++++++
>  2 files changed, 60 insertions(+), 32 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.txt
>  create mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.yaml

Please use scripts/get_maintainers.pl to get a list of necessary people
and lists to CC.  It might happen, that command when run on an older
kernel, gives you outdated entries.  Therefore please be sure you base
your patches on recent Linux kernel.

> 
> diff --git a/Documentation/devicetree/bindings/sound/ac97-bus.txt b/Documentation/devicetree/bindings/sound/ac97-bus.txt
> deleted file mode 100644
> index 103c428f2595..000000000000
> --- a/Documentation/devicetree/bindings/sound/ac97-bus.txt
> +++ /dev/null
> @@ -1,32 +0,0 @@
> -Generic AC97 Device Properties
> -
> -This documents describes the devicetree bindings for an ac97 controller child
> -node describing ac97 codecs.
> -
> -Required properties:
> --compatible : Must be "ac97,vendor_id1,vendor_id2
> -	      The ids shall be the 4 characters hexadecimal encoding, such as
> -	      given by "%04x" formatting of printf
> --reg	    : Must be the ac97 codec number, between 0 and 3
> -
> -Example:
> -ac97: sound@40500000 {
> -	compatible = "marvell,pxa270-ac97";
> -	reg = < 0x40500000 0x1000 >;
> -	interrupts = <14>;
> -	reset-gpios = <&gpio 95 GPIO_ACTIVE_HIGH>;
> -	#sound-dai-cells = <1>;
> -	pinctrl-names = "default";
> -	pinctrl-0 = < &pinctrl_ac97_default >;
> -	clocks = <&clks CLK_AC97>, <&clks CLK_AC97CONF>;
> -	clock-names = "AC97CLK", "AC97CONFCLK";
> -
> -	#address-cells = <1>;
> -	#size-cells = <0>;
> -	audio-codec@0 {
> -		reg = <0>;
> -		compatible = "ac97,574d,4c13";
> -		clocks = <&fixed_wm9713_clock>;
> -		clock-names = "ac97_clk";
> -	}
> -};
> diff --git a/Documentation/devicetree/bindings/sound/ac97-bus.yaml b/Documentation/devicetree/bindings/sound/ac97-bus.yaml
> new file mode 100644
> index 000000000000..4d86d557c303
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/ac97-bus.yaml
> @@ -0,0 +1,60 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/sound/ac97-bus.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Generic AC97 Device Properties
> +
> +maintainers:
> +  - Archana <craechal@gmail.com>
> +
> +description: |
> +  This documents describes the devicetree bindings for an ac97 controller child 
> +  node describing ac97 codecs.

Drop "This documents describes the devicetree bindings for an " but
describe hardware instead.

> +
> +allOf:
> +  - $ref: dai-common.yaml#
> +
> +properties:
> +  compatible:
> +    description:
> +      Must be "ac97,vendor_id1,vendor_id2". The ids shall be the 4 characters hexadecimal encoding, such as
> +      given by "%04x" formatting of printf
> +    pattern: "^ac97,[A-Fa-f0-9]{4},[A-Fa-f0-9]{4}$"
> +
> +  reg:
> +    description: Must be the ac97 codec number, between 0 and 3

Don't repeat constraints in free form text.

> +    minimum: 0
> +    maximum: 3
> +
> +required:
> +  - compatible
> +  - reg
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +    #include <dt-bindings/clock/pxa-clock.h>
> +    ac97: sound@40500000 {
> +      compatible = "marvell,pxa270-ac97";
> +      reg = < 0x40500000 0x1000 >;

Drop redundant spaces (use coding style matching DTS).

> +      interrupts = <14>;
> +      reset-gpios = <&gpio 95 GPIO_ACTIVE_HIGH>;
> +      #sound-dai-cells = <1>;
> +      pinctrl-names = "default";
> +      pinctrl-0 = < &pinctrl_ac97_default >;
> +      clocks = <&clks CLK_AC97>, <&clks CLK_AC97CONF>;
> +      clock-names = "AC97CLK", "AC97CONFCLK";
> +
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +      audio-codec@0 {
> +        reg = <0>;
> +        compatible = "ac97,574d,4c13";
> +        clocks = <&fixed_wm9713_clock>;
> +        clock-names = "ac97_clk";

Please put compatible first in the list of properties (and follow the
same order in "required"). It's the most important piece, so we want it
to be the first to see. It also follows the convention of DTS, where
compatible is expected to be first.

> +      };
> +    };

Best regards,
Krzysztof

Re: [PATCH v2] dt-bindings: convert ac97 controller child node codec to dtschema

[Rob Herring]

On Sat, 25 Mar 2023 20:49:44 +0000, Archana wrote:
> Convert codec bindings of an ac97 controller child node describing ac97 codecs to DT schema.
> Update example during conversion.
> 
> Signed-off-by: Archana <craechal@gmail.com>
> ---
> v1->v2:
> 1. Add newline at end of file
> 
>  .../devicetree/bindings/sound/ac97-bus.txt    | 32 ----------
>  .../devicetree/bindings/sound/ac97-bus.yaml   | 60 +++++++++++++++++++
>  2 files changed, 60 insertions(+), 32 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.txt
>  create mode 100644 Documentation/devicetree/bindings/sound/ac97-bus.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:
Documentation/devicetree/bindings/sound/ac97-bus.example.dtb: /example-0/sound@40500000: failed to match any schema with compatible: ['marvell,pxa270-ac97']

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20230325204944.7151-1-craechal@gmail.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

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 after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.