[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

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

[Jeremiah Bishop]

Thank you, and good catch.

ohci-pxa27x.c does indeed explicitly request vbus1, vbus2, and vbus3
regulators via devm_regulator_get(). I've added the corresponding
supply properties to the schema and will include the change in v2.

On Fri, May 29, 2026 at 12:01 PM <sashiko-bot@kernel.org> wrote:
>
> 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



-- 
Regards,
Jeremiah E. Bishop

[PATCH v2] 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>
---
Changes in v2:
- Add vbus1-supply, vbus2-supply, and vbus3-supply properties to the
  PXA OHCI schema.

 .../bindings/usb/marvell,pxa-ohci.yaml        | 100 ++++++++++++++++++
 .../bindings/usb/marvell,pxa270-udc.yaml      |  50 +++++++++
 .../devicetree/bindings/usb/pxa-usb.txt       |  53 ----------
 3 files changed, 150 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..5d660b92d3cb
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
@@ -0,0 +1,100 @@
+# 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.
+
+  vbus1-supply:
+    description: Regulator supplying VBUS for port 1.
+
+  vbus2-supply:
+    description: Regulator supplying VBUS for port 2.
+
+  vbus3-supply:
+    description: Regulator supplying VBUS for port 3.
+
+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 v2] dt-bindings: usb: convert PXA USB bindings to YAML

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Medium] YAML conversion incorrectly renames properties `marvell,power-sense-low` to `marvell,port-sense-low` and `marvell,power_on_delay` to `marvell,power-on-delay`, breaking validation and backward compatibility.
- [Medium] The `clocks` property is newly enforced as strictly required for `marvell,pxa-ohci`, which breaks schema validation for existing device trees.
--

commit 64a29827cc603985850c4a4a36ae40793189e8ff
Author: Jeremiah Bishop <jbishop.dev@gmail.com>
    
dt-bindings: usb: convert PXA USB bindings to YAML
    
Convert the legacy pxa-usb.txt binding documentation to YAML schemas. The
original text binding documented two distinct devices, which are now split
into marvell,pxa-ohci.yaml and marvell,pxa270-udc.yaml.
    
> diff --git a/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml b/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
> new file mode 100644
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/marvell,pxa-ohci.yaml
[ ... ]
> +  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.

[Severity: Medium]
The original text binding defined this property as "marvell,power-sense-low".
Will renaming "power" to "port" here cause validation failures for existing
device trees that use the legacy property name?

> +
> +  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.

[Severity: Medium]
The legacy binding documented this as "marvell,power_on_delay" with an
underscore. Could changing the underscore to a hyphen break ABI compatibility
with older device trees and drivers expecting the original format?

[ ... ]
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks

[Severity: Medium]
Is it intentional to enforce "clocks" as a strictly required property here? 

The original pxa-usb.txt binding didn't list "clocks" as required for the 
OHCI controller, and the original example omitted it. Since the schema uses
unevaluatedProperties: false, will enforcing this new requirement cause 
existing valid device trees to fail schema validation?

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