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

[Mika Westerberg <mika.westerberg@linux.intel.com>]

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.