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