[PATCH v2 0/4] thunderbolt: Notify userspace about tunneling events in the domain

[PATCH v2 0/4] thunderbolt: Notify userspace about tunneling events in the domain

[Mika Westerberg]

Hi all,

This series adds support to sending uevents to userspace about changes in
tunneling such as creation, removal and bandwidth related.  One intented
use-case for this is an upcoming USB-C daemon developed by Saranya that
then notifies user for example if there is not enough bandwidth for
DisplayPort requirements. We also added debug tools [1] support for these
(currently it just updates various screens on event but we are working on
add event log there too).

The Firmware Connection manager side is kind of limited though since there
are not that many notifications we get.

[1] https://github.com/intel/tbtools

Previous version can be found:

  https://lore.kernel.org/linux-usb/20250410125600.3074417-1-mika.westerberg@linux.intel.com/

Changes from the previous version:

  * Add missing SoB.
  * Add documentation to admin-guide/thunderbolt.rst.

Alan Borzeszkowski (4):
  thunderbolt: Introduce domain event message handler
  thunderbolt: Notify userspace about software CM tunneling events
  thunderbolt: Notify userspace about firmware CM tunneling events
  Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

 Documentation/admin-guide/thunderbolt.rst | 33 ++++++++
 drivers/thunderbolt/domain.c              |  2 +-
 drivers/thunderbolt/icm.c                 | 36 ++++++++-
 drivers/thunderbolt/tb.c                  | 22 +++++-
 drivers/thunderbolt/tb.h                  | 13 ++++
 drivers/thunderbolt/tb_msgs.h             |  1 +
 drivers/thunderbolt/tunnel.c              | 92 +++++++++++++++++++++--
 drivers/thunderbolt/tunnel.h              | 23 ++++++
 8 files changed, 212 insertions(+), 10 deletions(-)

-- 
2.47.2

[PATCH v2 1/4] thunderbolt: Introduce domain event message handler

[Mika Westerberg]

From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>

This patch introduces a function that can be used to send uevent
notifications in the domain to userspace. For instance, it can indicate
that a DisplayPort tunnel could not be established due to insufficient
bandwidth. Userspace can then forward to user via dialog or similar.

Convert boot_acl_store() to call this instead of open-coding.

Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/domain.c |  2 +-
 drivers/thunderbolt/tb.h     | 13 +++++++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/drivers/thunderbolt/domain.c b/drivers/thunderbolt/domain.c
index 144d0232a70c..a3a7c8059eee 100644
--- a/drivers/thunderbolt/domain.c
+++ b/drivers/thunderbolt/domain.c
@@ -217,7 +217,7 @@ static ssize_t boot_acl_store(struct device *dev, struct device_attribute *attr,
 	ret = tb->cm_ops->set_boot_acl(tb, acl, tb->nboot_acl);
 	if (!ret) {
 		/* Notify userspace about the change */
-		kobject_uevent(&tb->dev.kobj, KOBJ_CHANGE);
+		tb_domain_event(tb, NULL);
 	}
 	mutex_unlock(&tb->lock);
 
diff --git a/drivers/thunderbolt/tb.h b/drivers/thunderbolt/tb.h
index b54147a1ba87..5869b379e4f7 100644
--- a/drivers/thunderbolt/tb.h
+++ b/drivers/thunderbolt/tb.h
@@ -804,6 +804,19 @@ static inline void tb_domain_put(struct tb *tb)
 	put_device(&tb->dev);
 }
 
+/**
+ * tb_domain_event() - Notify userspace about an event in domain
+ * @tb: Domain where event occurred
+ * @envp: Array of uevent environment strings (can be %NULL)
+ *
+ * This function provides a way to notify userspace about any events
+ * that take place in the domain.
+ */
+static inline void tb_domain_event(struct tb *tb, char *envp[])
+{
+	kobject_uevent_env(&tb->dev.kobj, KOBJ_CHANGE, envp);
+}
+
 struct tb_nvm *tb_nvm_alloc(struct device *dev);
 int tb_nvm_read_version(struct tb_nvm *nvm);
 int tb_nvm_validate(struct tb_nvm *nvm);
-- 
2.47.2

[PATCH v2 2/4] thunderbolt: Notify userspace about software CM tunneling events

[Mika Westerberg]

From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>

This adds notification whenever software connection manager activates,
changes or deactivates a tunnel, and also if there is limitation in
bandwidth.

The notification looks like below:

  TUNNEL_EVENT=activated|changed|deactivated|low bandwidth|
  	       insufficient bandwidth
  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)

Userspace can then listen these and inform user if needed. For example
if there is not enough bandwidth, it can show warning dialog to the user.

Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/tb.c     | 22 +++++++--
 drivers/thunderbolt/tunnel.c | 92 ++++++++++++++++++++++++++++++++++--
 drivers/thunderbolt/tunnel.h | 23 +++++++++
 3 files changed, 129 insertions(+), 8 deletions(-)

diff --git a/drivers/thunderbolt/tb.c b/drivers/thunderbolt/tb.c
index 8c527af98927..c14ab1fbeeaf 100644
--- a/drivers/thunderbolt/tb.c
+++ b/drivers/thunderbolt/tb.c
@@ -952,6 +952,15 @@ static int tb_tunnel_usb3(struct tb *tb, struct tb_switch *sw)
 	tb_port_dbg(up, "available bandwidth for new USB3 tunnel %d/%d Mb/s\n",
 		    available_up, available_down);
 
+	/*
+	 * If the available bandwidth is less than 1.5 Gb/s notify
+	 * userspace that the connected isochronous device may not work
+	 * properly.
+	 */
+	if (available_up < 1500 || available_down < 1500)
+		tb_tunnel_event(tb, TB_TUNNEL_LOW_BANDWIDTH, TB_TUNNEL_USB3,
+				down, up);
+
 	tunnel = tb_tunnel_alloc_usb3(tb, up, down, available_up,
 				      available_down);
 	if (!tunnel) {
@@ -2000,8 +2009,10 @@ static void tb_tunnel_one_dp(struct tb *tb, struct tb_port *in,
 
 	ret = tb_available_bandwidth(tb, in, out, &available_up, &available_down,
 				     true);
-	if (ret)
+	if (ret) {
+		tb_tunnel_event(tb, TB_TUNNEL_NO_BANDWIDTH, TB_TUNNEL_DP, in, out);
 		goto err_reclaim_usb;
+	}
 
 	tb_dbg(tb, "available bandwidth for new DP tunnel %u/%u Mb/s\n",
 	       available_up, available_down);
@@ -2622,8 +2633,12 @@ static int tb_alloc_dp_bandwidth(struct tb_tunnel *tunnel, int *requested_up,
 			}
 		}
 
-		return tb_tunnel_alloc_bandwidth(tunnel, requested_up,
-						 requested_down);
+		ret = tb_tunnel_alloc_bandwidth(tunnel, requested_up,
+						requested_down);
+		if (ret)
+			goto fail;
+
+		return 0;
 	}
 
 	/*
@@ -2699,6 +2714,7 @@ static int tb_alloc_dp_bandwidth(struct tb_tunnel *tunnel, int *requested_up,
 			      "failing the request by rewriting allocated %d/%d Mb/s\n",
 			      allocated_up, allocated_down);
 		tb_tunnel_alloc_bandwidth(tunnel, &allocated_up, &allocated_down);
+		tb_tunnel_event(tb, TB_TUNNEL_NO_BANDWIDTH, TB_TUNNEL_DP, in, out);
 	}
 
 	return ret;
diff --git a/drivers/thunderbolt/tunnel.c b/drivers/thunderbolt/tunnel.c
index 76254ed3f47f..d52efe3f658c 100644
--- a/drivers/thunderbolt/tunnel.c
+++ b/drivers/thunderbolt/tunnel.c
@@ -100,6 +100,14 @@ MODULE_PARM_DESC(bw_alloc_mode,
 
 static const char * const tb_tunnel_names[] = { "PCI", "DP", "DMA", "USB3" };
 
+static const char * const tb_event_names[] = {
+	[TB_TUNNEL_ACTIVATED] = "activated",
+	[TB_TUNNEL_CHANGED] = "changed",
+	[TB_TUNNEL_DEACTIVATED] = "deactivated",
+	[TB_TUNNEL_LOW_BANDWIDTH] = "low bandwidth",
+	[TB_TUNNEL_NO_BANDWIDTH] = "insufficient bandwidth",
+};
+
 /* Synchronizes kref_get()/put() of struct tb_tunnel */
 static DEFINE_MUTEX(tb_tunnel_lock);
 
@@ -220,6 +228,72 @@ void tb_tunnel_put(struct tb_tunnel *tunnel)
 	mutex_unlock(&tb_tunnel_lock);
 }
 
+/**
+ * tb_tunnel_event() - Notify userspace about tunneling event
+ * @tb: Domain where the event occurred
+ * @event: Event that happened
+ * @type: Type of the tunnel in question
+ * @src_port: Tunnel source port (can be %NULL)
+ * @dst_port: Tunnel destination port (can be %NULL)
+ *
+ * Notifies userspace about tunneling @event in the domain. The tunnel
+ * does not need to exist (e.g the tunnel was not activated because
+ * there is not enough bandwidth). If the @src_port and @dst_port are
+ * given fill in full %TUNNEL_DETAILS environment variable. Otherwise
+ * uses the shorter one (just the tunnel type).
+ */
+void tb_tunnel_event(struct tb *tb, enum tb_tunnel_event event,
+		     enum tb_tunnel_type type,
+		     const struct tb_port *src_port,
+		     const struct tb_port *dst_port)
+{
+	char *envp[3] = { NULL };
+
+	if (WARN_ON_ONCE(event >= ARRAY_SIZE(tb_event_names)))
+		return;
+	if (WARN_ON_ONCE(type >= ARRAY_SIZE(tb_tunnel_names)))
+		return;
+
+	envp[0] = kasprintf(GFP_KERNEL, "TUNNEL_EVENT=%s", tb_event_names[event]);
+	if (!envp[0])
+		return;
+
+	if (src_port != NULL && dst_port != NULL) {
+		envp[1] = kasprintf(GFP_KERNEL, "TUNNEL_DETAILS=%llx:%u <-> %llx:%u (%s)",
+				    tb_route(src_port->sw), src_port->port,
+				    tb_route(dst_port->sw), dst_port->port,
+				    tb_tunnel_names[type]);
+	} else {
+		envp[1] = kasprintf(GFP_KERNEL, "TUNNEL_DETAILS=(%s)",
+				    tb_tunnel_names[type]);
+	}
+
+	if (envp[1])
+		tb_domain_event(tb, envp);
+
+	kfree(envp[1]);
+	kfree(envp[0]);
+}
+
+static inline void tb_tunnel_set_active(struct tb_tunnel *tunnel, bool active)
+{
+	if (active) {
+		tunnel->state = TB_TUNNEL_ACTIVE;
+		tb_tunnel_event(tunnel->tb, TB_TUNNEL_ACTIVATED, tunnel->type,
+				tunnel->src_port, tunnel->dst_port);
+	} else {
+		tunnel->state = TB_TUNNEL_INACTIVE;
+		tb_tunnel_event(tunnel->tb, TB_TUNNEL_DEACTIVATED, tunnel->type,
+				tunnel->src_port, tunnel->dst_port);
+	}
+}
+
+static inline void tb_tunnel_changed(struct tb_tunnel *tunnel)
+{
+	tb_tunnel_event(tunnel->tb, TB_TUNNEL_CHANGED, tunnel->type,
+			tunnel->src_port, tunnel->dst_port);
+}
+
 static int tb_pci_set_ext_encapsulation(struct tb_tunnel *tunnel, bool enable)
 {
 	struct tb_port *port = tb_upstream_port(tunnel->dst_port->sw);
@@ -992,7 +1066,7 @@ static void tb_dp_dprx_work(struct work_struct *work)
 				return;
 			}
 		} else {
-			tunnel->state = TB_TUNNEL_ACTIVE;
+			tb_tunnel_set_active(tunnel, true);
 		}
 		mutex_unlock(&tb->lock);
 	}
@@ -2326,7 +2400,7 @@ int tb_tunnel_activate(struct tb_tunnel *tunnel)
 		}
 	}
 
-	tunnel->state = TB_TUNNEL_ACTIVE;
+	tb_tunnel_set_active(tunnel, true);
 	return 0;
 
 err:
@@ -2356,7 +2430,7 @@ void tb_tunnel_deactivate(struct tb_tunnel *tunnel)
 	if (tunnel->post_deactivate)
 		tunnel->post_deactivate(tunnel);
 
-	tunnel->state = TB_TUNNEL_INACTIVE;
+	tb_tunnel_set_active(tunnel, false);
 }
 
 /**
@@ -2449,8 +2523,16 @@ int tb_tunnel_alloc_bandwidth(struct tb_tunnel *tunnel, int *alloc_up,
 	if (!tb_tunnel_is_active(tunnel))
 		return -ENOTCONN;
 
-	if (tunnel->alloc_bandwidth)
-		return tunnel->alloc_bandwidth(tunnel, alloc_up, alloc_down);
+	if (tunnel->alloc_bandwidth) {
+		int ret;
+
+		ret = tunnel->alloc_bandwidth(tunnel, alloc_up, alloc_down);
+		if (ret)
+			return ret;
+
+		tb_tunnel_changed(tunnel);
+		return 0;
+	}
 
 	return -EOPNOTSUPP;
 }
diff --git a/drivers/thunderbolt/tunnel.h b/drivers/thunderbolt/tunnel.h
index 8a0a0cb21a89..5e9fb73d5220 100644
--- a/drivers/thunderbolt/tunnel.h
+++ b/drivers/thunderbolt/tunnel.h
@@ -194,6 +194,29 @@ static inline bool tb_tunnel_direction_downstream(const struct tb_tunnel *tunnel
 						 tunnel->dst_port);
 }
 
+/**
+ * enum tb_tunnel_event - Tunnel related events
+ * @TB_TUNNEL_ACTIVATED: A tunnel was activated
+ * @TB_TUNNEL_CHANGED: There is a tunneling change in the domain. Includes
+ *		       full %TUNNEL_DETAILS if the tunnel in question is known
+ *		       (ICM does not provide that information).
+ * @TB_TUNNEL_DEACTIVATED: A tunnel was torn down
+ * @TB_TUNNEL_LOW_BANDWIDTH: Tunnel bandwidth is not optimal
+ * @TB_TUNNEL_NO_BANDWIDTH: There is not enough bandwidth for a tunnel
+ */
+enum tb_tunnel_event {
+	TB_TUNNEL_ACTIVATED,
+	TB_TUNNEL_CHANGED,
+	TB_TUNNEL_DEACTIVATED,
+	TB_TUNNEL_LOW_BANDWIDTH,
+	TB_TUNNEL_NO_BANDWIDTH,
+};
+
+void tb_tunnel_event(struct tb *tb, enum tb_tunnel_event event,
+		     enum tb_tunnel_type type,
+		     const struct tb_port *src_port,
+		     const struct tb_port *dst_port);
+
 const char *tb_tunnel_type_name(const struct tb_tunnel *tunnel);
 
 #define __TB_TUNNEL_PRINT(level, tunnel, fmt, arg...)                   \
-- 
2.47.2

[PATCH v2 3/4] thunderbolt: Notify userspace about firmware CM tunneling events

[Mika Westerberg]

From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>

In the same way we do for software connection manager, send
notifications about tunneling changes done by the firmware connection
manager as well. There are some limitations with this though, for
example we only get "DP Configuration Changed" message from the firmware
without any indication if DisplayPort tunnel was activated or
deactivated. Also we don't get information about the tunnel itself
either so the event then looks like:

  TUNNEL_EVENT=changed
  TUNNEL_DETAILS=(DP)

XDomain connections are similar to what the software connection manager
sends.

Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/icm.c     | 36 ++++++++++++++++++++++++++++++++++-
 drivers/thunderbolt/tb_msgs.h |  1 +
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/drivers/thunderbolt/icm.c b/drivers/thunderbolt/icm.c
index 7859bccc592d..f213d9174dc5 100644
--- a/drivers/thunderbolt/icm.c
+++ b/drivers/thunderbolt/icm.c
@@ -22,6 +22,7 @@
 #include "ctl.h"
 #include "nhi_regs.h"
 #include "tb.h"
+#include "tunnel.h"
 
 #define PCIE2CIO_CMD			0x30
 #define PCIE2CIO_CMD_TIMEOUT		BIT(31)
@@ -379,6 +380,27 @@ static bool icm_firmware_running(const struct tb_nhi *nhi)
 	return !!(val & REG_FW_STS_ICM_EN);
 }
 
+static void icm_xdomain_activated(struct tb_xdomain *xd, bool activated)
+{
+	struct tb_port *nhi_port, *dst_port;
+	struct tb *tb = xd->tb;
+
+	nhi_port = tb_switch_find_port(tb->root_switch, TB_TYPE_NHI);
+	dst_port = tb_xdomain_downstream_port(xd);
+
+	if (activated)
+		tb_tunnel_event(tb, TB_TUNNEL_ACTIVATED, TB_TUNNEL_DMA,
+				nhi_port, dst_port);
+	else
+		tb_tunnel_event(tb, TB_TUNNEL_DEACTIVATED, TB_TUNNEL_DMA,
+				nhi_port, dst_port);
+}
+
+static void icm_dp_event(struct tb *tb)
+{
+	tb_tunnel_event(tb, TB_TUNNEL_CHANGED, TB_TUNNEL_DP, NULL, NULL);
+}
+
 static bool icm_fr_is_supported(struct tb *tb)
 {
 	return !x86_apple_machine;
@@ -584,6 +606,7 @@ static int icm_fr_approve_xdomain_paths(struct tb *tb, struct tb_xdomain *xd,
 	if (reply.hdr.flags & ICM_FLAGS_ERROR)
 		return -EIO;
 
+	icm_xdomain_activated(xd, true);
 	return 0;
 }
 
@@ -603,6 +626,8 @@ static int icm_fr_disconnect_xdomain_paths(struct tb *tb, struct tb_xdomain *xd,
 	nhi_mailbox_cmd(tb->nhi, cmd, 1);
 	usleep_range(10, 50);
 	nhi_mailbox_cmd(tb->nhi, cmd, 2);
+
+	icm_xdomain_activated(xd, false);
 	return 0;
 }
 
@@ -1151,6 +1176,7 @@ static int icm_tr_approve_xdomain_paths(struct tb *tb, struct tb_xdomain *xd,
 	if (reply.hdr.flags & ICM_FLAGS_ERROR)
 		return -EIO;
 
+	icm_xdomain_activated(xd, true);
 	return 0;
 }
 
@@ -1191,7 +1217,12 @@ static int icm_tr_disconnect_xdomain_paths(struct tb *tb, struct tb_xdomain *xd,
 		return ret;
 
 	usleep_range(10, 50);
-	return icm_tr_xdomain_tear_down(tb, xd, 2);
+	ret = icm_tr_xdomain_tear_down(tb, xd, 2);
+	if (ret)
+		return ret;
+
+	icm_xdomain_activated(xd, false);
+	return 0;
 }
 
 static void
@@ -1718,6 +1749,9 @@ static void icm_handle_notification(struct work_struct *work)
 			if (tb_is_xdomain_enabled())
 				icm->xdomain_disconnected(tb, n->pkg);
 			break;
+		case ICM_EVENT_DP_CONFIG_CHANGED:
+			icm_dp_event(tb);
+			break;
 		case ICM_EVENT_RTD3_VETO:
 			icm->rtd3_veto(tb, n->pkg);
 			break;
diff --git a/drivers/thunderbolt/tb_msgs.h b/drivers/thunderbolt/tb_msgs.h
index a1670a96cbdc..144f7332d5d2 100644
--- a/drivers/thunderbolt/tb_msgs.h
+++ b/drivers/thunderbolt/tb_msgs.h
@@ -118,6 +118,7 @@ enum icm_event_code {
 	ICM_EVENT_DEVICE_DISCONNECTED = 0x4,
 	ICM_EVENT_XDOMAIN_CONNECTED = 0x6,
 	ICM_EVENT_XDOMAIN_DISCONNECTED = 0x7,
+	ICM_EVENT_DP_CONFIG_CHANGED = 0x8,
 	ICM_EVENT_RTD3_VETO = 0xa,
 };
 
-- 
2.47.2

[PATCH v2 4/4] Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

[Mika Westerberg]

From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>

Add documentation about the Thunderbolt/USB4 tunneling events to the
user’s and administrator’s guide.

Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 Documentation/admin-guide/thunderbolt.rst | 33 +++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
index d0502691dfa1..f0368ab6bd1f 100644
--- a/Documentation/admin-guide/thunderbolt.rst
+++ b/Documentation/admin-guide/thunderbolt.rst
@@ -296,6 +296,39 @@ information is missing.
 To recover from this mode, one needs to flash a valid NVM image to the
 host controller in the same way it is done in the previous chapter.
 
+Tunneling events
+----------------
+The driver sends ``KOBJ_CHANGE`` events to userspace when there is a
+tunneling change in the ``thunderbolt_domain``. The notification carries
+following environment variables::
+
+  TUNNEL_EVENT=<EVENT>
+  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)
+
+Possible values for ``<EVENT>`` are:
+
+  activated
+    The tunnel was activated (created).
+
+  changed
+    There is a change in this tunnel. For example bandwidth allocation was
+    changed.
+
+  deactivated
+    The tunnel was torn down.
+
+  low bandwidth
+    The tunnel is not getting optimal bandwidth.
+
+  insufficient bandwidth
+    There is not enough bandwidth for the current tunnel requirements.
+
+The ``TUNNEL_DETAILS`` is only provided if the tunnel is known. For
+example, in case of Firmware Connection Manager this is missing or does
+not provide full tunnel information. In case of Software Connection Manager
+this includes full tunnel details. The format matches what the driver uses
+when logging.
+
 Networking over Thunderbolt cable
 ---------------------------------
 Thunderbolt technology allows software communication between two hosts
-- 
2.47.2

Re: [PATCH v2 4/4] Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

[Greg KH]

On Thu, Apr 17, 2025 at 12:04:26PM +0300, Mika Westerberg wrote:
> From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> 
> Add documentation about the Thunderbolt/USB4 tunneling events to the
> user’s and administrator’s guide.
> 
> Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>  Documentation/admin-guide/thunderbolt.rst | 33 +++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
> index d0502691dfa1..f0368ab6bd1f 100644
> --- a/Documentation/admin-guide/thunderbolt.rst
> +++ b/Documentation/admin-guide/thunderbolt.rst
> @@ -296,6 +296,39 @@ information is missing.
>  To recover from this mode, one needs to flash a valid NVM image to the
>  host controller in the same way it is done in the previous chapter.
>  
> +Tunneling events
> +----------------
> +The driver sends ``KOBJ_CHANGE`` events to userspace when there is a
> +tunneling change in the ``thunderbolt_domain``. The notification carries
> +following environment variables::
> +
> +  TUNNEL_EVENT=<EVENT>
> +  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)

I'm ok with this, but wow TUNNEL_DETAILS is going to be hard to parse by
userspace, right?  Is this something that it is supposed to do something
with?

thanks,

greg k-h

Re: [PATCH v2 4/4] Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

[Mika Westerberg]

On Thu, Apr 17, 2025 at 11:39:38AM +0200, Greg KH wrote:
> On Thu, Apr 17, 2025 at 12:04:26PM +0300, Mika Westerberg wrote:
> > From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > 
> > Add documentation about the Thunderbolt/USB4 tunneling events to the
> > user’s and administrator’s guide.
> > 
> > Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > ---
> >  Documentation/admin-guide/thunderbolt.rst | 33 +++++++++++++++++++++++
> >  1 file changed, 33 insertions(+)
> > 
> > diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
> > index d0502691dfa1..f0368ab6bd1f 100644
> > --- a/Documentation/admin-guide/thunderbolt.rst
> > +++ b/Documentation/admin-guide/thunderbolt.rst
> > @@ -296,6 +296,39 @@ information is missing.
> >  To recover from this mode, one needs to flash a valid NVM image to the
> >  host controller in the same way it is done in the previous chapter.
> >  
> > +Tunneling events
> > +----------------
> > +The driver sends ``KOBJ_CHANGE`` events to userspace when there is a
> > +tunneling change in the ``thunderbolt_domain``. The notification carries
> > +following environment variables::
> > +
> > +  TUNNEL_EVENT=<EVENT>
> > +  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)
> 
> I'm ok with this, but wow TUNNEL_DETAILS is going to be hard to parse by
> userspace, right?  Is this something that it is supposed to do something
> with?

Yes, the reason it looks like that is because it matches the "format" we
use in the logging (in dmesg). For instance:

[   35.400488] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): activating
[   35.401237] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP IN maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
[   35.401239] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP OUT maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
[   35.401493] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode supported
[   35.402528] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): non-reduced bandwidth 8100 Mb/s x4 = 25920 Mb/s
[   35.402773] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): maximum bandwidth through allocation mode 20000 Mb/s x4 = 77575 Mb/s
[   35.402775] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): granularity 500 Mb/s
[   35.403029] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): estimated bandwidth 103500 Mb/s
[   35.404693] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode enabled

This allows matching the event with dmesg tunnel logs. If you think this is
not good we can change it.

Re: [PATCH v2 4/4] Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

[Greg KH]

On Thu, Apr 17, 2025 at 01:04:56PM +0300, Mika Westerberg wrote:
> On Thu, Apr 17, 2025 at 11:39:38AM +0200, Greg KH wrote:
> > On Thu, Apr 17, 2025 at 12:04:26PM +0300, Mika Westerberg wrote:
> > > From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > 
> > > Add documentation about the Thunderbolt/USB4 tunneling events to the
> > > user’s and administrator’s guide.
> > > 
> > > Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > > ---
> > >  Documentation/admin-guide/thunderbolt.rst | 33 +++++++++++++++++++++++
> > >  1 file changed, 33 insertions(+)
> > > 
> > > diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
> > > index d0502691dfa1..f0368ab6bd1f 100644
> > > --- a/Documentation/admin-guide/thunderbolt.rst
> > > +++ b/Documentation/admin-guide/thunderbolt.rst
> > > @@ -296,6 +296,39 @@ information is missing.
> > >  To recover from this mode, one needs to flash a valid NVM image to the
> > >  host controller in the same way it is done in the previous chapter.
> > >  
> > > +Tunneling events
> > > +----------------
> > > +The driver sends ``KOBJ_CHANGE`` events to userspace when there is a
> > > +tunneling change in the ``thunderbolt_domain``. The notification carries
> > > +following environment variables::
> > > +
> > > +  TUNNEL_EVENT=<EVENT>
> > > +  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)
> > 
> > I'm ok with this, but wow TUNNEL_DETAILS is going to be hard to parse by
> > userspace, right?  Is this something that it is supposed to do something
> > with?
> 
> Yes, the reason it looks like that is because it matches the "format" we
> use in the logging (in dmesg). For instance:
> 
> [   35.400488] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): activating
> [   35.401237] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP IN maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> [   35.401239] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP OUT maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> [   35.401493] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode supported
> [   35.402528] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): non-reduced bandwidth 8100 Mb/s x4 = 25920 Mb/s
> [   35.402773] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): maximum bandwidth through allocation mode 20000 Mb/s x4 = 77575 Mb/s
> [   35.402775] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): granularity 500 Mb/s
> [   35.403029] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): estimated bandwidth 103500 Mb/s
> [   35.404693] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode enabled

Kernel logs are not supposed to always be parsable, so this is fine :)

> This allows matching the event with dmesg tunnel logs. If you think this is
> not good we can change it.

It depends on what you are expecting userspace to do with this
information.  If it's a simple "here's some debugging information you
might like to look at" then it's fine.  If it is "here is some
information that you need to take a programatic action based on", then
that's different.

thanks,

greg k-h

Re: [PATCH v2 4/4] Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

[Mika Westerberg]

On Thu, Apr 17, 2025 at 12:25:19PM +0200, Greg KH wrote:
> On Thu, Apr 17, 2025 at 01:04:56PM +0300, Mika Westerberg wrote:
> > On Thu, Apr 17, 2025 at 11:39:38AM +0200, Greg KH wrote:
> > > On Thu, Apr 17, 2025 at 12:04:26PM +0300, Mika Westerberg wrote:
> > > > From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > > 
> > > > Add documentation about the Thunderbolt/USB4 tunneling events to the
> > > > user’s and administrator’s guide.
> > > > 
> > > > Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > > > ---
> > > >  Documentation/admin-guide/thunderbolt.rst | 33 +++++++++++++++++++++++
> > > >  1 file changed, 33 insertions(+)
> > > > 
> > > > diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
> > > > index d0502691dfa1..f0368ab6bd1f 100644
> > > > --- a/Documentation/admin-guide/thunderbolt.rst
> > > > +++ b/Documentation/admin-guide/thunderbolt.rst
> > > > @@ -296,6 +296,39 @@ information is missing.
> > > >  To recover from this mode, one needs to flash a valid NVM image to the
> > > >  host controller in the same way it is done in the previous chapter.
> > > >  
> > > > +Tunneling events
> > > > +----------------
> > > > +The driver sends ``KOBJ_CHANGE`` events to userspace when there is a
> > > > +tunneling change in the ``thunderbolt_domain``. The notification carries
> > > > +following environment variables::
> > > > +
> > > > +  TUNNEL_EVENT=<EVENT>
> > > > +  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)
> > > 
> > > I'm ok with this, but wow TUNNEL_DETAILS is going to be hard to parse by
> > > userspace, right?  Is this something that it is supposed to do something
> > > with?
> > 
> > Yes, the reason it looks like that is because it matches the "format" we
> > use in the logging (in dmesg). For instance:
> > 
> > [   35.400488] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): activating
> > [   35.401237] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP IN maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > [   35.401239] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP OUT maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > [   35.401493] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode supported
> > [   35.402528] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): non-reduced bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > [   35.402773] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): maximum bandwidth through allocation mode 20000 Mb/s x4 = 77575 Mb/s
> > [   35.402775] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): granularity 500 Mb/s
> > [   35.403029] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): estimated bandwidth 103500 Mb/s
> > [   35.404693] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode enabled
> 
> Kernel logs are not supposed to always be parsable, so this is fine :)
> 
> > This allows matching the event with dmesg tunnel logs. If you think this is
> > not good we can change it.
> 
> It depends on what you are expecting userspace to do with this
> information.  If it's a simple "here's some debugging information you
> might like to look at" then it's fine.  If it is "here is some
> information that you need to take a programatic action based on", then
> that's different.

It's purely informative. Userspace cannot take any programmatic action
based on this but it can use this to display user "more details" for
example if there is an error allocating bandwidth for DisplayPort.

Re: [PATCH v2 4/4] Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

[Greg KH]

On Thu, Apr 17, 2025 at 01:33:27PM +0300, Mika Westerberg wrote:
> On Thu, Apr 17, 2025 at 12:25:19PM +0200, Greg KH wrote:
> > On Thu, Apr 17, 2025 at 01:04:56PM +0300, Mika Westerberg wrote:
> > > On Thu, Apr 17, 2025 at 11:39:38AM +0200, Greg KH wrote:
> > > > On Thu, Apr 17, 2025 at 12:04:26PM +0300, Mika Westerberg wrote:
> > > > > From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > > > 
> > > > > Add documentation about the Thunderbolt/USB4 tunneling events to the
> > > > > user’s and administrator’s guide.
> > > > > 
> > > > > Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > > > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > > > > ---
> > > > >  Documentation/admin-guide/thunderbolt.rst | 33 +++++++++++++++++++++++
> > > > >  1 file changed, 33 insertions(+)
> > > > > 
> > > > > diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
> > > > > index d0502691dfa1..f0368ab6bd1f 100644
> > > > > --- a/Documentation/admin-guide/thunderbolt.rst
> > > > > +++ b/Documentation/admin-guide/thunderbolt.rst
> > > > > @@ -296,6 +296,39 @@ information is missing.
> > > > >  To recover from this mode, one needs to flash a valid NVM image to the
> > > > >  host controller in the same way it is done in the previous chapter.
> > > > >  
> > > > > +Tunneling events
> > > > > +----------------
> > > > > +The driver sends ``KOBJ_CHANGE`` events to userspace when there is a
> > > > > +tunneling change in the ``thunderbolt_domain``. The notification carries
> > > > > +following environment variables::
> > > > > +
> > > > > +  TUNNEL_EVENT=<EVENT>
> > > > > +  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)
> > > > 
> > > > I'm ok with this, but wow TUNNEL_DETAILS is going to be hard to parse by
> > > > userspace, right?  Is this something that it is supposed to do something
> > > > with?
> > > 
> > > Yes, the reason it looks like that is because it matches the "format" we
> > > use in the logging (in dmesg). For instance:
> > > 
> > > [   35.400488] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): activating
> > > [   35.401237] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP IN maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > > [   35.401239] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP OUT maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > > [   35.401493] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode supported
> > > [   35.402528] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): non-reduced bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > > [   35.402773] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): maximum bandwidth through allocation mode 20000 Mb/s x4 = 77575 Mb/s
> > > [   35.402775] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): granularity 500 Mb/s
> > > [   35.403029] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): estimated bandwidth 103500 Mb/s
> > > [   35.404693] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode enabled
> > 
> > Kernel logs are not supposed to always be parsable, so this is fine :)
> > 
> > > This allows matching the event with dmesg tunnel logs. If you think this is
> > > not good we can change it.
> > 
> > It depends on what you are expecting userspace to do with this
> > information.  If it's a simple "here's some debugging information you
> > might like to look at" then it's fine.  If it is "here is some
> > information that you need to take a programatic action based on", then
> > that's different.
> 
> It's purely informative. Userspace cannot take any programmatic action
> based on this but it can use this to display user "more details" for
> example if there is an error allocating bandwidth for DisplayPort.

Ok, that's fine then, hopefully no one tried to parse it in the future.

You might say "the format of this string may change over time" or
something like that?

thanks,

greg k-h

Re: [PATCH v2 4/4] Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

[Mika Westerberg]

On Thu, Apr 17, 2025 at 12:41:57PM +0200, Greg KH wrote:
> On Thu, Apr 17, 2025 at 01:33:27PM +0300, Mika Westerberg wrote:
> > On Thu, Apr 17, 2025 at 12:25:19PM +0200, Greg KH wrote:
> > > On Thu, Apr 17, 2025 at 01:04:56PM +0300, Mika Westerberg wrote:
> > > > On Thu, Apr 17, 2025 at 11:39:38AM +0200, Greg KH wrote:
> > > > > On Thu, Apr 17, 2025 at 12:04:26PM +0300, Mika Westerberg wrote:
> > > > > > From: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > > > > 
> > > > > > Add documentation about the Thunderbolt/USB4 tunneling events to the
> > > > > > user’s and administrator’s guide.
> > > > > > 
> > > > > > Signed-off-by: Alan Borzeszkowski <alan.borzeszkowski@linux.intel.com>
> > > > > > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > > > > > ---
> > > > > >  Documentation/admin-guide/thunderbolt.rst | 33 +++++++++++++++++++++++
> > > > > >  1 file changed, 33 insertions(+)
> > > > > > 
> > > > > > diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
> > > > > > index d0502691dfa1..f0368ab6bd1f 100644
> > > > > > --- a/Documentation/admin-guide/thunderbolt.rst
> > > > > > +++ b/Documentation/admin-guide/thunderbolt.rst
> > > > > > @@ -296,6 +296,39 @@ information is missing.
> > > > > >  To recover from this mode, one needs to flash a valid NVM image to the
> > > > > >  host controller in the same way it is done in the previous chapter.
> > > > > >  
> > > > > > +Tunneling events
> > > > > > +----------------
> > > > > > +The driver sends ``KOBJ_CHANGE`` events to userspace when there is a
> > > > > > +tunneling change in the ``thunderbolt_domain``. The notification carries
> > > > > > +following environment variables::
> > > > > > +
> > > > > > +  TUNNEL_EVENT=<EVENT>
> > > > > > +  TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)
> > > > > 
> > > > > I'm ok with this, but wow TUNNEL_DETAILS is going to be hard to parse by
> > > > > userspace, right?  Is this something that it is supposed to do something
> > > > > with?
> > > > 
> > > > Yes, the reason it looks like that is because it matches the "format" we
> > > > use in the logging (in dmesg). For instance:
> > > > 
> > > > [   35.400488] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): activating
> > > > [   35.401237] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP IN maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > > > [   35.401239] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): DP OUT maximum supported bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > > > [   35.401493] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode supported
> > > > [   35.402528] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): non-reduced bandwidth 8100 Mb/s x4 = 25920 Mb/s
> > > > [   35.402773] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): maximum bandwidth through allocation mode 20000 Mb/s x4 = 77575 Mb/s
> > > > [   35.402775] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): granularity 500 Mb/s
> > > > [   35.403029] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): estimated bandwidth 103500 Mb/s
> > > > [   35.404693] thunderbolt 0000:07:00.0: 0:13 <-> 1:19 (DP): bandwidth allocation mode enabled
> > > 
> > > Kernel logs are not supposed to always be parsable, so this is fine :)
> > > 
> > > > This allows matching the event with dmesg tunnel logs. If you think this is
> > > > not good we can change it.
> > > 
> > > It depends on what you are expecting userspace to do with this
> > > information.  If it's a simple "here's some debugging information you
> > > might like to look at" then it's fine.  If it is "here is some
> > > information that you need to take a programatic action based on", then
> > > that's different.
> > 
> > It's purely informative. Userspace cannot take any programmatic action
> > based on this but it can use this to display user "more details" for
> > example if there is an error allocating bandwidth for DisplayPort.
> 
> Ok, that's fine then, hopefully no one tried to parse it in the future.

;-)

> You might say "the format of this string may change over time" or
> something like that?

Good idea, We'll do that.

Re: [PATCH v2 0/4] thunderbolt: Notify userspace about tunneling events in the domain

[Mika Westerberg]

On Thu, Apr 17, 2025 at 12:04:22PM +0300, Mika Westerberg wrote:
> Hi all,
> 
> This series adds support to sending uevents to userspace about changes in
> tunneling such as creation, removal and bandwidth related.  One intented
> use-case for this is an upcoming USB-C daemon developed by Saranya that
> then notifies user for example if there is not enough bandwidth for
> DisplayPort requirements. We also added debug tools [1] support for these
> (currently it just updates various screens on event but we are working on
> add event log there too).
> 
> The Firmware Connection manager side is kind of limited though since there
> are not that many notifications we get.
> 
> [1] https://github.com/intel/tbtools
> 
> Previous version can be found:
> 
>   https://lore.kernel.org/linux-usb/20250410125600.3074417-1-mika.westerberg@linux.intel.com/
> 
> Changes from the previous version:
> 
>   * Add missing SoB.
>   * Add documentation to admin-guide/thunderbolt.rst.
> 
> Alan Borzeszkowski (4):
>   thunderbolt: Introduce domain event message handler
>   thunderbolt: Notify userspace about software CM tunneling events
>   thunderbolt: Notify userspace about firmware CM tunneling events
>   Documentation/admin-guide: Document Thunderbolt/USB4 tunneling events

Changed the documentation to say:

  "The format currently matches what the driver uses when logging. This may change over time."

and applied the whole series to thunderbolt.git/next.