[PATCH v3] dt-bindings: usb: uhci: convert to dt schema

[PATCH v3] dt-bindings: usb: uhci: convert to dt schema

[Mohammad Shehar Yaar Tausif]

Convert USB UHCI bindings to DT schema. Documenting aspeed compatibles
and missing properties. Adding aspeed/generic-uhci example and fix previous
incorrect example.

Signed-off-by: Mohammad Shehar Yaar Tausif <sheharyaar48@gmail.com>
---
Changes 
v1->v2:
- add aspeed compatible and deprecated platform-uhci compatible
v2->v3:
- fix property declaration and if-then-else block
- add generic-uhci example and fix prev incorrect example

v2 patch : https://lore.kernel.org/all/20240422093706.324115-1-sheharyaar48@gmail.com
v1 patch : https://lore.kernel.org/all/20240420142108.76984-1-sheharyaar48@gmail.com
---
 .../devicetree/bindings/usb/usb-uhci.txt      | 18 -----
 .../devicetree/bindings/usb/usb-uhci.yaml     | 72 +++++++++++++++++++
 2 files changed, 72 insertions(+), 18 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/usb/usb-uhci.txt
 create mode 100644 Documentation/devicetree/bindings/usb/usb-uhci.yaml

diff --git a/Documentation/devicetree/bindings/usb/usb-uhci.txt b/Documentation/devicetree/bindings/usb/usb-uhci.txt
deleted file mode 100644
index d1702eb2c8bd..000000000000
--- a/Documentation/devicetree/bindings/usb/usb-uhci.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-Generic Platform UHCI Controller
------------------------------------------------------
-
-Required properties:
-- compatible : "generic-uhci" (deprecated: "platform-uhci")
-- reg : Should contain 1 register ranges(address and length)
-- interrupts : UHCI controller interrupt
-
-additionally the properties from usb-hcd.yaml (in the current directory) are
-supported.
-
-Example:
-
-	uhci@d8007b00 {
-		compatible = "generic-uhci";
-		reg = <0xd8007b00 0x200>;
-		interrupts = <43>;
-	};
diff --git a/Documentation/devicetree/bindings/usb/usb-uhci.yaml b/Documentation/devicetree/bindings/usb/usb-uhci.yaml
new file mode 100644
index 000000000000..fc4f0174640c
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/usb-uhci.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/usb-uhci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic Platform UHCI Controller
+
+maintainers:
+  - Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+
+properties:
+  compatible:
+    oneOf:
+      - const: generic-uhci
+      - const: platform-uhci
+        deprecated: true
+      - items:
+          - enum:
+              - aspeed,ast2400-uhci
+              - aspeed,ast2500-uhci
+              - aspeed,ast2600-uhci
+          - const: generic-uhci
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  '#ports':
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+  clocks:
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: generic-uhci
+    then:
+      $ref: usb-hcd.yaml
+      required:
+        - clocks
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    uhci@d8007b00 {
+        compatible = "platform-uhci";
+        reg = <0xd8007b00 0x200>;
+        interrupts = <43>;
+    };
+  - |
+    #include <dt-bindings/clock/aspeed-clock.h>
+
+    usb@1e6b0000 {
+        compatible = "aspeed,ast2500-uhci", "generic-uhci";
+        reg = <0x1e6b0000 0x100>;
+        interrupts = <14>;
+        #ports = <2>;
+        clocks = <&syscon ASPEED_CLK_GATE_USBUHCICLK>;
+    };
+...
-- 
2.44.0

Re: [PATCH v3] dt-bindings: usb: uhci: convert to dt schema

[Krzysztof Kozlowski]

On 22/04/2024 14:21, Mohammad Shehar Yaar Tausif wrote:
> Convert USB UHCI bindings to DT schema. Documenting aspeed compatibles
> and missing properties. Adding aspeed/generic-uhci example and fix previous
> incorrect example.
> 
> Signed-off-by: Mohammad Shehar Yaar Tausif <sheharyaar48@gmail.com>

> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: generic-uhci
> +    then:
> +      $ref: usb-hcd.yaml

Nothing improved here.

> +      required:
> +        - clocks

And this was not tested.

> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    uhci@d8007b00 {
> +        compatible = "platform-uhci";

What happened here? This is deprecated!

> +        reg = <0xd8007b00 0x200>;
> +        interrupts = <43>;


Best regards,
Krzysztof

Re: [PATCH v3] dt-bindings: usb: uhci: convert to dt schema

[Mohammad Shehar Yaar Tausif]

On 4/23/24 12:24 PM, Krzysztof Kozlowski wrote:
> On 22/04/2024 14:21, Mohammad Shehar Yaar Tausif wrote:
>> Convert USB UHCI bindings to DT schema. Documenting aspeed compatibles
>> and missing properties. Adding aspeed/generic-uhci example and fix previous
>> incorrect example.
>>
>> Signed-off-by: Mohammad Shehar Yaar Tausif <sheharyaar48@gmail.com>
> 
>> +required:
>> +  - compatible
>> +  - reg
>> +  - interrupts
>> +
>> +allOf:
>> +  - if:
>> +      properties:
>> +        compatible:
>> +          contains:
>> +            const: generic-uhci
>> +    then:
>> +      $ref: usb-hcd.yaml
> 
> Nothing improved here.

Sorry, I could not understand this, please guide me about the correction 
required here.
I added $ref inside the if-then block because it was raising errors when 
tested against
dts files that used "platform-uhci" as the compatible. Putting it above 
the if block did
not work.

When I ref the usb-hcd.yaml, it also includes usb.yaml which requires 
the nodename to start with usb*,
but the dtsi that use the deprecated compatible 
(arch/arm/boot/dts/vt8500/wm8505.dtsi) have their nodename with
uhci*, which causes the tests to fail.

>> +      required:
>> +        - clocks
> 
> And this was not tested.
>> +
>> +unevaluatedProperties: false
>> +
>> +examples:
>> +  - |
>> +    uhci@d8007b00 {
>> +        compatible = "platform-uhci";
> 
> What happened here? This is deprecated!

The original example has the nodename as uhci* which causes the schema 
to fail as mentioned earlier.
Should I just remove the example or should I rename the node here and 
add clock field to the original example ?

Best Regards,
Shehar

Re: [PATCH v3] dt-bindings: usb: uhci: convert to dt schema

[Krzysztof Kozlowski]

On 23/04/2024 09:54, Mohammad Shehar Yaar Tausif wrote:
> On 4/23/24 12:24 PM, Krzysztof Kozlowski wrote:
>> On 22/04/2024 14:21, Mohammad Shehar Yaar Tausif wrote:
>>> Convert USB UHCI bindings to DT schema. Documenting aspeed compatibles
>>> and missing properties. Adding aspeed/generic-uhci example and fix previous
>>> incorrect example.
>>>
>>> Signed-off-by: Mohammad Shehar Yaar Tausif <sheharyaar48@gmail.com>
>>
>>> +required:
>>> +  - compatible
>>> +  - reg
>>> +  - interrupts
>>> +
>>> +allOf:
>>> +  - if:
>>> +      properties:
>>> +        compatible:
>>> +          contains:
>>> +            const: generic-uhci
>>> +    then:
>>> +      $ref: usb-hcd.yaml
>>
>> Nothing improved here.
> 
> Sorry, I could not understand this, please guide me about the correction 
> required here.
> I added $ref inside the if-then block because it was raising errors when 
> tested against
> dts files that used "platform-uhci" as the compatible. Putting it above 
> the if block did
> not work.

Where is it explained? The answer to such problem is not make bindings
incorrect... I mean, the easiest to understand if you are doing
something unusual is to check if you see such pattern. How many bindings
reference other schema in if:then:? Is this common?


> 
> When I ref the usb-hcd.yaml, it also includes usb.yaml which requires 
> the nodename to start with usb*,

Yeah, because DTS should be fixed, not bindings made incorrect.

> but the dtsi that use the deprecated compatible 
> (arch/arm/boot/dts/vt8500/wm8505.dtsi) have their nodename with
> uhci*, which causes the tests to fail.

So fix the DTS.

> 
>>> +      required:
>>> +        - clocks
>>
>> And this was not tested.
>>> +
>>> +unevaluatedProperties: false
>>> +
>>> +examples:
>>> +  - |
>>> +    uhci@d8007b00 {
>>> +        compatible = "platform-uhci";
>>
>> What happened here? This is deprecated!
> 
> The original example has the nodename as uhci* which causes the schema 
> to fail as mentioned earlier.

So the solution is to correct the name, not use deprecated compatible
and incorrect name.

> Should I just remove the example or should I rename the node here and 
> add clock field to the original example ?

I assume you understand the concept of bindings and went briefly through
DT specification or some tutorials. So yes, you must fix the node name.

Node names should be generic. See also an explanation and list of
examples (not exhaustive) in DT specification:
https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation

Best regards,
Krzysztof