[PATCH 2/2] dt-bindings: usb: snps,dwc3: Fix downstream port numbering - Chen-Yu Tsai

From: Chen-Yu Tsai <wenst@chromium.org>
To: Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Felipe Balbi <balbi@kernel.org>, Rob Herring <robh@kernel.org>,
	Krzysztof Kozlowski <krzk+dt@kernel.org>,
	Conor Dooley <conor+dt@kernel.org>
Cc: "Chen-Yu Tsai" <wenst@chromium.org>,
	linux-usb@vger.kernel.org, devicetree@vger.kernel.org,
	"Neil Armstrong" <neil.armstrong@linaro.org>,
	"Kevin Hilman" <khilman@baylibre.com>,
	"Jerome Brunet" <jbrunet@baylibre.com>,
	"Martin Blumenstingl" <martin.blumenstingl@googlemail.com>,
	"Sven Peter" <sven@kernel.org>, "Janne Grunau" <j@jannau.net>,
	"Neal Gompa" <neal@gompa.dev>, "Joel Stanley" <joel@jms.id.au>,
	"Andrew Jeffery" <andrew@codeconstruct.com.au>,
	"Ryan Chen" <ryan_chen@aspeedtech.com>,
	"Billy Tsai" <billy_tsai@aspeedtech.com>,
	"Michal Simek" <michal.simek@amd.com>,
	"Frank Li" <Frank.Li@nxp.com>,
	"Sascha Hauer" <s.hauer@pengutronix.de>,
	"Pengutronix Kernel Team" <kernel@pengutronix.de>,
	"Fabio Estevam" <festevam@gmail.com>,
	"Peter Griffin" <peter.griffin@linaro.org>,
	"André Draszik" <andre.draszik@linaro.org>,
	"Tudor Ambarus" <tudor.ambarus@linaro.org>,
	"Heiko Stuebner" <heiko@sntech.de>,
	"Alim Akhtar" <alim.akhtar@samsung.com>,
	"Kunihiko Hayashi" <hayashi.kunihiko@socionext.com>,
	"Masami Hiramatsu" <mhiramat@kernel.org>,
	"Yixun Lan" <dlan@kernel.org>,
	"Troy Mitchell" <troy.mitchell@linux.spacemit.com>,
	"Minda Chen" <minda.chen@starfivetech.com>,
	"Shyam Pandey" <radhey.shyam.pandey@amd.com>,
	"Wei Yang" <yangwei1@eswincomputing.com>,
	"Senchuan Zhang" <zhangsenchuan@eswincomputing.com>,
	"Hang Cao" <caohang@eswincomputing.com>,
	"Li Jun" <jun.li@nxp.com>, "Peng Fan" <peng.fan@nxp.com>,
	"Roy Luo" <royluo@google.com>,
	"Yang Xiwen" <forbidden405@foxmail.com>,
	"Ahmad Zainie" <wan.ahmad.zainie.wan.mohamad@intel.com>,
	"Robert Marko" <robert.marko@sartura.hr>,
	"Xu Yang" <xu.yang_2@nxp.com>,
	"Wesley Cheng" <quic_wcheng@quicinc.com>,
	"Stanley Chang" <stanley_chang@realtek.com>,
	"Ze Huang" <huang.ze@linux.dev>,
	"Aswath Govindraju" <a-govindraju@ti.com>,
	"Roger Quadros" <rogerq@kernel.org>,
	linux-arm-kernel@lists.infradead.org,
	linux-amlogic@lists.infradead.org, linux-kernel@vger.kernel.org,
	asahi@lists.linux.dev, linux-aspeed@lists.ozlabs.org,
	imx@lists.linux.dev, linux-samsung-soc@vger.kernel.org,
	linux-arm-msm@vger.kernel.org,
	linux-rockchip@lists.infradead.org,
	linux-riscv@lists.infradead.org, spacemit@lists.linux.dev
Subject: [PATCH 2/2] dt-bindings: usb: snps,dwc3: Fix downstream port numbering
Date: Wed, 14 Oct 2026 16:20:36 +0800	[thread overview]
Message-ID: <20261014082037.1774672-3-wenst@chromium.org> (raw)
In-Reply-To: <20261014082037.1774672-1-wenst@chromium.org>

The DWC3 controller can operate in host mode. It does so with a XHCI
compliant host controller. The XHCI has two downstream ports, one for
HS and one for SS. USB downstream ports start from 1, not 0.

Reconcile the downstream port numbering with the common USB host
binding, renumbering the downstream port numbers from 0 and 1 to
1 and 2.

This is non-backwards compatible, however it won't break current
major implementations:

- dwc3 "gadget mode" in Linux kernel only requires a connection to be
  present; it doesn't matter which port it is
  - dwc3 "host mode" OF graph connections aren't supported yet [1]
- FreeBSD doesn't use the OF graph for anything
- U-boot doesn't use the OF graph for USB
- OpenBSD doesn't support dwc3, only the XHCI in dwc3, and doesn't use
  the OF graph for USB
- coreboot doesn't use the OF graph for anything
- Zephyr doesn't support dwc3
- TF-A doesn't use the OF graph for anything
- EDK2 doesn't support dwc3 and doesn't support OF graph
- OP-TEE doesn't support dwc3 and doesn't support OF graph

[1] WIP to tie OF graph port node to USB port device

Fixes: a33113f73693 ("dt-bindings: usb: snps,dwc3: document HS & SS OF graph ports")
Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
---
It is unclear to me whether the HS/SS numbering is fixed for all dwc3
variants. I checked Allwinner H616 and Rockchip RK3588 and they both
have HS as port 1 and SS as port 2.

This also doesn't cover a potential "multi-port" DWC3 implementation,
which Qualcomm seems to have.
---
 Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
index 6c0b8b653824..4b6304bd2ec1 100644
--- a/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
+++ b/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
@@ -410,11 +410,11 @@ properties:
       property is used.
 
     properties:
-      port@0:
+      port@1:
         $ref: /schemas/graph.yaml#/properties/port
         description: High Speed (HS) data bus.
 
-      port@1:
+      port@2:
         $ref: /schemas/graph.yaml#/properties/port
         description: Super Speed (SS) data bus.
 
-- 
2.56.0.212.g129ede20d9-goog


_______________________________________________
linux-amlogic mailing list
linux-amlogic@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-amlogic
