1sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget+/translations/zh_CN/admin-guide/thunderboltmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/zh_TW/admin-guide/thunderboltmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/it_IT/admin-guide/thunderboltmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/ja_JP/admin-guide/thunderboltmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/ko_KR/admin-guide/thunderboltmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/pt_BR/admin-guide/thunderboltmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/sp_SP/admin-guide/thunderboltmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhE/var/lib/git/docbuild/linux/Documentation/admin-guide/thunderbolt.rsthKubhsection)}(hhh](htitle)}(hUSB4 and Thunderbolth]hUSB4 and Thunderbolt}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hX1USB4 is the public specification based on Thunderbolt 3 protocol with some differences at the register level among other things. Connection manager is an entity running on the host router (host controller) responsible for enumerating routers and establishing tunnels. A connection manager can be implemented either in firmware or software. Typically PCs come with a firmware connection manager for Thunderbolt 3 and early USB4 capable systems. Apple systems on the other hand use software connection manager and the later USB4 compliant devices follow the suit.h]hX1USB4 is the public specification based on Thunderbolt 3 protocol with some differences at the register level among other things. Connection manager is an entity running on the host router (host controller) responsible for enumerating routers and establishing tunnels. A connection manager can be implemented either in firmware or software. Typically PCs come with a firmware connection manager for Thunderbolt 3 and early USB4 capable systems. Apple systems on the other hand use software connection manager and the later USB4 compliant devices follow the suit.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXThe Linux Thunderbolt driver supports both and can detect at runtime which connection manager implementation is to be used. To be on the safe side the software connection manager in Linux also advertises security level ``user`` which means PCIe tunneling is disabled by default. The documentation below applies to both implementations with the exception that the software connection manager only supports ``user`` security level and is expected to be accompanied with an IOMMU based DMA protection.h](hThe Linux Thunderbolt driver supports both and can detect at runtime which connection manager implementation is to be used. To be on the safe side the software connection manager in Linux also advertises security level }(hhhhhNhNubhliteral)}(h``user``h]huser}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh which means PCIe tunneling is disabled by default. The documentation below applies to both implementations with the exception that the software connection manager only supports }(hhhhhNhNubh)}(h``user``h]huser}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubhU security level and is expected to be accompanied with an IOMMU based DMA protection.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h#Security levels and how to use themh]h#Security levels and how to use them}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!hhhhhKubh)}(hThe interface presented here is not meant for end users. Instead there should be a userspace tool that handles all the low-level details, keeps a database of the authorized devices and prompts users for new connections.h]hThe interface presented here is not meant for end users. Instead there should be a userspace tool that handles all the low-level details, keeps a database of the authorized devices and prompts users for new connections.}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj!hhubh)}(hMore details about the sysfs interface for Thunderbolt devices can be found in Documentation/ABI/testing/sysfs-bus-thunderbolt.h]hMore details about the sysfs interface for Thunderbolt devices can be found in Documentation/ABI/testing/sysfs-bus-thunderbolt.}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj!hhubh)}(hThose users who just want to connect any device without any sort of manual work can add following line to ``/etc/udev/rules.d/99-local.rules``::h](hjThose users who just want to connect any device without any sort of manual work can add following line to }(hjNhhhNhNubh)}(h$``/etc/udev/rules.d/99-local.rules``h]h /etc/udev/rules.d/99-local.rules}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjNubh:}(hjNhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK!hj!hhubh literal_block)}(hTACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1"h]hTACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1"}hjpsbah}(h]h ]h"]h$]h&]hhuh1jnhhhK%hj!hhubh)}(hThis will authorize all devices automatically when they appear. However, keep in mind that this bypasses the security levels and makes the system vulnerable to DMA attacks.h]hThis will authorize all devices automatically when they appear. However, keep in mind that this bypasses the security levels and makes the system vulnerable to DMA attacks.}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hj!hhubh)}(hXStarting with Intel Falcon Ridge Thunderbolt controller there are 4 security levels available. Intel Titan Ridge added one more security level (usbonly). The reason for these is the fact that the connected devices can be DMA masters and thus read contents of the host memory without CPU and OS knowing about it. There are ways to prevent this by setting up an IOMMU but it is not always available for various reasons.h]hXStarting with Intel Falcon Ridge Thunderbolt controller there are 4 security levels available. Intel Titan Ridge added one more security level (usbonly). The reason for these is the fact that the connected devices can be DMA masters and thus read contents of the host memory without CPU and OS knowing about it. There are ways to prevent this by setting up an IOMMU but it is not always available for various reasons.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK+hj!hhubh)}(htSome USB4 systems have a BIOS setting to disable PCIe tunneling. This is treated as another security level (nopcie).h]htSome USB4 systems have a BIOS setting to disable PCIe tunneling. This is treated as another security level (nopcie).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hj!hhubh)}(h#The security levels are as follows:h]h#The security levels are as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hj!hhubh block_quote)}(hXnone All devices are automatically connected by the firmware. No user approval is needed. In BIOS settings this is typically called *Legacy mode*. user User is asked whether the device is allowed to be connected. Based on the device identification information available through ``/sys/bus/thunderbolt/devices``, the user then can make the decision. In BIOS settings this is typically called *Unique ID*. secure User is asked whether the device is allowed to be connected. In addition to UUID the device (if it supports secure connect) is sent a challenge that should match the expected one based on a random key written to the ``key`` sysfs attribute. In BIOS settings this is typically called *One time saved key*. dponly The firmware automatically creates tunnels for Display Port and USB. No PCIe tunneling is done. In BIOS settings this is typically called *Display Port Only*. usbonly The firmware automatically creates tunnels for the USB controller and Display Port in a dock. All PCIe links downstream of the dock are removed. nopcie PCIe tunneling is disabled/forbidden from the BIOS. Available in some USB4 systems. h]hdefinition_list)}(hhh](hdefinition_list_item)}(hnone All devices are automatically connected by the firmware. No user approval is needed. In BIOS settings this is typically called *Legacy mode*. h](hterm)}(hnoneh]hnone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK:hjubh definition)}(hhh]h)}(hAll devices are automatically connected by the firmware. No user approval is needed. In BIOS settings this is typically called *Legacy mode*.h](hAll devices are automatically connected by the firmware. No user approval is needed. In BIOS settings this is typically called }(hjhhhNhNubhemphasis)}(h *Legacy mode*h]h Legacy mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK8hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK:hjubj)}(hXuser User is asked whether the device is allowed to be connected. Based on the device identification information available through ``/sys/bus/thunderbolt/devices``, the user then can make the decision. In BIOS settings this is typically called *Unique ID*. h](j)}(huserh]huser}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK@hj ubj)}(hhh]h)}(hUser is asked whether the device is allowed to be connected. Based on the device identification information available through ``/sys/bus/thunderbolt/devices``, the user then can make the decision. In BIOS settings this is typically called *Unique ID*.h](h~User is asked whether the device is allowed to be connected. Based on the device identification information available through }(hjhhhNhNubh)}(h ``/sys/bus/thunderbolt/devices``h]h/sys/bus/thunderbolt/devices}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhQ, the user then can make the decision. In BIOS settings this is typically called }(hjhhhNhNubj)}(h *Unique ID*h]h Unique ID}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK=hjubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhK@hjubj)}(hX8secure User is asked whether the device is allowed to be connected. In addition to UUID the device (if it supports secure connect) is sent a challenge that should match the expected one based on a random key written to the ``key`` sysfs attribute. In BIOS settings this is typically called *One time saved key*. h](j)}(hsecureh]hsecure}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKGhj]ubj)}(hhh]h)}(hX0User is asked whether the device is allowed to be connected. In addition to UUID the device (if it supports secure connect) is sent a challenge that should match the expected one based on a random key written to the ``key`` sysfs attribute. In BIOS settings this is typically called *One time saved key*.h](hUser is asked whether the device is allowed to be connected. In addition to UUID the device (if it supports secure connect) is sent a challenge that should match the expected one based on a random key written to the }(hjrhhhNhNubh)}(h``key``h]hkey}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjrubh< sysfs attribute. In BIOS settings this is typically called }(hjrhhhNhNubj)}(h*One time saved key*h]hOne time saved key}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjrubh.}(hjrhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKChjoubah}(h]h ]h"]h$]h&]uh1jhj]ubeh}(h]h ]h"]h$]h&]uh1jhhhKGhjubj)}(hdponly The firmware automatically creates tunnels for Display Port and USB. No PCIe tunneling is done. In BIOS settings this is typically called *Display Port Only*. h](j)}(hdponlyh]hdponly}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKLhjubj)}(hhh]h)}(hThe firmware automatically creates tunnels for Display Port and USB. No PCIe tunneling is done. In BIOS settings this is typically called *Display Port Only*.h](hThe firmware automatically creates tunnels for Display Port and USB. No PCIe tunneling is done. In BIOS settings this is typically called }(hjhhhNhNubj)}(h*Display Port Only*h]hDisplay Port Only}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKJhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKLhjubj)}(husbonly The firmware automatically creates tunnels for the USB controller and Display Port in a dock. All PCIe links downstream of the dock are removed. h](j)}(husbonlyh]husbonly}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKQhjubj)}(hhh]h)}(hThe firmware automatically creates tunnels for the USB controller and Display Port in a dock. All PCIe links downstream of the dock are removed.h]hThe firmware automatically creates tunnels for the USB controller and Display Port in a dock. All PCIe links downstream of the dock are removed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKQhjubj)}(h[nopcie PCIe tunneling is disabled/forbidden from the BIOS. Available in some USB4 systems. h](j)}(hnopcieh]hnopcie}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKUhj ubj)}(hhh]h)}(hSPCIe tunneling is disabled/forbidden from the BIOS. Available in some USB4 systems.h]hSPCIe tunneling is disabled/forbidden from the BIOS. Available in some USB4 systems.}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThj2ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhKUhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhhhK7hj!hhubh)}(hThe current security level can be read from ``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is the Thunderbolt domain the host controller manages. There is typically one domain per Thunderbolt host controller.h](h,The current security level can be read from }(hj[hhhNhNubh)}(h1``/sys/bus/thunderbolt/devices/domainX/security``h]h-/sys/bus/thunderbolt/devices/domainX/security}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhj[ubh where }(hj[hhhNhNubh)}(h ``domainX``h]hdomainX}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj[ubhv is the Thunderbolt domain the host controller manages. There is typically one domain per Thunderbolt host controller.}(hj[hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKWhj!hhubh)}(hIf the security level reads as ``user`` or ``secure`` the connected device must be authorized by the user before PCIe tunnels are created (e.g the PCIe device appears).h](hIf the security level reads as }(hjhhhNhNubh)}(h``user``h]huser}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh or }(hjhhhNhNubh)}(h ``secure``h]hsecure}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhs the connected device must be authorized by the user before PCIe tunnels are created (e.g the PCIe device appears).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK\hj!hhubh)}(hEach Thunderbolt device plugged in will appear in sysfs under ``/sys/bus/thunderbolt/devices``. The device directory carries information that can be used to identify the particular device, including its name and UUID.h](h>Each Thunderbolt device plugged in will appear in sysfs under }(hjhhhNhNubh)}(h ``/sys/bus/thunderbolt/devices``h]h/sys/bus/thunderbolt/devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh{. The device directory carries information that can be used to identify the particular device, including its name and UUID.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK`hj!hhubeh}(h]#security-levels-and-how-to-use-themah ]h"]#security levels and how to use themah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hAAuthorizing devices when security level is ``user`` or ``secure``h](h+Authorizing devices when security level is }(hjhhhNhNubh)}(h``user``h]huser}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh or }(hjhhhNhNubh)}(h ``secure``h]hsecure}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]uh1hhjhhhhhKfubh)}(h@When a device is plugged in it will appear in sysfs as follows::h]h?When a device is plugged in it will appear in sysfs as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKghjhhubjo)}(hX}/sys/bus/thunderbolt/devices/0-1/authorized - 0 /sys/bus/thunderbolt/devices/0-1/device - 0x8004 /sys/bus/thunderbolt/devices/0-1/device_name - Thunderbolt to FireWire Adapter /sys/bus/thunderbolt/devices/0-1/vendor - 0x1 /sys/bus/thunderbolt/devices/0-1/vendor_name - Apple, Inc. /sys/bus/thunderbolt/devices/0-1/unique_id - e0376f00-0300-0100-ffff-ffffffffffffh]hX}/sys/bus/thunderbolt/devices/0-1/authorized - 0 /sys/bus/thunderbolt/devices/0-1/device - 0x8004 /sys/bus/thunderbolt/devices/0-1/device_name - Thunderbolt to FireWire Adapter /sys/bus/thunderbolt/devices/0-1/vendor - 0x1 /sys/bus/thunderbolt/devices/0-1/vendor_name - Apple, Inc. /sys/bus/thunderbolt/devices/0-1/unique_id - e0376f00-0300-0100-ffff-ffffffffffff}hj&sbah}(h]h ]h"]h$]h&]hhuh1jnhhhKihjhhubh)}(hThe ``authorized`` attribute reads 0 which means no PCIe tunnels are created yet. The user can authorize the device by simply entering::h](hThe }(hj4hhhNhNubh)}(h``authorized``h]h authorized}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj4ubhu attribute reads 0 which means no PCIe tunnels are created yet. The user can authorize the device by simply entering:}(hj4hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKphjhhubjo)}(h6# echo 1 > /sys/bus/thunderbolt/devices/0-1/authorizedh]h6# echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized}hjTsbah}(h]h ]h"]h$]h&]hhuh1jnhhhKshjhhubh)}(hBThis will create the PCIe tunnels and the device is now connected.h]hBThis will create the PCIe tunnels and the device is now connected.}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKuhjhhubh)}(hIf the device supports secure connect, and the domain security level is set to ``secure``, it has an additional attribute ``key`` which can hold a random 32-byte value used for authorization and challenging the device in future connects::h](hOIf the device supports secure connect, and the domain security level is set to }(hjphhhNhNubh)}(h ``secure``h]hsecure}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjpubh!, it has an additional attribute }(hjphhhNhNubh)}(h``key``h]hkey}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjpubhl which can hold a random 32-byte value used for authorization and challenging the device in future connects:}(hjphhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKwhjhhubjo)}(hX/sys/bus/thunderbolt/devices/0-3/authorized - 0 /sys/bus/thunderbolt/devices/0-3/device - 0x305 /sys/bus/thunderbolt/devices/0-3/device_name - AKiTiO Thunder3 PCIe Box /sys/bus/thunderbolt/devices/0-3/key - /sys/bus/thunderbolt/devices/0-3/vendor - 0x41 /sys/bus/thunderbolt/devices/0-3/vendor_name - inXtron /sys/bus/thunderbolt/devices/0-3/unique_id - dc010000-0000-8508-a22d-32ca6421cb16h]hX/sys/bus/thunderbolt/devices/0-3/authorized - 0 /sys/bus/thunderbolt/devices/0-3/device - 0x305 /sys/bus/thunderbolt/devices/0-3/device_name - AKiTiO Thunder3 PCIe Box /sys/bus/thunderbolt/devices/0-3/key - /sys/bus/thunderbolt/devices/0-3/vendor - 0x41 /sys/bus/thunderbolt/devices/0-3/vendor_name - inXtron /sys/bus/thunderbolt/devices/0-3/unique_id - dc010000-0000-8508-a22d-32ca6421cb16}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhK|hjhhubh)}(h#Notice the key is empty by default.h]h#Notice the key is empty by default.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hIf the user does not want to use secure connect they can just ``echo 1`` to the ``authorized`` attribute and the PCIe tunnels will be created in the same way as in the ``user`` security level.h](h>If the user does not want to use secure connect they can just }(hjhhhNhNubh)}(h ``echo 1``h]hecho 1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh to the }(hjhhhNhNubh)}(h``authorized``h]h authorized}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhJ attribute and the PCIe tunnels will be created in the same way as in the }(hjhhhNhNubh)}(h``user``h]huser}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh security level.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hIf the user wants to use secure connect, the first time the device is plugged a key needs to be created and sent to the device::h]hIf the user wants to use secure connect, the first time the device is plugged a key needs to be created and sent to the device:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjo)}(h# key=$(openssl rand -hex 32) # echo $key > /sys/bus/thunderbolt/devices/0-3/key # echo 1 > /sys/bus/thunderbolt/devices/0-3/authorizedh]h# key=$(openssl rand -hex 32) # echo $key > /sys/bus/thunderbolt/devices/0-3/key # echo 1 > /sys/bus/thunderbolt/devices/0-3/authorized}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhKhjhhubh)}(hkNow the device is connected (PCIe tunnels are created) and in addition the key is stored on the device NVM.h]hkNow the device is connected (PCIe tunnels are created) and in addition the key is stored on the device NVM.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hbNext time the device is plugged in the user can verify (challenge) the device using the same key::h]haNext time the device is plugged in the user can verify (challenge) the device using the same key:}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjo)}(hi# echo $key > /sys/bus/thunderbolt/devices/0-3/key # echo 2 > /sys/bus/thunderbolt/devices/0-3/authorizedh]hi# echo $key > /sys/bus/thunderbolt/devices/0-3/key # echo 2 > /sys/bus/thunderbolt/devices/0-3/authorized}hj:sbah}(h]h ]h"]h$]h&]hhuh1jnhhhKhjhhubh)}(hIf the challenge the device returns back matches the one we expect based on the key, the device is connected and the PCIe tunnels are created. However, if the challenge fails no tunnels are created and error is returned to the user.h]hIf the challenge the device returns back matches the one we expect based on the key, the device is connected and the PCIe tunnels are created. However, if the challenge fails no tunnels are created and error is returned to the user.}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hIf the user still wants to connect the device they can either approve the device without a key or write a new key and write 1 to the ``authorized`` file to get the new key stored on the device NVM.h](hIf the user still wants to connect the device they can either approve the device without a key or write a new key and write 1 to the }(hjVhhhNhNubh)}(h``authorized``h]h authorized}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjVubh2 file to get the new key stored on the device NVM.}(hjVhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]9authorizing-devices-when-security-level-is-user-or-secureah ]h"]9authorizing devices when security level is user or secureah$]h&]uh1hhhhhhhhKfubh)}(hhh](h)}(hDe-authorizing devicesh]hDe-authorizing devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj~hhhhhKubh)}(hXIt is possible to de-authorize devices by writing ``0`` to their ``authorized`` attribute. This requires support from the connection manager implementation and can be checked by reading domain ``deauthorization`` attribute. If it reads ``1`` then the feature is supported.h](h2It is possible to de-authorize devices by writing }(hjhhhNhNubh)}(h``0``h]h0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh to their }(hjhhhNhNubh)}(h``authorized``h]h authorized}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhr attribute. This requires support from the connection manager implementation and can be checked by reading domain }(hjhhhNhNubh)}(h``deauthorization``h]hdeauthorization}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh attribute. If it reads }(hjhhhNhNubh)}(h``1``h]h1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh then the feature is supported.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj~hhubh)}(hXWhen a device is de-authorized the PCIe tunnel from the parent device PCIe downstream (or root) port to the device PCIe upstream port is torn down. This is essentially the same thing as PCIe hot-remove and the PCIe toplogy in question will not be accessible anymore until the device is authorized again. If there is storage such as NVMe or similar involved, there is a risk for data loss if the filesystem on that storage is not properly shut down. You have been warned!h]hXWhen a device is de-authorized the PCIe tunnel from the parent device PCIe downstream (or root) port to the device PCIe upstream port is torn down. This is essentially the same thing as PCIe hot-remove and the PCIe toplogy in question will not be accessible anymore until the device is authorized again. If there is storage such as NVMe or similar involved, there is a risk for data loss if the filesystem on that storage is not properly shut down. You have been warned!}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj~hhubeh}(h]de-authorizing-devicesah ]h"]de-authorizing devicesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hDMA protection utilizing IOMMUh]hDMA protection utilizing IOMMU}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXRecent systems from 2018 and forward with Thunderbolt ports may natively support IOMMU. This means that Thunderbolt security is handled by an IOMMU so connected devices cannot access memory regions outside of what is allocated for them by drivers. When Linux is running on such system it automatically enables IOMMU if not enabled by the user already. These systems can be identified by reading ``1`` from ``/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection`` attribute.h](hXRecent systems from 2018 and forward with Thunderbolt ports may natively support IOMMU. This means that Thunderbolt security is handled by an IOMMU so connected devices cannot access memory regions outside of what is allocated for them by drivers. When Linux is running on such system it automatically enables IOMMU if not enabled by the user already. These systems can be identified by reading }(hj hhhNhNubh)}(h``1``h]h1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh from }(hj hhhNhNubh)}(h=``/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection``h]h9/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh attribute.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXThe driver does not do anything special in this case but because DMA protection is handled by the IOMMU, security levels (if set) are redundant. For this reason some systems ship with security level set to ``none``. Other systems have security level set to ``user`` in order to support downgrade to older OS, so users who want to automatically authorize devices when IOMMU DMA protection is enabled can use the following ``udev`` rule::h](hThe driver does not do anything special in this case but because DMA protection is handled by the IOMMU, security levels (if set) are redundant. For this reason some systems ship with security level set to }(hj>hhhNhNubh)}(h``none``h]hnone}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>ubh+. Other systems have security level set to }(hj>hhhNhNubh)}(h``user``h]huser}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>ubh in order to support downgrade to older OS, so users who want to automatically authorize devices when IOMMU DMA protection is enabled can use the following }(hj>hhhNhNubh)}(h``udev``h]hudev}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>ubh rule:}(hj>hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjo)}(hvACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1"h]hvACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1"}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhKhjhhubeh}(h]dma-protection-utilizing-iommuah ]h"]dma protection utilizing iommuah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h4Upgrading NVM on Thunderbolt device, host or retimerh]h4Upgrading NVM on Thunderbolt device, host or retimer}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hX Since most of the functionality is handled in firmware running on a host controller or a device, it is important that the firmware can be upgraded to the latest where possible bugs in it have been fixed. Typically OEMs provide this firmware from their support site.h]hX Since most of the functionality is handled in firmware running on a host controller or a device, it is important that the firmware can be upgraded to the latest where possible bugs in it have been fixed. Typically OEMs provide this firmware from their support site.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX$Currently, recommended method of updating firmware is through "fwupd" tool. It uses LVFS (Linux Vendor Firmware Service) portal by default to get the latest firmware from hardware vendors and updates connected devices if found compatible. For details refer to: https://github.com/fwupd/fwupd.h](hX Currently, recommended method of updating firmware is through “fwupd” tool. It uses LVFS (Linux Vendor Firmware Service) portal by default to get the latest firmware from hardware vendors and updates connected devices if found compatible. For details refer to: }(hjhhhNhNubh reference)}(hhttps://github.com/fwupd/fwupdh]hhttps://github.com/fwupd/fwupd}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hBefore you upgrade firmware on a device, host or retimer, please make sure it is a suitable upgrade. Failing to do that may render the device in a state where it cannot be used properly anymore without special tools!h]hBefore you upgrade firmware on a device, host or retimer, please make sure it is a suitable upgrade. Failing to do that may render the device in a state where it cannot be used properly anymore without special tools!}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h0Host NVM upgrade on Apple Macs is not supported.h]h0Host NVM upgrade on Apple Macs is not supported.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(huFwupd is installed by default. If you don't have it on your system, simply use your distro package manager to get it.h]hwFwupd is installed by default. If you don’t have it on your system, simply use your distro package manager to get it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hTo see possible updates through fwupd, you need to plug in a Thunderbolt device so that the host controller appears. It does not matter which device is connected (unless you are upgrading NVM on a device - then you need to connect that particular device).h]hTo see possible updates through fwupd, you need to plug in a Thunderbolt device so that the host controller appears. It does not matter which device is connected (unless you are upgrading NVM on a device - then you need to connect that particular device).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hNote an OEM-specific method to power the controller up ("force power") may be available for your system in which case there is no need to plug in a Thunderbolt device.h]hNote an OEM-specific method to power the controller up (“force power”) may be available for your system in which case there is no need to plug in a Thunderbolt device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h\Updating firmware using fwupd is straightforward - refer to official readme on fwupd github.h]h\Updating firmware using fwupd is straightforward - refer to official readme on fwupd github.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hIf firmware image is written successfully, the device shortly disappears. Once it comes back, the driver notices it and initiates a full power cycle. After a while device appears again and this time it should be fully functional.h]hIf firmware image is written successfully, the device shortly disappears. Once it comes back, the driver notices it and initiates a full power cycle. After a while device appears again and this time it should be fully functional.}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hwDevice of interest should display new version under "Current version" and "Update State: Success" in fwupd's interface.h]hDevice of interest should display new version under “Current version” and “Update State: Success” in fwupd’s interface.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]3upgrading-nvm-on-thunderbolt-device-host-or-retimerah ]h"]4upgrading nvm on thunderbolt device, host or retimerah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hUpgrading firmware manuallyh]hUpgrading firmware manually}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjRhhhhhKubh)}(hIf possible, use fwupd to updated the firmware. However, if your device OEM has not uploaded the firmware to LVFS, but it is available for download from their side, you can use method below to directly upgrade the firmware.h]hIf possible, use fwupd to updated the firmware. However, if your device OEM has not uploaded the firmware to LVFS, but it is available for download from their side, you can use method below to directly upgrade the firmware.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjRhhubh)}(hManual firmware update can be done with 'dd' tool. To update firmware using this method, you need to write it to the non-active parts of NVM of the host or device. Example on how to update Intel NUC6i7KYK (Skull Canyon) Thunderbolt controller NVM::h]hManual firmware update can be done with ‘dd’ tool. To update firmware using this method, you need to write it to the non-active parts of NVM of the host or device. Example on how to update Intel NUC6i7KYK (Skull Canyon) Thunderbolt controller NVM:}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjRhhubjo)}(hU# dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmemh]hU# dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmem}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhKhjRhhubh)}(h_Once the operation completes we can trigger NVM authentication and upgrade process as follows::h]h^Once the operation completes we can trigger NVM authentication and upgrade process as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjRhhubjo)}(h<# echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticateh]h<# echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhjRhhubh)}(hQIf no errors are returned, device should behave as described in previous section.h]hQIf no errors are returned, device should behave as described in previous section.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjRhhubh)}(hUWe can verify that the new NVM firmware is active by running the following commands::h]hTWe can verify that the new NVM firmware is active by running the following commands:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjRhhubjo)}(hs# cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate 0x0 # cat /sys/bus/thunderbolt/devices/0-0/nvm_version 18.0h]hs# cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate 0x0 # cat /sys/bus/thunderbolt/devices/0-0/nvm_version 18.0}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhM hjRhhubh)}(hIf ``nvm_authenticate`` contains anything other than 0x0 it is the error code from the last authentication cycle, which means the authentication of the NVM image failed.h](hIf }(hjhhhNhNubh)}(h``nvm_authenticate``h]hnvm_authenticate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh contains anything other than 0x0 it is the error code from the last authentication cycle, which means the authentication of the NVM image failed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjRhhubh)}(hNote names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN`` depend on the order they are registered in the NVMem subsystem. N in the name is the identifier added by the NVMem subsystem.h](h Note names of the NVMem devices }(hjhhhNhNubh)}(h``nvm_activeN``h]h nvm_activeN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh and }(hjhhhNhNubh)}(h``nvm_non_activeN``h]hnvm_non_activeN}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh~ depend on the order they are registered in the NVMem subsystem. N in the name is the identifier added by the NVMem subsystem.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjRhhubeh}(h]upgrading-firmware-manuallyah ]h"]upgrading firmware manuallyah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h?Upgrading on-board retimer NVM when there is no cable connectedh]h?Upgrading on-board retimer NVM when there is no cable connected}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj-hhhhhMubh)}(hXDIf the platform supports, it may be possible to upgrade the retimer NVM firmware even when there is nothing connected to the USB4 ports. When this is the case the ``usb4_portX`` devices have two special attributes: ``offline`` and ``rescan``. The way to upgrade the firmware is to first put the USB4 port into offline mode::h](hIf the platform supports, it may be possible to upgrade the retimer NVM firmware even when there is nothing connected to the USB4 ports. When this is the case the }(hj>hhhNhNubh)}(h``usb4_portX``h]h usb4_portX}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>ubh& devices have two special attributes: }(hj>hhhNhNubh)}(h ``offline``h]hoffline}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>ubh and }(hj>hhhNhNubh)}(h ``rescan``h]hrescan}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>ubhR. The way to upgrade the firmware is to first put the USB4 port into offline mode:}(hj>hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj-hhubjo)}(h># echo 1 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/offlineh]h># echo 1 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/offline}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhj-hhubh)}(hThis step makes sure the port does not respond to any hotplug events, and also ensures the retimers are powered on. The next step is to scan for the retimers::h]hThis step makes sure the port does not respond to any hotplug events, and also ensures the retimers are powered on. The next step is to scan for the retimers:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM!hj-hhubjo)}(h=# echo 1 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/rescanh]h=# echo 1 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/rescan}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhM%hj-hhubh)}(hXHThis enumerates and adds the on-board retimers. Now retimer NVM can be upgraded in the same way than with cable connected (see previous section). However, the retimer is not disconnected as we are in offline mode, so after writing ``1`` to ``nvm_authenticate`` one should wait for 5 or more seconds before running rescan again::h](hThis enumerates and adds the on-board retimers. Now retimer NVM can be upgraded in the same way than with cable connected (see previous section). However, the retimer is not disconnected as we are in offline mode, so after writing }(hjhhhNhNubh)}(h``1``h]h1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh to }(hjhhhNhNubh)}(h``nvm_authenticate``h]hnvm_authenticate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhC one should wait for 5 or more seconds before running rescan again:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM'hj-hhubjo)}(h=# echo 1 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/rescanh]h=# echo 1 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/rescan}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhM-hj-hhubh)}(hXThis point if everything went fine, the port can be put back to functional state again::h]hWThis point if everything went fine, the port can be put back to functional state again:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM/hj-hhubjo)}(h># echo 0 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/offlineh]h># echo 0 > /sys/bus/thunderbolt/devices/0-0/usb4_port1/offline}hjsbah}(h]h ]h"]h$]h&]hhuh1jnhhhM2hj-hhubeh}(h]?upgrading-on-board-retimer-nvm-when-there-is-no-cable-connectedah ]h"]?upgrading on-board retimer nvm when there is no cable connectedah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h2Upgrading NVM when host controller is in safe modeh]h2Upgrading NVM when host controller is in safe mode}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM5ubh)}(hX0If the existing NVM is not properly authenticated (or is missing) the host controller goes into safe mode which means that the only available functionality is flashing a new NVM image. When in this mode, reading ``nvm_version`` fails with ``ENODATA`` and the device identification information is missing.h](hIf the existing NVM is not properly authenticated (or is missing) the host controller goes into safe mode which means that the only available functionality is flashing a new NVM image. When in this mode, reading }(hj! hhhNhNubh)}(h``nvm_version``h]h nvm_version}(hj) hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj! ubh fails with }(hj! hhhNhNubh)}(h ``ENODATA``h]hENODATA}(hj; hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj! ubh6 and the device identification information is missing.}(hj! hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM6hj hhubh)}(hTo recover from this mode, one needs to flash a valid NVM image to the host controller in the same way it is done in the previous chapter.h]hTo recover from this mode, one needs to flash a valid NVM image to the host controller in the same way it is done in the previous chapter.}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM<hj hhubeh}(h]2upgrading-nvm-when-host-controller-is-in-safe-modeah ]h"]2upgrading nvm when host controller is in safe modeah$]h&]uh1hhhhhhhhM5ubh)}(hhh](h)}(hTunneling eventsh]hTunneling events}(hjl hhhNhNubah}(h]h ]h"]h$]h&]uh1hhji hhhhhM@ubh)}(hThe driver sends ``KOBJ_CHANGE`` events to userspace when there is a tunneling change in the ``thunderbolt_domain``. The notification carries following environment variables::h](hThe driver sends }(hjz hhhNhNubh)}(h``KOBJ_CHANGE``h]h KOBJ_CHANGE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjz ubh= events to userspace when there is a tunneling change in the }(hjz hhhNhNubh)}(h``thunderbolt_domain``h]hthunderbolt_domain}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjz ubh;. The notification carries following environment variables:}(hjz hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMAhji hhubjo)}(h8TUNNEL_EVENT= TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)h]h8TUNNEL_EVENT= TUNNEL_DETAILS=0:12 <-> 1:20 (USB3)}hj sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMEhji hhubh)}(h$Possible values for ```` are:h](hPossible values for }(hj hhhNhNubh)}(h ````h]h}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh are:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMHhji hhubj)}(hXQactivated The tunnel was activated (created). changed There is a change in this tunnel. For example bandwidth allocation was changed. deactivated The tunnel was torn down. low bandwidth The tunnel is not getting optimal bandwidth. insufficient bandwidth There is not enough bandwidth for the current tunnel requirements. h]j)}(hhh](j)}(h.activated The tunnel was activated (created). h](j)}(h activatedh]h activated}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMKhj ubj)}(hhh]h)}(h#The tunnel was activated (created).h]h#The tunnel was activated (created).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMKhj ubj)}(hXchanged There is a change in this tunnel. For example bandwidth allocation was changed. h](j)}(hchangedh]hchanged}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMOhj ubj)}(hhh]h)}(hOThere is a change in this tunnel. For example bandwidth allocation was changed.h]hOThere is a change in this tunnel. For example bandwidth allocation was changed.}(hj% hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhj" ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMOhj ubj)}(h&deactivated The tunnel was torn down. h](j)}(h deactivatedh]h deactivated}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMRhj? ubj)}(hhh]h)}(hThe tunnel was torn down.h]hThe tunnel was torn down.}(hjT hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjQ ubah}(h]h ]h"]h$]h&]uh1jhj? ubeh}(h]h ]h"]h$]h&]uh1jhhhMRhj ubj)}(h;low bandwidth The tunnel is not getting optimal bandwidth. h](j)}(h low bandwidthh]h low bandwidth}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMUhjn ubj)}(hhh]h)}(h,The tunnel is not getting optimal bandwidth.h]h,The tunnel is not getting optimal bandwidth.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMUhj ubah}(h]h ]h"]h$]h&]uh1jhjn ubeh}(h]h ]h"]h$]h&]uh1jhhhMUhj ubj)}(hZinsufficient bandwidth There is not enough bandwidth for the current tunnel requirements. h](j)}(hinsufficient bandwidthh]hinsufficient bandwidth}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMXhj ubj)}(hhh]h)}(hBThere is not enough bandwidth for the current tunnel requirements.h]hBThere is not enough bandwidth for the current tunnel requirements.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMXhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jhhhMJhji hhubh)}(hXUThe ``TUNNEL_DETAILS`` is only provided if the tunnel is known. For example, in case of Firmware Connection Manager this is missing or does not provide full tunnel information. In case of Software Connection Manager this includes full tunnel details. The format currently matches what the driver uses when logging. This may change over time.h](hThe }(hj hhhNhNubh)}(h``TUNNEL_DETAILS``h]hTUNNEL_DETAILS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhX? is only provided if the tunnel is known. For example, in case of Firmware Connection Manager this is missing or does not provide full tunnel information. In case of Software Connection Manager this includes full tunnel details. The format currently matches what the driver uses when logging. This may change over time.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMZhji hhubeh}(h]tunneling-eventsah ]h"]tunneling eventsah$]h&]uh1hhhhhhhhM@ubh)}(hhh](h)}(h!Networking over Thunderbolt cableh]h!Networking over Thunderbolt cable}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMaubh)}(hhThunderbolt technology allows software communication between two hosts connected by a Thunderbolt cable.h]hhThunderbolt technology allows software communication between two hosts connected by a Thunderbolt cable.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMbhj hhubh)}(hIt is possible to tunnel any kind of traffic over a Thunderbolt link but currently we only support Apple ThunderboltIP protocol.h]hIt is possible to tunnel any kind of traffic over a Thunderbolt link but currently we only support Apple ThunderboltIP protocol.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMehj hhubh)}(hX7If the other host is running Windows or macOS, the only thing you need to do is to connect a Thunderbolt cable between the two hosts; the ``thunderbolt-net`` driver is loaded automatically. If the other host is also Linux you should load ``thunderbolt-net`` manually on one host (it does not matter which one)::h](hIf the other host is running Windows or macOS, the only thing you need to do is to connect a Thunderbolt cable between the two hosts; the }(hj- hhhNhNubh)}(h``thunderbolt-net``h]hthunderbolt-net}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj- ubhQ driver is loaded automatically. If the other host is also Linux you should load }(hj- hhhNhNubh)}(h``thunderbolt-net``h]hthunderbolt-net}(hjG hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj- ubh5 manually on one host (it does not matter which one):}(hj- hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhhj hhubjo)}(h# modprobe thunderbolt-neth]h# modprobe thunderbolt-net}hj_ sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMnhj hhubh)}(hThis triggers module load on the other host automatically. If the driver is built-in to the kernel image, there is no need to do anything.h]hThis triggers module load on the other host automatically. If the driver is built-in to the kernel image, there is no need to do anything.}(hjm hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMphj hhubh)}(hXThe driver will create one virtual ethernet interface per Thunderbolt port which are named like ``thunderbolt0`` and so on. From this point you can either use standard userspace tools like ``ip`` to configure the interface or let your GUI handle it automatically.h](h`The driver will create one virtual ethernet interface per Thunderbolt port which are named like }(hj{ hhhNhNubh)}(h``thunderbolt0``h]h thunderbolt0}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{ ubhM and so on. From this point you can either use standard userspace tools like }(hj{ hhhNhNubh)}(h``ip``h]hip}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{ ubhD to configure the interface or let your GUI handle it automatically.}(hj{ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMshj hhubeh}(h]!networking-over-thunderbolt-cableah ]h"]!networking over thunderbolt cableah$]h&]uh1hhhhhhhhMaubh)}(hhh](h)}(h.Streaming data directly over Thunderbolt cableh]h.Streaming data directly over Thunderbolt cable}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMyubh)}(hIn addition to Thunderbolt networking (aka. USB4NET) Linux supports streaming data directly over a cable as well (aka. USB4STREAM). This is possible through ``thunderbolt-stream`` driver.h](hIn addition to Thunderbolt networking (aka. USB4NET) Linux supports streaming data directly over a cable as well (aka. USB4STREAM). This is possible through }(hj hhhNhNubh)}(h``thunderbolt-stream``h]hthunderbolt-stream}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh driver.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMzhj hhubh)}(hGSimilarly to ``thunderbolt-net`` you load the driver first on one end::h](h Similarly to }(hj hhhNhNubh)}(h``thunderbolt-net``h]hthunderbolt-net}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh& you load the driver first on one end:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM~hj hhubjo)}(h#host1 # modprobe thunderbolt-streamh]h#host1 # modprobe thunderbolt-stream}hj sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhj hhubh)}(h(Then you configure it via ``ConfigFS``::h](hThen you configure it via }(hj hhhNhNubh)}(h ``ConfigFS``h]hConfigFS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjo)}(hhost1 # cd /sys/kernel/config/thunderbolt/stream host1 # mkdir -p 0-1.0/data host1 # cd 0-1.0 host1 # echo -1 > data/in_hopid host1 # echo -1 > data/out_hopidh]hhost1 # cd /sys/kernel/config/thunderbolt/stream host1 # mkdir -p 0-1.0/data host1 # cd 0-1.0 host1 # echo -1 > data/in_hopid host1 # echo -1 > data/out_hopid}hj4 sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhj hhubh)}(hThis information is automatically announced to the other side via XDomain properties so if you have cable connected the other side knows that there is a stream named ``data`` available and can configure it for you automatically::h](hThis information is automatically announced to the other side via XDomain properties so if you have cable connected the other side knows that there is a stream named }(hjB hhhNhNubh)}(h``data``h]hdata}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjB ubh6 available and can configure it for you automatically:}(hjB hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjo)}(hLhost2 # cd /sys/kernel/config/thunderbolt/stream host2 # mkdir -p 0-3.0/datah]hLhost2 # cd /sys/kernel/config/thunderbolt/stream host2 # mkdir -p 0-3.0/data}hjb sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhj hhubh)}(hHere we used auto-configuration but you can configure it manually too. In that case you need to fill ``in_hopid`` and ``out_hopid`` accordingly. If you set them to ``-1`` the next available HopID is used which is typically what we want.h](heHere we used auto-configuration but you can configure it manually too. In that case you need to fill }(hjp hhhNhNubh)}(h ``in_hopid``h]hin_hopid}(hjx hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjp ubh and }(hjp hhhNhNubh)}(h ``out_hopid``h]h out_hopid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjp ubh! accordingly. If you set them to }(hjp hhhNhNubh)}(h``-1``h]h-1}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjp ubhB the next available HopID is used which is typically what we want.}(hjp hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXOnce they are configured you can use ``/dev/tbstreamX`` on both sides to transfer data::h](h%Once they are configured you can use }(hj hhhNhNubh)}(h``/dev/tbstreamX``h]h/dev/tbstreamX}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh on both sides to transfer data:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjo)}(h9host2 # cat /dev/tbstream0 host1 # dmesg > /dev/tbstream0h]h9host2 # cat /dev/tbstream0 host1 # dmesg > /dev/tbstream0}hj sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhj hhubh)}(h7Once you are done with the stream you can remove them::h]h6Once you are done with the stream you can remove them:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjo)}(hhost2 # cd /sys/kernel/config/thunderbolt/stream host2 # rmdir -p 0-1.0/data host1 # cd /sys/kernel/config/thunderbolt/stream host1 # rmdir -p 0-3.0/datah]hhost2 # cd /sys/kernel/config/thunderbolt/stream host2 # rmdir -p 0-1.0/data host1 # cd /sys/kernel/config/thunderbolt/stream host1 # rmdir -p 0-3.0/data}hj sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhj hhubh)}(hSince streams are essentially files you can use any existing application that supports ``read(2)`` and ``write(2)`` in some form.h](hWSince streams are essentially files you can use any existing application that supports }(hj hhhNhNubh)}(h ``read(2)``h]hread(2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh and }(hj hhhNhNubh)}(h ``write(2)``h]hwrite(2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh in some form.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hIt is possible to have more than one stream and you can have both stream and ``thunderbolt-net`` in use simultaneously. For example we can create two streams with name ``control`` and ``data`` like this::h](hMIt is possible to have more than one stream and you can have both stream and }(hj0 hhhNhNubh)}(h``thunderbolt-net``h]hthunderbolt-net}(hj8 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj0 ubhH in use simultaneously. For example we can create two streams with name }(hj0 hhhNhNubh)}(h ``control``h]hcontrol}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj0 ubh and }(hj0 hhhNhNubh)}(h``data``h]hdata}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj0 ubh like this:}(hj0 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjo)}(h~host1 # cd /sys/kernel/config/thunderbolt/stream host1 # mkdir 0-1.0 host1 # cd 0-1.0 host1 # mkdir control host1 # mkdir datah]h~host1 # cd /sys/kernel/config/thunderbolt/stream host1 # mkdir 0-1.0 host1 # cd 0-1.0 host1 # mkdir control host1 # mkdir data}hjt sbah}(h]h ]h"]h$]h&]hhuh1jnhhhMhj hhubh)}(hThen you have ``/dev/tbstream0`` for ``control`` and ``/dev/tbstream1`` for ``data``. Before you can use them you need to configure them as shown above for the one stream case.h](hThen you have }(hj hhhNhNubh)}(h``/dev/tbstream0``h]h/dev/tbstream0}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh for }(hj hhhNhNubh)}(h ``control``h]hcontrol}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh and }(hj hhhNhNubh)}(h``/dev/tbstream1``h]h/dev/tbstream1}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh for }(hj hhhNhNubh)}(h``data``h]hdata}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh\. Before you can use them you need to configure them as shown above for the one stream case.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h].streaming-data-directly-over-thunderbolt-cableah ]h"].streaming data directly over thunderbolt cableah$]h&]uh1hhhhhhhhMyubh)}(hhh](h)}(h Forcing powerh]h Forcing power}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXGMany OEMs include a method that can be used to force the power of a Thunderbolt controller to an "On" state even if nothing is connected. If supported by your machine this will be exposed by the WMI bus with a sysfs attribute called "force_power", see Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt for details.R h]hXOMany OEMs include a method that can be used to force the power of a Thunderbolt controller to an “On” state even if nothing is connected. If supported by your machine this will be exposed by the WMI bus with a sysfs attribute called “force_power”, see Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt for details.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hONote: it's currently not possible to query the force power state of a platform.h]hQNote: it’s currently not possible to query the force power state of a platform.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h] forcing-powerah ]h"] forcing powerah$]h&]uh1hhhhhhhhMubeh}(h]usb4-and-thunderboltah ]h"]usb4 and thunderboltah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj@error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjjjj{jxjjjjjOjLj*j'j j jf jc j j j j j j jju nametypes}(jjj{jjjOj*j jf j j j juh}(jhjj!jxjjj~jjjLjj'jRj j-jc j j ji j j j j jj u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.