[PATCH] dt-bindings: usb: Add Aspeed AST2700 DWC3 controller

[PATCH] dt-bindings: usb: Add Aspeed AST2700 DWC3 controller

[Ryan Chen]

The Aspeed AST2700 SoC integrates the Synopsys DesignWare USB3 core with
no vendor glue logic: it is functionally compatible with snps,dwc3, uses
the standard DWC3 clocks, and the only SoC-specific part is a USB3 PHY
that is handled by a separate driver.

Add a dedicated binding document rather than adding the compatible and a
conditional to snps,dwc3.yaml. This follows the established per-vendor DWC3
convention (apple,dwc3.yaml, socionext,uniphier-dwc3.yaml, ...) and keeps
the AST2700-specific constraints - notably the mandatory USB3 PHY - out of
the generic schema.

Signed-off-by: Ryan Chen <ryan_chen@aspeedtech.com>
---
The common DWC3 node properties are inherited from snps,dwc3.yaml via the
allOf $ref, so this schema only defines the additional AST2700-specific
constraints (the compatible, a single interrupt and the USB3 PHY) and does
not redefine the properties covered there. snps,dwc3.yaml is used rather
than snps,dwc3-common.yaml because the controller uses the standard DWC3
bus_early/ref/suspend clocks defined there.

Because reg, clocks and clock-names are only defined indirectly through
the $ref, they still appear in the required list, the same approach as
apple,dwc3.yaml.
---
 .../devicetree/bindings/usb/aspeed,dwc3.yaml       | 81 ++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/Documentation/devicetree/bindings/usb/aspeed,dwc3.yaml b/Documentation/devicetree/bindings/usb/aspeed,dwc3.yaml
new file mode 100644
index 000000000000..976f80b87e24
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/aspeed,dwc3.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/aspeed,dwc3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed SuperSpeed DWC3 USB SoC controller
+
+maintainers:
+  - Ryan Chen <ryan_chen@aspeedtech.com>
+
+description:
+  The common content of the node is defined in snps,dwc3.yaml.
+
+select:
+  properties:
+    compatible:
+      contains:
+        const: aspeed,ast2700-xhci
+  required:
+    - compatible
+
+properties:
+  compatible:
+    items:
+      - const: aspeed,ast2700-xhci
+      - const: snps,dwc3
+
+  interrupts:
+    maxItems: 1
+
+  resets:
+    maxItems: 1
+
+  phys:
+    maxItems: 1
+
+  phy-names:
+    const: usb3-phy
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+  - resets
+  - phys
+  - phy-names
+
+allOf:
+  - $ref: snps,dwc3.yaml#
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/aspeed,ast2700-scu.h>
+    #include <dt-bindings/reset/aspeed,ast2700-scu.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    bus {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        usb@12030000 {
+            compatible = "aspeed,ast2700-xhci", "snps,dwc3";
+            reg = <0x0 0x12030000 0x0 0x10000>;
+            interrupts = <GIC_SPI 30 IRQ_TYPE_LEVEL_HIGH>;
+            clocks = <&syscon0 SCU0_CLK_GATE_PORTAUSB2CLK>,
+                     <&syscon0 SCU0_CLK_U2PHY_REFCLK>,
+                     <&syscon0 SCU0_CLK_U2PHY_CLK12M>;
+            clock-names = "bus_early", "ref", "suspend";
+            resets = <&syscon0 SCU0_RESET_PORTA_XHCI>;
+            pinctrl-names = "default";
+            pinctrl-0 = <&pinctrl_usb3axh_default &pinctrl_usb2axh_default>;
+            phys = <&uphy3a>;
+            phy-names = "usb3-phy";
+            dr_mode = "host";
+        };
+    };

---
base-commit: be5c93fa674f0fc3c8f359c2143abce6bbb422e6
change-id: 20260624-xhci-185ffd9ef8bd

Best regards,
-- 
Ryan Chen <ryan_chen@aspeedtech.com>

Re: [PATCH] dt-bindings: usb: Add Aspeed AST2700 DWC3 controller

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] The AST2700 DWC3 binding lists `clocks` and `clock-names` as required properties but fails to explicitly define strict constraints for them in the `properties:` block, relying on a loose generic schema.
--

--- Patch [1]: [PATCH] dt-bindings: usb: Add Aspeed AST2700 DWC3 controller ---
commit e94cba741ea120f96563c784f28513d593ede326
Author: Ryan Chen <ryan_chen@aspeedtech.com>

dt-bindings: usb: Add Aspeed AST2700 DWC3 controller

This commit adds a new device tree binding for the Aspeed AST2700 DWC3
controller. It uses a dedicated YAML file that references the generic
snps,dwc3.yaml schema and adds SoC-specific constraints such as a
mandatory USB3 PHY.

> Because reg, clocks and clock-names are only defined indirectly through
> the $ref, they still appear in the required list, the same approach as
> apple,dwc3.yaml.

[Severity: Low]
This isn't a bug, but is this description of apple,dwc3.yaml accurate?

Looking at apple,dwc3.yaml, it explicitly overrides reg in its properties:
block to enforce strict bounds, rather than relying on an indirect
definition through the $ref.

> diff --git a/Documentation/devicetree/bindings/usb/aspeed,dwc3.yaml b/Documentation/devicetree/bindings/usb/aspeed,dwc3.yaml
> new file mode 100644
> index 0000000000000..976f80b87e24c
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/aspeed,dwc3.yaml
[ ... ]
> +properties:
> +  compatible:
> +    items:
> +      - const: aspeed,ast2700-xhci
> +      - const: snps,dwc3
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  resets:
> +    maxItems: 1
> +
> +  phys:
> +    maxItems: 1
> +
> +  phy-names:
> +    const: usb3-phy

[Severity: Low]
Since clocks and clock-names are listed as required properties below, should
they be explicitly constrained here in the properties: block?

Without strict constraints defined here, device trees with an incorrect
number of clocks or invalid clock names for the AST2700 could silently pass
schema validation by falling back to the loosely defined generic schema in
snps,dwc3.yaml.

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +  - resets
> +  - phys
> +  - phy-names

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260707-xhci-v1-1-b202b9b3274e@aspeedtech.com?part=1

Re: [PATCH] dt-bindings: usb: Add Aspeed AST2700 DWC3 controller

[Krzysztof Kozlowski]

On Tue, Jul 07, 2026 at 02:12:04PM +0800, Ryan Chen wrote:
> The Aspeed AST2700 SoC integrates the Synopsys DesignWare USB3 core with
> no vendor glue logic: it is functionally compatible with snps,dwc3, uses
> the standard DWC3 clocks, and the only SoC-specific part is a USB3 PHY
> that is handled by a separate driver.
> 
> Add a dedicated binding document rather than adding the compatible and a
> conditional to snps,dwc3.yaml. This follows the established per-vendor DWC3
> convention (apple,dwc3.yaml, socionext,uniphier-dwc3.yaml, ...) and keeps
> the AST2700-specific constraints - notably the mandatory USB3 PHY - out of
> the generic schema.
> 
> Signed-off-by: Ryan Chen <ryan_chen@aspeedtech.com>
> ---

Why are clocks unconstrained?

Best regards,
Krzysztof

RE: [PATCH] dt-bindings: usb: Add Aspeed AST2700 DWC3 controller

[Ryan Chen]

> Subject: Re: [PATCH] dt-bindings: usb: Add Aspeed AST2700 DWC3 controller
> 
> On Tue, Jul 07, 2026 at 02:12:04PM +0800, Ryan Chen wrote:
> > The Aspeed AST2700 SoC integrates the Synopsys DesignWare USB3 core
> > with no vendor glue logic: it is functionally compatible with
> > snps,dwc3, uses the standard DWC3 clocks, and the only SoC-specific
> > part is a USB3 PHY that is handled by a separate driver.
> >
> > Add a dedicated binding document rather than adding the compatible and
> > a conditional to snps,dwc3.yaml. This follows the established
> > per-vendor DWC3 convention (apple,dwc3.yaml,
> > socionext,uniphier-dwc3.yaml, ...) and keeps the AST2700-specific
> > constraints - notably the mandatory USB3 PHY - out of the generic schema.
> >
> > Signed-off-by: Ryan Chen <ryan_chen@aspeedtech.com>
> > ---
> 
> Why are clocks unconstrained?
> 
They shouldn't be - I'll add the constraints in this schema:

  clocks:
    items:
      - description: Controller bus early clock
      - description: PHY reference clock
      - description: Controller suspend clock

  clock-names:
    items:
      - const: bus_early
      - const: ref
      - const: suspend