Re: [PATCH RFC] dt-bindings: thunderbolt: Add Qualcomm USB4 Host Router

Hi Konrad,

On Tue, Sep 16, 2025 at 10:06:01PM +0200, Konrad Dybcio wrote:

From: Konrad Dybcio <redacted>

Several Qualcomm platforms feature an in-house Host Router IP block,
which enables USB4 and Thunderbolt 3 functionality. It implements the
common NHI interface, allowing for easier integration with existing
Thunderbolt driver implementations.

The Host Router features a microcontroller (with loadable firmware),
which takes care of detecting and acting upon plug events, initiating
high-speed link establishment or performing HW power management
operations.

Each instance is connected to a single USB3.x host, a PCIe RC and a
DisplayPort controller through a fitting Protocol Adapter, allowing
for the tunneling of the respective protocols between the USB4/TBT3
device and the on-SoC controller.

Describe the block, as present on the X1E family of SoCs, where it
implements the USB4v1 standard.

This is nice!

Signed-off-by: Konrad Dybcio <redacted>
---
Hello!

This is our stab at USB4/Thunderbolt dt-bindings.

This submission, as stated in the commit message, describes our USB4
Host Router block, which is roughly the same class of hardware that you
can find on add-in PCIe cards aimed at x86 machines.

This specific patch is NOT supposed to be merged, since the bindings
may still ever so slightly change, as we continue work on the driver
(i.e. it's still possible that we omitted some resource).

It is however published early to create grounds for a discussion.
This is the first bring-up of USB4/TBT3 on a DT platform, so this
binding is likely going to influence all subsequent submissions. I've
added various DT and TBT folks to the recipient list to make everyone
aware of any decisions we settle on.

Comments very welcome!

P.S.
The driver part (which has quite some dependencies) is not yet 100%
ready to share and will be published at a later date.

Okay, I think it is beter to submit the bindings with the driver changes so
that we can see the big picture.

Are these the specific to the host controller? I mean route_config sounds
pretty much like Router Config space and that is available through the USB4
fabric so not sure why this is listed?

Also this does not list the standard Host Interface registers, is that on
purpose?

+
+  interrupts:
+    items:
+      - description: Combined event interrupt for all three rings
+      - description: OOB Firmware interrupt

No MSI? If not then at least I suggest to support it in the DT description.

+
+  interrupt-names:
+    items:
+      - const: ring
+      - const: fw
+
+  clocks:
+    maxItems: 10
+
+  clock-names:
+    items:
+      - const: sys
+      - const: tmu
+      - const: ahb
+      - const: axi
+      - const: master
+      - const: phy_rx0
+      - const: phy_rx1
+      - const: sb
+      - const: dp0
+      - const: dp1
+
+  resets:
+    maxItems: 13
+
+  reset-names:
+    items:
+      - const: core
+      - const: phy_nocsr
+      - const: sys
+      - const: rx0
+      - const: rx1
+      - const: usb_pipe
+      - const: pcie_pipe
+      - const: tmu
+      - const: sideband_iface
+      - const: hia_master
+      - const: ahb
+      - const: dp0
+      - const: dp1
+
+  power-domains:
+    maxItems: 1
+
+  required-opps:
+    maxItems: 1
+
+  phys:
+    maxItems: 1
+
+  phy-names:
+    const: usb4
+
+  iommus:
+    maxItems: 1
+
+  interconnects:
+    maxItems: 2
+
+  interconnect-names:
+    items:
+      - const: usb4-ddr
+      - const: apps-usb4
+
+  mode-switch: true
+
+  wakeup-source: true

What about the "power contract"? Are you using the existing we have for
ACPI:

https://learn.microsoft.com/en-us/windows-hardware/drivers/pci/dsd-for-pcie-root-ports#map-native-protocols-pcie-displayport-tunneled-through-usb4-to-usb4-host-routers

It was designed DT in mind but I don't think we have DT bindings for it.
This is needed to make sure the driver (Connection Manager) creates the
tunnels before the native protocol stacks get enumerated (e.g during power
transitions).

+
+allOf:
+  - $ref: /schemas/usb/usb-switch.yaml#
+
+required:
+  - compatible
+  - reg
+  - reg-names
+  - interrupts
+  - interrupt-names
+  - clocks
+  - clock-names
+  - resets
+  - reset-names
+  - power-domains
+  - phys
+  - phy-names
+  - iommus
+  - interconnects
+  - interconnect-names
+  - mode-switch
+  - port
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/qcom,x1e80100-gcc.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    soc {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        usb4_router0: usb4-host-router@15600000 {
+            compatible = "qcom,x1e80100-usb4-hr",
+                         "qcom,usb4-hr";
+            reg = <0x0 0x15600000 0x0 0x8000>,
+                  <0x0 0x15608000 0x0 0x70>,
+                  <0x0 0x15608070 0x0 0x500>,
+                  <0x0 0x1560d000 0x0 0x1000>,
+                  <0x0 0x15612000 0x0 0x1000>,
+                  <0x0 0x15613000 0x0 0xe000>,
+                  <0x0 0x15621000 0x0 0x2000>,
+                  <0x0 0x15623000 0x0 0x2000>,
+                  <0x0 0x1563f000 0x0 0x40000>,
+                  <0x0 0x1567f000 0x0 0x1000>,
+                  <0x0 0x15680000 0x0 0x1000>,
+                  <0x0 0x15681000 0x0 0x1000>,
+                  <0x0 0x15682000 0x0 0x1000>,
+                  <0x0 0x15683000 0x0 0x1000>,
+                  <0x0 0x15685000 0x0 0x1000>,
+                  <0x0 0x15686000 0x0 0x1000>,
+                  <0x0 0x15688000 0x0 0x1000>;
+            reg-names = "router",
+                        "router_config",
+                        "tmu_config",
+                        "port_group",
+                        "sideband",
+                        "uc_ram",
+                        "uc_per",
+                        "uc_mbox",
+                        "nhi",
+                        "cfg",
+                        "debug",
+                        "usbap_config",
+                        "pcieap_config",
+                        "dpap0_aux",
+                        "dpap0_config",
+                        "dpap1_aux",
+                        "dpap1_config";
+
+            interrupts = <GIC_SPI 472 IRQ_TYPE_LEVEL_HIGH>,
+                         <GIC_SPI 579 IRQ_TYPE_LEVEL_HIGH>;
+            interrupt-names = "ring",
+                              "fw";
+
+            clocks = <&gcc_usb4_0_sys_clk>,
+                     <&gcc_usb4_0_tmu_clk>,
+                     <&gcc_usb4_0_cfg_ahb_clk>,
+                     <&gcc_aggre_usb4_0_axi_clk>,
+                     <&gcc_usb4_0_master_clk>,
+                     <&gcc_usb4_0_phy_rx0_clk>,
+                     <&gcc_usb4_0_phy_rx1_clk>,
+                     <&gcc_usb4_0_sb_if_clk>,
+                     <&gcc_usb4_0_dp0_clk>,
+                     <&gcc_usb4_0_dp1_clk>;
+            clock-names = "sys",
+                          "tmu",
+                          "ahb",
+                          "axi",
+                          "master",
+                          "phy_rx0",
+                          "phy_rx1",
+                          "sb",
+                          "dp0",
+                          "dp1";
+
+            resets = <&gcc_usb4_0_bcr>,
+                     <&gcc_usb4phy_phy_prim_bcr>,
+                     <&gcc_usb4_0_misc_usb4_sys_bcr>,
+                     <&gcc_usb4_0_misc_rx_clk_0_bcr>,
+                     <&gcc_usb4_0_misc_rx_clk_1_bcr>,
+                     <&gcc_usb4_0_misc_usb_pipe_bcr>,
+                     <&gcc_usb4_0_misc_pcie_pipe_bcr>,
+                     <&gcc_usb4_0_misc_tmu_bcr>,
+                     <&gcc_usb4_0_misc_sb_if_bcr>,
+                     <&gcc_usb4_0_misc_hia_mstr_bcr>,
+                     <&gcc_usb4_0_misc_ahb_bcr>,
+                     <&gcc_usb4_0_misc_dp0_max_pclk_bcr>,
+                     <&gcc_usb4_0_misc_dp1_max_pclk_bcr>;
+            reset-names = "core",
+                          "phy_nocsr",
+                          "sys",
+                          "rx0",
+                          "rx1",
+                          "usb_pipe",
+                          "pcie_pipe",
+                          "tmu",
+                          "sideband_iface",
+                          "hia_master",
+                          "ahb",
+                          "dp0",
+                          "dp1";
+
+            power-domains = <&gcc GCC_USB4_0_GDSC>;
+
+            phys = <&usb4_phy>;
+            phy-names = "usb4";
+
+            iommus = <&apps_smmu 0x1440 0x0>;
+
+            interconnects = <&icc0 &icc1>,
+                            <&icc2 &icc3>;
+            interconnect-names = "usb4-ddr",
+                                 "apps-usb4";
+
+            mode-switch;
+
+            port {
+                usb4_0_mode_in: endpoint {
+                };

This describes the Downstream Facing Port (e.g USB4 port), right? We have
something similar used in Chromebooks so it would be good if we can make
the bindings close to each other if possible. This allows binding firmware
description to retimers (and also to "fixed/embedded" device routers as
recent changes to the USB4 spec makes possible).

See drivers/thunderbolt/acpi.c::tb_acpi_find_companion().