Document the device tree bindings for the DWC3 USB controller found in
Google Tensor SoCs, starting with the G5 generation.
The Tensor G5 silicon represents a complete architectural departure from
previous generations (like gs101), including entirely new clock/reset
schemes, top-level wrapper and register interface. Consequently,
existing Samsung/Exynos DWC3 USB bindings and drivers are incompatible,
necessitating this new device tree binding.
The USB controller on Tensor G5 is based on Synopsys DWC3 IP and features
Dual-Role Device single port with hibernation support.
Signed-off-by: Roy Luo <royluo@google.com>
---
.../bindings/usb/google,gs-dwc3.yaml | 145 ++++++++++++++++++
1 file changed, 145 insertions(+)
create mode 100644 Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
diff --git a/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
new file mode 100644
index 000000000000..9eb0bf726e8d
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2025, Google LLC
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/google,gs-dwc3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Google Tensor Series (G5+) DWC3 USB SoC Controller
+
+maintainers:
+ - Roy Luo <royluo@google.com>
+
+description: |
+ Describes the DWC3 USB controller block implemented on Google Tensor SoCs,
+ starting with the G5 generation. Based on Synopsys DWC3 IP, the controller
+ features Dual-Role Device single port with hibernation add-on.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - google,gs5-dwc3
+
+ reg:
+ minItems: 3
+ maxItems: 3
+
+ reg-names:
+ description: |
+ The following memory regions must present:
+ - dwc3_core: Core DWC3 IP registers.
+ - host_cfg_csr: Hibernation control registers.
+ - usbint_csr: Hibernation interrupt registers.
+ items:
+ - const: dwc3_core
+ - const: host_cfg_csr
+ - const: usbint_csr
+
+ interrupts:
+ minItems: 3
+ maxItems: 3
+
+ interrupt-names:
+ description: |
+ The following interrupts must present:
+ - dwc_usb3: Core DWC3 interrupt.
+ - hs_pme_irq: High speed remote wakeup interrupt for hibernation.
+ - ss_pme_irq: Super speed remote wakeup interrupt for hibernation.
+ items:
+ - const: dwc_usb3
+ - const: hs_pme_irq
+ - const: ss_pme_irq
+
+ clocks:
+ minItems: 3
+ maxItems: 3
+
+ clock-names:
+ minItems: 3
+ maxItems: 3
+
+ resets:
+ minItems: 5
+ maxItems: 5
+
+ reset-names:
+ items:
+ - const: usbc_non_sticky
+ - const: usbc_sticky
+ - const: usb_drd_bus
+ - const: u2phy_apb
+ - const: usb_top_csr
+
+ power-domains:
+ minItems: 2
+ maxItems: 2
+
+ power-domain-names:
+ description: |
+ The following power domain must present:
+ - usb_psw_pd: The child power domain of usb_top_pd. Turning it on puts the controller
+ into full power state, turning it off puts the controller into power
+ gated state.
+ - usb_top_pd: The parent power domain of usb_psw_pd. Turning it on puts the controller
+ into power gated state, turning it off completely shuts off the
+ controller.
+ items:
+ - const: usb_psw_pd
+ - const: usb_top_pd
+
+ iommus:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - interrupt-names
+ - clocks
+ - resets
+ - reset-names
+ - power-domains
+ - power-domain-names
+
+allOf:
+ - $ref: snps,dwc3-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ usb@c400000 {
+ compatible = "google,gs5-dwc3";
+ reg = <0 0x0c400000 0 0xd060>, <0 0x0c450000 0 0x14>, <0 0x0c450020 0 0x8>;
+ reg-names = "dwc3_core", "host_cfg_csr", "usbint_csr";
+ interrupts = <GIC_SPI 580 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 597 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 598 IRQ_TYPE_LEVEL_HIGH 0>;
+ interrupt-names = "dwc_usb3", "hs_pme_irq", "ss_pme_irq";
+ clocks = <&hsion_usbc_non_sticky_clk>, <&hsion_usbc_sticky_clk>,
+ <&hsion_u2phy_apb_clk>;
+ clock-names = "usbc_non_sticky", "usbc_sticky", "u2phy_apb";
+ resets = <&hsion_resets_usbc_non_sticky>, <&hsion_resets_usbc_sticky>,
+ <&hsion_resets_usb_drd_bus>, <&hsion_resets_u2phy_apb>,
+ <&hsion_resets_usb_top_csr>;
+ reset-names = "usbc_non_sticky", "usbc_sticky",
+ "usb_drd_bus", "u2phy_apb",
+ "usb_top_csr";
+ power-domains = <&hsio_n_usb_psw_pd>, <&hsio_n_usb_pd>;
+ power-domain-names = "usb_psw_pd", "usb_top_pd";
+ phys = <&usb_phy 0>;
+ phy-names = "usb2-phy";
+ snps,quirk-frame-length-adjustment = <0x20>;
+ snps,gfladj-refclk-lpm-sel-quirk;
+ snps,incr-burst-type-adjustment = <4>;
+ };
+ };
+...
--
2.51.0.710.ga91ca5db03-googOn 08/10/2025 14:59, Roy Luo wrote: > Document the device tree bindings for the DWC3 USB controller found in > Google Tensor SoCs, starting with the G5 generation. > > The Tensor G5 silicon represents a complete architectural departure from G5 does not have a model number like G1-G4? > previous generations (like gs101), including entirely new clock/reset > schemes, top-level wrapper and register interface. Consequently, > existing Samsung/Exynos DWC3 USB bindings and drivers are incompatible, Do not reference drivers. Explain the hardware. > necessitating this new device tree binding. > > The USB controller on Tensor G5 is based on Synopsys DWC3 IP and features > Dual-Role Device single port with hibernation support. > > Signed-off-by: Roy Luo <royluo@google.com> > --- > .../bindings/usb/google,gs-dwc3.yaml | 145 ++++++++++++++++++ > 1 file changed, 145 insertions(+) > create mode 100644 Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > > diff --git a/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > new file mode 100644 > index 000000000000..9eb0bf726e8d > --- /dev/null > +++ b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > @@ -0,0 +1,145 @@ > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) > +# Copyright (c) 2025, Google LLC > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/usb/google,gs-dwc3.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Google Tensor Series (G5+) DWC3 USB SoC Controller > + > +maintainers: > + - Roy Luo <royluo@google.com> > + > +description: | Do not need '|' unless you need to preserve formatting. > + Describes the DWC3 USB controller block implemented on Google Tensor SoCs, > + starting with the G5 generation. Based on Synopsys DWC3 IP, the controller > + features Dual-Role Device single port with hibernation add-on. > + > +properties: > + compatible: > + items: > + - enum: > + - google,gs5-dwc3 > + > + reg: > + minItems: 3 Drop > + maxItems: 3 > + > + reg-names: > + description: | > + The following memory regions must present: > + - dwc3_core: Core DWC3 IP registers. > + - host_cfg_csr: Hibernation control registers. > + - usbint_csr: Hibernation interrupt registers. Drop description or move it to items in reg. See other bindings. > + items: > + - const: dwc3_core > + - const: host_cfg_csr > + - const: usbint_csr > + > + interrupts: > + minItems: 3 Drop > + maxItems: 3 > + > + interrupt-names: > + description: | > + The following interrupts must present: > + - dwc_usb3: Core DWC3 interrupt. > + - hs_pme_irq: High speed remote wakeup interrupt for hibernation. > + - ss_pme_irq: Super speed remote wakeup interrupt for hibernation. From where did you get this style? Don't write bindings with chat gpt or whatever other tool. it is a waste of our time. > + items: > + - const: dwc_usb3 > + - const: hs_pme_irq > + - const: ss_pme_irq > + > + clocks: > + minItems: 3 > + maxItems: 3 > + > + clock-names: > + minItems: 3 > + maxItems: 3 From where did you get such syntax? > + > + resets: > + minItems: 5 > + maxItems: 5 > + > + reset-names: > + items: > + - const: usbc_non_sticky > + - const: usbc_sticky > + - const: usb_drd_bus > + - const: u2phy_apb > + - const: usb_top_csr > + > + power-domains: > + minItems: 2 > + maxItems: 2 > + > + power-domain-names: > + description: | > + The following power domain must present: > + - usb_psw_pd: The child power domain of usb_top_pd. Turning it on puts the controller > + into full power state, turning it off puts the controller into power > + gated state. > + - usb_top_pd: The parent power domain of usb_psw_pd. Turning it on puts the controller > + into power gated state, turning it off completely shuts off the > + controller. Same comments. > + items: > + - const: usb_psw_pd > + - const: usb_top_pd > + > + iommus: > + maxItems: 1 > + Best regards, Krzysztof
On Wed, Oct 8, 2025 at 4:56 PM Krzysztof Kozlowski <krzk@kernel.org> wrote: > > On 08/10/2025 14:59, Roy Luo wrote: > > Document the device tree bindings for the DWC3 USB controller found in > > Google Tensor SoCs, starting with the G5 generation. > > > > The Tensor G5 silicon represents a complete architectural departure from > > > G5 does not have a model number like G1-G4? There's no model number for G5, I'm sticking to the existing "gs" prefix as they're still in the same SoC family. Please let me know if you have any concerns. > > > previous generations (like gs101), including entirely new clock/reset > > schemes, top-level wrapper and register interface. Consequently, > > existing Samsung/Exynos DWC3 USB bindings and drivers are incompatible, > > Do not reference drivers. Explain the hardware. Ack, all mentions of "driver" will be removed in the next patch. > > > necessitating this new device tree binding. > > > > The USB controller on Tensor G5 is based on Synopsys DWC3 IP and features > > Dual-Role Device single port with hibernation support. > > > > Signed-off-by: Roy Luo <royluo@google.com> > > --- > > .../bindings/usb/google,gs-dwc3.yaml | 145 ++++++++++++++++++ > > 1 file changed, 145 insertions(+) > > create mode 100644 Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > > > > diff --git a/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > > new file mode 100644 > > index 000000000000..9eb0bf726e8d > > --- /dev/null > > +++ b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > > @@ -0,0 +1,145 @@ > > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) > > +# Copyright (c) 2025, Google LLC > > +%YAML 1.2 > > +--- > > +$id: http://devicetree.org/schemas/usb/google,gs-dwc3.yaml# > > +$schema: http://devicetree.org/meta-schemas/core.yaml# > > + > > +title: Google Tensor Series (G5+) DWC3 USB SoC Controller > > + > > +maintainers: > > + - Roy Luo <royluo@google.com> > > + > > +description: | > > > Do not need '|' unless you need to preserve formatting. Ack, will fix this in the next patch. > > > + Describes the DWC3 USB controller block implemented on Google Tensor SoCs, > > + starting with the G5 generation. Based on Synopsys DWC3 IP, the controller > > + features Dual-Role Device single port with hibernation add-on. > > + > > +properties: > > + compatible: > > + items: > > + - enum: > > + - google,gs5-dwc3 > > + > > + reg: > > + minItems: 3 > > Drop > > > + maxItems: 3 > > + > > + reg-names: > > + description: | > > + The following memory regions must present: > > + - dwc3_core: Core DWC3 IP registers. > > + - host_cfg_csr: Hibernation control registers. > > + - usbint_csr: Hibernation interrupt registers. > > Drop description or move it to items in reg. See other bindings. Ack, will use an item list in reg instead. > > > + items: > > + - const: dwc3_core > > + - const: host_cfg_csr > > + - const: usbint_csr > > + > > + interrupts: > > + minItems: 3 > > Drop Ack, will use an item list instead. > > > + maxItems: 3 > > + > > + interrupt-names: > > + description: | > > + The following interrupts must present: > > + - dwc_usb3: Core DWC3 interrupt. > > + - hs_pme_irq: High speed remote wakeup interrupt for hibernation. > > + - ss_pme_irq: Super speed remote wakeup interrupt for hibernation. > > From where did you get this style? Don't write bindings with chat gpt or > whatever other tool. it is a waste of our time. I referenced the style from a recent dt binding change [1] that adds "Documentation/devicetree/bindings/usb/qcom,snps-dwc3.yaml". I thought it would be a good reference because it's relatively new and is also a binding for SNPS dwc3 glue logic. Perhaps that style doesn't apply here because qcom,snps-dwc3.yaml supports multiple compatible and here we have only one? Just to clarify, I'm a Gemini user and this patch is 100% organic, hand-crafted by a living human brain :) [1] https://lore.kernel.org/all/20250414-dwc3-refactor-v7-2-f015b358722d@oss.qualcomm.com/ Thanks, Roy Luo > > > + items: > > + - const: dwc_usb3 > > + - const: hs_pme_irq > > + - const: ss_pme_irq > > + > > + clocks: > > + minItems: 3 > > + maxItems: 3 > > + > > + clock-names: > > + minItems: 3 > > + maxItems: 3 > > From where did you get such syntax? > > > + > > + resets: > > + minItems: 5 > > + maxItems: 5 > > + > > + reset-names: > > + items: > > + - const: usbc_non_sticky > > + - const: usbc_sticky > > + - const: usb_drd_bus > > + - const: u2phy_apb > > + - const: usb_top_csr > > + > > + power-domains: > > + minItems: 2 > > + maxItems: 2 > > + > > + power-domain-names: > > + description: | > > + The following power domain must present: > > + - usb_psw_pd: The child power domain of usb_top_pd. Turning it on puts the controller > > + into full power state, turning it off puts the controller into power > > + gated state. > > + - usb_top_pd: The parent power domain of usb_psw_pd. Turning it on puts the controller > > + into power gated state, turning it off completely shuts off the > > + controller. > > Same comments. > > > > + items: > > + - const: usb_psw_pd > > + - const: usb_top_pd > > + > > + iommus: > > + maxItems: 1 > > + > Best regards, > Krzysztof
On 09/10/2025 14:12, Roy Luo wrote: > On Wed, Oct 8, 2025 at 4:56 PM Krzysztof Kozlowski <krzk@kernel.org> wrote: >> >> On 08/10/2025 14:59, Roy Luo wrote: >>> Document the device tree bindings for the DWC3 USB controller found in >>> Google Tensor SoCs, starting with the G5 generation. >>> >>> The Tensor G5 silicon represents a complete architectural departure from >> >> >> G5 does not have a model number like G1-G4? > > There's no model number for G5, I'm sticking to the existing "gs" prefix > as they're still in the same SoC family. Please let me know if you have any > concerns. > >> >>> previous generations (like gs101), including entirely new clock/reset >>> schemes, top-level wrapper and register interface. Consequently, >>> existing Samsung/Exynos DWC3 USB bindings and drivers are incompatible, >> >> Do not reference drivers. Explain the hardware. > > Ack, all mentions of "driver" will be removed in the next patch. > >> >>> necessitating this new device tree binding. >>> >>> The USB controller on Tensor G5 is based on Synopsys DWC3 IP and features >>> Dual-Role Device single port with hibernation support. >>> >>> Signed-off-by: Roy Luo <royluo@google.com> >>> --- >>> .../bindings/usb/google,gs-dwc3.yaml | 145 ++++++++++++++++++ >>> 1 file changed, 145 insertions(+) >>> create mode 100644 Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml >>> >>> diff --git a/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml >>> new file mode 100644 >>> index 000000000000..9eb0bf726e8d >>> --- /dev/null >>> +++ b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml >>> @@ -0,0 +1,145 @@ >>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) >>> +# Copyright (c) 2025, Google LLC >>> +%YAML 1.2 >>> +--- >>> +$id: http://devicetree.org/schemas/usb/google,gs-dwc3.yaml# >>> +$schema: http://devicetree.org/meta-schemas/core.yaml# >>> + >>> +title: Google Tensor Series (G5+) DWC3 USB SoC Controller >>> + >>> +maintainers: >>> + - Roy Luo <royluo@google.com> >>> + >>> +description: | >> >> >> Do not need '|' unless you need to preserve formatting. > > Ack, will fix this in the next patch. > >> >>> + Describes the DWC3 USB controller block implemented on Google Tensor SoCs, >>> + starting with the G5 generation. Based on Synopsys DWC3 IP, the controller >>> + features Dual-Role Device single port with hibernation add-on. >>> + >>> +properties: >>> + compatible: >>> + items: >>> + - enum: >>> + - google,gs5-dwc3 >>> + >>> + reg: >>> + minItems: 3 >> >> Drop >> >>> + maxItems: 3 >>> + >>> + reg-names: >>> + description: | >>> + The following memory regions must present: >>> + - dwc3_core: Core DWC3 IP registers. >>> + - host_cfg_csr: Hibernation control registers. >>> + - usbint_csr: Hibernation interrupt registers. >> >> Drop description or move it to items in reg. See other bindings. > > Ack, will use an item list in reg instead. > >> >>> + items: >>> + - const: dwc3_core >>> + - const: host_cfg_csr >>> + - const: usbint_csr >>> + >>> + interrupts: >>> + minItems: 3 >> >> Drop > > Ack, will use an item list instead. > >> >>> + maxItems: 3 >>> + >>> + interrupt-names: >>> + description: | >>> + The following interrupts must present: >>> + - dwc_usb3: Core DWC3 interrupt. >>> + - hs_pme_irq: High speed remote wakeup interrupt for hibernation. >>> + - ss_pme_irq: Super speed remote wakeup interrupt for hibernation. >> >> From where did you get this style? Don't write bindings with chat gpt or >> whatever other tool. it is a waste of our time. > > I referenced the style from a recent dt binding change [1] that adds > "Documentation/devicetree/bindings/usb/qcom,snps-dwc3.yaml". > I thought it would be a good reference because it's relatively new > and is also a binding for SNPS dwc3 glue logic. Perhaps that style > doesn't apply here because qcom,snps-dwc3.yaml supports > multiple compatible and here we have only one? > > Just to clarify, I'm a Gemini user and this patch is 100% organic, > hand-crafted by a living human brain :) > > [1] https://lore.kernel.org/all/20250414-dwc3-refactor-v7-2-f015b358722d@oss.qualcomm.com/ Your code is not at all like above, you do not have any variants here, so you cannot use that syntax - is not correct here. Best regards, Krzysztof
On Thu, Oct 9, 2025 at 12:26 AM Krzysztof Kozlowski <krzk@kernel.org> wrote: > > On 09/10/2025 14:12, Roy Luo wrote: > > On Wed, Oct 8, 2025 at 4:56 PM Krzysztof Kozlowski <krzk@kernel.org> wrote: > >> > >> On 08/10/2025 14:59, Roy Luo wrote: > >>> Document the device tree bindings for the DWC3 USB controller found in > >>> Google Tensor SoCs, starting with the G5 generation. > >>> > >>> The Tensor G5 silicon represents a complete architectural departure from > >> > >> > >> G5 does not have a model number like G1-G4? > > > > There's no model number for G5, I'm sticking to the existing "gs" prefix > > as they're still in the same SoC family. Please let me know if you have any > > concerns. > > > >> > >>> previous generations (like gs101), including entirely new clock/reset > >>> schemes, top-level wrapper and register interface. Consequently, > >>> existing Samsung/Exynos DWC3 USB bindings and drivers are incompatible, > >> > >> Do not reference drivers. Explain the hardware. > > > > Ack, all mentions of "driver" will be removed in the next patch. > > > >> > >>> necessitating this new device tree binding. > >>> > >>> The USB controller on Tensor G5 is based on Synopsys DWC3 IP and features > >>> Dual-Role Device single port with hibernation support. > >>> > >>> Signed-off-by: Roy Luo <royluo@google.com> > >>> --- > >>> .../bindings/usb/google,gs-dwc3.yaml | 145 ++++++++++++++++++ > >>> 1 file changed, 145 insertions(+) > >>> create mode 100644 Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > >>> > >>> diff --git a/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > >>> new file mode 100644 > >>> index 000000000000..9eb0bf726e8d > >>> --- /dev/null > >>> +++ b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml > >>> @@ -0,0 +1,145 @@ > >>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) > >>> +# Copyright (c) 2025, Google LLC > >>> +%YAML 1.2 > >>> +--- > >>> +$id: http://devicetree.org/schemas/usb/google,gs-dwc3.yaml# > >>> +$schema: http://devicetree.org/meta-schemas/core.yaml# > >>> + > >>> +title: Google Tensor Series (G5+) DWC3 USB SoC Controller > >>> + > >>> +maintainers: > >>> + - Roy Luo <royluo@google.com> > >>> + > >>> +description: | > >> > >> > >> Do not need '|' unless you need to preserve formatting. > > > > Ack, will fix this in the next patch. > > > >> > >>> + Describes the DWC3 USB controller block implemented on Google Tensor SoCs, > >>> + starting with the G5 generation. Based on Synopsys DWC3 IP, the controller > >>> + features Dual-Role Device single port with hibernation add-on. > >>> + > >>> +properties: > >>> + compatible: > >>> + items: > >>> + - enum: > >>> + - google,gs5-dwc3 > >>> + > >>> + reg: > >>> + minItems: 3 > >> > >> Drop > >> > >>> + maxItems: 3 > >>> + > >>> + reg-names: > >>> + description: | > >>> + The following memory regions must present: > >>> + - dwc3_core: Core DWC3 IP registers. > >>> + - host_cfg_csr: Hibernation control registers. > >>> + - usbint_csr: Hibernation interrupt registers. > >> > >> Drop description or move it to items in reg. See other bindings. > > > > Ack, will use an item list in reg instead. > > > >> > >>> + items: > >>> + - const: dwc3_core > >>> + - const: host_cfg_csr > >>> + - const: usbint_csr > >>> + > >>> + interrupts: > >>> + minItems: 3 > >> > >> Drop > > > > Ack, will use an item list instead. > > > >> > >>> + maxItems: 3 > >>> + > >>> + interrupt-names: > >>> + description: | > >>> + The following interrupts must present: > >>> + - dwc_usb3: Core DWC3 interrupt. > >>> + - hs_pme_irq: High speed remote wakeup interrupt for hibernation. > >>> + - ss_pme_irq: Super speed remote wakeup interrupt for hibernation. > >> > >> From where did you get this style? Don't write bindings with chat gpt or > >> whatever other tool. it is a waste of our time. > > > > I referenced the style from a recent dt binding change [1] that adds > > "Documentation/devicetree/bindings/usb/qcom,snps-dwc3.yaml". > > I thought it would be a good reference because it's relatively new > > and is also a binding for SNPS dwc3 glue logic. Perhaps that style > > doesn't apply here because qcom,snps-dwc3.yaml supports > > multiple compatible and here we have only one? > > > > Just to clarify, I'm a Gemini user and this patch is 100% organic, > > hand-crafted by a living human brain :) > > > > [1] https://lore.kernel.org/all/20250414-dwc3-refactor-v7-2-f015b358722d@oss.qualcomm.com/ > > Your code is not at all like above, you do not have any variants here, > so you cannot use that syntax - is not correct here. > > Best regards, > Krzysztof Thanks for the clarification. Regards, Roy Luo
On Wed, Oct 08, 2025 at 05:59:57AM +0000, Roy Luo wrote:
> Document the device tree bindings for the DWC3 USB controller found in
> Google Tensor SoCs, starting with the G5 generation.
>
> The Tensor G5 silicon represents a complete architectural departure from
> previous generations (like gs101), including entirely new clock/reset
> schemes, top-level wrapper and register interface. Consequently,
> existing Samsung/Exynos DWC3 USB bindings and drivers are incompatible,
> necessitating this new device tree binding.
>
> The USB controller on Tensor G5 is based on Synopsys DWC3 IP and features
> Dual-Role Device single port with hibernation support.
>
> Signed-off-by: Roy Luo <royluo@google.com>
> ---
> .../bindings/usb/google,gs-dwc3.yaml | 145 ++++++++++++++++++
> 1 file changed, 145 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
>
> diff --git a/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
> new file mode 100644
> index 000000000000..9eb0bf726e8d
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
filename matching the compatible please.
> @@ -0,0 +1,145 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +# Copyright (c) 2025, Google LLC
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/usb/google,gs-dwc3.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Google Tensor Series (G5+) DWC3 USB SoC Controller
> +
> +maintainers:
> + - Roy Luo <royluo@google.com>
> +
> +description: |
> + Describes the DWC3 USB controller block implemented on Google Tensor SoCs,
> + starting with the G5 generation. Based on Synopsys DWC3 IP, the controller
> + features Dual-Role Device single port with hibernation add-on.
> +
> +properties:
> + compatible:
> + items:
> + - enum:
> + - google,gs5-dwc3
items is redundant here.
> +
> + reg:
> + minItems: 3
> + maxItems: 3
> +
> + reg-names:
> + description: |
> + The following memory regions must present:
> + - dwc3_core: Core DWC3 IP registers.
> + - host_cfg_csr: Hibernation control registers.
> + - usbint_csr: Hibernation interrupt registers.
Put this into reg as an items list, and you can drop the min/max items
from there.
Same applies to interrupts and power-domains.
> + items:
> + - const: dwc3_core
> + - const: host_cfg_csr
> + - const: usbint_csr
> +
> + interrupts:
> + minItems: 3
> + maxItems: 3
> +
> + interrupt-names:
> + description: |
> + The following interrupts must present:
> + - dwc_usb3: Core DWC3 interrupt.
> + - hs_pme_irq: High speed remote wakeup interrupt for hibernation.
> + - ss_pme_irq: Super speed remote wakeup interrupt for hibernation.
> + items:
> + - const: dwc_usb3
> + - const: hs_pme_irq
> + - const: ss_pme_irq
s/_irq//
> +
> + clocks:
> + minItems: 3
> + maxItems: 3
> +
> + clock-names:
> + minItems: 3
> + maxItems: 3
> +
> + resets:
> + minItems: 5
> + maxItems: 5
For clocks and resets, please provide descriptions. For clock-names, you
provided no names and therefore cannot use the property since anything
is valid!
> +
> + reset-names:
> + items:
> + - const: usbc_non_sticky
> + - const: usbc_sticky
> + - const: usb_drd_bus
> + - const: u2phy_apb
> + - const: usb_top_csr
"csr" is an odd thing to have in a reset name, since it usually means
"control and status register". Why is it here.
> +
> + power-domains:
> + minItems: 2
> + maxItems: 2
> +
> + power-domain-names:
> + description: |
> + The following power domain must present:
> + - usb_psw_pd: The child power domain of usb_top_pd. Turning it on puts the controller
> + into full power state, turning it off puts the controller into power
> + gated state.
> + - usb_top_pd: The parent power domain of usb_psw_pd. Turning it on puts the controller
> + into power gated state, turning it off completely shuts off the
> + controller.
> + items:
> + - const: usb_psw_pd
> + - const: usb_top_pd
s/_pd// at the very least, but I would question the need to put "usb" in
any of the names given that this is a usb device.
> +
> + iommus:
> + maxItems: 1
> +
> +required:
> + - compatible
> + - reg
> + - reg-names
> + - interrupts
> + - interrupt-names
> + - clocks
> + - resets
> + - reset-names
> + - power-domains
> + - power-domain-names
> +
> +allOf:
> + - $ref: snps,dwc3-common.yaml#
> +
> +unevaluatedProperties: false
So every property from snps,dwc3-common.yaml is valid here, with any of
the permitted values?
> +
> +examples:
> + - |
> + #include <dt-bindings/interrupt-controller/arm-gic.h>
> + #include <dt-bindings/interrupt-controller/irq.h>
> + soc {
> + #address-cells = <2>;
> + #size-cells = <2>;
> +
> + usb@c400000 {
> + compatible = "google,gs5-dwc3";
> + reg = <0 0x0c400000 0 0xd060>, <0 0x0c450000 0 0x14>, <0 0x0c450020 0 0x8>;
> + reg-names = "dwc3_core", "host_cfg_csr", "usbint_csr";
> + interrupts = <GIC_SPI 580 IRQ_TYPE_LEVEL_HIGH 0>,
> + <GIC_SPI 597 IRQ_TYPE_LEVEL_HIGH 0>,
> + <GIC_SPI 598 IRQ_TYPE_LEVEL_HIGH 0>;
> + interrupt-names = "dwc_usb3", "hs_pme_irq", "ss_pme_irq";
> + clocks = <&hsion_usbc_non_sticky_clk>, <&hsion_usbc_sticky_clk>,
> + <&hsion_u2phy_apb_clk>;
> + clock-names = "usbc_non_sticky", "usbc_sticky", "u2phy_apb";
> + resets = <&hsion_resets_usbc_non_sticky>, <&hsion_resets_usbc_sticky>,
> + <&hsion_resets_usb_drd_bus>, <&hsion_resets_u2phy_apb>,
> + <&hsion_resets_usb_top_csr>;
> + reset-names = "usbc_non_sticky", "usbc_sticky",
> + "usb_drd_bus", "u2phy_apb",
> + "usb_top_csr";
> + power-domains = <&hsio_n_usb_psw_pd>, <&hsio_n_usb_pd>;
> + power-domain-names = "usb_psw_pd", "usb_top_pd";
> + phys = <&usb_phy 0>;
> + phy-names = "usb2-phy";
> + snps,quirk-frame-length-adjustment = <0x20>;
> + snps,gfladj-refclk-lpm-sel-quirk;
> + snps,incr-burst-type-adjustment = <4>;
> + };
> + };
> +...
pw-bot: cr
On Wed, Oct 8, 2025 at 1:58 PM Conor Dooley <conor@kernel.org> wrote:
>
> On Wed, Oct 08, 2025 at 05:59:57AM +0000, Roy Luo wrote:
> > Document the device tree bindings for the DWC3 USB controller found in
> > Google Tensor SoCs, starting with the G5 generation.
> >
> > The Tensor G5 silicon represents a complete architectural departure from
> > previous generations (like gs101), including entirely new clock/reset
> > schemes, top-level wrapper and register interface. Consequently,
> > existing Samsung/Exynos DWC3 USB bindings and drivers are incompatible,
> > necessitating this new device tree binding.
> >
> > The USB controller on Tensor G5 is based on Synopsys DWC3 IP and features
> > Dual-Role Device single port with hibernation support.
> >
> > Signed-off-by: Roy Luo <royluo@google.com>
> > ---
> > .../bindings/usb/google,gs-dwc3.yaml | 145 ++++++++++++++++++
> > 1 file changed, 145 insertions(+)
> > create mode 100644 Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
> > new file mode 100644
> > index 000000000000..9eb0bf726e8d
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/usb/google,gs-dwc3.yaml
>
> filename matching the compatible please.
>
> > @@ -0,0 +1,145 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +# Copyright (c) 2025, Google LLC
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/usb/google,gs-dwc3.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Google Tensor Series (G5+) DWC3 USB SoC Controller
> > +
> > +maintainers:
> > + - Roy Luo <royluo@google.com>
> > +
> > +description: |
> > + Describes the DWC3 USB controller block implemented on Google Tensor SoCs,
> > + starting with the G5 generation. Based on Synopsys DWC3 IP, the controller
> > + features Dual-Role Device single port with hibernation add-on.
> > +
> > +properties:
> > + compatible:
> > + items:
> > + - enum:
> > + - google,gs5-dwc3
>
> items is redundant here.
>
> > +
> > + reg:
> > + minItems: 3
> > + maxItems: 3
> > +
> > + reg-names:
> > + description: |
> > + The following memory regions must present:
> > + - dwc3_core: Core DWC3 IP registers.
> > + - host_cfg_csr: Hibernation control registers.
> > + - usbint_csr: Hibernation interrupt registers.
>
> Put this into reg as an items list, and you can drop the min/max items
> from there.
> Same applies to interrupts and power-domains.
>
> > + items:
> > + - const: dwc3_core
> > + - const: host_cfg_csr
> > + - const: usbint_csr
> > +
> > + interrupts:
> > + minItems: 3
> > + maxItems: 3
> > +
> > + interrupt-names:
> > + description: |
> > + The following interrupts must present:
> > + - dwc_usb3: Core DWC3 interrupt.
> > + - hs_pme_irq: High speed remote wakeup interrupt for hibernation.
> > + - ss_pme_irq: Super speed remote wakeup interrupt for hibernation.
> > + items:
> > + - const: dwc_usb3
> > + - const: hs_pme_irq
> > + - const: ss_pme_irq
>
> s/_irq//
>
> > +
> > + clocks:
> > + minItems: 3
> > + maxItems: 3
> > +
> > + clock-names:
> > + minItems: 3
> > + maxItems: 3
> > +
> > + resets:
> > + minItems: 5
> > + maxItems: 5
>
> For clocks and resets, please provide descriptions. For clock-names, you
> provided no names and therefore cannot use the property since anything
> is valid!
>
> > +
> > + reset-names:
> > + items:
> > + - const: usbc_non_sticky
> > + - const: usbc_sticky
> > + - const: usb_drd_bus
> > + - const: u2phy_apb
> > + - const: usb_top_csr
>
> "csr" is an odd thing to have in a reset name, since it usually means
> "control and status register". Why is it here.
>
> > +
> > + power-domains:
> > + minItems: 2
> > + maxItems: 2
> > +
> > + power-domain-names:
> > + description: |
> > + The following power domain must present:
> > + - usb_psw_pd: The child power domain of usb_top_pd. Turning it on puts the controller
> > + into full power state, turning it off puts the controller into power
> > + gated state.
> > + - usb_top_pd: The parent power domain of usb_psw_pd. Turning it on puts the controller
> > + into power gated state, turning it off completely shuts off the
> > + controller.
> > + items:
> > + - const: usb_psw_pd
> > + - const: usb_top_pd
>
> s/_pd// at the very least, but I would question the need to put "usb" in
> any of the names given that this is a usb device.
>
> > +
> > + iommus:
> > + maxItems: 1
> > +
> > +required:
> > + - compatible
> > + - reg
> > + - reg-names
> > + - interrupts
> > + - interrupt-names
> > + - clocks
> > + - resets
> > + - reset-names
> > + - power-domains
> > + - power-domain-names
> > +
> > +allOf:
> > + - $ref: snps,dwc3-common.yaml#
> > +
> > +unevaluatedProperties: false
>
> So every property from snps,dwc3-common.yaml is valid here, with any of
> the permitted values?
Conor,
Appreciate the review.
Ack to all the comments, will fix them in the next patch.
And yes, every property from snps,dwc3-common.yaml is valid here.
You can find more context here [1], essentially the dwc3 glue would be
operating on the same platform device as the dwc3 core, hence all
properties are allowed.
[1] https://lore.kernel.org/all/20250414-dwc3-refactor-v7-0-f015b358722d@oss.qualcomm.com/
Thanks,
Roy Luo
> > +
> > +examples:
> > + - |
> > + #include <dt-bindings/interrupt-controller/arm-gic.h>
> > + #include <dt-bindings/interrupt-controller/irq.h>
> > + soc {
> > + #address-cells = <2>;
> > + #size-cells = <2>;
> > +
> > + usb@c400000 {
> > + compatible = "google,gs5-dwc3";
> > + reg = <0 0x0c400000 0 0xd060>, <0 0x0c450000 0 0x14>, <0 0x0c450020 0 0x8>;
> > + reg-names = "dwc3_core", "host_cfg_csr", "usbint_csr";
> > + interrupts = <GIC_SPI 580 IRQ_TYPE_LEVEL_HIGH 0>,
> > + <GIC_SPI 597 IRQ_TYPE_LEVEL_HIGH 0>,
> > + <GIC_SPI 598 IRQ_TYPE_LEVEL_HIGH 0>;
> > + interrupt-names = "dwc_usb3", "hs_pme_irq", "ss_pme_irq";
> > + clocks = <&hsion_usbc_non_sticky_clk>, <&hsion_usbc_sticky_clk>,
> > + <&hsion_u2phy_apb_clk>;
> > + clock-names = "usbc_non_sticky", "usbc_sticky", "u2phy_apb";
> > + resets = <&hsion_resets_usbc_non_sticky>, <&hsion_resets_usbc_sticky>,
> > + <&hsion_resets_usb_drd_bus>, <&hsion_resets_u2phy_apb>,
> > + <&hsion_resets_usb_top_csr>;
> > + reset-names = "usbc_non_sticky", "usbc_sticky",
> > + "usb_drd_bus", "u2phy_apb",
> > + "usb_top_csr";
> > + power-domains = <&hsio_n_usb_psw_pd>, <&hsio_n_usb_pd>;
> > + power-domain-names = "usb_psw_pd", "usb_top_pd";
> > + phys = <&usb_phy 0>;
> > + phy-names = "usb2-phy";
> > + snps,quirk-frame-length-adjustment = <0x20>;
> > + snps,gfladj-refclk-lpm-sel-quirk;
> > + snps,incr-burst-type-adjustment = <4>;
> > + };
> > + };
> > +...
>
> pw-bot: cr
On Wed, Oct 08, 2025 at 09:40:57PM -0700, Roy Luo wrote: > On Wed, Oct 8, 2025 at 1:58 PM Conor Dooley <conor@kernel.org> wrote: > > > > On Wed, Oct 08, 2025 at 05:59:57AM +0000, Roy Luo wrote: > > > +allOf: > > > + - $ref: snps,dwc3-common.yaml# > > > + > > > +unevaluatedProperties: false > > > > So every property from snps,dwc3-common.yaml is valid here, with any of > > the permitted values? > > Conor, > > Appreciate the review. > Ack to all the comments, will fix them in the next patch. > And yes, every property from snps,dwc3-common.yaml is valid here. > You can find more context here [1], essentially the dwc3 glue would be > operating on the same platform device as the dwc3 core, hence all > properties are allowed. > > [1] https://lore.kernel.org/all/20250414-dwc3-refactor-v7-0-f015b358722d@oss.qualcomm.com/ I find it exceedingly hard to believe that every property from that file, with every permitted value, is possible. AFAIU, the tensor g5 is a phone chip that's only used in pixel devices, not something that people can just buy and integrate into whatever device they feel like. There should be a vanishingly small number of possible configurations, possibly exactly one configuration. There are dozens of properties in the dwc3 common binding, of which at least 10 are for "quirks" or other sorts of hardware errata that are not going to be variable from one phone to another.
On Thu, Oct 9, 2025 at 10:13 AM Conor Dooley <conor@kernel.org> wrote:
>
> On Wed, Oct 08, 2025 at 09:40:57PM -0700, Roy Luo wrote:
> > On Wed, Oct 8, 2025 at 1:58 PM Conor Dooley <conor@kernel.org> wrote:
> > >
> > > On Wed, Oct 08, 2025 at 05:59:57AM +0000, Roy Luo wrote:
>
> > > > +allOf:
> > > > + - $ref: snps,dwc3-common.yaml#
> > > > +
> > > > +unevaluatedProperties: false
> > >
> > > So every property from snps,dwc3-common.yaml is valid here, with any of
> > > the permitted values?
> >
> > Conor,
> >
> > Appreciate the review.
> > Ack to all the comments, will fix them in the next patch.
> > And yes, every property from snps,dwc3-common.yaml is valid here.
> > You can find more context here [1], essentially the dwc3 glue would be
> > operating on the same platform device as the dwc3 core, hence all
> > properties are allowed.
> >
> > [1] https://lore.kernel.org/all/20250414-dwc3-refactor-v7-0-f015b358722d@oss.qualcomm.com/
>
> I find it exceedingly hard to believe that every property from that
> file, with every permitted value, is possible. AFAIU, the tensor g5 is a
> phone chip that's only used in pixel devices, not something that people
> can just buy and integrate into whatever device they feel like. There
> should be a vanishingly small number of possible configurations,
> possibly exactly one configuration. There are dozens of properties in
> the dwc3 common binding, of which at least 10 are for "quirks" or other
> sorts of hardware errata that are not going to be variable from one
> phone to another.
To my knowledge, the properties in snps,dwc3-common.yaml can generally
be categorized into two types:
- Function knobs: These properties translate directly to register writes that
modify the controller's fundamental behavior. Most quirks fall into this
category. For example, "snps,gfladj-refclk-lpm-sel-quirk" enables SOF counter.
- Tunable Values: These properties also map to register writes to influence
hardware behavior, but they typically adjust performance or interoperability
rather than essential function. While the hardware usually works fine with
default settings, these values allow for optimization. For example,
"tx-fifo-max-num" usually affects data throughput.
For DWC3 hardware errata and workarounds, my understanding is that they
are typically handled within the dwc3 driver, often involving a DWC3 revision
check (e.g. [1]), instead of in the device tree binding. While you may find
properties related to errata, they generally serve to enable or disable an
existing workaround (e.g. [2]).
For Pixel devices, it's shipped with a preferred configuration, but the hardware
is fundamentally capable of supporting other configurations since the properties
are backed by the SNPS DWC3 IP. Whether that's optimal is a different story.
I haven't tried toggling every single property but I'm not aware of any property
that obviously does not work on Tensor G5.
I hope this addresses your concern.
[1] https://github.com/torvalds/linux/commit/32a4a135847b1e600c64756b7c7c7a91eb2f0aa9
(sorry I'm unable to find the kernel lore link for this commit)
[2] https://lore.kernel.org/all/1509455515-5992-1-git-send-email-rogerq@ti.com/
Regards,
Roy Luo
© 2016 - 2026 Red Hat, Inc.