[PATCH v10 1/3] dt-bindings: usb: snps,dwc3: describe two connectors on one HS data bus

From: Qianhui Xu

Date: Fri Nov 20 2026 - 21:21:51 EST


Some designs route two USB Type-C receptacles through one High Speed D+/D-
pair with a GPIO multiplexer, so only one connector drives the controller
at a time. Each connector needs to be described: which role-switch input
belongs to it and which mux state selects it, because the role switch is
registered per connector and the driver must know the state to program
when that connector asks for a role.

Describe the two connectors as the two endpoints of the High Speed port,
which is what a mux'ed data stream is in the OF graph: port@0 of "ports"
carries endpoint@0 and endpoint@1 under "mux-controls", each with
"usb-role-switch" and the "mux-state" that reaches it. The mux
controller is referenced with "mux-controls", so an existing "gpio-mux"
controller can be used as is.

The High Speed port definition itself stays optional: a single-connector
controller keeps describing one plain "endpoint", and requiring the two
endpoints together with the rule that their mux states differ only
applies when "mux-controls" is present. The two states must be opposite,
and the driver rejects a device tree where two connectors claim the same
one.

*** AI-assistance disclosure ***
This patch was prepared with the help of an LLM coding assistant. The
author reviewed every line and ran the gates quoted in the series notes.

Signed-off-by: Qianhui Xu <xiaqinghuan@xxxxxxxxxxxxxxxx>
---
.../bindings/usb/snps,dwc3-common.yaml | 124 +++++++++++++++++-
1 file changed, 122 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
index 6c0b8b6538..57e3c1d9ed 100644
--- a/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
+++ b/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
@@ -13,6 +13,89 @@ description:
Defines the properties of the DWC3 core as being embedded in either an
vendor-specific implementation or as a standalone component.

+$defs:
+ hs-endpoint:
+ $ref: /schemas/graph.yaml#/$defs/endpoint-base
+ unevaluatedProperties: false
+
+ properties:
+ usb-role-switch:
+ type: boolean
+ description:
+ This connector endpoint has its own USB role switch. The switch is
+ registered against this endpoint and looked up with
+ usb_role_switch_at_endpoint().
+
+ mux-state:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description:
+ State of the High Speed data bus multiplexer which connects this
+ connector to the controller. The two connectors of one controller
+ must use different states; the driver rejects a device tree where
+ two connectors claim the same one.
+
+ dependentRequired:
+ usb-role-switch: [mux-state]
+ mux-state: [usb-role-switch]
+
+ hs-port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ # The two connectors are two mux'ed data streams of the same High Speed
+ # bus, so they are two endpoints of one port, not two ports: "ports"
+ # describes the controller's own data streams (HS in port@0, SS in
+ # port@1), and an endpoint describes one stream multiplexed onto a port.
+ #
+ # Nothing here is mandatory on its own: a single-connector controller
+ # keeps the plain graph port and only describes "endpoint". The mux
+ # branch of "allOf" requires the two endpoints when "mux-controls" is
+ # present, and the exclusivity below then applies because both endpoints
+ # exist.
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ endpoint@0:
+ $ref: '#/$defs/hs-endpoint'
+ required: [reg, usb-role-switch, mux-state]
+
+ endpoint@1:
+ $ref: '#/$defs/hs-endpoint'
+ required: [reg, usb-role-switch, mux-state]
+
+ if:
+ required: [endpoint@0, endpoint@1]
+ then:
+ # The two connectors must claim opposite mux states.
+ oneOf:
+ - properties:
+ endpoint@0:
+ properties:
+ mux-state:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ const: 0
+ endpoint@1:
+ properties:
+ mux-state:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ const: 1
+ - properties:
+ endpoint@0:
+ properties:
+ mux-state:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ const: 1
+ endpoint@1:
+ properties:
+ mux-state:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ const: 0
+
allOf:
- $ref: usb-drd.yaml#
- if:
@@ -26,8 +109,46 @@ allOf:
$ref: usb.yaml#
else:
$ref: usb-xhci.yaml#
+ - if:
+ required: [mux-controls]
+ then:
+ # The mux path is only taken when the controller itself carries
+ # "usb-role-switch": dwc3_get_dr_mode() forces dr_mode back to
+ # peripheral, dwc3_get_extcon() skips the role-switch branch and
+ # dwc3_drd_init() never sets the mux up without it.
+ required: [dr_mode, ports, usb-role-switch]
+ properties:
+ dr_mode:
+ const: otg
+ ports:
+ required: [port@0]
+ properties:
+ port@0:
+ required: ['#address-cells', '#size-cells',
+ endpoint@0, endpoint@1]
+ else:
+ # Without a mux the High Speed port keeps the generic graph port
+ # binding, so single-endpoint controllers are described as before.
+ # port@0 is referenced here rather than declared once in "ports"
+ # because the graph port forbids properties it does not know
+ # (unevaluatedProperties: false), which would reject the per-connector
+ # "usb-role-switch" and "mux-state" of the dual-connector form.
+ properties:
+ ports:
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/properties/port

properties:
+ mux-controls:
+ maxItems: 1
+ description:
+ Phandle to the multiplexer that selects which of the two connectors
+ drives the controller's shared High Speed data bus, e.g. a
+ "gpio-mux" controller. Each connector is described by the endpoint@0
+ or endpoint@1 of "port@0", and the endpoint of that connector carries
+ its own role-switch input and the "mux-state" it is reached in.
+
extcon:
maxItems: 1
deprecated: true
@@ -411,7 +532,7 @@ properties:

properties:
port@0:
- $ref: /schemas/graph.yaml#/properties/port
+ $ref: '#/$defs/hs-port'
description: High Speed (HS) data bus.

port@1:
@@ -429,4 +550,3 @@ required:

additionalProperties: true
...
-
--
2.53.0