Linux USB
 help / color / mirror / Atom feed
From: sashiko-bot@kernel.org
To: "Qianhui Xu" <xiaqinghuan@mail.ustc.edu.cn>
Cc: linux-usb@vger.kernel.org, devicetree@vger.kernel.org,
	robh@kernel.org, conor+dt@kernel.org
Subject: Re: [PATCH v9 1/3] dt-bindings: usb: snps,dwc3: two connectors are two endpoints of one port
Date: Tue, 17 Nov 2026 05:40:08 +0000	[thread overview]
Message-ID: <sashiko-outbox-218217@kernel.org> (raw)
In-Reply-To: <20261117052137.32833-2-xiaqinghuan@mail.ustc.edu.cn>

Thank you for your contribution! Sashiko AI review found 3 potential
issues to consider:
- [Medium] dt-bindings: usb: snps,dwc3: unconditional hs-port on port@0
  breaks non-mux DTs
- [Low] dt-bindings: usb: snps,dwc3: hs-port allows omitting mux-state
  on one endpoint
- [Low] dt-bindings: usb: snps,dwc3: commit message written as v8-to-v9
  changelog
--

commit 847f1c050f1cee5ea74edfc8b8a467a8d17c4c69
Author: Qianhui Xu <xiaqinghuan@mail.ustc.edu.cn>

> dt-bindings: usb: snps,dwc3: two connectors are two endpoints of one port
>
> Rework of the v8 binding per Rob Herring's review of
> 2026-11-10 16:36Z (<20261110163640.GA85824-robh@kernel.org>):
>
>   "ports are for separate data streams. Endpoints are for mux'ed data
>    streams. This looks like the latter, so port@0 should have 2 endpoints
>    and port@2 dropped."
>
> and, for the GPIO property:
>
>   "Use the gpio mux binding."
>
> Two connectors sharing one High Speed D+/D- pair are two mux'ed data
> streams of one port, so they become endpoint@0 and endpoint@1 of port@0
> (the Super Speed lane stays port@1).  The GPIO that selects between them
> is no longer described by a private "port-select-gpios" property but by a
> "gpio-mux" controller referenced from "mux-controls", and the endpoint of
> each connector carries the mux state that reaches it.
>
> *** 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@mail.ustc.edu.cn>

[Severity: Low]
This commit message is written as a v8-to-v9 revision log ("port@2 dropped",
"no longer described by a private port-select-gpios property"), but neither
port@2 nor port-select-gpios exists in the baseline binding.  Could the commit
message describe the newly added dual-connector High Speed mux binding
relative to the baseline tree, moving the inter-version changelog notes below
the "---" separator?

> diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
> index 6c0b8b6538246..81e3561e47ce6 100644
> --- a/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
> +++ b/Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml
> @@ -13,6 +13,84 @@ 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.
> +    properties:
> +      '#address-cells':
> +        const: 1
> +
> +      '#size-cells':
> +        const: 0
> +
> +      endpoint@0:
> +        $ref: '#/$defs/hs-endpoint'
> +        required: [reg]
> +
> +      endpoint@1:
> +        $ref: '#/$defs/hs-endpoint'
> +        required: [reg]
> +
> +    required: ['#address-cells', '#size-cells', endpoint@0, endpoint@1]
> +
> +    # The two connectors must claim opposite mux states; requiring both
> +    # endpoints in every branch is what makes the two cases mutually
> +    # exclusive for oneOf.
> +    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

[Severity: Low]
Does hs-port allow one of the two endpoints to omit both usb-role-switch and
mux-state?

Because hs-endpoint only ties usb-role-switch and mux-state together via
dependentRequired, and neither endpoint@0/endpoint@1 nor the oneOf branches
specify required: [mux-state], an endpoint that omits both properties
vacuously satisfies properties.mux-state in JSON Schema.  If endpoint@0 sets
usb-role-switch and mux-state = <0> while endpoint@1 omits both, the first
oneOf branch matches and the second fails on endpoint@0, so the incomplete DT
node passes dtbs_check even though the driver requires both properties on
both endpoints.

[ ... ]

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

[Severity: Medium]
Does replacing /schemas/graph.yaml#/properties/port with #/$defs/hs-port on
the top-level port@0 property break dtbs_check for all non-muxed DWC3 nodes?

Applying #/$defs/hs-port unconditionally here (in addition to the conditional
branch when mux-controls is present) forces every DWC3 node with ports/port@0
to define #address-cells, #size-cells, endpoint@0, and endpoint@1, rejecting
existing single-endpoint DWC3 device trees such as qcom/sm8250.dtsi.
Moreover, when mux-controls is absent, the else branch in allOf forbids
mux-state on both endpoints, causing both branches of hs-port's oneOf to match
vacuously and making port@0 impossible to validate without mux-controls.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261117052137.32833-1-xiaqinghuan@mail.ustc.edu.cn?part=1

  reply	other threads:[~2026-11-17  5:40 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-17  5:21 [PATCH v9 0/3] usb: dwc3: support two connectors sharing one HS data bus Qianhui Xu
2026-11-17  5:21 ` [PATCH v9 1/3] dt-bindings: usb: snps,dwc3: two connectors are two endpoints of one port Qianhui Xu
2026-11-17  5:40   ` sashiko-bot [this message]
2026-11-17  5:21 ` [PATCH v9 2/3] usb: roles: look up role switches attached to a graph endpoint Qianhui Xu
2026-11-17  5:27   ` sashiko-bot
2026-11-17  5:21 ` [PATCH v9 3/3] usb: dwc3: select the shared HS data bus with a mux controller Qianhui Xu
2026-11-17  5:37   ` sashiko-bot

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=sashiko-outbox-218217@kernel.org \
    --to=sashiko-bot@kernel.org \
    --cc=conor+dt@kernel.org \
    --cc=devicetree@vger.kernel.org \
    --cc=linux-usb@vger.kernel.org \
    --cc=robh@kernel.org \
    --cc=sashiko-reviews@lists.linux.dev \
    --cc=xiaqinghuan@mail.ustc.edu.cn \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox