About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / admin-guide / thunderbolt.rst




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.