- Joined
- Jul 22, 2018
- Messages
- 7,535
- Motherboard
- Supermicro X11SPA-T
- CPU
- Intel Xeon W-3275 28 Core
- Graphics
- 2xAMD RX 580 8GB
- OS X/macOS
- 13.x
- Bootloader
- OpenCore (UEFI)
- Mac
- Mac mini
- MacBook Pro
- Mobile Phone
- Android
- iOS
How to Enable Thunderbolt 4 Hotplug on macOS [Clover/OpenCore]
An EliteMacx86 Exclusive Guide - This guide covers implementation of Thunderbolt 4 Hotplug on macOS for built-in and Add In Card (AIC) Thunderbolt hardware.
Overview
Recently, Intel and Apple announced their new Thunderbolt lineup i.e Thunderbolt 4 which is Intel's and Apple's newest and most awaited interface. Thunderbolt 4 adding massive updates and improvements from its predecessor, Thunderbolt 3.
Packed with new features and functionality, the most noticeable update can be seen and experienced is the new speed. Featuring a much more "speed" and USB4 protocol and data rates.
In our previous post, we covered a guide about implementation of Thunderbolt 3 Hotplug on macOS. This guide covers the implementation of Thunderbolt 4 Hotplug on macOS.
Have another Thunderbolt hardware than Thunderbolt 4 and want to achieve Hotplug functionality? Check out our exclusive guides for Thunderbolt 3 linked below.
Enable Thunderbolt 3:
www.elitemacx86.com
Flashing Thunderbolt 3:
www.elitemacx86.com
Thunderbolt 3 Hotplug:
www.elitemacx86.com
Implementation of Hotplug with Thunderbolt has been always a major issue with macOS. But Thanks to users like DSM2, KGP, Elias, Casey who have made the progress so far. The reason why Thunderbolt Hotplug is not functional 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 about 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 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 function 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 functionality for Thunderbolt 4.
Requirements
Enabling hotplug can be 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.
Thunderbolt 4 Status and Comparisons
Following are the Thunderbolt Status for AIC and Built-In TB 4 chip. The table provides the functionality and features with Hotplug for several devices and with different Thunderbolt hardware setup such as Multiple Cards for extensive workflow.
macOS Support
You can find the support table listed below for each particular macOS version with each setup.
THB_C and TB Settings Support
You can find the requirement for THB_C, Thunderbolt Settings and USB Header for Hotplug
Thunderbolt Firmware Configuration
There can be normally two firmware configuration for Thunderbolt 4. Original and Custom firmware Configuration. Both of them have been described below.
Original Firmware:
A original firmware is provided by the vendor and is already flashed on the Thunderbolt Card. When you setup multiple Thunderbolt Cards, only one Card will work in a desired way and the other cards will not work due to the limitation of different device address.
Custom Firmware:
A custom firmware is a modified firmware provided by some of the experts from this community which eliminates the limitation of Thunderbolt Cards with different device addresses and also provides additional function such as Thunderbolt Bus and visibility under System Report>Thunderbolt.
Note:
As of now, no custom firmware is available for public testing. Tests are still under progress
Thunderbolt Configuration
There can be normally two configuration for Thunderbolt 4. Single Card and Multiple Card Configuration. Where, single card offers up to "two" thunderbolt 4 ports and multiple card can offer up to "twelve" thunderbolt 4 ports depending on the PCIe slots available on motherboard, where one slot is always reserved for the GPU. These can be further categorized into four more configuration which are outlined below.
Single Card with Original Firmware:
A single Card with original firmware can offer up to "two" Thunderbolt 4 ports which doesn't requires flashing of a custom firmware for macOS.
Single Card with Custom Firmware:
A single card with original firmware can offer up to "two" Thunderbolt 4 ports which requires flashing of a custom firmware for macOS. With a custom firmware, it can provide additional function, visibility and additional information of Thunderbolt under System Report>Thunderbolt section.
Multiple Card with Original Firmware:
Multiple cards with original firmware can range between two (minimum) or more (up to 6, maximum) Thunderbolt card 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 4 Cards. The drawback of using multiple cards with original firmware is that other than the reserved PCH slot, where the device address is usually PXSX, will be initialized and will work fully. 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, SL09.
Multiple Card with Custom Firmware:
Multiple cards with custom firmware can be best suited to professional music producers, video editors, motion and VFX artists. This option offers the maximum expandability of Thunderbolt 4. Offering 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 Cards, it removes the limitation of utilizing multiple Thunderbolt cards with different addresses. It also offers functionality such as Hot Plug 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 ports, select your configuration and start the preparation for Thunderbolt 3 Hotplug. If you're looking for a simple Thunderbolt with Hot Plug functionality and don't want to flash a custom firmware due to the complexity of the guide or not willing to take risk, the best choice would be to go for single card with original firmware. However, even if you don't want to flash your Thunderbolt with a custom firmware, you may need to flash it for some devices which requires Thunderbolt Bus to utilize a particular Thunderbolt device.
Flashing Custom Firmware
Currently, the custom firmware is not available for Thunderbolt 4. When the firmware is out, this thread will be updated automatically.
Enabling Thunderbolt 4 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.
Getting 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:
Connect any TB device and boot the system in order to get the ACPI path for the Thunderbolt Card on your Motherboard.
Now once the system is up, the next step is to get the ACPI path. To check the ACPI path, just open IOReg and type Thunderbolt in the search bar.
You should see something similar like in the attached screenshot.
View attachment 2047
Once you have located Thunderbolt node, you can clear the search to get the complete node info.
View attachment 2048
If you check, in the above screenshot, we have some Thunderbolt and USB connectors listed. You need to locate your current connector which is driving the connection to the Thunderbolt. A simple way to find this out is to just find the connector having Thunderbolt properties with AppleThunderboltHAL. In our case, it is PCI0/RP05/PXSX. Your system can have a different one. Make sure to locate the right one.
For Multiple Cards:
Getting ACPI path for multiple can be bit complex than single and onboard Thunderbolt. To find the ACPI path for multiple cards, follow the steps outlined below.
You can install all the Thunderbolt Cards and get multiple ACPI path at once or can also use one card in each particular slot and then get the ACPI path one by one.
To check the ACPI path, just open IOReg and type Thunderbolt in the search bar.
In our case, here are the following ACPI path
For Slot #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 the 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
Obtaining Sample Thunderbolt SSDT
To get the sample Thunderbolt SSDT, follow the steps below.
1. Open HackinDROM website in your web browser.
2. Select your Thunderbolt Controller from the drop-down list.
3. You'll see the list of available Motherboards and AIC like the screenshot attached below. The list is subject to change.
View attachment 3065
For Single Card and Onboard Thunderbolt:
If you're having an onboard Thunderbolt chip or a single Thunderbolt Card, just select the appropriate model from the list.
For Multiple Thunderbolt Card:
If you're having multiple Thunderbolt Card, the process will be bit different from the onboard and single Thunderbolt card.
1. Select the appropriate AIC model from the list.
Configuring TB Bus ID
For each Thunderbolt Card, you'll need to configure the TB Bus ID. This is necessary for multiple Thunderbolt Controllers installed in the system. Each unique Bus ID represents each unique Thunderbolt Controller. To configure the Bus ID, follow the steps below.
1. After selecting the AIC model from the list, click on Customize.
2. Under TB Bus ID, change the Bus ID. You can use Bus ID 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 TB Bus from 0, it would 0, 1 and 2 respectively and if you would like to use the TB Bus from 1, it would be simply 1, 2 and 3 respectively.
3. Once you've selected the TB Bus ID, click on COMPILE button.
4. Click on Download button and the SSDT will be downloaded/saved to your system's configured download location in your browser.
Note:
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 card 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 changed to the SSDT, would be the following.
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.
View attachment 3063
4. Click on All and the changes would be like the screenshot attached below.
View attachment 3064
Notes:
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.
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.
View attachment 3055
4. Click on All and the changes would be like the screenshot attached below.
View attachment 3056
5. Type RP21 in the first search box and type BR1A in the second search box.
View attachment 3057
6. Click on All and the changes would be like the screenshot attached below.
View attachment 3058
View attachment 3059
8. Click on All and the changes would be like the screenshot attached below.
View attachment 3060
Adding additional External Definition Block
If you remember the step of "Getting ACPI Path", you may have noticed that for 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.
2. Paste it just above the External (DTGP) line.
Once changed, the SSDT should look like the screenshot attached below.
View attachment 3061
3. Copy the following Scope
4. Paste it just above the "Scope (PEGP) line.
Once changed, the SSDT should look the screenshot attached below.
View attachment 3062
Click on Compile button and save the SSDT.
Note:
Slot Configuration
The slot configuration is purely cosmetic but is helpful when debugging and makes the Thunderbolt nearly perfect. The slot counts will be from the very slot present on the Motherboard, regardless of the slot type. There can be three slot configuration for Thunderbolt 3. Onboard and Single/Multiple Thunderbolt
Onboard Thunderbolt:
For onboard Thunderbolt, the slot will be configured as "built-in" due to onboard chip directly soldered on the Motherboard. For onboard Thunderbolt configuration, the sample SSDT should be good to go as it's already configured as built-in.
Singe/Multiple Thunderbolt Card:
For single or multiple Thunderbolt, the slot will be configured as Slot-1, Slot-2 and so on. To change the Slot configuration, follow the steps below.
If we consider our first sample SSDT, which refers to the very first Thunderbolt Card installed in Slot #2, the changes would be the following.
The sample SSDT has Slot-4 as a configuration and the changes would be the following.
Note:
Renaming SSDT
If you're using multiple Thunderbolt Card, it's strongly recommended to rename the SSDTs as SSDT-TB3-SLOT1, SSDT-TB3-SLOT2 and so on.
Installing the SSDT
Now, the SSDT has our ACPI path. The next step is to install the SSDT.
1. Mount the EFI partition of the system
2. Open the EFI folder.
For OpenCore:
1. Navigate to EFI/OC/ACPI/patched directory.
2. Place the SSDT-DTGP and the related SSDT-TB3-SLOT-X.
For Clover:
1. Navigate to EFI/Clover/ACPI/patched directory.
2. Place the SSDT-DTGP and the related SSDT-TB3-SLOT-X.
Notes:
1. Download the following kext and driver.
ThunderboltReset
TbtForcePower.efi
2. After downloading the drivers, extract it.
3. Copy ThunderboltReset.kext to EFI/Kext/Other directory.
4. Copy the TbtForcePower.efi to EFI/Drivers/UEFI
Restart your System
After performing all the above steps, restart your system for the applied changes to take effect.
Connect any TB Device and you're good to go!
Test Results
Following are the test results for various motherboards and Thunderbolt Devices.
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. 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.
Q. I've flashed my Thunderbolt Card with a 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 available yet.
Problem Reporting
Details:
Credits:
KGP
DSM2
CaseySJ
Elias64Fr
Mooseknuckleboi for testing, providing test reports and video demonstration
Dario
Sample Attachment
The SSDT is attached below which has been used as an example in this guide.
An EliteMacx86 Exclusive Guide - This guide covers implementation of Thunderbolt 4 Hotplug on macOS for built-in and Add In Card (AIC) Thunderbolt hardware.
Overview
Recently, Intel and Apple announced their new Thunderbolt lineup i.e Thunderbolt 4 which is Intel's and Apple's newest and most awaited interface. Thunderbolt 4 adding massive updates and improvements from its predecessor, Thunderbolt 3.
Packed with new features and functionality, the most noticeable update can be seen and experienced is the new speed. Featuring a much more "speed" and USB4 protocol and data rates.
In our previous post, we covered a guide about implementation of Thunderbolt 3 Hotplug on macOS. This guide covers the implementation of Thunderbolt 4 Hotplug on macOS.
Have another Thunderbolt hardware than Thunderbolt 4 and want to achieve Hotplug functionality? Check out our exclusive guides for Thunderbolt 3 linked below.
Enable Thunderbolt 3:
GUIDE - How to Enable ThunderBolt on macOS
How to Enable ThunderBolt 2, Thunderbolt 3 and Thunderbolt 4 on maOS [Clover/OpenCore] An EliteMacx86 Exclusive Guide - This guide covers implementation of Thunderbolt 2, Thunderbolt 3 and Thunderbolt 4 on macOS using Clover and OpenCore. Overview This guide covers the implementation of...
www.elitemacx86.com
Flashing Thunderbolt 3:
GUIDE - How to Flash Custom Firmware on Thunderbolt Card for macOS
How to Flash Custom Firmware on Thunderbolt Card for macOS Overview Following is a Thunderbolt firmware flashing guide exclusively for macOS. The guide is applicable for Motherboards having Built-In Thunderbolt, Laptops, and Add-In Cards. The method is tested by us on the following Add-In...
www.elitemacx86.com
Thunderbolt 3 Hotplug:
GUIDE - How to Enable Thunderbolt 3 Hotplug on macOS
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...
www.elitemacx86.com
Implementation of Hotplug with Thunderbolt has been always a major issue with macOS. But Thanks to users like DSM2, KGP, Elias, Casey who have made the progress so far. The reason why Thunderbolt Hotplug is not functional 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 about 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 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 function 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 functionality for Thunderbolt 4.
Requirements
| Compatible Thunderbolt Chipset | |
| Vanilla Thunderbolt kexts in S/L/E | |
| Any Thunderbolt compatible Device to check and verify the status | |
| MaciASL | |
| IOReg |
Enabling hotplug can be 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.
Thunderbolt 4 Status and Comparisons
Following are the Thunderbolt Status for AIC and Built-In TB 4 chip. The table provides the functionality and features with Hotplug for several devices and with different Thunderbolt hardware setup such as Multiple Cards for extensive workflow.
| Thunderbolt Comparison |
|---|
| Function on macOS | Single Card with Original Firmware | Single Card with Custom Firmware | Multiple Cards with Original Firmware | Multiple Cards with Custom Firmware |
|---|---|---|---|---|
| Booting with Thunderbolt Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Hotplug with Cold Boot | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Hotplug with Warm Boot | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Hotplug with no Device Connected at Boot | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Sleep with Thunderbolt Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Wake with Thunderbolt Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Shut Down with Thunderbolt Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Auto Reconnect after Sleep | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| USB Type-C Comparison |
|---|
| Function on macOS | Single Card with Original Firmware | Single Card with Custom Firmware | Multiple Cards with Original Firmware | Multiple Cards with Custom Firmware |
|---|---|---|---|---|
| Booting with USB Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| USB Hotplug with Cold Boot | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| USB Hotplug with Warm Boot | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Sleep with USB Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Wake with USB Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Shut Down with USB Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| USB Type-C Auto Reconnect after Sleep | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Display Comparison |
|---|
| Function on macOS | Single Card with Original Firmware | Single Card with Custom Firmware | Multiple Cards with Original Firmware | Multiple Cards with Custom Firmware |
|---|---|---|---|---|
| Booting with Thunderbolt Device Connected | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Display | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Type-C Display | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Type-C Display Cold Boot | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Type-C Display Hotplug | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Apple Thunderbolt Cinema Display | NOT TESTED |
| Dock Comparison |
|---|
| Function on macOS | Single Card with Original Firmware | Single Card with Custom Firmware | Multiple Cards with Original Firmware | Multiple Cards with Custom Firmware |
|---|---|---|---|---|
| Thunderbolt Dock | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Dock Hotplug | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Dock Ethernet | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Dock Display Port | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Dock HDMI | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Dock USB | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Dock Audio | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| eGPU Comparison |
|---|
| Function on macOS | Single Card with Original Firmware | Single Card with Custom Firmware | Multiple Cards with Original Firmware | Multiple Cards with Custom Firmware |
|---|---|---|---|---|
| Thunderbolt eGPU | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt eGPU Hotplug | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Audio Comparison |
|---|
| Function on macOS | Single Card with Original Firmware | Single Card with Custom Firmware | Multiple Cards with Original Firmware | Multiple Cards with Custom Firmware |
|---|---|---|---|---|
| Thunderbolt Audio Interface | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Audio Interface Hotplug | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Adapters Comparison |
|---|
| Function on macOS | Single Card with Original Firmware | Single Card with Custom Firmware | Multiple Cards with Original Firmware | Multiple Cards with Custom Firmware |
|---|---|---|---|---|
| Thunderbolt Ethernet Adapter | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Ethernet Adapter Hotplug | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt 2 to Thunderbolt 3 | YES | TEST IN PROGRESS | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt Comparison |
|---|
| Function on macOS | Original Firmware | Custom Firmware |
|---|---|---|
| Booting with Thunderbolt Device Connected | YES | TEST IN PROGRESS |
| Thunderbolt Hotplug with Cold Boot | YES | TEST IN PROGRESS |
| Thunderbolt Hotplug with Warm Boot | YES | TEST IN PROGRESS |
| Thunderbolt Hotplug with no Device Connected at Boot | YES | TEST IN PROGRESS |
| Sleep with Thunderbolt Device Connected | YES | TEST IN PROGRESS |
| Wake with Thunderbolt Device Connected | YES | TEST IN PROGRESS |
| Shut Down with Thunderbolt Device Connected | YES | TEST IN PROGRESS |
| Thunderbolt Auto Reconnect after Sleep | YES | TEST IN PROGRESS |
| USB Type-C Comparison |
|---|
| Function on macOS | Original Firmware | Custom Firmware |
|---|---|---|
| Booting with USB Device Connected | YES | TEST IN PROGRESS |
| USB Hotplug with Cold Boot | YES | TEST IN PROGRESS |
| USB Hotplug with Warm Boot | YES | TEST IN PROGRESS |
| Sleep with USB Device Connected | YES | TEST IN PROGRESS |
| Wake with USB Device Connected | YES | TEST IN PROGRESS |
| Shut Down with USB Device Connected | YES | TEST IN PROGRESS |
| USB Type-C Auto Reconnect after Sleep | YES | TEST IN PROGRESS |
| Display Comparison |
|---|
| Function on macOS | Original Firmware | Custom Firmware |
|---|---|---|
| Booting with Thunderbolt Device Connected | YES | TEST IN PROGRESS |
| Thunderbolt Display | YES | TEST IN PROGRESS |
| Type-C Display | YES | TEST IN PROGRESS |
| Type-C Display Cold Boot | YES | TEST IN PROGRESS |
| Type-C Display Hotplug | YES | TEST IN PROGRESS |
| Apple Thunderbolt Cinema Display | NOT TESTED |
| Dock Comparison |
|---|
| Function on macOS | Original Firmware | Custom Firmware |
|---|---|---|
| Thunderbolt Dock | YES | TEST IN PROGRESS |
| Thunderbolt Dock Hotplug | YES | TEST IN PROGRESS |
| Thunderbolt Dock Ethernet | YES | TEST IN PROGRESS |
| Thunderbolt Dock Display Port | YES | TEST IN PROGRESS |
| Thunderbolt Dock HDMI | YES | TEST IN PROGRESS |
| Thunderbolt Dock USB | YES | TEST IN PROGRESS |
| Thunderbolt Dock Audio | YES | TEST IN PROGRESS |
| eGPU Comparison |
|---|
| Function on macOS | Original Firmware | Custom Firmware |
|---|---|---|
| Booting with Thunderbolt eGPU | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt eGPU Hotplug on Cold Boot | TEST IN PROGRESS | TEST IN PROGRESS |
| Thunderbolt eGPU Hotplug on Warm Boot | TEST IN PROGRESS | |
| Sleep with Thunderbolt eGPU Hotplug | TEST IN PROGRESS | |
| Thunderbolt eGPU Auto Reconnect after Sleep | TEST IN PROGRESS |
| Audio Comparison |
|---|
| Function on macOS | Original Firmware | Custom Firmware |
|---|---|---|
| Thunderbolt Audio Interface | YES | TEST IN PROGRESS |
| Thunderbolt Audio Interface Hotplug | YES | TEST IN PROGRESS |
| Adapters Comparison |
|---|
| Function on macOS | Original Firmware | Custom Firmware |
|---|---|---|
| Thunderbolt Ethernet Adapter | YES | TEST IN PROGRESS |
| Thunderbolt Ethernet Adapter Hotplug | YES | TEST IN PROGRESS |
| Thunderbolt 2 to Thunderbolt 3 | YES | TEST IN PROGRESS |
macOS Support
You can find the support table listed below for each particular macOS version with each setup.
| Controller | Family | macOS Sierra | macOS High Sierra | macOS Mojave | macOS Catalina | macOS Big Sur |
|---|---|---|---|---|---|---|
| JHL8340 | Maple Ridge | NO | NO | NO | YES | YES |
| JHL8540 | Maple Ridge | NO | NO | NO | YES | YES |
| JHL8440 | Goshen Ridge | NO | NO | NO | YES | YES |
THB_C and TB Settings Support
You can find the requirement for THB_C, Thunderbolt Settings and USB Header for Hotplug
| Availability | Thunderbolt Hotplug | USB Type-C Hotplug |
|---|---|---|
| THB_C Header Connected | YES | YES |
| THB_C Header Disconnected | YES | YES |
| TB Settings Available | YES | YES |
| No TB Settings Available | YES | YES |
| USB Header Connected | YES | YES |
| USB Header Disconnected | YES | YES |
Thunderbolt Firmware Configuration
There can be normally two firmware configuration for Thunderbolt 4. Original and Custom firmware Configuration. Both of them have been described below.
Original Firmware:
A original firmware is provided by the vendor and is already flashed on the Thunderbolt Card. When you setup multiple Thunderbolt Cards, only one Card will work in a desired way and the other cards will not work due to the limitation of different device address.
Custom Firmware:
A custom firmware is a modified firmware provided by some of the experts from this community which eliminates the limitation of Thunderbolt Cards with different device addresses and also provides additional function such as Thunderbolt Bus and visibility under System Report>Thunderbolt.
Note:
As of now, no custom firmware is available for public testing. Tests are still under progress
Thunderbolt Configuration
There can be normally two configuration for Thunderbolt 4. Single Card and Multiple Card Configuration. Where, single card offers up to "two" thunderbolt 4 ports and multiple card can offer up to "twelve" thunderbolt 4 ports depending on the PCIe slots available on motherboard, where one slot is always reserved for the GPU. These can be further categorized into four more configuration which are outlined below.
Single Card with Original Firmware:
A single Card with original firmware can offer up to "two" Thunderbolt 4 ports which doesn't requires flashing of a custom firmware for macOS.
Single Card with Custom Firmware:
A single card with original firmware can offer up to "two" Thunderbolt 4 ports which requires flashing of a custom firmware for macOS. With a custom firmware, it can provide additional function, visibility and additional information of Thunderbolt under System Report>Thunderbolt section.
Multiple Card with Original Firmware:
Multiple cards with original firmware can range between two (minimum) or more (up to 6, maximum) Thunderbolt card 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 4 Cards. The drawback of using multiple cards with original firmware is that other than the reserved PCH slot, where the device address is usually PXSX, will be initialized and will work fully. 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, SL09.
Multiple Card with Custom Firmware:
Multiple cards with custom firmware can be best suited to professional music producers, video editors, motion and VFX artists. This option offers the maximum expandability of Thunderbolt 4. Offering 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 Cards, it removes the limitation of utilizing multiple Thunderbolt cards with different addresses. It also offers functionality such as Hot Plug 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 ports, select your configuration and start the preparation for Thunderbolt 3 Hotplug. If you're looking for a simple Thunderbolt with Hot Plug functionality and don't want to flash a custom firmware due to the complexity of the guide or not willing to take risk, the best choice would be to go for single card with original firmware. However, even if you don't want to flash your Thunderbolt with a custom firmware, you may need to flash it for some devices which requires Thunderbolt Bus to utilize a particular Thunderbolt device.
Flashing Custom Firmware
Currently, the custom firmware is not available for Thunderbolt 4. When the firmware is out, this thread will be updated automatically.
Enabling Thunderbolt 4 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.
Getting 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:
Connect any TB device and boot the system in order to get the ACPI path for the Thunderbolt Card on your Motherboard.
Now once the system is up, the next step is to get the ACPI path. To check the ACPI path, just open IOReg and type Thunderbolt in the search bar.
You should see something similar like in the attached screenshot.
View attachment 2047
Once you have located Thunderbolt node, you can clear the search to get the complete node info.
View attachment 2048
If you check, in the above screenshot, we have some Thunderbolt and USB connectors listed. You need to locate your current connector which is driving the connection to the Thunderbolt. A simple way to find this out is to just find the connector having Thunderbolt properties with AppleThunderboltHAL. In our case, it is PCI0/RP05/PXSX. Your system can have a different one. Make sure to locate the right one.
For Multiple Cards:
Getting ACPI path for multiple can be bit complex than single and onboard Thunderbolt. To find the ACPI path for multiple cards, follow the steps outlined below.
You can install all the Thunderbolt Cards and get multiple ACPI path at once or can also use one card in each particular slot and then get the ACPI path one by one.
To check the ACPI path, just open IOReg and type Thunderbolt in the search bar.
In our case, here are the following ACPI path
For Slot #2
For Slot #3
For Slot #5
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 the 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
For Slot #5
Obtaining Sample Thunderbolt SSDT
To get the sample Thunderbolt SSDT, follow the steps below.
1. Open HackinDROM website in your web browser.
2. Select your Thunderbolt Controller from the drop-down list.
3. You'll see the list of available Motherboards and AIC like the screenshot attached below. The list is subject to change.
View attachment 3065
For Single Card and Onboard Thunderbolt:
If you're having an onboard Thunderbolt chip or a single Thunderbolt Card, just select the appropriate model from the list.
For Multiple Thunderbolt Card:
If you're having multiple Thunderbolt Card, the process will be bit different from the onboard and single Thunderbolt card.
1. Select the appropriate AIC model from the list.
Configuring TB Bus ID
For each Thunderbolt Card, you'll need to configure the TB Bus ID. This is necessary for multiple Thunderbolt Controllers installed in the system. Each unique Bus ID represents each unique Thunderbolt Controller. To configure the Bus ID, follow the steps below.
1. After selecting the AIC model from the list, click on Customize.
2. Under TB Bus ID, change the Bus ID. You can use Bus ID 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 TB Bus from 0, it would 0, 1 and 2 respectively and if you would like to use the TB Bus from 1, it would be simply 1, 2 and 3 respectively.
3. Once you've selected the TB Bus ID, click on COMPILE button.
4. Click on Download button and the SSDT will be downloaded/saved to your system's configured download location in your browser.
Note:
- To activate Thunderbolt Bus, you'll need to flash a 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 random Unique ID (UID) respectively.
- The Slot having PXSX address, is recommended to have TB Bus ID as 0. The rest should have 1, 2, 3 and so on.
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 card 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 changed to the SSDT, would be the following.
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.
View attachment 3063
4. Click on All and the changes would be like the screenshot attached below.
View attachment 3064
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.
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.
View attachment 3055
4. Click on All and the changes would be like the screenshot attached below.
View attachment 3056
5. Type RP21 in the first search box and type BR1A in the second search box.
View attachment 3057
6. Click on All and the changes would be like the screenshot attached below.
View attachment 3058
7. Type PXSX in the first search box and type PEGP in the second search box.
View attachment 3059
8. Click on All and the changes would be like the screenshot attached below.
View attachment 3060
Adding additional External Definition Block
If you remember the step of "Getting ACPI Path", you may have noticed that for 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)Once changed, the SSDT should look like the screenshot attached below.
View attachment 3061
3. Copy the following Scope
Code:
Scope (SL01)
{
Name (_STA, Zero) // _STA: Status
}Once changed, the SSDT should look the screenshot attached below.
View attachment 3062
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.
Slot Configuration
The slot configuration is purely cosmetic but is helpful when debugging and makes the Thunderbolt nearly perfect. The slot counts will be from the very slot present on the Motherboard, regardless of the slot type. There can be three slot configuration for Thunderbolt 3. Onboard and Single/Multiple Thunderbolt
Onboard Thunderbolt:
For onboard Thunderbolt, the slot will be configured as "built-in" due to onboard chip directly soldered on the Motherboard. For onboard Thunderbolt configuration, the sample SSDT should be good to go as it's already configured as built-in.
Singe/Multiple Thunderbolt Card:
For single or multiple Thunderbolt, the slot will be configured as Slot-1, Slot-2 and so on. To change the Slot configuration, follow the steps below.
If we consider our first sample SSDT, which refers to the very first Thunderbolt Card installed in Slot #2, the changes would be the following.
The sample SSDT has Slot-4 as a configuration and the changes would be the following.
1. Type Slot-4 in the first search box and type Slot-2 in the second search box and click on All.
Note:
- When having a multiple Thunderbolt Card, the same steps will be applied as above to the rest of the SSDTs.
Renaming SSDT
If you're using multiple Thunderbolt Card, it's strongly recommended to rename the SSDTs as SSDT-TB3-SLOT1, SSDT-TB3-SLOT2 and so on.
Installing the SSDT
Now, the SSDT has our ACPI path. The next step is to install the SSDT.
1. Mount the EFI partition of the system
2. Open the EFI folder.
For OpenCore:
1. Navigate to EFI/OC/ACPI/patched directory.
2. Place the SSDT-DTGP and the related SSDT-TB3-SLOT-X.
For Clover:
1. Navigate to EFI/Clover/ACPI/patched directory.
2. Place the SSDT-DTGP and the related SSDT-TB3-SLOT-X.
Notes:
- For OpenCore, you'll need to add the SSDTs entry in the ACPI section of your config.plist.
- The SSDTs must be added in a sorted order. It's recommended to load the SSDT with "PXSX" first and then the rest and the TB Bus ID will be also start from PXSX SSDT, regardless of the Slot order.
1. Download the following kext and driver.
ThunderboltReset
TbtForcePower.efi
2. After downloading the drivers, extract it.
3. Copy ThunderboltReset.kext to EFI/Kext/Other directory.
4. Copy the TbtForcePower.efi to EFI/Drivers/UEFI
Restart your System
After performing all the above steps, restart your system for the applied changes to take effect.
Connect any TB Device and you're good to go!
Test Results
Following are the test results for various motherboards and Thunderbolt Devices.
Quick Video Demonstration:
TEST HARDWARE:
Motherboard: MSI MEG Z590 UNIFY
CPU: Intel Core i9 10900F
GPU: AMD 5700XT
Thunderbolt: Built-in JHL8540, original firmware
macOS: macOS Big Sur 11.2
Thunderbolt Devices:
No Thunderbolt Device Connected
System Report>PCI
System Report>Thunderbolt
UAD Control Panel
UAD Apollo Twin X - Duo Connected
System Report>PCI
System Report>Audio
System Preferences>Sound>Output
System Preferences>Sound>Input
UAD Control Panel with Apollo Twin X - DUO Connected
IOReg with UAD Apollo Twin X - Duo Connected
UAD Apollo x6 - HEXA Connected
Antelope Galaxy64 Connected, Hotplug Working State
IOReg with UAD Apollo x6 - HEXA Connected
IOReg with UAD Apollo x6 - HEXA Disconnected
UAD Apollo x6 - HEXA Reconnected
UAD Control Panel with Apollo Twin X - DUO Connected
UAD Apollo x16 - HEXA Connected
UAD Apollo x16 - HEXA Connected Hotplug
UAD Apollo x16 - HEXA Connected
UAD Apollo x16 - HEXA Disconnected
IOReg with UAD Apollo x16 - HEXA Reconnected
UAD Control Panel with UAD Apollo x16 - HEXA Connected
UAD-2 Satellite Thunderbolt 3 - OCTO Connected
IOReg with UAD-2 Satellite Thunderbolt 3 - OCTO Connected
IOReg with UAD-2 Satellite Thunderbolt 3 - OCTO Disconnected
IOReg with UAD-2 Satellite Thunderbolt 3 - OCTO Reconnected
UAD Control Panel with UAD-2 Satellite Thunderbolt 3 - OCTO Connected
Daisy chain with UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16
UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Connected
UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Disconnected
UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Reconnected
UAD Apollo Twin X - Duo+UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Connected
TEST HARDWARE:
Motherboard: MSI MEG Z590 UNIFY
CPU: Intel Core i9 10900F
GPU: AMD 5700XT
Thunderbolt: Built-in JHL8540, original firmware
macOS: macOS Big Sur 11.2
Thunderbolt Devices:
- SONY Professional RAID 4TB
- JZLL M.2 Drive Enclosure
- Apple Thunderbolt 3 (USB-C) to Thunderbolt 2 Adapter
- UAD Apollo Twin X - Duo
- UAD Apollo x6 - Hexa
- UAD Apollo x16 - Hexa
- UAD-2 Satellite Thunderbolt 3 - Octo
No Thunderbolt Device Connected
System Report>PCI
System Report>Thunderbolt
UAD Control Panel
UAD Apollo Twin X - Duo Connected
System Report>PCI
System Report>Audio
System Preferences>Sound>Output
System Preferences>Sound>Input
UAD Control Panel with Apollo Twin X - DUO Connected
IOReg with UAD Apollo Twin X - Duo Connected
UAD Apollo x6 - HEXA Connected
Antelope Galaxy64 Connected, Hotplug Working State
IOReg with UAD Apollo x6 - HEXA Connected
IOReg with UAD Apollo x6 - HEXA Disconnected
UAD Apollo x6 - HEXA Reconnected
UAD Control Panel with Apollo Twin X - DUO Connected
UAD Apollo x16 - HEXA Connected
UAD Apollo x16 - HEXA Connected Hotplug
UAD Apollo x16 - HEXA Connected
UAD Apollo x16 - HEXA Disconnected
IOReg with UAD Apollo x16 - HEXA Reconnected
UAD Control Panel with UAD Apollo x16 - HEXA Connected
UAD-2 Satellite Thunderbolt 3 - OCTO Connected
IOReg with UAD-2 Satellite Thunderbolt 3 - OCTO Connected
IOReg with UAD-2 Satellite Thunderbolt 3 - OCTO Disconnected
IOReg with UAD-2 Satellite Thunderbolt 3 - OCTO Reconnected
UAD Control Panel with UAD-2 Satellite Thunderbolt 3 - OCTO Connected
Daisy chain with UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16
UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Connected
UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Disconnected
UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Reconnected
UAD Apollo Twin X - Duo+UAD-2 Satellite Thunderbolt 3 - OCTO+UAD Apollo x6 - HEXA+UAD Apollo x16 Connected
To be added
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. 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.
Q. I've flashed my Thunderbolt Card with a 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 available yet.
Problem Reporting
Details:
- Thunderbolt Chip and Family
- Thunderbolt Vendor/Manufacturer
- Thunderbolt Type (Onboard or AIC)
- Thunderbolt AIC PCI Slot Location
- THB_C header Availability
- TB BIOS Settings Availability
- Motherboard Model
- CPU Model
- macOS version
- Copy of IOReg
- Kextcache output
- Hackintool>PCIe
- System Report>PCI
- For Clover, compress EFI/Clover, exclude the themes folder.
- For OpenCore, compress EFI/OC.
- Do not include 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:
KGP
DSM2
CaseySJ
Elias64Fr
Mooseknuckleboi for testing, providing test reports and video demonstration
Dario
Sample Attachment
The SSDT is attached below which has been used as an example in this guide.
Last edited:
