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 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
 156 Upgrading NVM on Thunderbolt device or host
 157 -------------------------------------------
 158 Since most of the functionality is handled in firmware running on a
 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
 163 There is also a central site which has links where to download firmware
 164 for some machines:
 165
 166   `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_
 167
 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
 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
 179 Note an OEM-specific method to power the controller up ("force power") may
 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
 199 We can verify that the new NVM firmware is active by running the following
 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
 207 If ``nvm_authenticate`` contains anything other than 0x0 it is the error
 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``
 212 depend on the order they are registered in the NVMem subsystem. N in
 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
 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
 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
 224 host controller in the same way it is done in the previous chapter.
 225
 226 Networking over Thunderbolt cable
 227 ---------------------------------
 228 Thunderbolt technology allows software communication between two hosts
 229 connected by a Thunderbolt cable.
 230
 231 It is possible to tunnel any kind of traffic over a Thunderbolt link but
 232 currently we only support Apple ThunderboltIP protocol.
 233
 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)::
 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
 248 configure the interface or let your GUI handle it automatically.
 249
 250 Forcing power
 251 -------------
 252 Many OEMs include a method that can be used to force the power of a
 253 Thunderbolt controller to an "On" state even if nothing is connected.
 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:
 258   /sys/bus/wmi/devices/86CCFD48-205E-4A77-9C48-2021CBEDE341/force_power
 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.