Commit | Line | Data |
---|---|---|
163f1511 MW |
1 | ============= |
2 | Thunderbolt | |
3 | ============= | |
4 | The interface presented here is not meant for end users. Instead there | |
5 | should be a userspace tool that handles all the low-level details, keeps | |
54e36a2d | 6 | a database of the authorized devices and prompts users for new connections. |
163f1511 MW |
7 | |
8 | More details about the sysfs interface for Thunderbolt devices can be | |
9 | found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``. | |
10 | ||
11 | Those users who just want to connect any device without any sort of | |
54e36a2d | 12 | manual work can add following line to |
163f1511 MW |
13 | ``/etc/udev/rules.d/99-local.rules``:: |
14 | ||
15 | ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1" | |
16 | ||
17 | This will authorize all devices automatically when they appear. However, | |
18 | keep in mind that this bypasses the security levels and makes the system | |
19 | vulnerable to DMA attacks. | |
20 | ||
21 | Security levels and how to use them | |
22 | ----------------------------------- | |
54e36a2d | 23 | Starting with Intel Falcon Ridge Thunderbolt controller there are 4 |
6fc14e1a MW |
24 | security levels available. Intel Titan Ridge added one more security level |
25 | (usbonly). The reason for these is the fact that the connected devices can | |
26 | be DMA masters and thus read contents of the host memory without CPU and OS | |
27 | knowing about it. There are ways to prevent this by setting up an IOMMU but | |
28 | it is not always available for various reasons. | |
163f1511 MW |
29 | |
30 | The 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 | |
54e36a2d | 40 | ``/sys/bus/thunderbolt/devices``, the user then can make the decision. |
163f1511 MW |
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 | |
54e36a2d | 47 | written to the ``key`` sysfs attribute. In BIOS settings this is |
163f1511 MW |
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 | ||
6fc14e1a MW |
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 | ||
163f1511 MW |
60 | The current security level can be read from |
61 | ``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is | |
62 | the Thunderbolt domain the host controller manages. There is typically | |
63 | one domain per Thunderbolt host controller. | |
64 | ||
65 | If the security level reads as ``user`` or ``secure`` the connected | |
66 | device must be authorized by the user before PCIe tunnels are created | |
67 | (e.g the PCIe device appears). | |
68 | ||
69 | Each Thunderbolt device plugged in will appear in sysfs under | |
70 | ``/sys/bus/thunderbolt/devices``. The device directory carries | |
71 | information that can be used to identify the particular device, | |
72 | including its name and UUID. | |
73 | ||
74 | Authorizing devices when security level is ``user`` or ``secure`` | |
75 | ----------------------------------------------------------------- | |
76 | When 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 | ||
85 | The ``authorized`` attribute reads 0 which means no PCIe tunnels are | |
54e36a2d | 86 | created yet. The user can authorize the device by simply entering:: |
163f1511 MW |
87 | |
88 | # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized | |
89 | ||
90 | This will create the PCIe tunnels and the device is now connected. | |
91 | ||
92 | If the device supports secure connect, and the domain security level is | |
93 | set to ``secure``, it has an additional attribute ``key`` which can hold | |
54e36a2d | 94 | a random 32-byte value used for authorization and challenging the device in |
163f1511 MW |
95 | future 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 | ||
105 | Notice the key is empty by default. | |
106 | ||
54e36a2d | 107 | If the user does not want to use secure connect they can just ``echo 1`` |
163f1511 | 108 | to the ``authorized`` attribute and the PCIe tunnels will be created in |
54e36a2d | 109 | the same way as in the ``user`` security level. |
163f1511 MW |
110 | |
111 | If the user wants to use secure connect, the first time the device is | |
54e36a2d | 112 | plugged a key needs to be created and sent to the device:: |
163f1511 MW |
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 | ||
118 | Now the device is connected (PCIe tunnels are created) and in addition | |
119 | the key is stored on the device NVM. | |
120 | ||
121 | Next time the device is plugged in the user can verify (challenge) the | |
122 | device 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 | ||
127 | If the challenge the device returns back matches the one we expect based | |
128 | on the key, the device is connected and the PCIe tunnels are created. | |
54e36a2d | 129 | However, if the challenge fails no tunnels are created and error is |
163f1511 MW |
130 | returned to the user. |
131 | ||
54e36a2d RD |
132 | If the user still wants to connect the device they can either approve |
133 | the device without a key or write a new key and write 1 to the | |
163f1511 MW |
134 | ``authorized`` file to get the new key stored on the device NVM. |
135 | ||
dcc3c9e3 MW |
136 | DMA protection utilizing IOMMU |
137 | ------------------------------ | |
138 | Recent systems from 2018 and forward with Thunderbolt ports may natively | |
139 | support IOMMU. This means that Thunderbolt security is handled by an IOMMU | |
140 | so connected devices cannot access memory regions outside of what is | |
141 | allocated for them by drivers. When Linux is running on such system it | |
142 | automatically enables IOMMU if not enabled by the user already. These | |
143 | systems can be identified by reading ``1`` from | |
144 | ``/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection`` attribute. | |
145 | ||
146 | The driver does not do anything special in this case but because DMA | |
147 | protection is handled by the IOMMU, security levels (if set) are | |
148 | redundant. For this reason some systems ship with security level set to | |
149 | ``none``. Other systems have security level set to ``user`` in order to | |
150 | support downgrade to older OS, so users who want to automatically | |
151 | authorize devices when IOMMU DMA protection is enabled can use the | |
152 | following ``udev`` rule:: | |
153 | ||
154 | ACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1" | |
155 | ||
163f1511 MW |
156 | Upgrading NVM on Thunderbolt device or host |
157 | ------------------------------------------- | |
54e36a2d | 158 | Since most of the functionality is handled in firmware running on a |
163f1511 MW |
159 | host controller or a device, it is important that the firmware can be |
160 | upgraded to the latest where possible bugs in it have been fixed. | |
161 | Typically OEMs provide this firmware from their support site. | |
162 | ||
54e36a2d | 163 | There is also a central site which has links where to download firmware |
163f1511 MW |
164 | for some machines: |
165 | ||
166 | `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_ | |
167 | ||
54e36a2d RD |
168 | Before you upgrade firmware on a device or host, please make sure it is a |
169 | suitable upgrade. Failing to do that may render the device (or host) in a | |
163f1511 MW |
170 | state where it cannot be used properly anymore without special tools! |
171 | ||
172 | Host NVM upgrade on Apple Macs is not supported. | |
173 | ||
174 | Once the NVM image has been downloaded, you need to plug in a | |
175 | Thunderbolt device so that the host controller appears. It does not | |
176 | matter which device is connected (unless you are upgrading NVM on a | |
177 | device - then you need to connect that particular device). | |
178 | ||
54e36a2d | 179 | Note an OEM-specific method to power the controller up ("force power") may |
163f1511 MW |
180 | be available for your system in which case there is no need to plug in a |
181 | Thunderbolt device. | |
182 | ||
183 | After that we can write the firmware to the non-active parts of the NVM | |
184 | of the host or device. As an example here is how Intel NUC6i7KYK (Skull | |
185 | Canyon) 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 | ||
189 | Once the operation completes we can trigger NVM authentication and | |
190 | upgrade process as follows:: | |
191 | ||
192 | # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate | |
193 | ||
194 | If no errors are returned, the host controller shortly disappears. Once | |
195 | it comes back the driver notices it and initiates a full power cycle. | |
196 | After a while the host controller appears again and this time it should | |
197 | be fully functional. | |
198 | ||
54e36a2d | 199 | We can verify that the new NVM firmware is active by running the following |
163f1511 MW |
200 | commands:: |
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 | ||
54e36a2d | 207 | If ``nvm_authenticate`` contains anything other than 0x0 it is the error |
163f1511 MW |
208 | code from the last authentication cycle, which means the authentication |
209 | of the NVM image failed. | |
210 | ||
211 | Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN`` | |
54e36a2d | 212 | depend on the order they are registered in the NVMem subsystem. N in |
163f1511 MW |
213 | the name is the identifier added by the NVMem subsystem. |
214 | ||
215 | Upgrading NVM when host controller is in safe mode | |
216 | -------------------------------------------------- | |
217 | If the existing NVM is not properly authenticated (or is missing) the | |
54e36a2d RD |
218 | host controller goes into safe mode which means that the only available |
219 | functionality is flashing a new NVM image. When in this mode, reading | |
163f1511 MW |
220 | ``nvm_version`` fails with ``ENODATA`` and the device identification |
221 | information is missing. | |
222 | ||
223 | To recover from this mode, one needs to flash a valid NVM image to the | |
54e36a2d | 224 | host controller in the same way it is done in the previous chapter. |
e69b6c02 AL |
225 | |
226 | Networking over Thunderbolt cable | |
227 | --------------------------------- | |
54e36a2d | 228 | Thunderbolt technology allows software communication between two hosts |
e69b6c02 AL |
229 | connected by a Thunderbolt cable. |
230 | ||
54e36a2d | 231 | It is possible to tunnel any kind of traffic over a Thunderbolt link but |
e69b6c02 AL |
232 | currently we only support Apple ThunderboltIP protocol. |
233 | ||
54e36a2d RD |
234 | If the other host is running Windows or macOS, the only thing you need to |
235 | do is to connect a Thunderbolt cable between the two hosts; the | |
236 | ``thunderbolt-net`` driver is loaded automatically. If the other host is | |
237 | also Linux you should load ``thunderbolt-net`` manually on one host (it | |
238 | does not matter which one):: | |
e69b6c02 AL |
239 | |
240 | # modprobe thunderbolt-net | |
241 | ||
242 | This triggers module load on the other host automatically. If the driver | |
243 | is built-in to the kernel image, there is no need to do anything. | |
244 | ||
245 | The driver will create one virtual ethernet interface per Thunderbolt | |
246 | port which are named like ``thunderbolt0`` and so on. From this point | |
247 | you can either use standard userspace tools like ``ifconfig`` to | |
54e36a2d | 248 | configure the interface or let your GUI handle it automatically. |
07c455ee | 249 | |
ce6a9002 ML |
250 | Forcing power |
251 | ------------- | |
252 | Many OEMs include a method that can be used to force the power of a | |
54e36a2d | 253 | Thunderbolt controller to an "On" state even if nothing is connected. |
ce6a9002 ML |
254 | If supported by your machine this will be exposed by the WMI bus with |
255 | a sysfs attribute called "force_power". | |
256 | ||
257 | For example the intel-wmi-thunderbolt driver exposes this attribute in: | |
cce1fea5 | 258 | /sys/bus/wmi/devices/86CCFD48-205E-4A77-9C48-2021CBEDE341/force_power |
ce6a9002 ML |
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 | ||
263 | Note: it's currently not possible to query the force power state of a platform. |