Re: git: 2f7a796b590e - main - thunderbolt.4: Initial manual for HW Relnotes

On Oct 2, 2025, at 12:22, Mark Millard <marklmi@yahoo.com> wrote:

> On Oct 2, 2025, at 10:25, Alexander Ziaee <ziaee@runbox.com> wrote:
> 
>> On 2025-10-02 12:47 -04:00 EDT, "Mark Millard" <marklmi@yahoo.com> wrote:
>>> Alexander Ziaee <ziaee_at_FreeBSD.org> wrote on
>>> Date: Thu, 02 Oct 2025 15:14:07 UTC :
>>> 
>>>> The branch main has been updated by ziaee:
>>>> 
>>>> URL: https://cgit.FreeBSD.org/src/commit/?id=2f7a796b590e67c5d123f2b00b3aaf7ba7a32a13
>>>> 
>>>> commit 2f7a796b590e67c5d123f2b00b3aaf7ba7a32a13
>>>> Author: Alexander Ziaee <ziaee@FreeBSD.org>
>>>> AuthorDate: 2025-10-02 12:05:25 +0000
>>>> Commit: Alexander Ziaee <ziaee@FreeBSD.org>
>>>> CommitDate: 2025-10-02 15:12:48 +0000
>>>> 
>>>> thunderbolt.4: Initial manual for HW Relnotes
>>>> 
>>>> This manual contains nothing and is only suitable for the HW Relnotes,
>>>> but lets get it in so we have something and then can iterate on it.
>>>> 
>>>> MFC after: 3 minutes
>>>> Fixes: 2ed9833791f2 (thunderbolt: Import USB4 code)
>>>> Discussed with: obiwac
>>>> Differential Revision: https://reviews.freebsd.org/D52847
>>>> ---
>>>> share/man/man4/Makefile | 1 +
>>>> share/man/man4/thunderbolt.4 | 22 ++++++++++++++++++++++
>>>> 2 files changed, 23 insertions(+)
>>>> 
>>>> diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
>>>> index f5d7a0e081fc..6e076722c786 100644
>>>> --- a/share/man/man4/Makefile
>>>> +++ b/share/man/man4/Makefile
>>>> @@ -589,6 +589,7 @@ MAN= aac.4 \
>>>> tdfx.4 \
>>>> termios.4 \
>>>> textdump.4 \
>>>> + thunderbolt.4 \
>>>> ti.4 \
>>>> timecounters.4 \
>>>> tmpfs.4 \
>>>> diff --git a/share/man/man4/thunderbolt.4 b/share/man/man4/thunderbolt.4
>>>> new file mode 100644
>>>> index 000000000000..3477c11fb60d
>>>> --- /dev/null
>>>> +++ b/share/man/man4/thunderbolt.4
>>>> @@ -0,0 +1,22 @@
>>>> +.\"
>>>> +.\" Copyright (c) 2025 Alexander Ziaee
>>>> +.\"
>>>> +.\" SPDX-License-Identifier: BSD-2-Clause
>>>> +.\"
>>>> +.Dd October 2, 2025
>>>> +.Dt THUNDERBOLT 4
>>>> +.Os
>>>> +.Sh NAME
>>>> +.Nm thunderbolt
>>>> +.Nd USB4 controller driver
>>>> +.Sh SYNOPSIS
>>>> +.Cd device thunderbolt
>>>> +.Sh HARDWARE
>>>> +The
>>>> +.Nm
>>>> +driver supports USB4 controllers.
>>> 
>>> As I understand things, being fairly explicit related the
>>> following is likely required (not a proposed wording or
>>> presentation):
>>> 
>>> Quoting USB4 V2: "A USB4 Host or USB4 Peripheral Device can
>>> optionally support interoperability with Thunderbolt 3
>>> (TBT3) products."
>>> 
>>> Quoting USB4 V1: "A USB4 host or USB4 peripheral device can
>>> optionally support interoperability with Thunderbolt 3
>>> (TBT3) products."
>>> 
>>> In both, this is tied to Chapter 13, "Interoperability with
>>> Thunderbolt(tm) 3 systems". As I understand FreeBSD is not
>>> trying to meet the criteria in that chapter, for example.
>>> 
>>> USB4 does not require a certification process, as I
>>> remember. Thunderbolt 4 and 5 do, as I remember.
>>> 
>>> As I remember, a distinction between USB4 and Thunderbolt 4
>>> and 5 was that Thunderbolt 4 and 5 require (nearly?) all
>>> optional items from the matching USB4 version to be
>>> implemented (so: not optional if Thunderbolt 4 or 5 is
>>> claimed/certified). Also, it seems unlikely that FreeBSD
>>> would go through a Thunderbolt 4 or 5 certification process.
>>> 
>>> Overall this seems to mean not meeting the Thunderbolt 4
>>> and/or 5 criteria fully and not supporting Thunderbolt 3
>>> --but just meeting the criteria for one or both of:
>>> 
>>> ) USB4 V1 without "TBT3" support
>>> ) USB4 V2 without "TBT3" support
>>> 
>>> That would be a subset of the Thunderbolt 4 or 5 criteria
>>> in a way that excludes Thunderbolt 3.
>>> 
>>> Referencing Thunderbolt without someplace being fairly
>>> explicit about those types of relationships could easily
>>> leave a misimpression (even if I've gotten some of the
>>> status wrong above).
>>> 
>>> My guess here is that enough is known about the intent
>>> in this area to be able to have material about this type
>>> of thing in place at any time.
>> 
>> My impression is that actually nothing works yet, but we now have a driver called thunderbolt which is made to support these controllers. The driver is in, allegedly, and so it's existence needs to be mentioned in the canonical places where we mention our drivers because people are looking for them for assorted reasons.
> 
> I've actually booted a Dell Precision 5490 via external
> USB4 media, but only when it was downstream of a Thunderbolt
> 3 hub. All 4 USB ports are USB4 on this 5490. And that was
> some time ago: early 2025-Feb with 1500031 of main 15. It
> saw the USB4 media as nda0 at nvme0 .
> 
> This only works as much as it does because the UEFI/ACPI
> involved supports enough to make some things possible
> such that FreeBSD does not need to be as involved.
> 
> As I remember, I set up and did some live-plugging/unlugging
> experiments any they lead to panics. The configuration had
> to be as it was at boot time. If I remember right this
> looked like Thunderbolt 3 mishandling (no surprise).
> 
> Directly connected, the transition from the kernel to
> the world/root mount for the USB4 media fails instead.
> 
> I've not yet tried updating the USB4 media with a more
> recent FreeBSD main 16 to see what happens now.

I updated the USB4 boot media to be based on:

# uname -apKU
FreeBSD USB4sys 16.0-CURRENT FreeBSD 16.0-CURRENT main-n280801-213170eb956f GENERIC-NODEBUG amd64 amd64 1600001 1600001

(It is from official pkgbase distribution use, a
copy of another boot media with some parameters
replaced afterwards.)

I tried it and the system booted --via the USB4
media being "da0":

# gpart show -p
=>       34  500118125    nda0  GPT  (238G)
         34       2014          - free -  (1.0M)
       2048    1925120  nda0p1  efi  (940M)
    1927168   25165824  nda0p2  ms-reserved  (12G)
   27092992  473024512  nda0p3  linux-data  (226G)
  500117504        655          - free -  (328K)

=>        40  3907029088    da0  GPT  (1.8T)
          40      409600  da0p1  efi  (200M)
      409640  3638558720  da0p2  freebsd-ufs  (1.7T)
  3638968360   251658240  da0p3  freebsd-swap  (120G)
  3890626600    16402528         - free -  (7.8G)

No external hub involved.

(As before, the external USB Ethernet plugged into
one of the USB4 ports works too.)

(The internal nvme showing up as nda0 has a
ubuntu installation on it, as distributed
by Dell.)

I've only done basic boot testing and minimal
use after that. Some basic testing of plugging
and unplugging Thunderbolt 3 media did not lead
to any crashes. This was both via a USB4 port
and via the Thunderbolt 3 hub. An example for
a USB4 port produced:

pci12: <PCI bus> on pcib8
pcib17: <PCI-PCI bridge> at device 0.0 on pci12
pcib17: failed to allocate initial I/O port window: 0-0xfff
pcib17: failed to allocate initial memory window: 0-0xfffff
pcib17: failed to allocate initial prefetch window: 0-0xfffff
pci13: <PCI bus> on pcib17
pcib18: <PCI-PCI bridge> at device 1.0 on pci13
pcib18: failed to allocate initial I/O port window: 0-0xfff
pcib18: failed to allocate initial memory window: 0-0xfffff
pcib18: failed to allocate initial prefetch window: 0-0xfffff
pci14: <PCI bus> on pcib18
pcib19: <PCI-PCI bridge> at device 2.0 on pci13
pcib19: failed to allocate initial I/O port window: 0-0xfff
pcib19: failed to allocate initial memory window: 0-0xfffff
pcib19: failed to allocate initial prefetch window: 0-0xfffff
pci15: <PCI bus> on pcib19
xhci2: <Intel Titan Ridge Thunderbolt 3 USB controller> mem 0x73e00000-0x73e0ffff at device 0.0 on pci15
xhci2: 32 bytes context size, 64-bit DMA
xhci2: xECP capabilities <PROTO,VEND(c0),LEGACY,VEND(c6),VEND(c7),VEND(c2),DEBUG,VEND(c3),VEND(c4),VEND(c5),VEND(c8),VEND(c9),PROTO,VEND(ca)>
usbus2 on xhci2
usbus2: 5.0Gbps Super Speed USB v3.0
pcib20: <PCI-PCI bridge> at device 4.0 on pci13
pcib20: failed to allocate initial I/O port window: 0-0xfff
pcib20: failed to allocate initial memory window: 0-0xfffff
pcib20: failed to allocate initial prefetch window: 0-0xfffff
ugen2.1: <Intel XHCI root HUB> at usbus2
uhub6 on usbus2
uhub6: <Intel XHCI root HUB, class 9/0, rev 3.00/1.00, addr 1> on usbus2
uhub6: 4 ports with 4 removable, self powered
pcib20: detached
uhub6: detached
ugen2.1: <Intel XHCI root HUB> at usbus2 (disconnected)
unknown: at usbus2, port 1, addr 1 (disconnected)
usbus2: detached
xhci2: Controller reset timeout.
xhci2: detached
pci15: detached
pcib19: detached
pci14: detached
pcib18: detached
pci13: detached
pcib17: detached
pci12: detached


FYI:

CPU: Intel(R) Core(TM) Ultra 7 165H (3072.00-MHz K8-class CPU)
  Origin="GenuineIntel"  Id=0xa06a4  Family=0x6  Model=0xaa  Stepping=4
. . .
WARNING: L3 data cache covers more APIC IDs than a package (6 > 3)
FreeBSD/SMP: Multiprocessor System Detected: 22 CPUs
FreeBSD/SMP: Non-uniform topology

# dmesg -a | grep "no driver attached"
pci0: <multimedia> at device 5.0 (no driver attached)
pci1: <network> at device 0.0 (no driver attached)
pci0: <unknown> at device 11.0 (no driver attached)
pci0: <serial bus, USB> at device 13.2 (no driver attached)
pci0: <serial bus, USB> at device 13.3 (no driver attached)
pci0: <simple comms, UART> at device 18.0 (no driver attached)
pci0: <memory, RAM> at device 20.2 (no driver attached)
pci0: <serial bus> at device 21.0 (no driver attached)
pci0: <serial bus> at device 21.3 (no driver attached)
pci0: <simple comms> at device 22.0 (no driver attached)
pci4: <unknown> at device 0.0 (no driver attached)
pci0: <serial bus> at device 31.5 (no driver attached)

>> Patches to the doc are extremely welcome!
> 
> I'd need a lot more certainty about interpreting the
> more informal references that are around vs. the
> terminology in the USB4 specifications (or other
> such).
> 
> I've been more trying to point out subject areas than
> knowing for sure the details that I used for
> illustration.
> 
>> Best,
>> Alex
>> 
>>>> +.Sh HISTORY
>>>> +The
>>>> +.Nm
>>>> +driver appeared in
>>>> +.Fx 15.0 .
>>>> 
>>> 
>>> ===
>>> Mark Millard
>>> marklmi at yahoo.com



===
Mark Millard
marklmi at yahoo.com