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 database of the authorized devices and prompts user 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 from 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``. user then can do 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 ``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::
  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 it can just ``echo 1``
 103 to the ``authorized`` attribute and the PCIe tunnels will be created in
 104 the same way than in ``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 send 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 failed no tunnels are created and error is
 125 returned to the user.
 126
 127 If the user still wants to connect the device it can either approve
 128 the device without a key or write 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 a 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 firmwares
 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
 144 the suitable. 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 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 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 else 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 depends 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 only available
 194 functionality is flashing new NVM image. When in this mode the 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 host controller in the same way it is done in the previous chapter.