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.