[PATCH] dt-bindings: nvmem: sprd-efuse: convert to YAML

[PATCH] dt-bindings: nvmem: sprd-efuse: convert to YAML

[Stanislav Jakubek]

Convert the Spreadtrum eFuse bindings to DT schema. Since they are very
similar, both of the existing Spreadtrum txt bindings were merged into
one common binding document, named after the only in-tree user, SC2731.

Signed-off-by: Stanislav Jakubek <stano.jakubek@gmail.com>
---
 .../bindings/nvmem/sc27xx-efuse.txt           | 52 -----------
 .../bindings/nvmem/sprd,sc2731-efuse.yaml     | 88 +++++++++++++++++++
 .../devicetree/bindings/nvmem/sprd-efuse.txt  | 39 --------
 3 files changed, 88 insertions(+), 91 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt
 create mode 100644 Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml
 delete mode 100644 Documentation/devicetree/bindings/nvmem/sprd-efuse.txt

diff --git a/Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt b/Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt
deleted file mode 100644
index 586c08286aa9..000000000000
--- a/Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-= Spreadtrum SC27XX PMIC eFuse device tree bindings =
-
-Required properties:
-- compatible: Should be one of the following.
-	"sprd,sc2720-efuse"
-	"sprd,sc2721-efuse"
-	"sprd,sc2723-efuse"
-	"sprd,sc2730-efuse"
-	"sprd,sc2731-efuse"
-- reg: Specify the address offset of efuse controller.
-- hwlocks: Reference to a phandle of a hwlock provider node.
-
-= Data cells =
-Are child nodes of eFuse, bindings of which as described in
-bindings/nvmem/nvmem.txt
-
-Example:
-
-	sc2731_pmic: pmic@0 {
-		compatible = "sprd,sc2731";
-		reg = <0>;
-		spi-max-frequency = <26000000>;
-		interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>;
-		interrupt-controller;
-		#interrupt-cells = <2>;
-		#address-cells = <1>;
-		#size-cells = <0>;
-
-		efuse@380 {
-			compatible = "sprd,sc2731-efuse";
-			reg = <0x380>;
-			#address-cells = <1>;
-			#size-cells = <1>;
-			hwlocks = <&hwlock 12>;
-
-			/* Data cells */
-			thermal_calib: calib@10 {
-				reg = <0x10 0x2>;
-			};
-		};
-	};
-
-= Data consumers =
-Are device nodes which consume nvmem data cells.
-
-Example:
-
-	thermal {
-		...
-		nvmem-cells = <&thermal_calib>;
-		nvmem-cell-names = "calibration";
-	};
diff --git a/Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml b/Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml
new file mode 100644
index 000000000000..98d1400991d7
--- /dev/null
+++ b/Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/nvmem/sprd,sc2731-efuse.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Spreadtrum eFuse
+
+maintainers:
+  - Orson Zhai <orsonzhai@gmail.com>
+  - Baolin Wang <baolin.wang7@gmail.com>
+  - Chunyan Zhang <zhang.lyra@gmail.com>
+
+properties:
+  compatible:
+    enum:
+      - sprd,sc2720-efuse
+      - sprd,sc2721-efuse
+      - sprd,sc2723-efuse
+      - sprd,sc2730-efuse
+      - sprd,sc2731-efuse
+      - sprd,ums312-efuse
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    const: enable
+
+  hwlocks:
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+  - hwlocks
+
+allOf:
+  - $ref: nvmem.yaml#
+  - $ref: nvmem-deprecated-cells.yaml#
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: sprd,ums312-efuse
+    then:
+      required:
+        - clocks
+        - clock-names
+    else:
+      properties:
+        clocks: false
+        clock-names: false
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    pmic {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      efuse@380 {
+        compatible = "sprd,sc2731-efuse";
+        reg = <0x380>;
+        hwlocks = <&hwlock 12>;
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        /* Data cells */
+        fgu_calib: calib@6 {
+          reg = <0x6 0x2>;
+          bits = <0 9>;
+        };
+
+        adc_big_scale: calib@24 {
+          reg = <0x24 0x2>;
+        };
+
+        adc_small_scale: calib@26 {
+          reg = <0x26 0x2>;
+        };
+      };
+    };
+...
diff --git a/Documentation/devicetree/bindings/nvmem/sprd-efuse.txt b/Documentation/devicetree/bindings/nvmem/sprd-efuse.txt
deleted file mode 100644
index 96b6feec27f0..000000000000
--- a/Documentation/devicetree/bindings/nvmem/sprd-efuse.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-= Spreadtrum eFuse device tree bindings =
-
-Required properties:
-- compatible: Should be "sprd,ums312-efuse".
-- reg: Specify the address offset of efuse controller.
-- clock-names: Should be "enable".
-- clocks: The phandle and specifier referencing the controller's clock.
-- hwlocks: Reference to a phandle of a hwlock provider node.
-
-= Data cells =
-Are child nodes of eFuse, bindings of which as described in
-bindings/nvmem/nvmem.txt
-
-Example:
-
-	ap_efuse: efuse@32240000 {
-		compatible = "sprd,ums312-efuse";
-		reg = <0 0x32240000 0 0x10000>;
-		clock-names = "enable";
-		hwlocks = <&hwlock 8>;
-		clocks = <&aonapb_gate CLK_EFUSE_EB>;
-
-		/* Data cells */
-		thermal_calib: calib@10 {
-			reg = <0x10 0x2>;
-		};
-	};
-
-= Data consumers =
-Are device nodes which consume nvmem data cells.
-
-Example:
-
-	thermal {
-		...
-
-		nvmem-cells = <&thermal_calib>;
-		nvmem-cell-names = "calibration";
-	};
-- 
2.34.1

Re: [PATCH] dt-bindings: nvmem: sprd-efuse: convert to YAML

[Stanislav Jakubek]

Just noticed this old series which among other things, also converted
these bindings to YAML:
https://lore.kernel.org/lkml/20230819055141.29455-1-yanxin.huang@unisoc.com/

CC people from that series, I assume this will be relevant for them as well.

Regards,
Stanislav

Re: [PATCH] dt-bindings: nvmem: sprd-efuse: convert to YAML

[Krzysztof Kozlowski]

On 13/07/2024 14:12, Stanislav Jakubek wrote:
> Convert the Spreadtrum eFuse bindings to DT schema. Since they are very
> similar, both of the existing Spreadtrum txt bindings were merged into
> one common binding document, named after the only in-tree user, SC2731.
> 
> Signed-off-by: Stanislav Jakubek <stano.jakubek@gmail.com>
> ---
>  .../bindings/nvmem/sc27xx-efuse.txt           | 52 -----------
>  .../bindings/nvmem/sprd,sc2731-efuse.yaml     | 88 +++++++++++++++++++
>  .../devicetree/bindings/nvmem/sprd-efuse.txt  | 39 --------
>  3 files changed, 88 insertions(+), 91 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt
>  create mode 100644 Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml
>  delete mode 100644 Documentation/devicetree/bindings/nvmem/sprd-efuse.txt
> 
> diff --git a/Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt b/Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt
> deleted file mode 100644
> index 586c08286aa9..000000000000
> --- a/Documentation/devicetree/bindings/nvmem/sc27xx-efuse.txt
> +++ /dev/null
> @@ -1,52 +0,0 @@
> -= Spreadtrum SC27XX PMIC eFuse device tree bindings =
> -
> -Required properties:
> -- compatible: Should be one of the following.
> -	"sprd,sc2720-efuse"
> -	"sprd,sc2721-efuse"
> -	"sprd,sc2723-efuse"
> -	"sprd,sc2730-efuse"
> -	"sprd,sc2731-efuse"
> -- reg: Specify the address offset of efuse controller.
> -- hwlocks: Reference to a phandle of a hwlock provider node.
> -
> -= Data cells =
> -Are child nodes of eFuse, bindings of which as described in
> -bindings/nvmem/nvmem.txt
> -
> -Example:
> -
> -	sc2731_pmic: pmic@0 {
> -		compatible = "sprd,sc2731";
> -		reg = <0>;
> -		spi-max-frequency = <26000000>;
> -		interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>;
> -		interrupt-controller;
> -		#interrupt-cells = <2>;
> -		#address-cells = <1>;
> -		#size-cells = <0>;
> -
> -		efuse@380 {
> -			compatible = "sprd,sc2731-efuse";
> -			reg = <0x380>;
> -			#address-cells = <1>;
> -			#size-cells = <1>;
> -			hwlocks = <&hwlock 12>;
> -
> -			/* Data cells */
> -			thermal_calib: calib@10 {
> -				reg = <0x10 0x2>;
> -			};
> -		};
> -	};
> -
> -= Data consumers =
> -Are device nodes which consume nvmem data cells.
> -
> -Example:
> -
> -	thermal {
> -		...
> -		nvmem-cells = <&thermal_calib>;
> -		nvmem-cell-names = "calibration";
> -	};
> diff --git a/Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml b/Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml
> new file mode 100644
> index 000000000000..98d1400991d7
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml
> @@ -0,0 +1,88 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/nvmem/sprd,sc2731-efuse.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Spreadtrum eFuse
> +
> +maintainers:
> +  - Orson Zhai <orsonzhai@gmail.com>
> +  - Baolin Wang <baolin.wang7@gmail.com>
> +  - Chunyan Zhang <zhang.lyra@gmail.com>
> +
> +properties:
> +  compatible:
> +    enum:
> +      - sprd,sc2720-efuse
> +      - sprd,sc2721-efuse
> +      - sprd,sc2723-efuse
> +      - sprd,sc2730-efuse
> +      - sprd,sc2731-efuse
> +      - sprd,ums312-efuse
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: enable
> +
> +  hwlocks:
> +    maxItems: 1
> +
> +required:
> +  - compatible
> +  - reg
> +  - hwlocks
> +
> +allOf:
> +  - $ref: nvmem.yaml#
> +  - $ref: nvmem-deprecated-cells.yaml#
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: sprd,ums312-efuse
> +    then:
> +      required:
> +        - clocks
> +        - clock-names
> +    else:
> +      properties:
> +        clocks: false
> +        clock-names: false

Half of the binding is this "if:", so I would say they are not that
similar. I think it would be easier to read them if these were split
into two bindings.

Best regards,
Krzysztof

Re: [PATCH] dt-bindings: nvmem: sprd-efuse: convert to YAML

[Stanislav Jakubek]

On Sat, Jul 13, 2024 at 08:31:31PM +0200, Krzysztof Kozlowski wrote:
> On 13/07/2024 14:12, Stanislav Jakubek wrote:

[snip]

> > +allOf:
> > +  - $ref: nvmem.yaml#
> > +  - $ref: nvmem-deprecated-cells.yaml#
> > +  - if:
> > +      properties:
> > +        compatible:
> > +          contains:
> > +            const: sprd,ums312-efuse
> > +    then:
> > +      required:
> > +        - clocks
> > +        - clock-names
> > +    else:
> > +      properties:
> > +        clocks: false
> > +        clock-names: false
> 
> Half of the binding is this "if:", so I would say they are not that
> similar. I think it would be easier to read them if these were split
> into two bindings.
> 
> Best regards,
> Krzysztof
> 

Hi Krzysztof,

pretty much this exact if-then-else is described in the "Writing Devicetree
Bindings in json-schema" documentation as a "typical case" for its usage, so
I went with that. I think that it's simple enough that it only minimally
hampers readability.

I admit that there might be some confusion, since I forgot to include an
example for the sprd,ums312-efuse (i.e. with clocks and clock-names).
Could I just add this example in V2 and keep it as-is otherwise?

Regards,
Stanislav

Re: [PATCH] dt-bindings: nvmem: sprd-efuse: convert to YAML

[Krzysztof Kozlowski]

On 14/07/2024 13:10, Stanislav Jakubek wrote:
> On Sat, Jul 13, 2024 at 08:31:31PM +0200, Krzysztof Kozlowski wrote:
>> On 13/07/2024 14:12, Stanislav Jakubek wrote:
> 
> [snip]
> 
>>> +allOf:
>>> +  - $ref: nvmem.yaml#
>>> +  - $ref: nvmem-deprecated-cells.yaml#
>>> +  - if:
>>> +      properties:
>>> +        compatible:
>>> +          contains:
>>> +            const: sprd,ums312-efuse
>>> +    then:
>>> +      required:
>>> +        - clocks
>>> +        - clock-names
>>> +    else:
>>> +      properties:
>>> +        clocks: false
>>> +        clock-names: false
>>
>> Half of the binding is this "if:", so I would say they are not that
>> similar. I think it would be easier to read them if these were split
>> into two bindings.
>>
>> Best regards,
>> Krzysztof
>>
> 
> Hi Krzysztof,
> 
> pretty much this exact if-then-else is described in the "Writing Devicetree
> Bindings in json-schema" documentation as a "typical case" for its usage, so
> I went with that. I think that it's simple enough that it only minimally
> hampers readability.

Example schema has a lot of stuff shown, because it is example...

> 
> I admit that there might be some confusion, since I forgot to include an
> example for the sprd,ums312-efuse (i.e. with clocks and clock-names).
> Could I just add this example in V2 and keep it as-is otherwise?

Usually one example per binding is enough, if devices differ by one
property.


Best regards,
Krzysztof