[PATCH v2] dt-bindings: usb: maxim,max3421: convert to DT schema

[PATCH v2] dt-bindings: usb: maxim,max3421: convert to DT schema

[Rodrigo Gobbi]

Convert legacy maxim,max3421.txt to proper format.

Signed-off-by: Rodrigo Gobbi <rodrigo.gobbi.7@gmail.com>
---
Hi, all

At this v2, I`m reverting my previous idea about documenting new properties
because this is just a conversion from txt file. At v1, a question
was raised about that:

On 10/9/25 22:34, Krzysztof Kozlowski wrote:
> maxim,vbus-en-pin, maxim,gpx-pin, reset pin and supplies. Also add a
> Why new properties? You must explain not only the difference but WHY you
> are doing this.
In this case, I`ve kept the maxim,vbus-en-pin prop because it was already
described in the legacy file and the driver expects that property according
to [1] and [2].

[1] https://github.com/torvalds/linux/blob/a1388fcb52fcad3e0b06e2cdd0ed757a82a5be30/drivers/usb/host/max3421-hcd.c#L1807
[2] https://github.com/torvalds/linux/blob/a1388fcb52fcad3e0b06e2cdd0ed757a82a5be30/drivers/usb/host/max3421-hcd.c#L1845-L1847

Tks and regards to all!

Changelog:
v2: - fix subject/commit msg;
    - remove $ref/desc from spi-max-frequency;
    - add spi-peripheral-props/unevaluatedProperties;
    - remove the "new properties";
    - remove fallback compatible with the 'e' pattern;
    - fix file name, didn`t notice at previous version;
v1: https://lore.kernel.org/all/20251009182046.185520-1-rodrigo.gobbi.7@gmail.com/
---
 .../devicetree/bindings/usb/maxim,max3421.txt | 23 -------
 .../bindings/usb/maxim,max3421.yaml           | 67 +++++++++++++++++++
 2 files changed, 67 insertions(+), 23 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/usb/maxim,max3421.txt
 create mode 100644 Documentation/devicetree/bindings/usb/maxim,max3421.yaml

diff --git a/Documentation/devicetree/bindings/usb/maxim,max3421.txt b/Documentation/devicetree/bindings/usb/maxim,max3421.txt
deleted file mode 100644
index 90495b1aeec2..000000000000
--- a/Documentation/devicetree/bindings/usb/maxim,max3421.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-Maxim Integrated SPI-based USB 2.0 host controller MAX3421E
-
-Required properties:
- - compatible: Should be "maxim,max3421"
- - spi-max-frequency: maximum frequency for this device must not exceed 26 MHz.
- - reg: chip select number to which this device is connected.
- - maxim,vbus-en-pin: <GPOUTx ACTIVE_LEVEL>
-   GPOUTx is the number (1-8) of the GPOUT pin of MAX3421E to drive Vbus.
-   ACTIVE_LEVEL is 0 or 1.
- - interrupts: the interrupt line description for the interrupt controller.
-   The driver configures MAX3421E for active low level triggered interrupts,
-   configure your interrupt line accordingly.
-
-Example:
-
-	usb@0 {
-		compatible = "maxim,max3421";
-		reg = <0>;
-		maxim,vbus-en-pin = <3 1>;
-		spi-max-frequency = <26000000>;
-		interrupt-parent = <&PIC>;
-		interrupts = <42>;
-	};
diff --git a/Documentation/devicetree/bindings/usb/maxim,max3421.yaml b/Documentation/devicetree/bindings/usb/maxim,max3421.yaml
new file mode 100644
index 000000000000..4639be7ab059
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/maxim,max3421.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/maxim,max3421.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MAXIM MAX3421e USB Peripheral/Host Controller
+
+maintainers:
+  - David Mosberger <davidm@egauge.net>
+
+description: |
+  The controller provides USB2.0 compliant with Full Speed or Low Speed when in
+  the host mode. At peripheral, it operates at Full Speed. At both cases, it
+  uses a SPI interface.
+  Datasheet at:
+    https://www.analog.com/media/en/technical-documentation/data-sheets/max3421e.pdf
+
+properties:
+  compatible:
+    const: maxim,max3421
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  spi-max-frequency:
+    maximum: 26000000
+
+  maxim,vbus-en-pin:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    description:
+      One of eight GPOUT pins to control external VBUS power and the polarity
+      of the active level. It's an array of GPIO number and the active level of it.
+    minItems: 2
+    maxItems: 2
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - maxim,vbus-en-pin
+
+allOf:
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+    spi {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        usb@0 {
+          compatible = "maxim,max3421";
+          reg = <0>;
+          maxim,vbus-en-pin = <3 1>;
+          spi-max-frequency = <26000000>;
+          interrupt-parent = <&gpio>;
+          interrupts = <42>;
+        };
+    };
-- 
2.48.1

Re: [PATCH v2] dt-bindings: usb: maxim,max3421: convert to DT schema

[Krzysztof Kozlowski]

On Thu, Nov 06, 2025 at 09:06:22PM -0300, Rodrigo Gobbi wrote:
> Convert legacy maxim,max3421.txt to proper format.
> 
> Signed-off-by: Rodrigo Gobbi <rodrigo.gobbi.7@gmail.com>
> ---
> Hi, all
> 
> At this v2, I`m reverting my previous idea about documenting new properties
> because this is just a conversion from txt file. At v1, a question
> was raised about that:
> 
> On 10/9/25 22:34, Krzysztof Kozlowski wrote:
> > maxim,vbus-en-pin, maxim,gpx-pin, reset pin and supplies. Also add a
> > Why new properties? You must explain not only the difference but WHY you
> > are doing this.
> In this case, I`ve kept the maxim,vbus-en-pin prop because it was already
> described in the legacy file and the driver expects that property according
> to [1] and [2].

This is not a commit msg. Apply this patch from the lists and look
whether the information is there.

So again:

You commit msg explain any unusual changes - like modifying binding
while ONLY converting it - and WHY you are doing the unusual changes.

Best regards,
Krzysztof

Re: [PATCH v2] dt-bindings: usb: maxim,max3421: convert to DT schema

[Rodrigo Gobbi]

On 11/7/25 05:03, Krzysztof Kozlowski wrote:
> On Thu, Nov 06, 2025 at 09:06:22PM -0300, Rodrigo Gobbi wrote:
>> Convert legacy maxim,max3421.txt to proper format.
>> 
>> Signed-off-by: Rodrigo Gobbi <rodrigo.gobbi.7@gmail.com>
>> ---
>> Hi, all
>> 
>> At this v2, I`m reverting my previous idea about documenting new properties
>> because this is just a conversion from txt file. At v1, a question
>> was raised about that:
>> 
>> On 10/9/25 22:34, Krzysztof Kozlowski wrote:
>> > maxim,vbus-en-pin, maxim,gpx-pin, reset pin and supplies. Also add a
>> > Why new properties? You must explain not only the difference but WHY you
>> > are doing this.
>> In this case, I`ve kept the maxim,vbus-en-pin prop because it was already
>> described in the legacy file and the driver expects that property according
>> to [1] and [2].
> 
> This is not a commit msg. Apply this patch from the lists and look
> whether the information is there.
> 
> So again:
> 
> You commit msg explain any unusual changes - like modifying binding
> while ONLY converting it - and WHY you are doing the unusual changes.
> 
> Best regards,
> Krzysztof
> 

Hi, Krzysztof,
I was wondering about this again and I need to clarify the expectations here. 
So my v2 patch is only doing the conversion from txt to yaml without any additional
changes. That being said, at v2, there are no new properties and no unusual changes.

What happened was that under the ---, in order to save the lore and the previous discussion
from v1, I`ve quoted the sentence about the "maxim,vbus-en-pin" prop from v1. Here, at v2,
what I meant under the --- was that the "maxim,vbus-en-pin" was not new and it already existed
in .txt file and the driver is already expecting that.

So, even if I send a v3, it will be exactly the same direct conversion with the same commit msg
because nothing was changed from txt.
Maybe my intention was not right, my idea was to just save the lore/"answer" a previous point
raised inside ---. 

Tks and best regards.

Re: [PATCH v2] dt-bindings: usb: maxim,max3421: convert to DT schema

[Krzysztof Kozlowski]

On 06/12/2025 14:38, Rodrigo Gobbi wrote:
> On 11/7/25 05:03, Krzysztof Kozlowski wrote:
>>
>> You commit msg explain any unusual changes - like modifying binding
>> while ONLY converting it - and WHY you are doing the unusual changes.
>>
>> Best regards,
>> Krzysztof
>>
> 
> Hi, Krzysztof,
> I was wondering about this again and I need to clarify the expectations here. 
> So my v2 patch is only doing the conversion from txt to yaml without any additional
> changes. That being said, at v2, there are no new properties and no unusual changes.
> 
> What happened was that under the ---, in order to save the lore and the previous discussion
> from v1, I`ve quoted the sentence about the "maxim,vbus-en-pin" prop from v1. Here, at v2,
> what I meant under the --- was that the "maxim,vbus-en-pin" was not new and it already existed
> in .txt file and the driver is already expecting that.
> 
> So, even if I send a v3, it will be exactly the same direct conversion with the same commit msg
> because nothing was changed from txt.
> Maybe my intention was not right, my idea was to just save the lore/"answer" a previous point
> raised inside ---. 
> 
> Tks and best regards.

Indeed, I think I misread or went too fast through your changelog.
Everything looks correct, thanks for clarification.

Best regards,
Krzysztof

Re: [PATCH v2] dt-bindings: usb: maxim,max3421: convert to DT schema

[Krzysztof Kozlowski]

On 07/11/2025 01:06, Rodrigo Gobbi wrote:
> Convert legacy maxim,max3421.txt to proper format.
> 
> Signed-off-by: Rodrigo Gobbi <rodrigo.gobbi.7@gmail.com>
> ---
> Hi, all


Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>

You might need to resend it, quite likely it is not anymore in Greg's
inbox. Please include above tag when resending and please resend AFTER
the merge window.

Best regards,
Krzysztof