[PATCH] dt-bindings: usb: convert PXA USB bindings to YAML

[PATCH] dt-bindings: usb: convert PXA USB bindings to YAML

[Jeremiah Bishop]

Convert the legacy pxa-usb.txt binding documentation to YAML schemas.

The original text binding documented two distinct devices: the PXA OHCI
USB host controller and the PXA270 USB device controller. Split the
documentation into separate schemas, marvell,pxa-ohci.yaml and
marvell,pxa270-udc.yaml, and remove the obsolete text binding.

The schemas preserve the existing compatible strings and properties used
by current in-tree users while adding machine-readable validation and
examples.

Signed-off-by: Jeremiah Bishop <jbishop.dev@gmail.com>
---
 .../bindings/usb/marvell,pxa-ohci.yaml        | 91 +++++++++++++++++++
 .../bindings/usb/marvell,pxa270-udc.yaml      | 50 ++++++++++
 .../devicetree/bindings/usb/pxa-usb.txt       | 53 -----------
 3 files changed, 141 insertions(+), 53 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
 create mode 100644 Documentation/devicetree/bindings/usb/marvell,pxa270-udc.yaml
 delete mode 100644 Documentation/devicetree/bindings/usb/pxa-usb.txt

diff --git a/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml b/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
new file mode 100644
index 000000000000..3f7935384b9f
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/marvell,pxa-ohci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell PXA OHCI USB Host Controller
+
+maintainers:
+  - Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+  - Alan Stern <stern@rowland.harvard.edu>
+
+allOf:
+  - $ref: usb-hcd.yaml#
+
+properties:
+  compatible:
+    const: marvell,pxa-ohci
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  marvell,enable-port1:
+    type: boolean
+    description: Enable USB port 1 if present.
+
+  marvell,enable-port2:
+    type: boolean
+    description: Enable USB port 2 if present.
+
+  marvell,enable-port3:
+    type: boolean
+    description: Enable USB port 3 if present.
+
+  marvell,port-sense-low:
+    type: boolean
+    description: Port sense pin in low-active.
+
+  marvell,power-control-low:
+    type: boolean
+    description: Power control pin is low-active.
+
+  marvell,no-oc-protection:
+    type: boolean
+    description: Disable over-current protection.
+
+  marvell,oc-mode-perport:
+    type: boolean
+    description: Enable per-port over-current protection.
+
+  marvell,power-on-delay:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Power On to Power Good time in milliseconds.
+
+  marvell,port-mode:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [1, 2, 3]
+    description: |
+      Selects the mode of the ports.
+        1 = PMM_NPS_MODE
+        2 = PMM_GLOBAL_MODE
+        3 = PMM_PERPORT_MODE
+
+  marvell,power-budget:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: USB power budget.
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    usb@4c000000 {
+        compatible = "marvell,pxa-ohci";
+        reg = <0x4c000000 0x100000>;
+        interrupts = <3>;
+        clocks = <&clks 11>;
+        marvell,enable-port1;
+        marvell,port-mode = <2>; /* PMM_GLOBAL_MODE */
+    };
diff --git a/Documentation/devicetree/bindings/usb/marvell,pxa270-udc.yaml b/Documentation/devicetree/bindings/usb/marvell,pxa270-udc.yaml
new file mode 100644
index 000000000000..0be51e0db80b
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/marvell,pxa270-udc.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/marvell,pxa270-udc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell PXA27x USB Device Controller (UDC)
+
+maintainers:
+  - Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+
+properties:
+  compatible:
+    const: marvell,pxa270-udc
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  gpios:
+    maxItems: 1
+    description: GPIO to control the USB D+ pullup.
+
+  phys:
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+
+    udc@40600000 {
+        compatible = "marvell,pxa270-udc";
+        reg = <0x40600000 0x10000>;
+        interrupts = <11>;
+        clocks = <&clks 11>;
+        gpios = <&gpio 22 GPIO_ACTIVE_LOW>;
+    };
diff --git a/Documentation/devicetree/bindings/usb/pxa-usb.txt b/Documentation/devicetree/bindings/usb/pxa-usb.txt
deleted file mode 100644
index 53fdae4fa6f6..000000000000
--- a/Documentation/devicetree/bindings/usb/pxa-usb.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-PXA USB controllers
-
-OHCI
-
-Required properties:
- - compatible: Should be "marvell,pxa-ohci" for USB controllers
-   used in host mode.
-
-Optional properties:
- - "marvell,enable-port1", "marvell,enable-port2", "marvell,enable-port3"
-   If present, enables the appropriate USB port of the controller.
- - "marvell,port-mode" selects the mode of the ports:
-	1 = PMM_NPS_MODE
-	2 = PMM_GLOBAL_MODE
-	3 = PMM_PERPORT_MODE
- - "marvell,power-sense-low" - power sense pin is low-active.
- - "marvell,power-control-low" - power control pin is low-active.
- - "marvell,no-oc-protection" - disable over-current protection.
- - "marvell,oc-mode-perport" - enable per-port over-current protection.
- - "marvell,power_on_delay" Power On to Power Good time - in ms.
-
-Example:
-
-	usb0: ohci@4c000000 {
-		compatible = "marvell,pxa-ohci";
-		reg = <0x4c000000 0x100000>;
-		interrupts = <18>;
-		marvell,enable-port1;
-		marvell,port-mode = <2>; /* PMM_GLOBAL_MODE */
-	};
-
-UDC
-
-Required properties:
- - compatible: Should be "marvell,pxa270-udc" for USB controllers
-   used in device mode.
- - reg: usb device MMIO address space
- - interrupts: single interrupt generated by the UDC IP
- - clocks: input clock of the UDC IP (see clock-bindings.txt)
-
-Optional properties:
- - gpios:
-   - gpio activated to control the USB D+ pullup (see gpio.txt)
-
-Example:
-
-		pxa27x_udc: udc@40600000 {
-			compatible = "marvell,pxa270-udc";
-			reg = <0x40600000 0x10000>;
-			interrupts = <11>;
-			clocks = <&pxa2xx_clks 11>;
-			gpios = <&gpio 22 GPIO_ACTIVE_LOW>;
-		};
-- 
2.43.0

Re: [PATCH] dt-bindings: usb: convert PXA USB bindings to YAML

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] The `marvell,pxa-ohci.yaml` schema omits the `vbus1-supply`, `vbus2-supply`, and `vbus3-supply` properties but enforces `unevaluatedProperties: false`, which will cause valid device trees to fail schema validation.
--

commit 78f580ae03eab5d588221a2a8289471c77c1c517
Author: Jeremiah Bishop <jbishop.dev@gmail.com>

dt-bindings: usb: convert PXA USB bindings to YAML

This commit converts the legacy pxa-usb.txt binding documentation to
YAML schemas. It splits the documentation into marvell,pxa-ohci.yaml
and marvell,pxa270-udc.yaml to provide machine-readable validation for
both the host and device controllers.

> diff --git a/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml b/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
> new file mode 100644
> index 0000000000000..3f7935384b9f5
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
[ ... ]
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +
> +unevaluatedProperties: false

[Severity: Medium]
Will this strict validation reject valid device trees that provide vbus
regulators? 

The PXA OHCI driver in drivers/usb/host/ohci-pxa27x.c explicitly calls
devm_regulator_get() for "vbus1", "vbus2", and "vbus3" for enabled ports.
These requests resolve to the vbus1-supply, vbus2-supply, and vbus3-supply
properties in the device tree.

Because these properties are not defined in this schema or inherited from
usb-hcd.yaml, and unevaluatedProperties is set to false, it appears that
any device tree describing the vbus supplies will falsely fail the
dt_binding_check validation.

Could these supply properties be added to the schema to prevent validation
errors for existing users?

> +
> +examples:
> +  - |
[ ... ]

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260529213506.37462-1-jbishop.dev@gmail.com?part=1