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 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.