[PATCH v3 0/6] Add USB3.1 support for Agilex5

[PATCH v3 0/6] Add USB3.1 support for Agilex5

[Adrian Ng Ho Yin]

Agilex5 integrates a Synopsys DesignWare USB3 controller via a
SoC-specific wrapper that requires dedicated clock, reset, PHY, and
optional SMMU integration. The USB DMA path on the interconnect is
limited to a 40-bit address width.

This series adds the missing USB3.1 reference clock ID and registers
it in the Agilex5 clock driver so the DWC3 "ref" and "suspend" inputs
can be requested by name.

It also adds a device tree binding for the Agilex5 DWC3 controller and
introduces the corresponding USB3.1 node in the Agilex5 SoC and SoCDK
device trees. The controller is placed under a simple-bus with a 40-bit
dma-ranges window so the DMA/IOMMU stack respects the interconnect address
width when SMMU is enabled. As the SoCDK only exposes the USB3.1 interface,
the unused USB0 node is removed.

Finally, the Agilex5 compatible string is added to the dwc3 generic
platform driver so the controller can probe through that glue driver.

---
changelog:
v2->v3:
* Add the missing USB3.1 reference clock ID and register usb31_ref_clk
  as a fixed-factor clock in the Agilex5 clock driver.
* Drop dma_addressable_bits core/glue changes; describe the 40-bit DMA
  limit in DT with dma-ranges instead.
* Wrap the USB3.1 node in a simple-bus with a 40-bit dma-ranges window.
* Keep Agilex5 support in dwc3-generic-plat as a compatible match only
  (no platform-specific DMA mask override).

v2 patch link:
https://lore.kernel.org/all/cover.1765249127.git.adrianhoyin.ng@altera.com/

v1->v2:
* Update new binding name to match compatible.
* Update binding to use single node instead of parent child node structure.
* Update binding according to comments from maintainer.
* Split USB3 and USB2 changes in dts into separate commits.
* Update to use flattened model and use dwc3-generic-plat driver instead of
  dwc3-of-simple driver.
* Add dma_addressable_bits as a dwc3 property which is set by the glue driver
  which is used to configure the dma mask in the core driver.

v1 patch link:
https://lore.kernel.org/all/cover.1762839776.git.adrianhoyin.ng@altera.com/
---

Adrian Ng Ho Yin (6):
  dt-bindings: clock: agilex5: Add USB3.1 reference clock ID
  clk: socfpga: agilex5: add usb3.1 reference clock
  dt-bindings: usb: add Altera Agilex5 DWC3 controller
  arm64: dts: intel: agilex5: add USB3.1 controller node
  arm64: dts: intel: agilex5: remove usb0 in Agilex5 SoCDK
  usb: dwc3: add Altera Agilex5 support to generic platform driver

 .../bindings/usb/altr,agilex5-dwc3.yaml       | 102 ++++++++++++++++++
 .../arm64/boot/dts/intel/socfpga_agilex5.dtsi |  27 +++++
 .../boot/dts/intel/socfpga_agilex5_socdk.dts  |   4 +-
 drivers/clk/socfpga/clk-agilex5.c             |  15 +++
 drivers/usb/dwc3/dwc3-generic-plat.c          |   1 +
 .../dt-bindings/clock/intel,agilex5-clkmgr.h  |   3 +-
 6 files changed, 149 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml

-- 
2.49.GIT

[PATCH v3 1/6] dt-bindings: clock: agilex5: Add USB3.1 reference clock ID

[Adrian Ng Ho Yin]

The Synopsys DWC3 USB3.1 controller requires two separately named
clocks: a suspend clock and a reference clock. The existing binding
only exposes AGILEX5_USB31_SUSPEND_CLK. Add AGILEX5_USB31_REF_CLK
to allow DT nodes to reference the reference clock by its own ID,
and update AGILEX5_NUM_CLKS accordingly.

Signed-off-by: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
---
 include/dt-bindings/clock/intel,agilex5-clkmgr.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/include/dt-bindings/clock/intel,agilex5-clkmgr.h b/include/dt-bindings/clock/intel,agilex5-clkmgr.h
index 2f3a23b31c5c..196c0bad3e52 100644
--- a/include/dt-bindings/clock/intel,agilex5-clkmgr.h
+++ b/include/dt-bindings/clock/intel,agilex5-clkmgr.h
@@ -95,6 +95,7 @@
 #define AGILEX5_SOFTPHY_REG_PCLK	79
 #define AGILEX5_SOFTPHY_PHY_CLK		80
 #define AGILEX5_SOFTPHY_CTRL_CLK	81
-#define AGILEX5_NUM_CLKS		82
+#define AGILEX5_USB31_REF_CLK		82
+#define AGILEX5_NUM_CLKS		83
 
 #endif	/* __DT_BINDINGS_INTEL_AGILEX5_CLKMGR_H */
-- 
2.49.GIT

[PATCH v3 2/6] clk: socfpga: agilex5: add usb3.1 reference clock

[Adrian Ng Ho Yin]

The Agilex5 DWC3 controller exposes separate ref and suspend clock
inputs. On this SoC both inputs are driven by the same hardware source,
usb31_suspend_clk.

Register usb31_ref_clk as a fixed-factor 1:1 child of usb31_suspend_clk
so the DWC3 driver can request each input by name. A fixed-factor clock
is used instead of a gate entry because agilex5_register_gate() assigns
the gate register unconditionally; a zero gate_reg maps to the clock
manager base address, which would corrupt the boot PLL register on
clk_enable().

Signed-off-by: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
---
 drivers/clk/socfpga/clk-agilex5.c | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/drivers/clk/socfpga/clk-agilex5.c b/drivers/clk/socfpga/clk-agilex5.c
index f7f0ad884f64..af3009ddc6ab 100644
--- a/drivers/clk/socfpga/clk-agilex5.c
+++ b/drivers/clk/socfpga/clk-agilex5.c
@@ -526,6 +526,21 @@ static int agilex5_clkmgr_init(struct platform_device *pdev)
 	agilex5_clk_register_gate(agilex5_gate_clks,
 				  ARRAY_SIZE(agilex5_gate_clks), clk_data);
 
+	/*
+	 * usb31_ref_clk is a 1:1 alias of usb31_suspend_clk. The DWC3
+	 * controller uses the same source for both its suspend and reference
+	 * clock inputs on this SoC. Register it as a fixed-factor (passthrough)
+	 * clock so that enabling it propagates to the parent gate without
+	 * touching any gate register of its own.
+	 */
+	clk_data->clk_data.hws[AGILEX5_USB31_REF_CLK] =
+		devm_clk_hw_register_fixed_factor(dev, "usb31_ref_clk",
+						  "usb31_suspend_clk", 0, 1, 1);
+	if (IS_ERR(clk_data->clk_data.hws[AGILEX5_USB31_REF_CLK]))
+		return dev_err_probe(dev,
+			PTR_ERR(clk_data->clk_data.hws[AGILEX5_USB31_REF_CLK]),
+			"failed to register clock usb31_ref_clk\n");
+
 	of_clk_add_hw_provider(np, of_clk_hw_onecell_get, &clk_data->clk_data);
 	return 0;
 }
-- 
2.49.GIT

Re: [PATCH v3 2/6] clk: socfpga: agilex5: add usb3.1 reference clock

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [High] Returning an error from probe after registering non-devm managed clocks leaves dangling pointers to devm-managed I/O memory in the global clock tree.
--

--- Patch [2]: [PATCH v3 2/6] clk: socfpga: agilex5: add usb3.1 reference clock ---
commit 10f11218bd38bd2427f2a47b44a955f750a91676
Author: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>

clk: socfpga: agilex5: add usb3.1 reference clock

This commit adds a fixed-factor reference clock for the Agilex5 DWC3
controller so the driver can request each input by name.

> diff --git a/drivers/clk/socfpga/clk-agilex5.c b/drivers/clk/socfpga/clk-agilex5.c
> index f7f0ad884f645..af3009ddc6ab3 100644
> --- a/drivers/clk/socfpga/clk-agilex5.c
> +++ b/drivers/clk/socfpga/clk-agilex5.c
> @@ -526,6 +526,21 @@ static int agilex5_clkmgr_init(struct platform_device *pdev)
>  	agilex5_clk_register_gate(agilex5_gate_clks,
>  				  ARRAY_SIZE(agilex5_gate_clks), clk_data);
>  
> +	/*
> +	 * usb31_ref_clk is a 1:1 alias of usb31_suspend_clk. The DWC3
> +	 * controller uses the same source for both its suspend and reference
> +	 * clock inputs on this SoC. Register it as a fixed-factor (passthrough)
> +	 * clock so that enabling it propagates to the parent gate without
> +	 * touching any gate register of its own.
> +	 */
> +	clk_data->clk_data.hws[AGILEX5_USB31_REF_CLK] =
> +		devm_clk_hw_register_fixed_factor(dev, "usb31_ref_clk",
> +						  "usb31_suspend_clk", 0, 1, 1);
> +	if (IS_ERR(clk_data->clk_data.hws[AGILEX5_USB31_REF_CLK]))
> +		return dev_err_probe(dev,
> +			PTR_ERR(clk_data->clk_data.hws[AGILEX5_USB31_REF_CLK]),
> +			"failed to register clock usb31_ref_clk\n");

[Severity: High]
If devm_clk_hw_register_fixed_factor() fails and we return an error here,
will this leave dangling pointers in the Common Clock Framework?

The previous clocks registered earlier in agilex5_clkmgr_init() (like PLLs
and gates) are registered globally without devm management. Since clk_data
and the IO memory base are devm-managed, returning an error from probe
causes them to be freed and unmapped.

Could this cause the system to crash due to unmapped memory access when the
clock framework later accesses these dangling clocks (for example, during
clk_disable_unused())?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/cover.1786518803.git.adrian.ho.yin.ng@altera.com?part=2

[PATCH v3 3/6] dt-bindings: usb: add Altera Agilex5 DWC3 controller

[Adrian Ng Ho Yin]

Add a binding for the Altera Agilex5 SoC integration of the Synopsys DWC3
USB controller (compatible "altr,agilex5-dwc3"), covering clocks, resets,
PHYs, and optional IOMMU support.

Signed-off-by: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
---
 .../bindings/usb/altr,agilex5-dwc3.yaml       | 102 ++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml

diff --git a/Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml b/Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml
new file mode 100644
index 000000000000..8a815e8a3b7d
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/altr,agilex5-dwc3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera Agilex5 DWC3 USB SoC Controller
+
+maintainers:
+  - Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
+
+description:
+  The Altera Agilex5 SoCFPGA integrates a Synopsys DesignWare USB3 (DWC3)
+  controller that supports host, device and DRD modes.
+
+allOf:
+  - $ref: snps,dwc3-common.yaml#
+
+properties:
+  compatible:
+    const: altr,agilex5-dwc3
+
+  reg:
+    description: DWC3 USB3 controller register region.
+    maxItems: 1
+
+  clocks:
+    items:
+      - description: Controller reference clock
+      - description: Controller suspend clock
+      - description: Master/Core bus clock
+
+  clock-names:
+    items:
+      - const: ref
+      - const: suspend
+      - const: bus_early
+
+  interrupts:
+    maxItems: 1
+
+  phys:
+    minItems: 2
+    maxItems: 2
+
+  phy-names:
+    items:
+      - const: usb2-phy
+      - const: usb3-phy
+
+  iommus:
+    maxItems: 1
+
+  resets:
+    description: Resets for the DWC3 core and its ECC block.
+    items:
+      - description: DWC3 core reset
+      - description: DWC3 ECC reset
+
+  reset-names:
+    items:
+      - const: dwc3
+      - const: dwc3-ecc
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - interrupts
+  - phys
+  - phy-names
+  - resets
+  - reset-names
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+    #include <dt-bindings/reset/altr,rst-mgr-s10.h>
+    #include <dt-bindings/clock/intel,agilex5-clkmgr.h>
+
+    soc {
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        usb@11000000 {
+            compatible = "altr,agilex5-dwc3";
+            reg = <0x11000000 0x100000>;
+            interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>;
+            clocks = <&clkmgr AGILEX5_USB31_REF_CLK>,
+                     <&clkmgr AGILEX5_USB31_SUSPEND_CLK>,
+                     <&clkmgr AGILEX5_USB31_BUS_CLK_EARLY>;
+            clock-names = "ref", "suspend", "bus_early";
+            phys = <&usbphy0>, <&usbphy1>;
+            phy-names = "usb2-phy", "usb3-phy";
+            resets = <&rst USB1_RESET>, <&rst USB1_OCP_RESET>;
+            reset-names = "dwc3", "dwc3-ecc";
+            iommus = <&smmu 7>;
+        };
+    };
-- 
2.49.GIT

Re: [PATCH v3 3/6] dt-bindings: usb: add Altera Agilex5 DWC3 controller

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] Missing generic fallback compatible string in DWC3 devicetree binding
--

--- Patch [3]: [PATCH v3 3/6] dt-bindings: usb: add Altera Agilex5 DWC3 controller ---
commit 1039f7f38ac48bd8193ef808b132fbeb99505e18
Author: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>

dt-bindings: usb: add Altera Agilex5 DWC3 controller

This commit adds a devicetree binding for the Altera Agilex5 SoC integration
of the Synopsys DWC3 USB controller.

> diff --git a/Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml b/Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml
> new file mode 100644
> index 0000000000000..8a815e8a3b7d1
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/altr,agilex5-dwc3.yaml
> @@ -0,0 +1,102 @@

[ ... ]

> +properties:
> +  compatible:
> +    const: altr,agilex5-dwc3

[Severity: Medium]
Does the compatible property definition need to include the generic
fallback string "snps,dwc3"?

Since this is rigidly constrained as a const, providing the generic fallback
string in a devicetree node will cause schema validation to fail. 

If a device tree node only uses "altr,agilex5-dwc3" to satisfy this schema,
the generic DWC3 driver (drivers/usb/dwc3/core.c) will ignore the device
because it requires "snps,dwc3" or "synopsys,dwc3".

Should this be structured to allow an array of items including the fallback?

> +
> +  reg:
> +    description: DWC3 USB3 controller register region.
> +    maxItems: 1

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/cover.1786518803.git.adrian.ho.yin.ng@altera.com?part=3

[PATCH v3 4/6] arm64: dts: intel: agilex5: add USB3.1 controller node

[Adrian Ng Ho Yin]

Add a DTS node for the Synopsys DWC3 USB3.1 controller on the Agilex5 SoC.
Place it under a simple-bus with a 40-bit dma-ranges window to match the
USB DMA address width of the interconnect. It is enabled in host mode on
the SoCDK board.

Signed-off-by: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
---
 .../arm64/boot/dts/intel/socfpga_agilex5.dtsi | 27 +++++++++++++++++++
 .../boot/dts/intel/socfpga_agilex5_socdk.dts  |  5 ++++
 2 files changed, 32 insertions(+)

diff --git a/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi b/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi
index b06c6d5d60ee..043b980832c2 100644
--- a/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi
+++ b/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi
@@ -494,6 +494,33 @@ usb0: usb@10b00000 {
 			status = "disabled";
 		};
 
+		usb31_bus: usb-bus@11000000 {
+			compatible = "simple-bus";
+			#address-cells = <1>;
+			#size-cells = <2>;
+			ranges = <0x00 0x11000000 0x00 0x100000>;
+			dma-ranges = <0x00 0x00 0x100 0x00>;
+
+			usb31: usb@0 {
+				compatible = "altr,agilex5-dwc3";
+				reg = <0x0 0x0 0x100000>;
+				interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>;
+				clocks = <&clkmgr AGILEX5_USB31_REF_CLK>,
+					 <&clkmgr AGILEX5_USB31_SUSPEND_CLK>,
+					 <&clkmgr AGILEX5_USB31_BUS_CLK_EARLY>;
+				clock-names = "ref", "suspend", "bus_early";
+				resets = <&rst USB1_RESET>, <&rst USB1_OCP_RESET>;
+				reset-names = "dwc3", "dwc3-ecc";
+				iommus = <&smmu 7>;
+				phys = <&usbphy0>, <&usbphy0>;
+				phy-names = "usb2-phy", "usb3-phy";
+				maximum-speed = "super-speed";
+				snps,dis_u2_susphy_quirk;
+				snps,dis_u3_susphy_quirk;
+				status = "disabled";
+			};
+		};
+
 		watchdog0: watchdog@10d00200 {
 			compatible = "snps,dw-wdt";
 			reg = <0x10d00200 0x100>;
diff --git a/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts b/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts
index 57d3c5807c65..dc62772e10ed 100644
--- a/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts
+++ b/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts
@@ -109,6 +109,11 @@ &usb0 {
 	disable-over-current;
 };
 
+&usb31 {
+	dr_mode = "host";
+	status = "okay";
+};
+
 &watchdog0 {
 	status = "okay";
 };
-- 
2.49.GIT

Re: [PATCH v3 4/6] arm64: dts: intel: agilex5: add USB3.1 controller node

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [High] Devicetree structurally contradicts itself regarding 40-bit DMA support for the USB3.1 controller.
--

--- Patch [4]: [PATCH v3 4/6] arm64: dts: intel: agilex5: add USB3.1 controller node ---
commit 2f2039b2059cdc372b94f8f6d45151844510ff80
Author: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>

arm64: dts: intel: agilex5: add USB3.1 controller node

This patch adds a DTS node for the Synopsys DWC3 USB3.1 controller on the
Agilex5 SoC. It places the device under a simple-bus configured with a 40-bit
DMA window and enables it in host mode on the SoCDK board.

> diff --git a/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi b/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi
> index b06c6d5d60eed..043b980832c23 100644
> --- a/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi
> +++ b/arch/arm64/boot/dts/intel/socfpga_agilex5.dtsi
> @@ -494,6 +494,33 @@ usb0: usb@10b00000 {
>  			status = "disabled";
>  		};
>  
> +		usb31_bus: usb-bus@11000000 {
> +			compatible = "simple-bus";
> +			#address-cells = <1>;
> +			#size-cells = <2>;
> +			ranges = <0x00 0x11000000 0x00 0x100000>;
> +			dma-ranges = <0x00 0x00 0x100 0x00>;

[Severity: High]
Does this dma-ranges property structurally contradict the #address-cells
configuration for a 40-bit DMA window?

The usb31_bus node and its parent soc@0 both use #address-cells = <1>.
With a 32-bit (4 GB) child address space, is it mathematically possible to
accommodate the 1 TB (<0x100 0x00>) window length specified in dma-ranges?

When the Linux OF core parses this, won't it truncate the window against the
parent's 32-bit boundaries and silently limit the device to 32-bit DMA?

[ ... ]

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/cover.1786518803.git.adrian.ho.yin.ng@altera.com?part=4

[PATCH v3 5/6] arm64: dts: intel: agilex5: remove usb0 in Agilex5 SoCDK

[Adrian Ng Ho Yin]

The Agilex5 SoCDK daughter card only provides a USB3.1 interface (USB1).
USB0 is not connected or used on this board. Removing the USB0 node to
avoid unnecessary initialization and potential resource conflicts.

Signed-off-by: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
---
 arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts b/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts
index dc62772e10ed..ce5e29da1e62 100644
--- a/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts
+++ b/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts
@@ -104,11 +104,6 @@ &uart0 {
 	status = "okay";
 };
 
-&usb0 {
-	status = "okay";
-	disable-over-current;
-};
-
 &usb31 {
 	dr_mode = "host";
 	status = "okay";
-- 
2.49.GIT

[PATCH v3 6/6] usb: dwc3: add Altera Agilex5 support to generic platform driver

[Adrian Ng Ho Yin]

Add the "altr,agilex5-dwc3" compatible string to dwc3-generic-plat so the
Agilex5 USB3.1 DWC3 controller can probe through the generic DWC3 platform
glue.

Signed-off-by: Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
---
 drivers/usb/dwc3/dwc3-generic-plat.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/usb/dwc3/dwc3-generic-plat.c b/drivers/usb/dwc3/dwc3-generic-plat.c
index ca69ac0eb07c..8781d7ec6b9e 100644
--- a/drivers/usb/dwc3/dwc3-generic-plat.c
+++ b/drivers/usb/dwc3/dwc3-generic-plat.c
@@ -232,6 +232,7 @@ static const struct dwc3_generic_config eic7700_dwc3 =  {
 };
 
 static const struct of_device_id dwc3_generic_of_match[] = {
+	{ .compatible = "altr,agilex5-dwc3", },
 	{ .compatible = "spacemit,k1-dwc3", &spacemit_k1_dwc3},
 	{ .compatible = "spacemit,k3-dwc3", },
 	{ .compatible = "fsl,ls1028a-dwc3", &fsl_ls1028_dwc3},
-- 
2.49.GIT