• Become a Premium Member for $25/year with no ads to improve your community experience.

EliteMacx86

Administrator
Staff member
Joined
Jul 22, 2018
Messages
6,695
Motherboard
Supermicro X11SPA-T
CPU
Intel Xeon W-3275 28 Core
Graphics
2xAMD RX 580 8GB
OS X/macOS
13.x
Bootloader
  1. OpenCore (UEFI)
Mac
  1. Mac mini
  2. MacBook Pro
Mobile Phone
  1. Android
  2. iOS
How to Enable Thunderbolt 3 Hotplug on macOS [Clover/OpenCore]
An EliteMacx86 Exclusive Guide - This guide covers the implementation of Thunderbolt™ 3 Hotplug on macOS for single and multiple Thunderbolt 3 Cards.

Overview


An EliteMacx86 Exclusive Guide - In our previous post, we covered a guide about the implementation of Thunderbolt on macOS. This guide covers the implementation of Thunderbolt 3 Hotplug. By following this guide, you'll be able to use HotPlug function on macOS for your Thunderbolt 3.

You can read about the implementation of Thunderbolt 3 here:

For more information on Thunderbolt 4 Hotplug, refer to the guide linked below.

Implementation of Hotplug with Thunderbolt has been always a major issue with macOS. But Thanks to users like KGP who have been able to implement it on the hardware. The reason for the not working of Hotplug with the Thunderbolt is due to the working style of thunderbolt on both the platform i.e. Windows and Mac. On Windows hardware, the working of Thunderbolt is different as compared to a real Macintosh.

Before getting into it, let's get to know about the working of ThunderBolt on Mac and Windows hardware which will help you to understand the working of Hotplug.

On Windows hardware, the Thunderbolt is only powered up when any Thunderbolt compatible Device is connected. The device triggers the thunderbolt to function and turns on the power to the connected device. Once, it's disconnected, the power to the port is also turned off.

On the other hand, on Mac, it's not the same. On Mac, the Thunderbolt is always on until the system is turned off. When any device is connected to the Thunderbolt port, the Device automatically connects to the thunderbolt and this is the reason the hotplug basically works. The Thunderbolt is always active as it keeps drawing the power.

On the Hackintosh, it's a little bit different or you can say, it's mixed. The thunderbolt will function only if the device is connected before booting to macOS i.e preboot mode. If you disconnect it, the device no longer functions and you need to restart the system again. Hence, the system is not capable of Hotplug.

But by using this guide, you would be able to implement Hotplug.


USB Type-C® and Thunderbolt™ 3


With the introduction of Thunderbolt™ technology back in 2010, Thunderbolt 1 and 2 used the "mDP" connector type to connect. Fast forward to 2015, since the release of Thunderbolt 3, it uses the new "Type-C" connector as per the new industry standards. While it was easy to differentiate between Thunderbolt 1 and 2, it is a bit difficult for users who are new to this technology, to understand the difference between a USB Type-C and Thunderbolt 3 as both of these shares the same "Type-C" connector. Nonetheless, this is one of the most common questions we hear from users regarding the difference between USB-C and Thunderbolt 3.




One of the most common questions we hear from users is regarding the difference between USB-C and Thunderbolt 3.

USB Type-C, or USB-C, is a specification for connectors and cables.
  • Symmetrical and flip-able, or reversible. Both sides (top and bottom) can be inserted in the port in either direction, meaning that you no longer have to make sure a cable is inserted “right-side” up.
  • Delivery of up to 100W of power.
  • Supports alternate modes, such as DisplayPort, Thunderbolt, etc.
Thunderbolt 3 defines a superset of capabilities that runs on USB-C connectors and cables. In brief, Thunderbolt 3 brings Thunderbolt to USB-C. Here are the superset of features that Thunderbolt 3 provides:

  • At 40 Gbps, Thunderbolt 3 is the fastest connection available. By comparison, native USB 3.1 operates at 10 Gbps.
  • Thunderbolt 3 is bi-directional with four lanes of PCI Express Gen 3 and eight lanes of DisplayPort 1.2.
  • Now with a Thunderbolt 3 port, you can connect to any dock, device, or display, including billions of USB devices.

However, both, USB Type-C and Thunderbolt uses the same "Type-C" connector type to connect. Despite using the same "Type-C" connector type, it internally differs. When you connect a Thunderbolt Device on a system running macOS/OS X, it communicates with the NHI Driver and will connect to the Thunderbolt Bus (DSB1 and DSB4 ports) which is capable of delivering up to a maximum speed of 40Gb/s. Whereas, connecting a Type-C Device to the Thunderbolt Ports will communicate with the XHC Driver and fall back to the XHC Bus (typically SSP1 and SSP2 ports) instead of utilizing the Thunderbolt Bus and can deliver upto a maximum speed of 10Gb/s. If the connected Type-C Device is a USB 2.0 Device (such as iPhone, or iPad), it will communicate with Intel's "built-in" XHC Driver and fall back to the Intel XHC Bus (typically two of the HSXX ports) and can deliver upto a maximum speed of 480Mb/s respectively. See Thunderbolt Connection Modes for more information.

While some Dock (such as RazerBlade ) and Storage SSDs (such as Samsung T7) may use Type-C interface, they may not be actual Thunderbolt Devices (although Thunderbolt Compatible) and all such Devices will use the XHC Bus instead of the Thunderbolt Bus. A Thunderbolt Device will always have a discrete Thunderbolt Chip (Thunderbolt 1/Thunderbolt 2/Thunderbolt 3 or even Thunderbolt 4) on its board which communicates with the system's Thunderbolt Chip (either Onboard or AIC) and a connection is established.

In addition, there can be several other Devices that uses Type-C connector to connect but are not actually even Type-C i.e not capable of delivering Higher Speeds. The Type-C is capable of delivering up to a maximum speed of 5Gb/s (USB 3.1 Gen1) and 10Gb/s (USB 3.1 Gen2 and USB 3.2 Gen2) respectively. However, these devices (such as Audio Interface, Card Reader, iPhone or iPad) will just have the Type-C connector but still use the USB 2.0 Bus, which will fallback to the Intel's Onboard or "built-in" XHC Bus (typically HSXX ports) with a maximum speed of 480Mb/s. This means, when you connect these devices, instead of connecting to the XHC Bus (SSP1 and SSP2 Ports) on Thunderbolt Controller, it will route to Intel XHC Bus and will utilize the (HSXX) port.

Thunderbolt Connection Modes


With Thunderbolt 3 having dynamic detection of the capabilities of the cables and devices that are plugged in, there are several modes that can be detected and activated. This allows connecting devices with different capabilities, without the need for any additional configuration as the switching between operating modes takes place automatically and not limiting it to a particular device capability. This not only gives the ability to connect different devices with different capabilities but also does not requires the user to change the system for each of the devices to support or vice-versa.

When devices with different capabilities are connected, the connection will only support the lowest common data rate. For example, you can plug a USB 3.2 cable into a Thunderbolt™ 3 port, and the port will negotiate data, power, and video signal capabilities with the connected device at a USB 3.2 level. Depending on the device connected, the protocol will negotiate what operating mode to enter and the function to deliver. This detection happens automatically based on the device protocol and is achieved by a physical interface (PHY) layer that can dynamically switch its operating mode to drive either:

– USB 2.0, 3.0, and 3.1
– DisplayPort 1.1 and 1.2a
– Thunderbolt at 20 and 40 Gbps

USB Only Mode
If a USB device is plugged in, a USB host controller inside the Thunderbolt 3 enabled system is activated, and the Thunderbolt 3 silicon PHY drives USB (2.0, 3.0, or 3.1) signals to the USB-C port. In this mode, a Thunderbolt 3 port behaves exactly like a typical USB-C 3.1 enabled connector.

DisplayPort Only Mode
If a DisplayPort display or adapter is plugged in, the Thunderbolt 3 enabled system will detect this, and switch the pins driving the USB-C connector to the DisplayPort alternate mode. Thunderbolt 3 silicon will then act as a router to send raw DisplayPort traffic from the graphics engine within the system out over the USB-C connector pins and pass that DisplayPort link directly to the display or adapter. In this mode, a Thunderbolt 3 enabled USB-C port will support a single four lane (4 x 5.4 Gbps, or HBR2) link of DisplayPort. These four links run across the two pairs of high-speed wires in the USB-C connector and cable. This kind of DisplayPort link can support a single, uncompressed display, at 4K resolution at 60 Hz.

DisplayPort and USB Mulit-Function Mode
In this alternate mode of operation, one of the high-speed connector pin pairs of signals will be dedicated to DisplayPort (now 2 lanes at 5.4 Gbps) and one to USB 3.1 This allows for a basic connectivity for data and display devices such as docking stations or data and display dongles. With two lanes of DisplayPort 1.2a, resolutions Quad HD (QHD) can be achieved, or 2560 x1600 at 60 Hz.

Thunderbolt 3 Mode
If a cable and device supporting Thunderbolt are plugged in, the Thunderbolt silicon activates its highest capability mode and configures four high-speed links at either 10 Gbps or 20 Gbps (depending on cable and device support) to support the Thunderbolt transport. This provides bidirectional data rates of 20 or 40 Gbps (Figure 4 illustrates the 40 Gbps case). Additionally, to fill this Thunderbolt link, the silicon extracts and routes up to 4 lanes of PCI Express Gen 3 (4 x 8 Gbps) and up to two full (4 lanes) links of DisplayPort out over the Thunderbolt cable and connector to the device(s) attached downstream from the host system. The first device in the Thunderbolt link has a few options of how it can use this underlying PCI Express and DisplayPort traffic:
• Consume the data from PCI Express by connecting it to PCI Express enabled devices such as networking, storage, cameras, DSP or FPGA adapters, or perhaps some new custom product
• Consume the DisplayPort links by exposing them to a display panel, or a display connector(s)
• Pass the unused PCI Express or DisplayPort data capabilities down to another Thunderbolt device(s) via a second, daisy-chained Thunderbolt 3 port
• Some or all of the above

If the Thunderbolt device has two Thunderbolt ports, the dynamic mode configuration described above will be configured on the downstream or second port of the device when another cable and device are plugged into it. Each mode will still be supported on this downstream connector, and data and display traffic will be provided as demanded to that downstream port. If each consecutive device is a Thunderbolt device, up to 6 devices in a chain can be supported. At any time if a USB or DisplayPort device is plugged directly into the USB-C connector downstream from any device, then the Thunderbolt daisy chain is terminated at that point.

Thunderbolt Networking Mode
An additional, powerful capability of Thunderbolt also allows the connection of two or more hosts directly (or on separate ends of a Thunderbolt chain) via Thunderbolt. In this case, Thunderbolt has software which creates an IP networking link between these systems (see Figure 5). This networking mode allows for the Thunderbolt interface to act as a virtual Ethernet adapter and transfer traffic over the PCI Express interface the Thunderbolt silicon has in each host system.

Power Delivery and Charging
In each of the modes listed above, the Thunderbolt 3 system (if designed to support this by the system manufacturer) can also request to charge over the connector from a device or adapter designed for delivering power to the system, up to 100 W, via the USB-PD specification. In this way, it is possible for the Thunderbolt 3 enabled USB-C connector to support charging, display, data, or all of them at the same time in various configurations. Separately, but related, every USB-C port enabled with Thunderbolt 3 supports the basic USB 2.0 and USB 3.0/3.1 power delivery modes (power sent from the system to a device). In addition to this, Thunderbolt 3 provides the ability of the host system to send 15 W of power on at least one port if a Thunderbolt 3 device that requires bus power is connected (see Figure 6).1 This power delivery allows Thunderbolt devices to support additional performance and capabilities given this extra power. Also, just like a two port Thunderbolt device supports the same capabilities on its downstream port as the Thunderbolt host, this also holds true for power delivery.


See Power Delivery for more information.




Power Delivery


USB Power Delivery (USB PD) is a fast-charging technology based on the USB-C standard. The USB Power Delivery (USB PD) Specification enables the maximum functionality of USB by providing more flexible power delivery along with data over a single cable. This specification is for handling higher power and allows a range of devices to charge quickly over a USB connection. It operates by facilitating a conversation between two devices to negotiate a power contract so they can determine how much power can be pulled from the charger or a particular source. Power Delivery starts at the 5V setting and is configurable up to 20V. Certain Apple® and Android smartphones/tablets and various Laptop manufacturers support this technology, which provides much higher performance than standard charging methods.

Announced in 2021, the USB PD Revision 3.1 specification is a major update to enable delivering up to 240W of power over a full-featured USB Type-C® cable and connector, which is enough to charge Laptops and other devices that require more power than USB-C alone can supply. This specification was created by the USB-IF in response to requests from laptop manufacturers for a connector that could deliver more power. Prior to this update, USB PD was limited to 100W using a solution based on 20V using USB Type-C cables rated at 5A. The USB Type-C specification has also been updated to Release 2.1 to define 240W cable requirements, and with the updated USB PD protocol and power supply definition, this extends the applicability of USB power delivery to a large number of applications where 100W wasn't adequate.

The USB-C PD standard is compatible with the USB4 and USB Power Delivery 3.1 specifications. The USB-C PD specification defines how devices can use the USB-C connector to supply power and how these devices are identified and managed. It defines what the pins in the connector do and how they can be used to provide power at various voltages and currents.

Depending on the system you have, either (PC/Workstation/Server or a Laptop), the Power Delivery Spec may vary and can range between 5V/3A (15W) and 20V/5A (100W). This is due to the difference in the Computer Type, Power Delivery Standard, and the decisions made by the manufacturer regarding the circuit design to meet their end goal.

The AIC (Add-In-Cards) can offer up to 100W standard Power Delivery which is more than enough to charge heavy devices, including MacBooks from recent lineups which use Type-C for charging (such as MacBookPro15,1 - Mid-2018) based on Intel CPU and (MacBookAir10,1 - 2020) based on Apple M1 Silicon Chip.

However, depending on the board design, the Power Delivery Spec can differ. For example, the Gigabyte GC-Alpine Ridge v1.0 and v2.0 (featuring JHL6540 - Thunderbolt 3) supports PD2.0 Standard and offers up to 5V/3A (15W) and 12V/3A (36W) Power Delivery Spec. Whereas, the Gigabyte GC-Titan Ridge v1.0 and v2.0 (featuring JHL7540 - Thunderbolt 3) supports PD3.0 Standard, with Port 1 offering up to 5V/3A (15W), 9V/3A (27W), 15V/3A (45W), 20V/5A (100W) Power Delivery Spec and Port 2 offering up to 5V/3A (15W), 9V/3A (27W) Power Delivery Spec.

The Gigabyte GC-Maple Ridge v1.0 (featuring JHL8540 - Thunderbolt 4) also supports PD3.0 Standard, with Port 1 offering up to 5V/3A (15W), 9V/3A(27W), 15V/3A (45W), 19V/5A(95W) Power Delivery Spec and Port 2 offering upto 5V/3A (15W), 9V/3A (27W) Power Delivery Spec respectively.

Similarly, ASUS THUNDERBOLTEX 3 (featuring JHL6540 - Thunderbolt 3) also supports PD2.0 Standard and offers up to 12V/3A (36W) Power Delivery Spec. Whereas, the ASUS THUNDERBOLTEX 3-TR (featuring JHL7540 - Thunderbolt 3) and ASUS THUNDERBOLTEX 4 (featuring JHL8540 - Thunderbolt 4), both support PD3.0 Standard, with Port 1 offering up to 20V/5A (100W) Power Delivery Spec and Port 2 offering up to 9V/3A (27W) Power Delivery Spec respectively.

Coming down the AIC line, the ASRock Thunderbolt 3 AIC (featuring JHL6540 - Thunderbolt 3) and ASRock Thunderbolt 3 AIC R2.0 (featuring JHL6540 - Thunderbolt 3), both support PD2.0 Standard and offer up to 12V/3A (36W) Power Delivery Spec. Despite having Thunderbolt 4, the ASRock Thunderbolt 4 AIC (featuring JHL8540) still supports PD2.0 Standard, offering up to 5V/3A (15W) and 9V/3A (27W) Power Delivery Spec respectively.

Looking at the Data Sheet of built-in Thunderbolt Chip, certain Desktop Motherboards with an onboard Thunderbolt Chip can offer up to 9V/3A (27W) Power Delivery Spec. Whereas, this can be way more limited for Laptops (such as Dell XPS 9560/9570) offering up to 5V/3A (15W) Power Delivery Spec.

Thunderbolt Capabilities



Thunderbolt Display
Unlike several other features Thunderbolt offers, the Thunderbolt 3 is also capable of displaying output via the Thunderbolt Type-C Ports and supports up to two external displays, ranging between 2K, 4K, 5K, and 8K display resolutions, and upto 240Hz Refresh rate.

TechnologyAnnouncedBandwidthDisplay SupportConnector Type
Thunderbolt 120112x10Gbps1x2560x1600 @60HzMini DisplayPort
Thunderbolt 2201320Gbps1x4K @60Hz
2x1440p @60Hz
Mini DisplayPort
Thunderbolt 3201540Gbps1x4K @120Hz
1x5K @60Hz
2x4K @60Hz
USB Type-C
Thunderbolt 4202040Gbps1x4K @120Hz
2x4K @60Hz
1x5K @60Hz
1x8K @60Hz
USB Type-C




As Thunderbolt itself doesn't have any kind of GPU, but it is capable of video signal passthrough and therefore, to get a display via Thunderbolt Port, you must connect a DisplayPort Cable from your GPU to the Thunderbolt "DP IN" ports. Without this setup, connecting any Display Device (such as Thunderbolt or a Type-C monitor) to the Thunderbolt Port will not have any display and will result in a black screen due to no video signals.

For Add-In Cards (AIC) Thunderbolt, it contains a "Mini DisplayPort In" (mDP) Port. As the name suggests, it's the port where your GPU signals goes in. Depending on the Thunderbolt specification, board design, and manufacturer's decision, it can be either "1xDP IN" or "2xDP IN" Port(s).

For Motherboards and systems with Onboard Thunderbolt Chip, it has a dedicated "DP IN" Port, usually located at the rear I/O panel of the system, and depending on the Thunderbolt specification, board design, and manufacturer's decision, the given DP IN Port can be either a single port that will passthrough signals to both the Thunderbolt Ports or specifically two dedicated "DP IN" Ports for each of the Thunderbolt Ports having individual video signals and individual controls.

For AIO, NUC, and Laptop computers, there is an internal routing of video signals (either from the IGPU or dGPU or both) to the Thunderbolt Chip and requires no additional configuration, other than a few BIOS Settings.

In addition, it's worth noting that Certain Laptops tend to route the video signals from the dGPU to the Thunderbolt Ports and as the dGPU isn't supported on macOS (in a muxless configuration) and needs to be disabled, you cannot drive a display via Thunderbolt Ports. This is one of the limitation unlike several other limitations on non-Apple computers running macOS/OS X. Such configuration can be often seen on certain high-end Laptops with powerful dGPU (such as RTX3060), where all the external video ports (including HDMI and mDP) are tied to the dGPU instead of IGPU and only a very few selected Laptop models (such as Dell Precision 5750) provide the option to switch between IGPU and dGPU signals for the external Ports such as HDMI, mDP, and Thunderbolt Ports. See Disabling dGPU on Laptops for more information.






Target Display Mode
Another exciting feature from Apple for its Mac lineup. Target Display mode is a feature available with certain older Mac models.



Display Conversion Support
Although, Thunderbolt's video component is a standard DisplayPort signal, but can be converted to any format that DisplayPort can be converted to. This allows connecting HDMI, DVI, and VGA displays via converters or via a Dock.





Daisy Chaining

Daisy Chain is yet another exciting feature that Thunderbolt offers. One Thunderbolt Device can be plugged into the end of a string of devices, one after other. This feature is referred to as Daisy Chain. Each device must be powered on for subsequent devices to operate. Thunderbolt Daisy Chaining allows you to connect multiple Thunderbolt devices to your computer. These daisy-chained devices connect in a series to communicate so a single connection can support multiple devices. Data, power, and video signals can flow from the computer and down the chain into additional connected accessories. This gives the ability to daisy-chain up to a maximum of six (6 ) Thunderbolt Devices per Thunderbolt Bus and up to a total of (twelve) 12 Thunderbolt Devices for both Bus. This means, systems having two Thunderbolt 3 chips, can give you the ability to daisy chain up to a total of 24 Thunderbolt Devices (each chip having two Thunderbolt Bus) for all four Buses.

Generally, this is useful for most of the users involved in content creation (such as Music or Video Production) and helps users to maximize their productivity, reduces cable management, and gives a tidier workspace by consolidating all accessories into a single connection.

However, at any time, if a USB or DisplayPort device is plugged directly into the USB-C connector downstream from any device, then the Thunderbolt Daisy Chain is terminated at that particular point.

While Thunderbolt supports Daisy Chaining, USB and USB Type-C cannot daisy chain at all and they must be plugged into a Star Topology, e.g. directly into the computer or into the Thunderbolt Dock/Hub itself.


Thunderbolt Networking

Thunderbolt Networking provides peer-to-peer connections to transfer files between computers, perform PC migrations, and/or set up small workgroups with shared storage. This is a virtual connection that emulates an Ethernet adapter that enables Ethernet networking with the benefit of Thunderbolt superfast medium capability.

Thunderbolt Networking enables two hosts and several devices that have a Thunderbolt controller to be connected together in a linear (Daisy chain) series from a single port.


Thunderbolt Networking for Linux is compatible with Thunderbolt Networking on systems running macOS or Windows and also supports Thunderbolt generation 2 and 3 controllers.

The Thunderbolt Networking also supports backward compatibility i.e you can connect between two computers having two different Thunderbolt Controllers, specifically, one side having Generation 2 or Generation 3 Controllers or vice-versa.




In addition of tunneling PCIe, Display Port, and USB traffic, Thunderbolt allows connecting two hosts (domains) over a Thunderbolt cable. It is possible to tunnel arbitrary data packets over such connection using high-speed DMA rings available in the Thunderbolt host controller.

In order to discover Thunderbolt services the other host supports, there is a software protocol running on top of the automatically configured control channel (ring 0). This protocol is called XDomain discovery protocol and it uses XDomain properties to describe the host (domain) and the services it supports. Once both sides have agreed on what services are supported, they can enable high-speed DMA rings to transfer data over the cable.




The XDomain protocol and networking support is available in Windows, macOS, and Linux and therefore, it is possible to connect Windows to macOS and Linux and vice-versa. When connecting Linux to a macOS or a Windows based system, everything is done automatically as those systems have the networking service enabled by default. However, for a Linux-to-Linux connection over Thunderbolt, one host needs to load the networking driver first so that the other side can locate the networking service and load the corresponding driver.

The XDomain Protocol is used by FireWire and Thunderbolt.


Thunderbolt Boot Support



Thunderbolt Security


VT-d based DMA protection helps prevent security threats by remapping requests from external devices and checking for proper permissions.

With the release of Thunderbolt devices and connections, many users are gearing up for improved connectivity and universal compatibility. One of the notices that came with the release of Thunderbolt™ 4 and could be flying under the radar is that it now comes with VT-d DMA protection standard. While this is also a major upgrade to the technology, not that many people might understand what VT-d DMA protection is and why it matters.



Intel® Virtualization Technology for Directed I/O (VT-d), specialized hardware capabilities built into Intel processors is the foundation for DMA protection on Thunderbolt ports that helps prevent physical DMA attacks. These solutions block peripheral devices from unauthorized access to system memory. Leading Operating Systems such as Windows, macOS, and Linux have already implemented DMA protection using Intel VT-d Technology. Intel’s Thunderbolt 4 certification requires VT-d based DMA protection. It is strongly recommended on computers utilizing Thunderbolt (either AIC or Onboard) and has been enabled on systems, where supported.

With USB-C connector-based computer ports that provide PCI Express (PCIe) Protocol, users can connect PCIe devices to the computer just as if they were installed internally. Such devices include Portable and Desktop Storage, External Graphics (eGPU), Audio Interface, Memory Card Readers, Ethernet Adapters, and other PCIe-based devices. PCIe devices are unique because they are capable of Direct Memory Access (DMA), which enables fast and efficient access to the system memory without involving the processor. However, shared memory between all the different devices in the system including those that are externally connected via the USB-C port may present a security risk if not properly protected. Security for Thunderbolt computer ports is hardware-based and built on Intel’s Virtualization Technology for Directed I/O (Intel VT-d), an Intel processor technology that provides IO virtualization (often referred to as IO Memory Management Unit or IOMMU). One of VT-d technology’s features is DMA remapping (DMA-r) which is used for DMA protection by operating systems and BIOS. DMA-r helps protect the system memory by providing an isolated memory region for each device connecting to the system. This way a device will only have access to its assigned memory and cannot read or write to other memory areas outside its own.

The following Operating Systems versions have VT-d and DMA-r based protection against DMA attacks on Thunderbolt™ computer ports:

• Windows OS implementation, known as Kernel DMA Protection, exists on all Windows 10 versions starting with 1803 (RedStone 4) and is enabled by default on systems that support it. See Kernel DMA Protection for more information.

• macOS/OS X implementation, known as AppleVTD, exists on all macOS/OS X versions starting with OS X Mountain Lion (10.8.2) and is enabled by default on Macs since 2012. See Thunderbolt Device Driver Programming Guide for more information.

• On Linux VT-d based security has been supported since Kernel version 4.21.

Operating system implementation helps protect the system during run time. In order to help protect against DMA attacks before the system boots and until the transition to the operating system, Intel has implemented UEFI firmware (BIOS) support for DMA-r based security that helps block devices from unauthorized access to system memory. Although physical attacks may be hard to perform and require that an attacker possess your PC, nonetheless, Intel recommends standard security practices to reduce the risk of physical attacks. Such practices include using only trusted peripherals and preventing unauthorized physical access to computers. Hard disk drive (HDD) and Solid State Drive (SSD) encryption and a BIOS Password can provide an additional layer of protection.


Security Levels

Since Thunderbolt presents some unique security considerations, there are several different "Security Levels" for a system equipped with Thunderbolt Controller that can be configured in the system's BIOS. Depending on the manufacturer, a particular Security Level can be implemented as a default Security Level in the UEFI Firmware (BIOS) of the designated system. This Security Level is also present in the Thunderbolt Firmware, and is useful in cases where no Thunderbolt Support is present from the manufacturer's end, either in the System's UEFI Firmware (BIOS), or in terms of Hardware.

The reason the Security Levels were introduced is because Thunderbolt allows access to PCIe, which poses unique security considerations that do not apply to standard USBs, and the fact that the connected devices can be DMA masters and thus read contents of the host memory without the 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. Security Levels prevent malicious TB devices from accessing the PCIe domain, thereby protecting against:

• Device-to-host DMA attacks
• Device-to-device (P2P) DMA attacks
• PCI ID spoofing to target vulnerable device drivers
• TLP source ID spoofing

The Security Level is only present on Thunderbolt Compatible Systems, i.e. a system that either has an Onboard Thunderbolt Controller or has the option to install Add-In Card (AIC) Thunderbolt Controller (such as Gigabyte GC-Titan Ridge or ASUS THUNDERBOLTEX3/TR) and is completely absent on systems where no Thunderbolt Support is present from the manufacturer's end and these Security Levels will not tend to appear even by installing a suitable Add-In Card (AIC) Thunderbolt Controller to the system. This is because several Thunderbolt EFI Modules are always missing from the UEFI Firmware (BIOS) on non-compatible Thunderbolt systems. It's worth noting that these Security Levels will only appear in UEFI Setup Menu when the Thunderbolt Controller is turned on in BIOS.

The Thunderbolt Security Levels only apply to PCIe Protocol, while DisplayPort connects by default as it has no DMA capability exposure. Therefore, these modes only come into play when connecting Thunderbolt Devices. They do not apply when connecting a USB Device to a Thunderbolt Port. Do note that these Security Levels are usually manufacturer dependent.

Starting with the Intel Falcon Ridge Thunderbolt Controller, there are 4 Security Levels available, and with the release of Titan Ridge, adding one more Security Level (USBOnly). The security levels are as follows:

Security LevelDescription
SL0 (None)
  • All devices are automatically connected by the firmware. No user approval is needed. In BIOS settings this is typically called Legacy mode.
SL1 (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.
SL2 (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.
SL3 (DisplayPort Only)
  • 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.
SL4 (Daisy Chaining Disabled/USB Docks Only)
SL5 (NoPCIe)
  • PCIe tunneling is disabled/forbidden from the BIOS. Available in some USB4 systems.
  • Some USB4 systems have a BIOS setting to disable PCIe tunneling. This is treated as another security level (nopcie).



SL0 (No Security)

When the Thunderbolt Controller is set to SL0 Mode, you can connect any Thunderbolt 3 device and it will immediately start working. In this mode, all connected Thunderbolt Devices are automatically connected and no user approval is needed. The danger to this mode is that since Thunderbolt supports PCIe, and PCIe allows direct access to system memory, a malicious Thunderbolt device could access potentially sensitive data in your system’s memory, and in SL0 mode, the device would simply need to be plugged in to do so. The typical threat model here would involve an attacker doing this while you had left your system unattended somewhere. This may not be a practical risk for everyone, but it's why the higher security levels exist.


SL1 (User Authorization)

When a Thunderbolt Device is connected, the user is asked for permission to allow to connect a particular Thunderbolt Device and the user must respond to a popup dialog box to explicitly allow the connection. This is the default mode and requires administrator level access to add new PCIe enabled devices. This mitigates the SL0 risk described above.

The Thunderbolt™ software (Intel Thunderbolt Control Center) on the PC maintains a list of the Unique IDs for every Thunderbolt™ peripheral that has received user permission to “always connect.” (Access Control List). If the Unique ID of the Thunderbolt™ peripheral is not on the ACL, the PCIe connection is not allowed until the user responds to a connection prompt, typically with the following options: (1) Connect one time, (2) Always connect, (3) Do not connect. Depending on the user preference, the user can choose between these options to allow once or to always allow or deny the particular Thunderbolt Device. Do note that the connection permissions are managed per PC, and not per user login.


SL2 (Secure Connection)

Similar to SL1 mode, but with the addition of cryptographic authentication. In this mode, a hardware based security challenge/response mechanism is involved.

The first time a Thunderbolt™ peripheral’s Unique ID is granted “always connect” PCIe access, a cryptographic key is written to the peripheral controller’s non-volatile memory and added to the host PC’s ACL list in order to perform a more robust "identity verification" of that particular device on subsequent connections, using a challenge/response mechanism, to ensure only specific, approved devices are allowed to connect to the system. Each time a peripheral’s Unique ID is found on the ACL, the PC’s controller sends a security challenge. The response from the peripheral is then verified before the PCIe connection is allowed. If the response is not valid, the user receives a connection permission prompt to allow or deny the connection.

This prevents an attacker from taking the Unique ID of a peripheral that had been granted "always allow" access and cloning it onto a malicious device, which under SL1 mode would allow that malicious device to gain "always allow" access. However, not all Thunderbolt 3 peripherals support SL2. Beyond the new hardware cryptographic authentication, the user experience is the same as SL1.

SL3 (DisplayPort and USB only)

When the Thunderbolt Controller is set to SL3 mode, the Thunderbolt Port will provide USB, Power Delivery, and DisplayPort functionality. In this mode, only DisplayPort traffic is allowed over Thunderbolt Port, but not the PCIe, and will not tunnel or transmit PCIe data. This will allow you to automatically connect to DisplayPort and USB devices only. No Thunderbolt Adapter or PCIe devices are allowed to connect including eGPU.

However, when a Thunderbolt device is attached, a Thunderbolt link will be established, but PCIe will not be tunneled through that link, which can result in either no functionality or limited functionality for an attached Thunderbolt device. This is because the SL3 mode blocks the PCIe function, and as a Thunderbolt device requires PCIe transmission to transmit the PCIe data between the host and the Thunderbolt device, any connected Thunderbolt Device or a Device connected through Thunderbolt peripheral will not function at all.

This is still different from a regular USB Type-C DisplayPort connection because an actual Thunderbolt link is still established, which means that if the Thunderbolt controller has two DisplayPort interfaces wired to it from the system's GPU (which is optional in the Thunderbolt spec), they would both be available, thereby offering more display bandwidth than a regular USB Type-C DisplayPort connection, where at most one full DisplayPort interface of bandwidth is available.

The "USB" portion of this security level is where it gets tricky. If you plug a variety of USB3.x device or a regular USB Type-C Dock (i.e. non-Thunderbolt Dock) into your Thunderbolt Port, it will work as normal, since this particular scenario doesn't involve an actual Thunderbolt link. However, as outlined in the "Thunderbolt Connection Modes" above, USB 3.x is not natively carried over an actual Thunderbolt 3 link. This means if the system is set to SL3 mode and when an actual Thunderbolt Dock is connected, you will get the display output, but you will not be able to use any USB 3.x ports or other dock functionality that runs through the dock's USB Controller (typically all the other ports like Ethernet, Audio, etc.). This is because the SL3 mode blocks the PCIe transmission, which prevents transmitting the data between the dock and the system, and as those functions are dependent on PCIe, they will not function at all.



The only USB functionality you could potentially get from a Thunderbolt Dock would be anything that runs as USB 2.0, since as mentioned earlier, a USB-C connector contains dedicated pins for USB 2.0, and that traffic runs completely independently of Thunderbolt. However, even USB 2.0 devices connected to the dock's USB ports and internal dock devices that run on USB 2.0 (possibly the dock's audio controller) would still typically run through the dock's own PCIe-based USB controller rather than being passed straight through to the attached system as native USB 2.0.


\\\Recommend using this mode only when there is no requirement to support Thunderbolt™ peripherals, or Thunderbolt™ peripherals that only require the DisplayPort interface to be fully functional.///

SL4 (Daisy Chaining Disabled/USB Docks Only)

This mode refers to Thunderbolt Daisy Chaining, not DisplayPort Diasy Chaining. This mode uses an Intel® proprietary approach to terminate the PCIe tunneling within the first Thunderbolt Device connected to a Thunderbolt host port. In this mode, PCIe is allowed, but only for the first Thunderbolt Device in the chain, and would not be allowed to use the PCIe function to connect any further Thunderbolt Devices down the chain.

This means if the system is set to SL4 mode and you have a Thunderbolt device that has daisy chaining capability, connecting that particular device to a Thunderbolt port will be fully functional, but if you connect any other Thunderbolt device to that particular Thunderbolt device, it will be completely blocked from connecting and will not function at all. This mode is designed to prevent a malicious Thunderbolt peripheral from gaining access to your system through a trusted device (such as a dock) when using a Daisy Chain setup.

For example, if you connect a Thunderbolt SSD into an "upstream" Thunderbolt port on your Thunderbolt Dock, and you connect that dock to your system while the system is set to SL4 mode, the Thunderbolt Dock would be allowed and will be fully functional, but the Thunderbolt SSD would be blocked and will not function. This is because the SL4 mode disables the Daisy Chaining, which prevents PCIe tunneling for the rest of the Thunderbolt Devices connected to the first Thunderbolt Peripheral in a Daisy Chain mode.

In addition, when the system is set in SL4 mode, the user will not be able to Daisy Chain Thunderbolt Devices from Thunderbolt Port B.
















If 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).









IOMMU
Kernel DMA Protection


Thunderbolt Bandwidth

Although Thunderbolt 3 is capable of delivering speeds up to 40Gb/s, the actual throughput

Although the maximum throughput is 40Gb/s for Thunderbolt, the actual speed bandwidth depends on the end Thunderbolt Device. For example, if you connect an end Device that is TB2 (capable of 20Gb/s), you'll get 20Gb/s instead of 40Gb/s. This is because to utilize a proper 40Gb/s speed, the Thunderbolt Controller and the end connected Device should be of the same speed.

Requirements


Following are the requirements for enabling Thunderbolt 3 HotPlug on macOS. Please ensure you meet the requirements before proceeding with this guide.

Thunderbolt
Motherboard
  • Thunderbolt compatible Motherboard is preferred.
  • Motherboards which does not feature the THB_C Header can be also used with some limitations. See Setting up Thunderbolt for more information.
Kexts
  • Vanilla Thunderbolt kexts in S/L/E
Extra Hardware
  • Any Thunderbolt compatible Device to check and verify the status.
  • Storage Devices or Audio Interface are the best suited hardware for testing
Tools
  • Hackintool
  • IOReg
  • MaciASL


Enabling hotplug can be a quite complex process and time consuming. But if done correctly, you can have a working Thunderbolt with hotplug feature with the required speed and performance.

Following are the test devices used as an example for this guide which features Audio Interfaces, Dock, and Thunderbolt drives. From consumer series to HEDT series motherboard, it works as expected.

Thunderbolt Devices:
  • Element 88 from Apogeedigital
  • G-Technology 3TB
  • UAD Twin Apollo
  • Belkin Thunderbolt 3 Mini Dock with 4K Dual HDMI
  • Ash Creek NVMe
  • TBT3 SSD 480

Motherboards:
  • GIGABYTE Z370 AORUS GAMING 3
  • GIGABYTE Z390 AORUS ELITE
  • GIGABYTE Z490 VISION G
  • GIGABYTE X299X DESIGNARE 10G
  • GIGABYTE Z370 AORUS GAMING 7
  • ASUS X299 A
  • ASUS X299 PRIME DELUXE
  • ASUS PRIME Z690M-PLUS D4
  • MSI X299 RAIDER
  • EVGA X299 Micro

Thunderbolt Status


Following are the Thunderbolt Status for the following Thunderbolt Hardware. The table provides the functionality and features with Hotplug for several devices and with different Thunderbolt hardware setups such as Multiple Alpine Ridge and Titan Ridge Card for a TB extensive workflow.

Thunderbolt:
FunctionSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Booting with Thunderbolt Device ConnectedYES✅❌✅
Thunderbolt Hotplug with Cold BootYES✅❌✅
Thunderbolt Hotplug with Warm BootYES✅❌✅
Thunderbolt Hotplug with no Device Connected at BootYES❌❌❌
Sleep with Thunderbolt Device ConnectedYES✅❌Inconsistent Sleep
Wake with Thunderbolt Device ConnectedYES✅❌❌
Shut Down with Thunderbolt Device ConnectedYES✅❌❌
Thunderbolt Auto Reconnect after SleepYESNO

USB Type-C:
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Booting with USB Device ConnectedYES✅❌✅
USB Hotplug with Cold BootYES✅❌✅
USB Hotplug with Warm BootYES✅❌✅
Sleep with USB Device ConnectedYES✅❌✅
Wake with USB Device ConnectedYES✅❌✅
Shut Down with USB Device ConnectedYES✅❌✅
USB Type-C Auto Reconnect after SleepYES

Display
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt DisplayNot TestedNot TestedNot TestedNot Tested
Type-C Display✅✅❌✅
Type-C Display Cold Boot❌Not Tested❌Not Tested
Type-C Display Hotplug✅✅❌✅

Drive
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Drive✅✅❌✅
Thunderbolt Drive Hotplug✅✅❌✅
Thunderbolt NVMe✅✅❌✅
Thunderbolt NVMe Hotplug✅✅❌✅

Dock
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Dock✅✅❌✅
Thunderbolt Dock Hotplug✅✅❌✅
Thunderbolt Dock Ethernet✅✅❌✅
Thunderbolt Dock Display Port✅✅❌✅
Thunderbolt Dock HDMI✅✅❌✅
Thunderbolt Dock USB✅✅❌✅
Thunderbolt Dock Audio✅✅❌✅

eGPU
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt eGPU✅✅❌✅
Thunderbolt eGPU Hotplug❌❌❌❌

Audio
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Audio Interface✅✅❌✅
Thunderbolt Audio Interface Hotplug✅✅❌✅

Adapters
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Ethernet Adapter✅✅❌✅
Thunderbolt Ethernet Adapter Hotplug✅✅❌✅
Thunderbolt 2 to Thunderbolt 3✅✅❌✅

Thunderbolt:
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Booting with Thunderbolt Device Connected✅✅❌✅
Thunderbolt Hotplug with Cold Boot✅✅❌✅
Thunderbolt Hotplug with Warm Boot✅✅❌✅
Thunderbolt Hotplug with no Device Connected at Boot✅❌❌❌
Sleep with Thunderbolt Device Connected✅✅❌Inconsistent Sleep
Wake with Thunderbolt Device Connected✅✅❌❌
Shut Down with Thunderbolt Device Connected✅✅❌❌
Thunderbolt Auto Reconnect after SleepYESNO

USB Type-C:
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Booting with USB Device Connected✅✅❌✅
USB Hotplug with Cold Boot✅✅❌✅
USB Hotplug with Warm Boot✅✅❌✅
Sleep with USB Device Connected✅✅❌✅
Wake with USB Device Connected✅✅❌✅
Shut Down with USB Device Connected✅✅❌✅
USB Type-C Auto Reconnect after SleepYESNO

Display
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt DisplayNot TestedNot TestedNot TestedNot Tested
Type-C Display✅✅❌✅
Type-C Display Cold Boot❌Not Tested❌Not Tested
Type-C Display Hotplug✅✅❌✅

Drive
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Drive✅✅❌✅
Thunderbolt Drive Hotplug✅✅❌✅
Thunderbolt NVMe✅✅❌✅
Thunderbolt NVMe Hotplug✅✅❌✅

Dock
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Dock✅✅❌✅
Thunderbolt Dock Hotplug✅✅❌✅
Thunderbolt Dock Ethernet✅✅❌✅
Thunderbolt Dock Display Port✅✅❌✅
Thunderbolt Dock HDMI✅✅❌✅
Thunderbolt Dock USB✅✅❌✅
Thunderbolt Dock Audio✅✅❌✅

eGPU
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt eGPU✅✅❌✅
Thunderbolt eGPU Hotplug❌❌❌❌

Audio
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Audio Interface✅✅❌✅
Thunderbolt Audio Interface Hotplug✅✅❌✅

Adapters
OptionsSingle Card with Original FirmwareSingle Card with Custom FirmwareMultiple Cards with Original FirmwareMultiple Cards with Custom Firmware
Thunderbolt Ethernet Adapter✅✅❌✅
Thunderbolt Ethernet Adapter Hotplug✅✅❌✅
Thunderbolt 2 to Thunderbolt 3✅✅❌✅

SPECIFICATION
ModelControllerFamilyInterfaceSpeedPortsTB Device Per PortDisplay SupportDaisy ChainThunderbolt HeaderUSB HeaderAdditional Power
GIGABYTE GC-Thunderbolt 2PCIe 2.0 x420Gb/s2xTB2 | 2xDP IN6 Devices per port4KYESYESNONO
GIGABYTE GC-ALPINE RIDGE Rev. 1.0DSL6540 B-StepAlpine RidgePCIe 3.0 x440Gb/s2xTB3 | 1xHDMI | 2xDP IN6 Devices per port1x5K @60Hz or 2x4K @60HzYES1xNO
GIGABYTE GC-ALPINE RIDGE Rev. 2.0DSL650 C-StepAlpine RidgePCIe 3.0 x440Gb/s2xTB3 | 1xHDMI | 2xDP IN6 Devices per port1x5K @60Hz or 2x4K @60HzYES1xNO
GIGABYTE GC-TITAN RIDGE Rev. 1.0DSL7540Titan RidgePCIe 3.0 x440Gb/s2xTB3/USB 3.1 Gen2 Type-C | 1xDP | 2xmDP IN6 Devices per port4KYES1x5PINYES2x6PIN PCIE
GIGABYTE GC-TITAN RIDGE Rev. 2.0DSL7540Titan RidgePCIe 3.0 x440Gb/s2xTB3/USB 3.1 Gen2 Type-C | 1xDP | 2xmDP IN6 Devices per port4KYES1x5PINYES2x6PIN PCIE


Thunderbolt
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with Thunderbolt Device ConnectedYESYESNONOYES
Thunderbolt Hotplug with Cold BootYESYESNONOYES
Thunderbolt Hotplug with Warm BootYESYESNONOYES
Thunderbolt Hotplug with no Device Connected at BootYESNONONONO
Sleep with Thunderbolt Device ConnectedYESYESNONOINCONSISTENT SLEEP
Wake with Thunderbolt Device ConnectedYESYESNONONO
Shut Down with Thunderbolt Device ConnectedYESYESNONONO
Thunderbolt Auto Reconnect after SleepYESNONONOT TESTED

USB Type-C
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with USB Device ConnectedYESNONOYES
USB Hotplug with Cold BootYESNONOYES
USB Hotplug with Warm BootYESNONOYES
Sleep with USB Device ConnectedYESNONOYES
Wake with USB Device ConnectedYESNONOYES
Shut Down with USB Device ConnectedYESNONOYES
USB Type-C Auto Reconnect after SleepYESNONONOT TESTED


Display
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with Thunderbolt Device ConnectedYES
NO
NONOT TESTED
Thunderbolt DisplayYESNONO
Type-C DisplayYESNONO
Type-C Display Cold BootYESNONONOT TESTED
Type-C Display HotplugYESNONO


Dock
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt DockYESNONOYES
Thunderbolt Dock HotplugYESNONOYES
Thunderbolt Dock EthernetYESNO
NO
YES
Thunderbolt Dock Display PortYESNONOYES
Thunderbolt Dock HDMIYESNONOYES
Thunderbolt Dock USBYESNONOYES
Thunderbolt Dock AudioYESNONOYES


eGPU
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt eGPUYESNONOYES
Thunderbolt eGPU HotplugYESNONO


Audio
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt Audio InterfaceYESNONOYES
Thunderbolt Audio Interface HotplugYESNONOYES


Adapters
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt Ethernet AdapterYESNOYESYESNOYES
Thunderbolt Ethernet Adapter HotplugYESNOYESYESNOYES
Thunderbolt 2 to Thunderbolt 3YESNOYESYESNOYES

Notes:
  • *Refers to Single Thunderbolt Card.
  • **Refers to Multiple Thunderbolt Cards.

ModelControllerFamilyInterfaceSpeedPortsTB Device Per PortDisplay SupportDaisy ChainThunderbolt HeaderUSB HeaderAdditional Power
ASUS THUNDERBOLTEX 3DSLXXXPCIe 3.0 x440Gb/s1xTB3/Type-C | 1xUSB 3.1 Type-A | 1xmDP IN6 Devices per port4K @60HzYESYESNONO
ASUS THUNDERBOLTEX 3-TRJHL7540Titan RidgePCIe 3.0 x440Gb/s2xTB3/Type-C | 1xDP IN | 1xmDP IN6 Devices per port8K @60HzYES1x5PINYES1x6PIN PCIE
ASUS THUNDERBOLTEX-4JHLXXXXPCIe 3.0 x440Gb/s2xTB3/Type-C | 1xDP IN | 2xmDP IN and 1xInternal Mini DP5 Devices per port8K @60HzYES1x5PINYES1x6PIN PCIE


Thunderbolt
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with Thunderbolt Device ConnectedYES
Thunderbolt Hotplug with Cold BootYES
Thunderbolt Hotplug with Warm BootYES
Thunderbolt Hotplug with no Device Connected at BootYES
Sleep with Thunderbolt Device ConnectedYES
Wake with Thunderbolt Device ConnectedYES
Shut Down with Thunderbolt Device ConnectedYES
Thunderbolt Auto Reconnect after SleepYES

USB Type-C
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with USB Device ConnectedYES
USB Hotplug with Cold BootYES
USB Hotplug with Warm BootYES
Sleep with USB Device ConnectedYES
Wake with USB Device ConnectedYES
Shut Down with USB Device ConnectedYES
USB Type-C Auto Reconnect after SleepYES


Display
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with Thunderbolt Device ConnectedYES
Thunderbolt DisplayYES
Type-C DisplayYES
Type-C Display Cold BootYES
Type-C Display HotplugYES


Dock
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt DockYES
Thunderbolt Dock HotplugYES
Thunderbolt Dock EthernetYES
Thunderbolt Dock Display PortYES
Thunderbolt Dock HDMIYES
Thunderbolt Dock USBYES
Thunderbolt Dock AudioYES


eGPU
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt eGPUYES
Thunderbolt eGPU HotplugYES
Thunderbolt eGPU HotplugYES


Audio
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt Audio InterfaceYES
Thunderbolt Audio Interface HotplugYES


Adapters
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt Ethernet AdapterYES
Thunderbolt Ethernet Adapter HotplugYES
Thunderbolt 2 to Thunderbolt 3YES

Notes:
  • *Refers to Single Thunderbolt Card.
  • **Refers to Multiple Thunderbolt Cards.

ModelControllerInterfaceSpeedPortsTB Device Per PortDisplay SupportDaisy ChainThunderbolt HeaderUSB HeaderAdditional Power
AsRock Thunderbolt 3 AICJHL6540PCIe 3.0 x440Gb/s2xTB3/Type-C | 1xDP IN | 1xmDP IN6 Devices per port1x5K @60Hz or 2x4K @60HzYES1x5PINNONO
AsRock Thunderbolt 3 AIC R2.0JHL6540PCIe 3.0 x440Gb/s2xTB3/Type-C | 1xDP IN | 1xmDP IN and 1xInternal Mini DP6 Devices per port1x5K @60Hz or 2x4K @60HzYES1x5PINNONO


Thunderbolt
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with Thunderbolt Device ConnectedYES
Thunderbolt Hotplug with Cold BootYES
Thunderbolt Hotplug with Warm BootYES
Thunderbolt Hotplug with no Device Connected at BootYES
Sleep with Thunderbolt Device ConnectedYES
Wake with Thunderbolt Device ConnectedYES
Shut Down with Thunderbolt Device ConnectedYES
Thunderbolt Auto Reconnect after SleepYES

USB Type-C
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with USB Device ConnectedYES
USB Hotplug with Cold BootYES
USB Hotplug with Warm BootYES
Sleep with USB Device ConnectedYES
Wake with USB Device ConnectedYES
Shut Down with USB Device ConnectedYES
USB Type-C Auto Reconnect after SleepYES


Display
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Booting with Thunderbolt Device ConnectedYES
Thunderbolt DisplayYES
Type-C DisplayYES
Type-C Display Cold BootYES
Type-C Display HotplugYES


Dock
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt DockYES
Thunderbolt Dock HotplugYES
Thunderbolt Dock EthernetYES
Thunderbolt Dock Display PortYES
Thunderbolt Dock HDMIYES
Thunderbolt Dock USBYES
Thunderbolt Dock AudioYES


eGPU
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt eGPUYES
Thunderbolt eGPU HotplugYES
Thunderbolt eGPU HotplugYES


Audio
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt Audio InterfaceYES
Thunderbolt Audio Interface HotplugYES


Adapters
Function on macOSAlpine Ridge with Original Firmware*Alpine Ridge with Custom Firmware*Alpine Ridge Cards with Original Firmware**Alpine Ridge Cards with Custom Firmware**Single Titan Ridge with Original Firmware*Single Titan Ridge with Custom Firmware*Titan Ridge Cards with Original Firmware**Titan Ridge Cards with Custom Firmware**
Thunderbolt Ethernet AdapterYES
Thunderbolt Ethernet Adapter HotplugYES
Thunderbolt 2 to Thunderbolt 3YES

Notes:
  • *Refers to Single Thunderbolt Card.
  • **Refers to Multiple Thunderbolt Cards.


Thunderbolt Firmware Configuration


There can be normally two firmware configurations for Thunderbolt 3. Original and Custom firmware Configuration. Both of them have been described below.

ConfigurationDescription
Original/Stock Firmware
  • The original firmware is provided and is already flashed on the Thunderbolt Card.
  • When you set up multiple Thunderbolt Cards, only one Card will work in the desired way and the other cards will not work due to the limitation of the different device addresses.
Custom Firmware
  • Custom firmware is modified by some of the experts from this community which eliminates the limitation of Thunderbolt Cards with different device addresses and also provides additional functions such as Thunderbolt Bus configuration, and visibility under System Report>Thunderbolt.


Thunderbolt Setup Configuration


There can be normally two configurations for Thunderbolt 3. Single Card and Multiple Card Configuration. Where, a single card offers up to "two" thunderbolt 3 ports and multiple cards can offer up to "twelve" thunderbolt 3 ports depending on the PCIe slots available where one slot is always reserved for the GPU. These can be further categorized into four more configurations which are outlined below.


ConfigurationDescription
Single Card with Original Firmware
  • A single Card with original firmware can offer up to "two" Thunderbolt 3 ports which don't require flashing of a custom firmware for macOS.
  • Lacks AVB feature.
  • Lacks Thunderbolt Bus
  • No TB information under System Report>Thunderbolt
  • It May not work with every Thunderbolt Device
  • May not support HotPlug with every Thunderbolt Card
  • eGPU HotPlug may not work
  • Cannot connect between two computers using Thunderbolt
Single Card with Custom Firmware
  • A single card with original firmware can offer up to "two" Thunderbolt 3 ports which require flashing of a custom firmware for macOS.
  • AVB Function
  • Thunderbolt Bus Feature
  • TB information under System Report>Thunderbolt
  • Can work with most of the Thunderbolt Device
  • eGPU HotPlug
  • Can connect between two computers using Thunderbolt
Multiple Card with Original Firmware
  • Multiple cards with original firmware can range between two (minimum) or more (up to 6, maximum) Thunderbolt cards installed.
  • HEDT and Workstation motherboards can offer up to 7 PCIe slots. However, one slot is reserved for GPU. Hence, the maximum capacity is six Thunderbolt 3 Cards.
  • The drawback of using multiple cards with original firmware is that other than the reserved slot for Thunderbolt or small peripherals where the device address is usually PXSX, will be initialized and fully work, more likely as a single card with custom firmware. The rest of the cards installed will not function in any way. This is because, unless the card is flashed with a custom firmware, the Thunderbolt cannot be driven due to having different addresses such as BR1A, BR3A, PEGP, SL01, and SL09. A few exceptions are ASUS Motherboards and ASUS Thunderbolt Cards
Multiple Card with Custom Firmware
  • Multiple cards with custom firmware can be best suited to professional music producers, video editors, and motion and VFX artists.
  • This option offers the maximum expandability of Thunderbolt 3.
  • Offers up to 12 ports when 6 Thunderbolt Card is installed which is a maximum configuration as of now. Note that one slot is always reserved for GPU.
  • With a custom firmware flashed on multiple Thunderbolt Card, it removes the limitation of utilizing multiple Thunderbolt cards.
  • It also offers functionality such as Hotplug which can be achieved very easily.

Selecting Thunderbolt Configuration


Depending on your need for Thunderbolt, where the key factor can be the requirement of each individual Thunderbolt 3 port, select your configuration and start the preparation for Thunderbolt 3 Hotplug. If you're looking for a simple Thunderbolt with Hotplug functionality and don't want to flash a custom firmware due to the complexity of the guide or are not willing to take risk, the best choice would be to go for a single card with the original firmware. However, even if you don't want to flash your Thunderbolt with custom firmware, you may need to flash it for some devices which require Thunderbolt Bus to utilize a particular Thunderbolt device.

Flashing Custom Firmware

If you're planning to flash the custom firmware depending on your Thunderbolt needs, @mooseknuckleboi has written a very well guide explaining flashing Thunderbolt Cards for macOS. You can find more information for his thread linked below.

Enabling Thunderbolt 3 Hotplug


Now, you have enough information about Thunderbolt configuration, firmware, and the limitations and the next step is to enable Thunderbolt Hotplug. To enable Hotplug, follow the steps outlined below.

Following are the steps to enable Thunderbolt 3 HotPlug.

STEP 1: Enable Thunderbolt

This guide assumes that you're already having Thunderbolt 3 enabled on your hardware, with the exception of HotPlug. As this guide requires a working Thunderbolt to grab ACPI paths, it is important that you enable your Thunderbolt first. If you don't have the Thunderbolt enabled, refer to the guide linked below.



Single Card and Onboard Thunderbolt

STEP 2: Getting the ACPI path


Before you start preparing the SSDT, it's recommended to find the ACPI path of the Thunderbolt Card.

For Single Card and Onboard Thunderbolt:
1. Connect any Thunderbolt device to the Thunderbolt port and boot the system into macOS.
2. Download and open IOReg and type Thunderbolt in the search bar. You should see something similar to the screenshot attached below.

Screen Shot 2022-12-27 at 1.48.37 AM-min.png
Screenshot 2020-01-28 at 5.52.53 AM.png
4. Once you have located the Thunderbolt node, you can clear the search to get the complete node info.

Screen Shot 2022-12-27 at 2.10.13 AM-min.png Screenshot 2020-01-28 at 6.00.06 AM.png
5. If you check, in the above screenshot, we have some Thunderbolt and USB connectors listed. You need to locate your current path which is driving the connection to the Thunderbolt. A simple way to find this out is to just find the path having Thunderbolt properties with AppleThunderboltHAL. In our case, it is PC00.RP09.PXSX and this is our ACPI Path. Your system can have a different one. Make sure to locate the right one.

STEP 3: Obtaining Sample Thunderbolt SSDT

The next step is to obtain a sample Thunderbolt SSDT for enabling HotPlug. To obtain the sample Thunderbolt SSDT, follow the steps below.

1. Open HackinDROM website in your web browser.

Screen Shot 2022-12-25 at 6.20.04 AM-min.png
2. Depending on your Thunderbolt chipset, select the appropriate Thunderbolt Controller from the drop-down list. If you're having an onboard Thunderbolt chip, select the System Model from the list. You'll see the list of available System Models and AIC like the screenshot attached below. The list is subject to change.

Screen Shot 2021-03-13 at 5.02.25 PM.png
3. Once you select the Thunderbolt model from the drop-down list, the download button will appear. Click on the Download button to download the sample Thunderbolt SSDT.

STEP 5: Changing the ACPI Path

Now, we have got the ACPI path of the Thunderbolt. To enable the hotplug, you must change the ACPI path to match yours.

Once you have obtained the ACPI path of the Thunderbolt, the next step is to change the ACPI path in the Thunderbolt SSDT to enable Hotplug. To change the ACPI path, follow the steps below.

1. Download MaciASL of your choice.
2. Extract the MaciASL and move it to the Applications folder
3. Open the downloaded SSDT-TB3-HackinDROM.aml using MaciASL
4. Depending on your ACPI path, change the ACPI Path with the value obtained in the STEP #1. In our case, the ACPI path would be PC00.RP09.PXSX.

Before changing:
Screen Shot 2022-12-26 at 10.32.25 PM-min.png

After changing:
Screen Shot 2022-12-26 at 10.38.13 PM-min.png

6. Click on compile and look for errors in the Compiler Summary. If there's an error, fix it and again click on Compile.
Screen Shot 2022-12-26 at 10.47.02 PM-min.png

Removing additional address

For a few systems (usually Broadwell and older and some AMD) having onboard or single Thunderbolt Card installed, you'll need to remove an additional address in the SSDT. Although, this is dependent on the CPU, the amount of PCIe Devices installed and the BIOS version, this may not be the always case and your configuration may differ. This step should be only used if you have an address like below.

1. Depending on your ACPI path, you'll need to remove the External method from the sample SSDT. In our case, the system has PCI0.NPE7 ACPI path and the sample SSDT we obtained has the following external methods (after changing the ACPI path to match ours).

Code:
External (_SB_.PCI0.NPE7, DeviceObj)    // (from opcode)
External (_SB_.PCI0.NPE7.PXSX, DeviceObj)    // (from opcode)
External (DTGP, MethodObj)    // 5 Arguments (from opcode)

Now, as our system does not have the PXSX address, but only PCI0.NPE7 ACPI path, we need to remove the following External method above the DTGP line.
Code:
External (_SB_.PCI0.NPE7.PXSX, DeviceObj)    // (from opcode)

However, depending on the system you have and the sample SSDT you obtained, the external method may differ and you'll have to remove the external method accordingly.

2. As we have removed the PXSX External method, we need to remove the PXSX Scope too so that you can only have the main path.
Code:
Scope (PXSX)
{
    Name (_STA, Zero)  // _STA: Status
}

Before removing:

After removing:

3. Click on compile and look for errors in the Compiler Summary. If there's an error, fix it and again click on Compile.
Screen Shot 2022-12-26 at 10.47.02 PM-min.png

Defining additional address

For Desktop Motherboards starting with 500 series and newer, you'll also need to define an additional address in the SSDT.

1. Copy the following External method
Code:
External (_SB_.PCXX.RPXX.HRUS, DeviceObj)    // (from opcode)

2. Paste it just two lines above from the External (DTGP) line and adjust the External method as per your ACPI Path. In our case, it would be PC00.RP09.

Before changing:
Screen Shot 2022-12-26 at 10.38.13 PM-min.png
After changing:
Screen Shot 2022-12-26 at 10.42.37 PM-min.png


3. Copy the following Scope
Code:
Scope (HRUS)
{
    Name (_STA, Zero)  // _STA: Status
}

4. Put two space at the end of the first scope and paste it below the first Scope

Before changing:
Screen Shot 2022-12-26 at 10.42.37 PM-min.png

After changing:

Screen Shot 2022-12-27 at 2.14.10 AM-min.png

5. Click on compile and look for errors in the Compiler Summary. If there's an error, fix it and again click on Compile.
Screen Shot 2022-12-26 at 10.47.02 PM-min.png


STEP 6: Changing the Slot Configuration

The slot configuration is purely cosmetic but is helpful when debugging and makes the Thunderbolt nearly perfect. For onboard Thunderbolt, the slot name should be configured as Thunderbolt due to the onboard chip directly soldered on the Motherboard and for Single Thunderbolt Card, the Slot name should be configured as Slot-X. Where, the value of X depends on the physical PCIe slot having the Thunderbolt Card installed. The slot counts from the very first slot present on the Motherboard (below the CPU), regardless of the slot type i.e PCIe x1, PCIe x4, PCIe x8 or PCIe x16.

For systems with onboard Thunderbolt, the sample SSDT should be good to go as it's already configured as "Thunderbolt". To change the slot info for Single Thunderbolt Card, follow the steps below.

1. Open the modified SSDT-TB3-HackinDROM.aml using MaciASL.
2. Depending on the slot which has the Thunderbolt Card installed, change the value of AAPL, slot-name to Slot-X. There are a total of 4 occurrence and you must change all 4 of them for the full effect.

Before changing:

After changing:


3. Click on compile and look for errors in the Compiler Summary. If there's an error, fix it and again click on Compile.

Screen Shot 2022-12-26 at 10.47.02 PM-min.png

4. Save the changes to the SSDT using File>Save option.

Screen Shot 2022-12-04 at 10.06.59 PM-min.png


STEP 7: Renaming the SSDT

For Onboard Thunderbolt, rename the SSDT-TB3-HackinDROM.aml to SSDT-TB3.aml and for systems with single Thunderbolt Card, rename the SSDT-TB3-HackinDROM.aml to SSDT-TB3-SLOT-X.aml.

STEP 8: Installing the SSDT

The next step is to install the SSDT for enabling the HotPlug. Follow the steps below to install the SSDT.

1. Mount your ESP
2. Depending on your bootloader,

For Clover
If you're using Clover, copy SSDT-DTGP.aml and the related SSDT-TB3.aml to EFI/Clover/ACPI/patched directory.

For OpenCore
If you're using OpenCore, copy SSDT-DTGP.aml and the related SSDT-TB3.aml to EFI/OC/ACPI directory. You'll also need to add the ACPI entries in ACPI>Add section of your config.plist

3. Save your config.plist

STEP 5: Restarting your System

After performing all the above steps, restart your system for the applied changes to take effect. It is recommended to reset NVRAM twice at least.


Multiple Thunderbolt Setup

STEP 2: Getting the ACPI path

The next step is to find the ACPI path of the Thunderbolt Card. Without the correct path, the Thunderbolt SSDT will never load and as a result, the HotPlug will never work.
Getting the ACPI path for multiple cards is much more complex than the onboard and single Thunderbolt card setup. Follow the steps below to get the ACPI path.



You can install all the Thunderbolt Cards and get multiple ACPI paths or can also use one card in each particular slot and then get the ACPI path.

1. To check the ACPI path, just open IOReg and type Thunderbolt in the search bar.

In our case, it's PCI0.RP21.PXSX (for slot #2), PC01.BR1A.SL01 (for Slot #3) and PC03.BR3A.SL09 (for Slot #5).


2. However, this is the first phase of the ACPI path. To complete the second phase, you'll need to use a Thunderbolt SSDT and adapt for every slot except PXSX and note down the new ACPI path. Note that normally its PEGP. However, we recommend you to go through the second phase and confirm the ACPI path to make sure there is no fluke.

For Slot #3
PC01.BR1A.PEGP
For Slot #5
PC03.BR3A.PEGP


STEP 4: Configuring Thunderbolt Bus ID

With a Multiple Thunderbolt setup, you'll need to configure the Thunderbolt Bus ID for each of the Thunderbolt Card installed. The Thunderbolt Bus ID configuration is necessary for multiple Thunderbolt Controllers to make sure there is no conflicts between the multiple controllers. Each unique Bus ID represents each unique Thunderbolt Controller. To configure the Thunderbolt Bus ID, follow the steps below.

1. After selecting the Thunderbolt model from the drop-down list, click on the Customize button.
2. Under the Thunderbolt Bus ID section, change the Bus ID. You can use Bus ID starting from 0 or 1, where the 0 or 1 belongs to the first Thunderbolt Card. For example, if you have 3 Thunderbolt Cards and you would like to use the Thunderbolt Bus from 0, it would be 0, 1, and 2 respectively and if you would like to use the Thunderbolt Bus from 1, it would be simply 1, 2 and 3 respectively.
3. Once you've set the Thunderbolt Bus ID, click on the Compile button.
4. Click on the Download button and the SSDT will be downloaded/saved to your system's configured download location in your browser.
5. You'll need to refresh the website and repeat the steps 1-4 for configuring the Thunderbolt Bus ID for each of the Thunderbolt Card you have installed. This step is necessary for multiple Thunderbolt Controllers to make sure each Thunderbolt Controller has a unique Thunderbolt Bus ID and unique Thunderbolt UID. For example, if you have 3 Thunderbolt cards, you'll need to repeat the steps 1-4 for three times so that each SSDT has a different DROM.

NOTES:
  • To activate Thunderbolt Bus, you'll need to flash custom firmware onto your Thunderbolt Card.
  • For multiple Thunderbolt Cards, it's strongly recommended that you refresh the website and configure the TB Bus ID for each card to generate a random Unique ID (UID) respectively.
  • The Slot having a PXSX address is recommended to have TB Bus ID as 0 or 1. The rest should have the consecutive Bus ID.


STEP 3: Changing the ACPI Path

Once you have obtained configured the Thunderbolt Bus ID, the next step is to change the ACPI path.



STEP 5: Changing the ACPI path
Now, we have got the ACPI path of the Thunderbolt. To enable the hotplug, you must change the ACPI path to match yours.

1. Open the downloaded SSDT

For Single Card and Onboard Thunderbolt:
For single cards and onboard Thunderbolt, the steps are very simple.

If we consider our first Thunderbolt Card, which is installed on Slot #2 as the Slot #1 is reserved for GPU, the change to the SSDT, would be the following.
PCI0>PC00
1. To change that, press Command+F on your Keyboard.
2. Click on Replace checkbox in the right corner.
3. Type PCI0 in the first search box and type PC00 in the second search box.
Screen Shot 2021-03-13 at 4.00.21 PM.png
4. Click on All and the changes would be like the screenshot attached below.

Screen Shot 2021-03-13 at 4.07.01 PM.png

NOTES:
  • The rest of the path will not be changed as per the IOReg, the ACPI path for the very first Card, for Slot #2, was PC00.RP21.PXSX.
  • For the Slot having PXSX as a path in IOReg, no further SSDT modification is required.

For Multiple Thunderbolt Cards:
For Multiple Thunderbolt Cards, you'll need to perform some additional steps.

If we consider our second Thunderbolt SSDT, here would be the changes.
PCI0>PC01
1. To change that, press Command+F on your Keyboard.
2. Click on Replace checkbox in the right corner.
3. Type PCI0 in the first search box and type PC01 in the second search box.
Screen Shot 2021-03-13 at 3.18.26 PM.png
4. Click on All and the changes would be like the screenshot attached below.
Screen Shot 2021-03-13 at 3.19.13 PM.png
RP21>BR1A

5. Type RP21 in the first search box and type BR1A in the second search box.
Screen Shot 2021-03-13 at 3.19.55 PM.png
6. Click on All and the changes would be like the screenshot attached below.
Screen Shot 2021-03-13 at 3.20.50 PM.png
PXSX>PEGP
7. Type PXSX in the first search box and type PEGP in the second search box.

Screen Shot 2021-03-13 at 3.25.13 PM.png
8. Click on All and the changes would be like the screenshot attached below.

Screen Shot 2021-03-13 at 3.26.05 PM.png
Adding additional External Definition Block
If you remember the step of "Getting ACPI Path", you may have noticed that for the second Thunderbolt Card, the path was PC01.BR1A.SL01 but here we have been using PEGP. Hence, we need to add PC01.BR1A.SL01 and also define SL01. To do that, follow the steps below.

1. Copy the following External method.
Code:
External (_SB_.PC01.BR1A.SL01, DeviceObj)    // (from opcode)
2. Paste it just above the External (DTGP) line.
Once changed, the SSDT should look like the screenshot attached below.
Screen Shot 2021-03-13 at 3.33.42 PM.png

3. Copy the following Scope
Code:
Scope (SL01)
            {
                Name (_STA, Zero)  // _STA: Status
            }
4. Paste it just above the "Scope (PEGP) line.
Once changed, the SSDT should look like the screenshot attached below.
Screen Shot 2021-03-13 at 3.37.09 PM.png
Click on Compile button and save the SSDT.

NOTE:
  • You must replace the ACPI path with yours for each Thunderbolt Card installed in your system.


STEP 6: Slot Configuration

The slot configuration is purely cosmetic but is helpful when debugging and makes the Thunderbolt nearly perfect. For systems with multiple Thunderbolt Card installed, the Slot name should be configured as Slot-X, Slot-Y and so on. Where, the value of X and Y depends on the physical PCIe slot having the Thunderbolt Card installed. The slot counts from the very first slot present on the Motherboard (below the CPU), regardless of the slot type i.e PCIe x1, PCIe x4, PCIe x8 or PCIe x16. This will be applicable for each of the Thunderbolt Card installed in each of the PCIe slot and the slots will be configured using the same manner i.e Card 1 (Slot-X), Card 2 (Slot-Y) and so on. To change the slot info for Multiple Thunderbolt Cards, follow the steps below.

1. Open the modified SSDT-TB3-HackinDROM.aml using MaciASL.
2. Depending on the slot which has the Thunderbolt Card installed, change the value of AAPL, slot-name to Slot-X. There are a total of 4 occurrence and you must change all 4 of them for the full effect.

Before changing:

After changing:



3. Repeat the same steps for each of the SSDT applicable for each of the Thunderbolt Card.

STEP 7: Renaming SSDT

For multiple Thunderbolt Card setup, it's strongly recommended to rename the related SSDT-TB3-HackinDROM.aml as SSDT-TB3-SLOT-1, SSDT-TB3-SLOT-2 and so on.

STEP 8: Installing the SSDT

The next step is to install the SSDT for enabling the HotPlug. Follow the steps below to install the SSDT.

1. Mount your ESP
2. Depending on your bootloader,

For Clover
If you're using Clover, copy SSDT-DTGP.aml and the related SSDT-TB3-SLOT-X to EFI/Clover/ACPI/patched directory.

For OpenCore
If you're using OpenCore, copy SSDT-DTGP.aml and the related SSDT-TB3-SLOT-X to EFI/OC/ACPI directory. You'll also need to add the ACPI entries in ACPI>Add section of your config.plist

3. Save your config.plist

NOTES:
  • The SSDTs must be added in sorted order.
  • For Multiple Thunderbolt Cards setup, it's recommended to load the SSDT with Bus 0 first and then the rest of the Thunderbolt SSDTs.
  • For Hotplug to work with Alpine Ridge Cards, the Thunderbolt cable must be disconnected from THB_C Header.


STEP 9: Restart your System

After performing all the above steps, restart your system for the applied changes to take effect. It is recommended to reset NVRAM twice at least.

Connect any TB Device and you're good to go!


Verifying HotPlug


The next step is to verify whether the HotPlug is working or not. Follow the steps below to verify the HotPlug.




Test Results


Following are the test results for various motherboards and Thunderbolt Devices.

TEST HARDWARE:
Motherboard: GIGABYTE Z370 AORUS Elite
CPU: Intel Core i9 9900K
GPU: NVIDIA GTX 1080Ti
Thunderbolt: GIGABYTE GC-Titan Ridge, original firmware
macOS: macOS Big High Sierra 10.13.6

Thunderbolt Devices:
  • Element88
  • G-Technology


The screenshot below is with no any Thunderbolt Device connected.
Screen Shot 2020-01-22 at 20.53.42.png
The screenshot below is with the Thunderbolt Drive connected using TB2 adapter to the Motherboard.

Screen Shot 2020-01-22 at 20.51.17.png
Once the TB device is connected, the PCI looks like the following.

Screen Shot 2020-01-22 at 20.53.42.png
The Storage looks like the following.
Screen Shot 2020-01-22 at 21.04.32.png
Once the Element 88 is connected via Thunderbolt using a TB2 Adapter, the Audio looks like the following. As you can see, the transport method is TB :)
Screen Shot 2020-01-22 at 21.06.47.png
The screenshot below is with the Thunderbolt Audio Interface (Element 88) connected using TB2 adapter to the Motherboard.
Screen Shot 2020-01-22 at 21.08.09.png
In the System Preferences>Sound

Screen Shot 2020-01-22 at 21.09.50.png Screen Shot 2020-01-22 at 21.10.33.png
The IOReg for the Thunderbolt Drive. As you can see, the TB Device is connected to RP21 and the Drive is connected to DSB4 node.

Screenshot 2020-01-22 at 1.09.32 PM.png

The IOReg for the Audio Interface (Element 88). As you can see, the TB Device is connected to RP21 and the Drive is connected to DSB4 node.

Screenshot 2020-01-22 at 1.07.15 PM.png
TEST HARDWARE:
Motherboard: GIGABYTE X299X Designare 10G
CPU: Intel Core i9 10980XE
GPU: AMD 5700XT
Thunderbolt: Built-in JHL7540, original firmware
macOS: macOS Catalina 10.15.7

Thunderbolt Devices:
  • Apple Ethernet Adapter
  • Lacie Rugged 2TB
  • UAD Apollo Twin X - Duo
  • UAD-2 Satellite Thunderbolt 3 - Octo
No Thunderbolt Device Connected.

Screenshot 2020-11-12 at 13.09.22.png

Apollo Twin X Duo Connected.

Screenshot 2020-11-12 at 13.57.15.png




Screenshot 2020-11-12 at 13.56.11.png

System Preferences>Sound
Screenshot 2020-11-12 at 13.59.56.png
Screenshot 2020-11-13 at 19.32.09.png

Screenshot 2020-11-13 at 19.32.43.png

IOReg with Apollo Twin X Connected.

Screenshot 2020-11-12 at 13.53.22.png

Lacie Rugged 2TB Connected.

Screenshot 2020-11-12 at 14.05.50.png

System Report>SATA/SATA Express.

Screenshot 2020-11-12 at 14.06.32.png

DaisyChain with Port 1

UAD-2 Satellite - OCTO


Screenshot 2020-11-12 at 16.48.59.png


Apollo Twin X - DUO Connected.


Screenshot 2020-11-12 at 16.49.13.png

System Report>Audio
Screenshot 2020-11-12 at 16.48.09.png
Screenshot 2020-11-13 at 19.40.07.png

IOReg with UAD-2 Satellite - OCTO and Apollo Twin X - DUO

Screenshot 2020-11-12 at 16.47.23.png

DaisyChain with Port 2

Screenshot 2020-11-12 at 16.51.29.png

UAD connected to Port 1 and DSP to Port 2

Screenshot 2020-11-12 at 17.01.59.png

UAD Connected to Port 2 and DSP to Port 1

Screenshot 2020-11-12 at 17.09.15.png
TEST HARDWARE:
Motherboard: MSI X299 RAIDER
CPU: Intel Core i9 10940X
GPU: AMD 5700XT
Thunderbolt: 3xGIGABYTE GC-Titan Ridge, custom firmware
macOS: macOS Catalina 10.15.7

Thunderbolt Devices:
  • TBT3 SSD 480
  • Ash Creek
  • Belkin Thunderbolt 3 Mini Dock with 4K Dual HDMI
  • eGPU


Thunderbolt Bus

Screen Shot 2021-03-09 at 1.17.15 PM.png



Screen Shot 2021-03-09 at 1.17.47 PM.png








Screen Shot 2021-03-09 at 1.17.57 PM.png


Screen Shot 2021-03-09 at 1.10.02 PM.png
Screen Shot 2021-03-09 at 1.10.19 PM.png

Screen Shot 2021-03-09 at 1.10.35 PM.png
TEST HARDWARE:
Motherboard: GIGABYTE Z370 Aorus Gaming 3
CPU: Intel Core i9 10940X
GPU: AMD RX 580
Thunderbolt: GIGABYTE GC-Titan Ridge, Original Firmware
macOS: macOS Big Sur

Type-C Devices:
  • LG 38WK95C-W
TEST HARDWARE:
Motherboard: GIGABYTE Z370 Aorus Gaming 3
CPU: Intel Core i9 10940X
GPU: AMD RX 580
Thunderbolt: GIGABYTE GC-Titan Ridge, Original Firmware
macOS: macOS Big Sur

Type-C Devices:
  • LG 38WK95C-W
TEST HARDWARE:
Motherboard: EVGA X299 Micro
CPU: Intel Core i9 10940X
GPU: AMD 5700XT
Thunderbolt: 3xGIGABYTE GC-Titan Ridge, custom firmware
macOS: macOS Catalina 10.15.7

Thunderbolt Devices:
  • TBT3 SSD 480
  • Ash Creek
  • Belkin Thunderbolt 3 Mini Dock with 4K Dual HDMI
  • eGPU

FAQ [Frequently Asked Questions]


Q. Is my Thunderbolt Compatible?
A.
All the Thunderbolt models and Family listed above, at the starting of this guide are compatible and has been tested. If you have any other model and Family, feel free to post or create a separate thread.

Q. I don't see Thunderbolt information under System Report>Thunderbolt. I only see "No Drivers are loaded". Is that normal?
A. Yes, it's very normal. The reason you don't see the Thunderbolt information is due to the lack of Thunderbolt Bus, which typically requires flashing the card with a custom firmware that activates Thunderbolt Bus.

Q. Is it necessary to Flash Thunderbolt Card?
A. Yes, it's necessary if you want to use any special device which requires Bus Activation and networking capability and when using multiple Thunderbolt cards on one motherboard. Devices like Drobo require a bus activation.

Q. I've flashed my Thunderbolt Card with custom firmware. Do I still need to use SSDT?
A. Yes, you'll need to use the SSDT regardless of the case. The SSDT is what provides PCI Device, Hotplug and Bus ID.

Q. Can I activate TB Bus ID without the need of flashing the custom firmware on Alpine Ridge?
A. Yes, you can.

Q. Can I activate TB Bus ID without the need of flashing the custom firmware on Titan Ridge?
A. It may be possible. But as of now, no information is available yet.

Q. I cannot use the Audio Interface from Antelope, Presonus, Slate Digital, Focusrite, and Apogee Digital?
A. Yes, that's a well-known issue. For more information, refer to the setup linked below.

Should i disable Thunderbolt?
If you don't have any Thunderbolt Device and don't have plan at the moment or simply don't have the use case, consider it disabling to save more battery. However, disabling the Thunderbolt will also stop the Type-C function.




Problem Reporting


Details:
  1. Thunderbolt Chip and Family
  2. Thunderbolt Vendor/Manufacturer
  3. Thunderbolt Type (Onboard or AIC)
  4. Thunderbolt AIC PCI Slot Location
  5. THB_C header Availability
  6. TB BIOS Settings Availability
  7. Motherboard Model
  8. CPU Model
  9. macOS version
  10. Copy of IOReg (original, without Thunderbolt SSDT and with Thunderbolt SSDT injected)
  11. Kextcache output
Screenshots:
  • Hackintool>PCIe
  • System Report>PCI
Files:
  • For Clover, compress EFI/Clover, exclude the themes folder.
  • For OpenCore, compress EFI/OC.
Notes:
  • Do not include the complete EFI folder.
  • Put all files in a folder with your name, compress files as Zip and attach files using site attachments only.
  • Do not use any external links.

Credits :
Intel
Apple
LWN
KGP
DSM2
CaseySJ
Elias64Fr
Osy
BerndVP
Mooseknuckleboi
Ferz
OmegaRed1723


Sample Attachment



The ACPI files are attached below which has been used as an example in this guide.
 

Attachments

  • Screenshot 2020-01-28 at 7.50.41 AM.png
    Screenshot 2020-01-28 at 7.50.41 AM.png
    211.9 KB · Views: 14,835
  • Screen Shot 2020-01-22 at 21.49.22.png
    Screen Shot 2020-01-22 at 21.49.22.png
    378.7 KB · Views: 1,512
  • Screenshot 2020-11-12 at 13.56.57.png
    Screenshot 2020-11-12 at 13.56.57.png
    174.3 KB · Views: 519
  • Screenshot 2020-11-13 at 19.32.09.png
    Screenshot 2020-11-13 at 19.32.09.png
    28.7 KB · Views: 559
  • Screenshot 2020-11-13 at 19.32.43.png
    Screenshot 2020-11-13 at 19.32.43.png
    335.8 KB · Views: 974
  • SSDT-DTPG.aml.zip
    882 bytes · Views: 612
  • Screen Shot 2022-12-25 at 10.17.20 PM-min.png
    Screen Shot 2022-12-25 at 10.17.20 PM-min.png
    9.8 KB · Views: 126
Last edited:
Hello guys, thanks for the guide. Does this also work for my z170x-ud5-th? Do I need to use another SSDT? Thanks!
 
Hello guys, thanks for the guide. Does this also work for my z170x-ud5-th? Do I need to use another SSDT? Thanks!
Yes, it will work. Yes, you need to follow the guide to change the ACPI path.
 
Hello, I have tried but nothing happens. I mean, Thunderbolt works as usual but not the hotplug. Furthermore, I got an error on gigabyte bios screen on boot ”i2cwr device error” it's something related to the CPU. I rolled back my Clover folder and the error disappeared.
I will provide the screenshot and my Clover folder soon.
 
Hello, I have tried but nothing happens. I mean, Thunderbolt works as usual but not the hotplug. Furthermore, I got an error on gigabyte bios screen on boot ”i2cwr device error” it's something related to the CPU. I rolled back my Clover folder and the error disappeared.
I will provide the screenshot and my Clover folder soon.
Okay, sure.
 
I hope I've attached all the necessary. Thanks

Screenshot 2020-04-04 at 10.42.01.png Screenshot 2020-04-04 at 10.41.28.png Screenshot 2020-04-04 at 10.41.05.png
 

Attachments

  • Bardaxx's Clover Folder.zip
    1.9 MB · Views: 601
  • ioReg-Bardaxx’s iMac.zip
    858.9 KB · Views: 511
  • b6f393fc-bca4-405a-80da-95310ec4b0ff.jpg
    b6f393fc-bca4-405a-80da-95310ec4b0ff.jpg
    50.7 KB · Views: 1,043
The driver is missing. Check the guide. The configuration is not upto the mark. Grab the config.plist from here:

Change the SMBIOS to iMacPro1,1. The correct way to check TB Hotplug is. Boot the system. Connect TB, disconnect, connect. Check.

For the error during BIOS splash, is normal when using the above two drivers.
 
Which driver is missing? Can you be more specific? thanks
 

Forum statistics

Threads
1,483
Messages
14,104
Members
21,279
Latest member
katz331