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

[Greg KH <gregkh@linuxfoundation.org>]

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