GNU Linux-libre 4.19.211-gnu1
[releases.git] / Documentation / admin-guide / thunderbolt.rst
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
6 a database of the authorized devices and prompts users for new connections.
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
12 manual 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
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 -----------------------------------
23 Starting with Intel Falcon Ridge Thunderbolt controller there are 4
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.
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
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
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
86 created yet. The user can authorize the device by simply entering::
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
94 a random 32-byte value used for authorization and challenging the device in
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
107 If the user does not want to use secure connect they can just ``echo 1``
108 to the ``authorized`` attribute and the PCIe tunnels will be created in
109 the same way as in the ``user`` security level.
110
111 If the user wants to use secure connect, the first time the device is
112 plugged 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
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.
129 However, if the challenge fails no tunnels are created and error is
130 returned to the user.
131
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
134 ``authorized`` file to get the new key stored on the device NVM.
135
136 Upgrading NVM on Thunderbolt device or host
137 -------------------------------------------
138 Since most of the functionality is handled in firmware running on a
139 host controller or a device, it is important that the firmware can be
140 upgraded to the latest where possible bugs in it have been fixed.
141 Typically OEMs provide this firmware from their support site.
142
143 There is also a central site which has links where to download firmware
144 for some machines:
145
146   `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_
147
148 Before you upgrade firmware on a device or host, please make sure it is a
149 suitable upgrade. Failing to do that may render the device (or host) in a
150 state where it cannot be used properly anymore without special tools!
151
152 Host NVM upgrade on Apple Macs is not supported.
153
154 Once the NVM image has been downloaded, you need to plug in a
155 Thunderbolt device so that the host controller appears. It does not
156 matter which device is connected (unless you are upgrading NVM on a
157 device - then you need to connect that particular device).
158
159 Note an OEM-specific method to power the controller up ("force power") may
160 be available for your system in which case there is no need to plug in a
161 Thunderbolt device.
162
163 After that we can write the firmware to the non-active parts of the NVM
164 of the host or device. As an example here is how Intel NUC6i7KYK (Skull
165 Canyon) 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
169 Once the operation completes we can trigger NVM authentication and
170 upgrade process as follows::
171
172   # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate
173
174 If no errors are returned, the host controller shortly disappears. Once
175 it comes back the driver notices it and initiates a full power cycle.
176 After a while the host controller appears again and this time it should
177 be fully functional.
178
179 We can verify that the new NVM firmware is active by running the following
180 commands::
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
187 If ``nvm_authenticate`` contains anything other than 0x0 it is the error
188 code from the last authentication cycle, which means the authentication
189 of the NVM image failed.
190
191 Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN``
192 depend on the order they are registered in the NVMem subsystem. N in
193 the name is the identifier added by the NVMem subsystem.
194
195 Upgrading NVM when host controller is in safe mode
196 --------------------------------------------------
197 If the existing NVM is not properly authenticated (or is missing) the
198 host controller goes into safe mode which means that the only available
199 functionality is flashing a new NVM image. When in this mode, reading
200 ``nvm_version`` fails with ``ENODATA`` and the device identification
201 information is missing.
202
203 To recover from this mode, one needs to flash a valid NVM image to the
204 host controller in the same way it is done in the previous chapter.
205
206 Networking over Thunderbolt cable
207 ---------------------------------
208 Thunderbolt technology allows software communication between two hosts
209 connected by a Thunderbolt cable.
210
211 It is possible to tunnel any kind of traffic over a Thunderbolt link but
212 currently we only support Apple ThunderboltIP protocol.
213
214 If the other host is running Windows or macOS, the only thing you need to
215 do is to connect a Thunderbolt cable between the two hosts; the
216 ``thunderbolt-net`` driver is loaded automatically. If the other host is
217 also Linux you should load ``thunderbolt-net`` manually on one host (it
218 does not matter which one)::
219
220   # modprobe thunderbolt-net
221
222 This triggers module load on the other host automatically. If the driver
223 is built-in to the kernel image, there is no need to do anything.
224
225 The driver will create one virtual ethernet interface per Thunderbolt
226 port which are named like ``thunderbolt0`` and so on. From this point
227 you can either use standard userspace tools like ``ifconfig`` to
228 configure the interface or let your GUI handle it automatically.
229
230 Forcing power
231 -------------
232 Many OEMs include a method that can be used to force the power of a
233 Thunderbolt controller to an "On" state even if nothing is connected.
234 If supported by your machine this will be exposed by the WMI bus with
235 a sysfs attribute called "force_power".
236
237 For 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
243 Note: it's currently not possible to query the force power state of a platform.