[PATCHv3] dt-bindings: mfd: omap-usb-tll: convert to YAML

[PATCHv3] dt-bindings: mfd: omap-usb-tll: convert to YAML

[Karol Przybylski]

Conversion of omap-usb-tll.txt into yaml format, inspired by discussion in
lore.kernel.org/all/cd915c18-7230-4c38-a860-d2a777223147@kernel.org/

Changes made to the binding during conversion:
- Added Roger Quadros as maintainer
- Removed deprecated ti,hwmod
- Renamed .yaml file to ti,usbhs-tll.yaml

Signed-off-by: Karol Przybylski <karprzy7@gmail.com>
---
 .../devicetree/bindings/mfd/omap-usb-tll.txt  | 27 -----------
 .../devicetree/bindings/mfd/ti,usbhs-tll.yaml | 47 +++++++++++++++++++
 2 files changed, 47 insertions(+), 27 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/mfd/omap-usb-tll.txt
 create mode 100644 Documentation/devicetree/bindings/mfd/ti,usbhs-tll.yaml

diff --git a/Documentation/devicetree/bindings/mfd/omap-usb-tll.txt b/Documentation/devicetree/bindings/mfd/omap-usb-tll.txt
deleted file mode 100644
index c58d70437..000000000
--- a/Documentation/devicetree/bindings/mfd/omap-usb-tll.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-OMAP HS USB Host TLL (Transceiver-Less Interface)
-
-Required properties:
-
-- compatible : should be "ti,usbhs-tll"
-- reg : should contain one register range i.e. start and length
-- interrupts : should contain the TLL module's interrupt
-- ti,hwmod : must contain "usb_tll_hs"
-
-Optional properties:
-
-- clocks: a list of phandles and clock-specifier pairs, one for each entry in
-  clock-names.
-
-- clock-names: should include:
-  * "usb_tll_hs_usb_ch0_clk" - USB TLL channel 0 clock
-  * "usb_tll_hs_usb_ch1_clk" - USB TLL channel 1 clock
-  * "usb_tll_hs_usb_ch2_clk" - USB TLL channel 2 clock
-
-Example:
-
-	usbhstll: usbhstll@4a062000 {
-		compatible = "ti,usbhs-tll";
-		reg = <0x4a062000 0x1000>;
-		interrupts = <78>;
-		ti,hwmods = "usb_tll_hs";
-	  };
diff --git a/Documentation/devicetree/bindings/mfd/ti,usbhs-tll.yaml b/Documentation/devicetree/bindings/mfd/ti,usbhs-tll.yaml
new file mode 100644
index 000000000..aa4edc51d
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/ti,usbhs-tll.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/ti,usbhs-tll.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OMAP HS USB Host TLL (Transceiver-Less Interface)
+
+maintainers:
+  - Roger Quadros <rogerq@kernel.org>
+
+properties:
+  compatible:
+    enum:
+      - ti,usbhs-tll
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    minItems: 1
+    maxItems: 3
+
+  clock-names:
+    items:
+      - const: usb_tll_hs_usb_ch0_clk
+      - const: usb_tll_hs_usb_ch1_clk
+      - const: usb_tll_hs_usb_ch2_clk
+    minItems: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+additionalProperties: false
+
+examples:
+  - |
+    usbhstll@4a062000 {
+      compatible = "ti,usbhs-tll";
+      reg = <0x4a062000 0x1000>;
+      interrupts = <78>;
+    };
-- 
2.34.1

Re: [PATCHv3] dt-bindings: mfd: omap-usb-tll: convert to YAML

[Krzysztof Kozlowski]

On Sat, Dec 14, 2024 at 10:52:07PM +0100, Karol Przybylski wrote:
> Conversion of omap-usb-tll.txt into yaml format, inspired by discussion in
> lore.kernel.org/all/cd915c18-7230-4c38-a860-d2a777223147@kernel.org/
> 
> Changes made to the binding during conversion:
> - Added Roger Quadros as maintainer
> - Removed deprecated ti,hwmod
> - Renamed .yaml file to ti,usbhs-tll.yaml
> 
> Signed-off-by: Karol Przybylski <karprzy7@gmail.com>
> ---

Changelog goes here. I asked about this last time.

Use b4 or `git format-patch -v3`, so there will be proper space before
v3 in subject prefix.

These are nits but the problem is that you never responded to my review
and did not implement it fully.

>  .../devicetree/bindings/mfd/omap-usb-tll.txt  | 27 -----------
>  .../devicetree/bindings/mfd/ti,usbhs-tll.yaml | 47 +++++++++++++++++++
>  2 files changed, 47 insertions(+), 27 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/mfd/omap-usb-tll.txt
>  create mode 100644 Documentation/devicetree/bindings/mfd/ti,usbhs-tll.yaml

...

> +  clocks:
> +    minItems: 1
> +    maxItems: 3
> +
> +  clock-names:
> +    items:
> +      - const: usb_tll_hs_usb_ch0_clk
> +      - const: usb_tll_hs_usb_ch1_clk
> +      - const: usb_tll_hs_usb_ch2_clk
> +    minItems: 1

Same question as last time - why the number of clocks is flexible?
Original binding suggested that if clocks are present, then three clocks
are required, so you are changing here something which should be
explained in commit msg.

More over, implementation suggests that you could provide clock "ch2"
without "ch0" and "ch1", which your binding does not allow. So again a
change or deviation from the current ABI.

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    usbhstll@4a062000 {
> +      compatible = "ti,usbhs-tll";
> +      reg = <0x4a062000 0x1000>;
> +      interrupts = <78>;

Nothing improved here. See my last comment.

Best regards,
Krzysztof