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