^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) USB4 and Thunderbolt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) USB4 is the public specification based on Thunderbolt 3 protocol with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) some differences at the register level among other things. Connection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) manager is an entity running on the host router (host controller)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) responsible for enumerating routers and establishing tunnels. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) connection manager can be implemented either in firmware or software.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Typically PCs come with a firmware connection manager for Thunderbolt 3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) and early USB4 capable systems. Apple systems on the other hand use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) software connection manager and the later USB4 compliant devices follow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) the suit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) The Linux Thunderbolt driver supports both and can detect at runtime which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) connection manager implementation is to be used. To be on the safe side the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) software connection manager in Linux also advertises security level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) ``user`` which means PCIe tunneling is disabled by default. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) documentation below applies to both implementations with the exception that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) the software connection manager only supports ``user`` security level and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) is expected to be accompanied with an IOMMU based DMA protection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) Security levels and how to use them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) -----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) The interface presented here is not meant for end users. Instead there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) should be a userspace tool that handles all the low-level details, keeps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) a database of the authorized devices and prompts users for new connections.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) More details about the sysfs interface for Thunderbolt devices can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Those users who just want to connect any device without any sort of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) manual work can add following line to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ``/etc/udev/rules.d/99-local.rules``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) This will authorize all devices automatically when they appear. However,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) keep in mind that this bypasses the security levels and makes the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) vulnerable to DMA attacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Starting with Intel Falcon Ridge Thunderbolt controller there are 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) security levels available. Intel Titan Ridge added one more security level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) (usbonly). The reason for these is the fact that the connected devices can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) be DMA masters and thus read contents of the host memory without CPU and OS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) knowing about it. There are ways to prevent this by setting up an IOMMU but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) it is not always available for various reasons.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) The security levels are as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) All devices are automatically connected by the firmware. No user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) approval is needed. In BIOS settings this is typically called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) *Legacy mode*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) User is asked whether the device is allowed to be connected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Based on the device identification information available through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ``/sys/bus/thunderbolt/devices``, the user then can make the decision.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) In BIOS settings this is typically called *Unique ID*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) secure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) User is asked whether the device is allowed to be connected. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) addition to UUID the device (if it supports secure connect) is sent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) a challenge that should match the expected one based on a random key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) written to the ``key`` sysfs attribute. In BIOS settings this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) typically called *One time saved key*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) dponly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) The firmware automatically creates tunnels for Display Port and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) USB. No PCIe tunneling is done. In BIOS settings this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) typically called *Display Port Only*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) usbonly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) The firmware automatically creates tunnels for the USB controller and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) Display Port in a dock. All PCIe links downstream of the dock are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) removed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) The current security level can be read from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) the Thunderbolt domain the host controller manages. There is typically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) one domain per Thunderbolt host controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) If the security level reads as ``user`` or ``secure`` the connected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) device must be authorized by the user before PCIe tunnels are created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) (e.g the PCIe device appears).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) Each Thunderbolt device plugged in will appear in sysfs under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) ``/sys/bus/thunderbolt/devices``. The device directory carries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) information that can be used to identify the particular device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) including its name and UUID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) Authorizing devices when security level is ``user`` or ``secure``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) -----------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) When a device is plugged in it will appear in sysfs as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) /sys/bus/thunderbolt/devices/0-1/authorized - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) /sys/bus/thunderbolt/devices/0-1/device - 0x8004
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) /sys/bus/thunderbolt/devices/0-1/device_name - Thunderbolt to FireWire Adapter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) /sys/bus/thunderbolt/devices/0-1/vendor - 0x1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) /sys/bus/thunderbolt/devices/0-1/vendor_name - Apple, Inc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) /sys/bus/thunderbolt/devices/0-1/unique_id - e0376f00-0300-0100-ffff-ffffffffffff
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) The ``authorized`` attribute reads 0 which means no PCIe tunnels are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) created yet. The user can authorize the device by simply entering::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) This will create the PCIe tunnels and the device is now connected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) If the device supports secure connect, and the domain security level is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) set to ``secure``, it has an additional attribute ``key`` which can hold
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) a random 32-byte value used for authorization and challenging the device in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) future connects::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) /sys/bus/thunderbolt/devices/0-3/authorized - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) /sys/bus/thunderbolt/devices/0-3/device - 0x305
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) /sys/bus/thunderbolt/devices/0-3/device_name - AKiTiO Thunder3 PCIe Box
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) /sys/bus/thunderbolt/devices/0-3/key -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) /sys/bus/thunderbolt/devices/0-3/vendor - 0x41
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) /sys/bus/thunderbolt/devices/0-3/vendor_name - inXtron
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) /sys/bus/thunderbolt/devices/0-3/unique_id - dc010000-0000-8508-a22d-32ca6421cb16
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Notice the key is empty by default.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) If the user does not want to use secure connect they can just ``echo 1``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) to the ``authorized`` attribute and the PCIe tunnels will be created in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) the same way as in the ``user`` security level.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) If the user wants to use secure connect, the first time the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) plugged a key needs to be created and sent to the device::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) # key=$(openssl rand -hex 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) # echo $key > /sys/bus/thunderbolt/devices/0-3/key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) # echo 1 > /sys/bus/thunderbolt/devices/0-3/authorized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) Now the device is connected (PCIe tunnels are created) and in addition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) the key is stored on the device NVM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Next time the device is plugged in the user can verify (challenge) the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) device using the same key::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) # echo $key > /sys/bus/thunderbolt/devices/0-3/key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) # echo 2 > /sys/bus/thunderbolt/devices/0-3/authorized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) If the challenge the device returns back matches the one we expect based
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) on the key, the device is connected and the PCIe tunnels are created.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) However, if the challenge fails no tunnels are created and error is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) returned to the user.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) If the user still wants to connect the device they can either approve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) the device without a key or write a new key and write 1 to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) ``authorized`` file to get the new key stored on the device NVM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) DMA protection utilizing IOMMU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) Recent systems from 2018 and forward with Thunderbolt ports may natively
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) support IOMMU. This means that Thunderbolt security is handled by an IOMMU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) so connected devices cannot access memory regions outside of what is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) allocated for them by drivers. When Linux is running on such system it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) automatically enables IOMMU if not enabled by the user already. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) systems can be identified by reading ``1`` from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) ``/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection`` attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) The driver does not do anything special in this case but because DMA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) protection is handled by the IOMMU, security levels (if set) are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) redundant. For this reason some systems ship with security level set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) ``none``. Other systems have security level set to ``user`` in order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) support downgrade to older OS, so users who want to automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) authorize devices when IOMMU DMA protection is enabled can use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) following ``udev`` rule::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) ACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) Upgrading NVM on Thunderbolt device, host or retimer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) ----------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) Since most of the functionality is handled in firmware running on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) host controller or a device, it is important that the firmware can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) upgraded to the latest where possible bugs in it have been fixed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) Typically OEMs provide this firmware from their support site.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) There is also a central site which has links where to download firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) for some machines:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) Before you upgrade firmware on a device, host or retimer, please make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) sure it is a suitable upgrade. Failing to do that may render the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) in a state where it cannot be used properly anymore without special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) tools!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) Host NVM upgrade on Apple Macs is not supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Once the NVM image has been downloaded, you need to plug in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Thunderbolt device so that the host controller appears. It does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) matter which device is connected (unless you are upgrading NVM on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) device - then you need to connect that particular device).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) Note an OEM-specific method to power the controller up ("force power") may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) be available for your system in which case there is no need to plug in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) Thunderbolt device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) After that we can write the firmware to the non-active parts of the NVM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) of the host or device. As an example here is how Intel NUC6i7KYK (Skull
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Canyon) Thunderbolt controller NVM is upgraded::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) # dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) Once the operation completes we can trigger NVM authentication and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) upgrade process as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) If no errors are returned, the host controller shortly disappears. Once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) it comes back the driver notices it and initiates a full power cycle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) After a while the host controller appears again and this time it should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) be fully functional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) We can verify that the new NVM firmware is active by running the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) commands::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) 0x0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) # cat /sys/bus/thunderbolt/devices/0-0/nvm_version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) 18.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) If ``nvm_authenticate`` contains anything other than 0x0 it is the error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) code from the last authentication cycle, which means the authentication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) of the NVM image failed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) depend on the order they are registered in the NVMem subsystem. N in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) the name is the identifier added by the NVMem subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) Upgrading NVM when host controller is in safe mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) --------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) If the existing NVM is not properly authenticated (or is missing) the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) host controller goes into safe mode which means that the only available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) functionality is flashing a new NVM image. When in this mode, reading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) ``nvm_version`` fails with ``ENODATA`` and the device identification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) information is missing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) To recover from this mode, one needs to flash a valid NVM image to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) host controller in the same way it is done in the previous chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) Networking over Thunderbolt cable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) ---------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) Thunderbolt technology allows software communication between two hosts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) connected by a Thunderbolt cable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) It is possible to tunnel any kind of traffic over a Thunderbolt link but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) currently we only support Apple ThunderboltIP protocol.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) If the other host is running Windows or macOS, the only thing you need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) do is to connect a Thunderbolt cable between the two hosts; the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) ``thunderbolt-net`` driver is loaded automatically. If the other host is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) also Linux you should load ``thunderbolt-net`` manually on one host (it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) does not matter which one)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) # modprobe thunderbolt-net
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) This triggers module load on the other host automatically. If the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) is built-in to the kernel image, there is no need to do anything.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) The driver will create one virtual ethernet interface per Thunderbolt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) port which are named like ``thunderbolt0`` and so on. From this point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) you can either use standard userspace tools like ``ifconfig`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) configure the interface or let your GUI handle it automatically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) Forcing power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) Many OEMs include a method that can be used to force the power of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) Thunderbolt controller to an "On" state even if nothing is connected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) If supported by your machine this will be exposed by the WMI bus with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) a sysfs attribute called "force_power".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) For example the intel-wmi-thunderbolt driver exposes this attribute in:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) /sys/bus/wmi/devices/86CCFD48-205E-4A77-9C48-2021CBEDE341/force_power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) To force the power to on, write 1 to this attribute file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) To disable force power, write 0 to this attribute file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) Note: it's currently not possible to query the force power state of a platform.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags