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 136DMA protection utilizing IOMMU 137------------------------------ 138Recent systems from 2018 and forward with Thunderbolt ports may natively 139support IOMMU. This means that Thunderbolt security is handled by an IOMMU 140so connected devices cannot access memory regions outside of what is 141allocated for them by drivers. When Linux is running on such system it 142automatically enables IOMMU if not enabled by the user already. These 143systems can be identified by reading ``1`` from 144``/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection`` attribute. 145 146The driver does not do anything special in this case but because DMA 147protection is handled by the IOMMU, security levels (if set) are 148redundant. For this reason some systems ship with security level set to 149``none``. Other systems have security level set to ``user`` in order to 150support downgrade to older OS, so users who want to automatically 151authorize devices when IOMMU DMA protection is enabled can use the 152following ``udev`` rule:: 153 154 ACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1" 155 156Upgrading NVM on Thunderbolt device or host 157------------------------------------------- 158Since most of the functionality is handled in firmware running on a 159host controller or a device, it is important that the firmware can be 160upgraded to the latest where possible bugs in it have been fixed. 161Typically OEMs provide this firmware from their support site. 162 163There is also a central site which has links where to download firmware 164for some machines: 165 166 `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_ 167 168Before you upgrade firmware on a device or host, please make sure it is a 169suitable upgrade. Failing to do that may render the device (or host) in a 170state where it cannot be used properly anymore without special tools! 171 172Host NVM upgrade on Apple Macs is not supported. 173 174Once the NVM image has been downloaded, you need to plug in a 175Thunderbolt device so that the host controller appears. It does not 176matter which device is connected (unless you are upgrading NVM on a 177device - then you need to connect that particular device). 178 179Note an OEM-specific method to power the controller up ("force power") may 180be available for your system in which case there is no need to plug in a 181Thunderbolt device. 182 183After that we can write the firmware to the non-active parts of the NVM 184of the host or device. As an example here is how Intel NUC6i7KYK (Skull 185Canyon) Thunderbolt controller NVM is upgraded:: 186 187 # dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmem 188 189Once the operation completes we can trigger NVM authentication and 190upgrade process as follows:: 191 192 # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate 193 194If no errors are returned, the host controller shortly disappears. Once 195it comes back the driver notices it and initiates a full power cycle. 196After a while the host controller appears again and this time it should 197be fully functional. 198 199We can verify that the new NVM firmware is active by running the following 200commands:: 201 202 # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate 203 0x0 204 # cat /sys/bus/thunderbolt/devices/0-0/nvm_version 205 18.0 206 207If ``nvm_authenticate`` contains anything other than 0x0 it is the error 208code from the last authentication cycle, which means the authentication 209of the NVM image failed. 210 211Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN`` 212depend on the order they are registered in the NVMem subsystem. N in 213the name is the identifier added by the NVMem subsystem. 214 215Upgrading NVM when host controller is in safe mode 216-------------------------------------------------- 217If the existing NVM is not properly authenticated (or is missing) the 218host controller goes into safe mode which means that the only available 219functionality is flashing a new NVM image. When in this mode, reading 220``nvm_version`` fails with ``ENODATA`` and the device identification 221information is missing. 222 223To recover from this mode, one needs to flash a valid NVM image to the 224host controller in the same way it is done in the previous chapter. 225 226Networking over Thunderbolt cable 227--------------------------------- 228Thunderbolt technology allows software communication between two hosts 229connected by a Thunderbolt cable. 230 231It is possible to tunnel any kind of traffic over a Thunderbolt link but 232currently we only support Apple ThunderboltIP protocol. 233 234If the other host is running Windows or macOS, the only thing you need to 235do is to connect a Thunderbolt cable between the two hosts; the 236``thunderbolt-net`` driver is loaded automatically. If the other host is 237also Linux you should load ``thunderbolt-net`` manually on one host (it 238does not matter which one):: 239 240 # modprobe thunderbolt-net 241 242This triggers module load on the other host automatically. If the driver 243is built-in to the kernel image, there is no need to do anything. 244 245The driver will create one virtual ethernet interface per Thunderbolt 246port which are named like ``thunderbolt0`` and so on. From this point 247you can either use standard userspace tools like ``ifconfig`` to 248configure the interface or let your GUI handle it automatically. 249 250Forcing power 251------------- 252Many OEMs include a method that can be used to force the power of a 253Thunderbolt controller to an "On" state even if nothing is connected. 254If supported by your machine this will be exposed by the WMI bus with 255a sysfs attribute called "force_power". 256 257For example the intel-wmi-thunderbolt driver exposes this attribute in: 258 /sys/bus/wmi/devices/86CCFD48-205E-4A77-9C48-2021CBEDE341/force_power 259 260 To force the power to on, write 1 to this attribute file. 261 To disable force power, write 0 to this attribute file. 262 263Note: it's currently not possible to query the force power state of a platform. 264