[PATCH 0/2] dt-bindings: usb: downstream host ports for hcd and dwc3

[PATCH 0/2] dt-bindings: usb: downstream host ports for hcd and dwc3

[Chen-Yu Tsai]

Hi folks,

I mentioned to a couple people at LPC that the USB host controller
bindings were missing downstream port definitions, and that the ones
used for dwc3 don't align with USB hardware port numbering.

The dwc3 discrepancy was originally noticed by Wei [1] and Konrad [2]
while adapting my M.2 E-key USB support series [3][4] to Qualcomm devices.

Here are the binding changes. If you were CC-ed, then you were listed as
the maintainer of any one of the dwc3 implementations or platforms using
it. So this change would affect you.

Patch 1 adds the "ports" definitions to the common USB host controller
binding. This just follows what is used in usb-hub.yaml. Nothing
special.

Patch 2 "fixes" the port numbering used in the common dwc3 binding. The
dwc3 includes an XHCI for host mode operation, and its port numbering
should follow the common usb-hcd.yaml binding. This clashes with the
existing arbitrary port numbering found in dwc3. I checked all the
big projects, and it seems that only Linux is using them, and it doesn't
care about the numbering anyway.

So while the patches looks small, there are actually 26 other dwc3
implementation bindings that are affected.

And this series currently only has the binding changes. There are
probably close to 500 dts files that need to be fixed as well. I asked
LLM to help me fix the arm64 ones already, and it seemed to do a good
job with some hand holding.

Please have a look. I fully expect there to be a lot of hair pulling.


Thanks
ChenYu

[1] https://lore.kernel.org/all/20260731073306.1895428-1-wei.deng@oss.qualcomm.com/
[2] https://lore.kernel.org/all/c6526ba0-be08-46c6-a501-1b161939657c@oss.qualcomm.com/
[3] v6: https://lore.kernel.org/all/20260721065413.2306137-1-wenst@chromium.org/
[4] v9 (latest): https://lore.kernel.org/all/20260916075745.3549953-1-wenst@chromium.org/


Chen-Yu Tsai (2):
  dt-bindings: usb: hcd: Add downstream USB ports
  dt-bindings: usb: snps,dwc3: Fix downstream port numbering

 .../devicetree/bindings/usb/snps,dwc3-common.yaml      |  4 ++--
 Documentation/devicetree/bindings/usb/usb-hcd.yaml     | 10 +++++++++-
 2 files changed, 11 insertions(+), 3 deletions(-)

-- 
2.56.0.212.g129ede20d9-goog

[PATCH 1/2] dt-bindings: usb: hcd: Add downstream USB ports

[Chen-Yu Tsai]

Besides hard-wired downstream USB devices, a USB HCD's downstream ports
can also connect to USB connector nodes via OF graph, just like with a
USB hub.

Allow a "ports" child node and describe the possible downstream port
nodes. USB downstream port numbers start at 1.

Also fix up the address portion of hard-wired downstream USB devices to
match.

Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
---
 Documentation/devicetree/bindings/usb/usb-hcd.yaml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/usb/usb-hcd.yaml b/Documentation/devicetree/bindings/usb/usb-hcd.yaml
index 45a19d4928af..24df99dfb243 100644
--- a/Documentation/devicetree/bindings/usb/usb-hcd.yaml
+++ b/Documentation/devicetree/bindings/usb/usb-hcd.yaml
@@ -29,8 +29,16 @@ properties:
   "#size-cells":
     const: 0
 
+  ports:
+    $ref: /schemas/graph.yaml#/properties/ports
+    description: The downstream facing USB ports
+
+    patternProperties:
+      "^port@[1-9a-f][0-9a-f]?$":
+        $ref: /schemas/graph.yaml#/properties/port
+
 patternProperties:
-  "^.*@[0-9a-f]{1,2}$":
+  "^.*@[1-9a-f][0-9a-f]?$":
     description: The hard wired USB devices
     type: object
     $ref: /schemas/usb/usb-device.yaml
-- 
2.56.0.212.g129ede20d9-goog

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

[Chen-Yu Tsai]

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

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

[Neil Armstrong]

On 10/14/26 10:20, Chen-Yu Tsai wrote:
> 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.

Is there something in index 0 we will need to define at some point ?

Using 0 as base for numbering in DT isn't incompatible with the USB
spec using base 1 for numbering,

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

It breaks the current Qualcomm numbering on numerous boards.

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

Re: [PATCH 1/2] dt-bindings: usb: hcd: Add downstream USB ports

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] dt-bindings: usb: port@0 schema constraint bypassed
--

commit aaa6107663f4d524c266c3a18264c416a86a4bb4
Author: Chen-Yu Tsai <wenst@chromium.org>

dt-bindings: usb: hcd: Add downstream USB ports

This commit adds a "ports" child node to the USB HCD binding to support
connecting downstream USB connector nodes via OF graph. It attempts to enforce
that USB downstream port numbers start at 1, and updates the address matching
for hard-wired downstream devices.

> diff --git a/Documentation/devicetree/bindings/usb/usb-hcd.yaml b/Documentation/devicetree/bindings/usb/usb-hcd.yaml
> index 45a19d4928afa..24df99dfb243c 100644
> --- a/Documentation/devicetree/bindings/usb/usb-hcd.yaml
> +++ b/Documentation/devicetree/bindings/usb/usb-hcd.yaml
> @@ -29,8 +29,16 @@ properties:
>    "#size-cells":
>      const: 0
>  
> +  ports:
> +    $ref: /schemas/graph.yaml#/properties/ports
> +    description: The downstream facing USB ports
> +
> +    patternProperties:
> +      "^port@[1-9a-f][0-9a-f]?$":
> +        $ref: /schemas/graph.yaml#/properties/port

[Severity: Medium]
Does this local constraint actually prevent port@0 from passing validation?

Since JSON schema patternProperties only restrict matching nodes, a
non-matching node like port@0 will fall back to the generic graph.yaml
reference.

Because graph.yaml evaluates anything matching ^port(@.*)?$, wouldn't
port@0 be evaluated as valid and silently pass, completely bypassing the
intent that downstream port numbers start at 1?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261014082037.1774672-1-wenst@chromium.org?part=1

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

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [High] dt-bindings: usb: snps,dwc3: ABI breakage and semantic mismatch for OF graph ports
--

commit 8b21cb9c9f29433cb69a312829ee4e457fe73ca5
Author: Chen-Yu Tsai <wenst@chromium.org>

dt-bindings: usb: snps,dwc3: Fix downstream port numbering

The DWC3 controller can operate in host mode, and USB downstream ports start
from 1, not 0. This commit reconciles the downstream port numbering with the
common USB host binding by renumbering ports 0 and 1 to 1 and 2, which is
explicitly noted as non-backwards compatible.

> diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
> index 6c0b8b6538246..4b6304bd2ec16 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.

[Severity: High]
Does this change break ABI backwards compatibility for existing in-tree
device trees?

For example, existing in-tree device trees like
arch/arm64/boot/dts/qcom/sm6115.dtsi already define port@0 for HS and
port@1 for SS:

					port@0 {
						reg = <0>;

						usb_dwc3_hs: endpoint {
						};
					};

					port@1 {
						reg = <1>;

						usb_dwc3_ss: endpoint {
							remote-endpoint = <&usb_qmpphy_usb_ss_in>;
						};
					};

These existing device trees will now fail dtbs_check schema validation
because port@0 is no longer valid, and port@1 is documented as High Speed
when existing trees use it for Super Speed.

Furthermore, when the WIP OF graph host mode connections mentioned in the
commit message are merged, will a future kernel attempting to configure
port@1 as the High Speed port functionally break USB host mode on older
DTBs that route port@1 to the Super Speed PHY?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261014082037.1774672-1-wenst@chromium.org?part=2

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

[Chen-Yu Tsai]

On Wed, Oct 14, 2026 at 5:28 PM Neil Armstrong
<neil.armstrong@linaro.org> wrote:
>
> On 10/14/26 10:20, Chen-Yu Tsai wrote:
> > 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.
>
> Is there something in index 0 we will need to define at some point ?

On the host side, no. Downstream ports start at 1.

On the device mode side, I believe the numbers are completely made up.

> Using 0 as base for numbering in DT isn't incompatible with the USB
> spec using base 1 for numbering,

But you end up with diverging numbering schemes, and it diverges
from other USB controllers, particularly XHCI, which DWC3 embeds.

And it also differs from the numbering currently used for directly
connected onboard devices (like hubs), which use or expect the USB
numbering scheme.

Sure we can make DWC3 "special", drop inclusion of usb-hcd.yaml,
and duplicate the section for onboard devices. On Linux, we can
add some more code to xhci_find_raw_port_number() to make an
exception for DWC3 controllers.

Also, usb_of_get_connect_type() is already broken for DWC3 based
controllers that only describe the HS connection but not the SS
connection. usb_of_get_connect_type() currently doesn't call
usb_hcd_find_raw_port_number() so both HS and SS get mapped to port 1,
which wouldn't be in the DT since HS is currently port@0. But even if
it did, SS would get mapped to port 2 anyway.


IMHO having consistent numbering across controller types would be
better. This avoids making the USB core and hub code deal with more
exceptions, and also easier to understand and write device trees.

> > 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.
>
> It breaks the current Qualcomm numbering on numerous boards.

Yes. It breaks _everyone_ using the current numbering in the sense that
they are no longer valid, but should not affect actual usage.

This comment refers to "multiport" controllers from Qualcomm [1], which
would have ports beyond 1 and 2.

[1] https://lore.kernel.org/all/20240420044901.884098-8-quic_kriskura@quicinc.com/


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

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

[Neil Armstrong]

On 10/14/26 11:29, Chen-Yu Tsai wrote:
> On Wed, Oct 14, 2026 at 5:28 PM Neil Armstrong
> <neil.armstrong@linaro.org> wrote:
>>
>> On 10/14/26 10:20, Chen-Yu Tsai wrote:
>>> 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.
>>
>> Is there something in index 0 we will need to define at some point ?
> 
> On the host side, no. Downstream ports start at 1.
> 
> On the device mode side, I believe the numbers are completely made up.
> 
>> Using 0 as base for numbering in DT isn't incompatible with the USB
>> spec using base 1 for numbering,
> 
> But you end up with diverging numbering schemes, and it diverges
> from other USB controllers, particularly XHCI, which DWC3 embeds.
> 
> And it also differs from the numbering currently used for directly
> connected onboard devices (like hubs), which use or expect the USB
> numbering scheme.
> 
> Sure we can make DWC3 "special", drop inclusion of usb-hcd.yaml,
> and duplicate the section for onboard devices. On Linux, we can
> add some more code to xhci_find_raw_port_number() to make an
> exception for DWC3 controllers.
> 
> Also, usb_of_get_connect_type() is already broken for DWC3 based
> controllers that only describe the HS connection but not the SS
> connection. usb_of_get_connect_type() currently doesn't call
> usb_hcd_find_raw_port_number() so both HS and SS get mapped to port 1,
> which wouldn't be in the DT since HS is currently port@0. But even if
> it did, SS would get mapped to port 2 anyway.
> 
> 
> IMHO having consistent numbering across controller types would be
> better. This avoids making the USB core and hub code deal with more
> exceptions, and also easier to understand and write device trees.

I was in the impression the port number not necessarily reflects
an actual physical numbering, and can be a logical number we would
then map in the kernel.

I don't see any issue here having base 0 for the bindings and then
converting it to base 1 for the XHCI port numbering.

Each controller (Host, Device, OTG) will have it's own numbering anyway,
so using the XHCI numbering only sounds a bad idea TBH.

> 
>>> 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.
>>
>> It breaks the current Qualcomm numbering on numerous boards.
> 
> Yes. It breaks _everyone_ using the current numbering in the sense that
> they are no longer valid, but should not affect actual usage.

Older DT are supposed to be working on new kernels, you will break ABI
and will break usage if the port numbering is enforced to enabled embedded
hubs for example.

Neil

> 
> This comment refers to "multiport" controllers from Qualcomm [1], which
> would have ports beyond 1 and 2.
> 
> [1] https://lore.kernel.org/all/20240420044901.884098-8-quic_kriskura@quicinc.com/
> 
> 
>>> ---
>>>    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.
>>>
>>

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

[Chen-Yu Tsai]

On Wed, Oct 14, 2026 at 6:44 PM Neil Armstrong
<neil.armstrong@linaro.org> wrote:
>
> On 10/14/26 11:29, Chen-Yu Tsai wrote:
> > On Wed, Oct 14, 2026 at 5:28 PM Neil Armstrong
> > <neil.armstrong@linaro.org> wrote:
> >>
> >> On 10/14/26 10:20, Chen-Yu Tsai wrote:
> >>> 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.
> >>
> >> Is there something in index 0 we will need to define at some point ?
> >
> > On the host side, no. Downstream ports start at 1.
> >
> > On the device mode side, I believe the numbers are completely made up.
> >
> >> Using 0 as base for numbering in DT isn't incompatible with the USB
> >> spec using base 1 for numbering,
> >
> > But you end up with diverging numbering schemes, and it diverges
> > from other USB controllers, particularly XHCI, which DWC3 embeds.
> >
> > And it also differs from the numbering currently used for directly
> > connected onboard devices (like hubs), which use or expect the USB
> > numbering scheme.
> >
> > Sure we can make DWC3 "special", drop inclusion of usb-hcd.yaml,
> > and duplicate the section for onboard devices. On Linux, we can
> > add some more code to xhci_find_raw_port_number() to make an
> > exception for DWC3 controllers.
> >
> > Also, usb_of_get_connect_type() is already broken for DWC3 based
> > controllers that only describe the HS connection but not the SS
> > connection. usb_of_get_connect_type() currently doesn't call
> > usb_hcd_find_raw_port_number() so both HS and SS get mapped to port 1,
> > which wouldn't be in the DT since HS is currently port@0. But even if
> > it did, SS would get mapped to port 2 anyway.
> >
> >
> > IMHO having consistent numbering across controller types would be
> > better. This avoids making the USB core and hub code deal with more
> > exceptions, and also easier to understand and write device trees.
>
> I was in the impression the port number not necessarily reflects
> an actual physical numbering, and can be a logical number we would
> then map in the kernel.
>
> I don't see any issue here having base 0 for the bindings and then
> converting it to base 1 for the XHCI port numbering.
>
> Each controller (Host, Device, OTG) will have it's own numbering anyway,
> so using the XHCI numbering only sounds a bad idea TBH.

OK. So we keep the port numbering, which is different from the embedded
device numbering, even for the same dual role controller? See below.

I hope you see why I think it is confusing.

> >
> >>> 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.
> >>
> >> It breaks the current Qualcomm numbering on numerous boards.
> >
> > Yes. It breaks _everyone_ using the current numbering in the sense that
> > they are no longer valid, but should not affect actual usage.
>
> Older DT are supposed to be working on new kernels, you will break ABI
> and will break usage if the port numbering is enforced to enabled embedded
> hubs for example.

On that front, embedded hubs already require you to use the USB numbering.

If you write

    dwc3 {
        hub@0 {
            compatible = "usb0123,abcd";
            reg = "0";
        };
    };

It won't match anything. The current USB HCD binding doesn't prevent you
from using port 0, but the kernel won't tie the USB device to it, even
if it is a single port USB controller. As I mentioned, USB downstream
ports start at 1, even for root hubs that only have 1 downstream port.

The kernel also doesn't check if the compatible property is correct, but
that is a separate issue. Maybe it should though, so people can see that
their DT is incorrect, like if they swapped HS and SS ports for a USB 3.x
hub.


ChenYu


> Neil
>
> >
> > This comment refers to "multiport" controllers from Qualcomm [1], which
> > would have ports beyond 1 and 2.
> >
> > [1] https://lore.kernel.org/all/20240420044901.884098-8-quic_kriskura@quicinc.com/
> >
> >
> >>> ---
> >>>    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.
> >>>
> >>
>

Re: [PATCH 1/2] dt-bindings: usb: hcd: Add downstream USB ports

[Chen-Yu Tsai]

On Wed, Oct 14, 2026 at 5:31 PM <sashiko-bot@kernel.org> wrote:
>
> Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
> - [Medium] dt-bindings: usb: port@0 schema constraint bypassed
> --
>
> commit aaa6107663f4d524c266c3a18264c416a86a4bb4
> Author: Chen-Yu Tsai <wenst@chromium.org>
>
> dt-bindings: usb: hcd: Add downstream USB ports
>
> This commit adds a "ports" child node to the USB HCD binding to support
> connecting downstream USB connector nodes via OF graph. It attempts to enforce
> that USB downstream port numbers start at 1, and updates the address matching
> for hard-wired downstream devices.
>
> > diff --git a/Documentation/devicetree/bindings/usb/usb-hcd.yaml b/Documentation/devicetree/bindings/usb/usb-hcd.yaml
> > index 45a19d4928afa..24df99dfb243c 100644
> > --- a/Documentation/devicetree/bindings/usb/usb-hcd.yaml
> > +++ b/Documentation/devicetree/bindings/usb/usb-hcd.yaml
> > @@ -29,8 +29,16 @@ properties:
> >    "#size-cells":
> >      const: 0
> >
> > +  ports:
> > +    $ref: /schemas/graph.yaml#/properties/ports
> > +    description: The downstream facing USB ports
> > +
> > +    patternProperties:
> > +      "^port@[1-9a-f][0-9a-f]?$":
> > +        $ref: /schemas/graph.yaml#/properties/port
>
> [Severity: Medium]
> Does this local constraint actually prevent port@0 from passing validation?
>
> Since JSON schema patternProperties only restrict matching nodes, a
> non-matching node like port@0 will fall back to the generic graph.yaml
> reference.
>
> Because graph.yaml evaluates anything matching ^port(@.*)?$, wouldn't
> port@0 be evaluated as valid and silently pass, completely bypassing the
> intent that downstream port numbers start at 1?

I suspect I need to write it as:

    ports:
      properties:
        port@0: false
      patternProperties:
        "^port@[1-9a-f][0-9a-f]?$": ...

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

[Neil Armstrong]

On 10/14/26 12:14, Chen-Yu Tsai wrote:
> On Wed, Oct 14, 2026 at 6:44 PM Neil Armstrong
> <neil.armstrong@linaro.org> wrote:
>>
>> On 10/14/26 11:29, Chen-Yu Tsai wrote:
>>> On Wed, Oct 14, 2026 at 5:28 PM Neil Armstrong
>>> <neil.armstrong@linaro.org> wrote:
>>>>
>>>> On 10/14/26 10:20, Chen-Yu Tsai wrote:
>>>>> 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.
>>>>
>>>> Is there something in index 0 we will need to define at some point ?
>>>
>>> On the host side, no. Downstream ports start at 1.
>>>
>>> On the device mode side, I believe the numbers are completely made up.
>>>
>>>> Using 0 as base for numbering in DT isn't incompatible with the USB
>>>> spec using base 1 for numbering,
>>>
>>> But you end up with diverging numbering schemes, and it diverges
>>> from other USB controllers, particularly XHCI, which DWC3 embeds.
>>>
>>> And it also differs from the numbering currently used for directly
>>> connected onboard devices (like hubs), which use or expect the USB
>>> numbering scheme.
>>>
>>> Sure we can make DWC3 "special", drop inclusion of usb-hcd.yaml,
>>> and duplicate the section for onboard devices. On Linux, we can
>>> add some more code to xhci_find_raw_port_number() to make an
>>> exception for DWC3 controllers.
>>>
>>> Also, usb_of_get_connect_type() is already broken for DWC3 based
>>> controllers that only describe the HS connection but not the SS
>>> connection. usb_of_get_connect_type() currently doesn't call
>>> usb_hcd_find_raw_port_number() so both HS and SS get mapped to port 1,
>>> which wouldn't be in the DT since HS is currently port@0. But even if
>>> it did, SS would get mapped to port 2 anyway.
>>>
>>>
>>> IMHO having consistent numbering across controller types would be
>>> better. This avoids making the USB core and hub code deal with more
>>> exceptions, and also easier to understand and write device trees.
>>
>> I was in the impression the port number not necessarily reflects
>> an actual physical numbering, and can be a logical number we would
>> then map in the kernel.
>>
>> I don't see any issue here having base 0 for the bindings and then
>> converting it to base 1 for the XHCI port numbering.
>>
>> Each controller (Host, Device, OTG) will have it's own numbering anyway,
>> so using the XHCI numbering only sounds a bad idea TBH.
> 
> OK. So we keep the port numbering, which is different from the embedded
> device numbering, even for the same dual role controller? See below.
> 
> I hope you see why I think it is confusing.
> 
>>>
>>>>> 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.
>>>>
>>>> It breaks the current Qualcomm numbering on numerous boards.
>>>
>>> Yes. It breaks _everyone_ using the current numbering in the sense that
>>> they are no longer valid, but should not affect actual usage.
>>
>> Older DT are supposed to be working on new kernels, you will break ABI
>> and will break usage if the port numbering is enforced to enabled embedded
>> hubs for example.
> 
> On that front, embedded hubs already require you to use the USB numbering.
> 
> If you write
> 
>      dwc3 {
>          hub@0 {
>              compatible = "usb0123,abcd";
>              reg = "0";
>          };
>      };
> 
> It won't match anything. The current USB HCD binding doesn't prevent you
> from using port 0, but the kernel won't tie the USB device to it, even
> if it is a single port USB controller. As I mentioned, USB downstream
> ports start at 1, even for root hubs that only have 1 downstream port.
> 
> The kernel also doesn't check if the compatible property is correct, but
> that is a separate issue. Maybe it should though, so people can see that
> their DT is incorrect, like if they swapped HS and SS ports for a USB 3.x
> hub.

TBH this USB device bindings for embedded hubs is wrong in many of ways.

So, is the downstream port index a numbering scheme from Linux ? Will each port
will have the same number on every OS implementation ? Do all OSes implement
the root as a the virtual root hub ? do they always use the same indexing ?

My comparison is PCI(e) where the controller port number is a Linux internal
numbering we don't use in DT, we only use the BDF of the downstream bus/endpoints
enumeration which is standardized.

So I think we should actually use the same scheme for usb, but having a subnode
per controller usb port with a hierarchy of nodes representing devices.

Keeping the current USB device bindings and trying to make it work is wrong here.

Neil

> 
> 
> ChenYu
> 
> 
>> Neil
>>
>>>
>>> This comment refers to "multiport" controllers from Qualcomm [1], which
>>> would have ports beyond 1 and 2.
>>>
>>> [1] https://lore.kernel.org/all/20240420044901.884098-8-quic_kriskura@quicinc.com/
>>>
>>>
>>>>> ---
>>>>>     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.
>>>>>
>>>>
>>