GUIDE How to Enable Native USB Ports on macOS

[EliteMacx86]

How to Enable Native USB Ports on macOS​

This guide describes how to enable native USB ports on macOS. By following this guide, you'll be able to map the USB ports on macOS. This guide supports both, Intel and AMD platforms and works with Clover and OpenCore bootloaders.

I. Overview​

Often, the USB ports are not well recognized or have certain issues. This is quite true on AMD platforms running macOS, especially on Desktops and/or HEDT segments. Although there are several ways to enable the USB ports on macOS, including but not limited to USBInjectAll paired with Xhciportlimit quirk and some other kexts that are depreciated now and some injector based kexts such as XHCIUnsupported.kext. The method to enable the USB ports via ACPI edit using the native ACPI table has existed for almost a decade and that's how the USB ports are actually defined by the OEM. This table can be modified to enable/disable the ports on the fly.

In the ACPI namespace, the _UPC controls the USB. This optional object is a method that allows the platform to communicate to the operating system, certain USB port capabilities that are not provided for through current USB host bus adaptor specifications (e.g. UHCI, OHCI and EHCI). If implemented by the platform, this object will be present for each USB port (child) on a given USB host bus adaptor; operating system software can examine these characteristics at boot time in order to gain knowledge about the system’s USB topology, available USB ports, etc. This method is applicable to USB root hub ports as well as ports that are implemented through integrated USB hubs.

II. Why USB Mapping is necessary?​

USB Mapping is necessary because of the following reasons which have been mentioned below.

• macOS is unable to recognize the USB ports and their type;
• Few ports run at a slower speed than their original rated speed;
• Port Type mismatch;
• Bluetooth or Webcam not working;
• Broken Sleep/Wake function. Most of the sleep related issues are caused by the USB ports.

III. Port Limit​

Since OS X 10.11 (El Capitan), Apple introduced Port Limit. Port Limit under OS X/macOS is a limitation of the number of ports per USB Controller. Apple set 15 ports per controller which work great for Apple Mac computers, however, it is an issue for non-Apple computers. By default, most Desktop boards define a significant number of USB Ports in the ACPI Table. For example, according to Intel's Skylake specs, there can be up to 24 ports and in some cases, the newer series chipset can have up to 26 ports in total. Depending on the chipset, the port specs can actually differ. For example, Intel's 8/9 series chipsets support a maximum of 14 ports. Note that USB 3.0 ports are counted twice (once at the beginning in USB 2.0 mode, then at the end in USB 3.0 mode). These are not the actual physical ports but are declared in ACPI Table and due to this, OS X/macOS cannot differentiate between a real port and one which is not removed in the ACPI tables.

You may have a question that why did Apple choose 15 ports as the limit, there is an answer to your question. Apple chooses 15 ports as a limit due to two specific reasons.

• Hexadecimal system. If you convert 15 to Hexadecimal, it would be 0xF and this made more sense to stop at 15 than to expand the port limit.
• Secondly, no Macs have more than 15 ports and even if a user adds an external USB Card, it will have its own 15 port limit as the controller differs. The thumb of the rule is 15 ports per controller.

To determine whether you have such a limit and if your system is affected, you can run the following commands in the Terminal

Code:
# For OS X 10.11<br>syslog | grep "ports limit reached"<br><br>#For macOS 10.12 and newer<br>log show --last boot | grep "ports limit reached"

Running the above command on a typical Z370 Chipset, the output of the operation may look like below

Code:
XHC @14000000: AppleUSBXHCIPCI::createPorts: ports limit reached. Not creating the remaining 6 ports

If you're having such a limit, it can be an issue and not only it affects the speed of the USB ports but most of the USB ports (typically USB 3.0/3.1/3.2/Type-C) will not be recognized due to the fact when having more than 15 ports defined in ACPI Table, not all ports are recognized by OS X/macOS but only the first 15 ports and the rest ports remain uninitialized.

To get around this port limit issue, a workaround was discovered back then, which was to use a Kernel Patch (known as Port Limit Patch) to increase the port limit to 26 so that OS X/macOS can initialize more ports instead of 15. You can increase it to the desired number using a patch. Still, mapping was considered the best option as it is now, however, this served lazy users who didn't want to go through the long process of mapping.

Spoiler: Port Limit Patches

Initially, these port limit patches served for a quite long time (OS X El Capitan to macOS Catalina) but in fact, Apple is constantly changing the code, and patches for the port limit change every 2-3 minor updates. So, with the introduction of OpenCore, these port limit patches (depreciated now) were replaced by XhciPortLimit Quirk and it worked well till macOS Big Sur 11.2.3. This means up to macOS Big Sur 11.2.3, it was possible to bypass the port limit where you can have more than 15 ports. But since Big Sur 11.3, Apple made some changes to its USB implementation. With the new re-written drivers, the port limit was broken and it was limited back to 15 only. This simply means that on Big Sur 11.3 and later, you cannot have more than 15 ports. Due to this, some users have either all 2.0 ports or 3.0 only or a mixed combination (if using XhciPortLimit Quirk). However, this caused problems with Bluetooth and HID devices which use pure USB 2.0 to function. However, a workaround was to map the USB ports and use XhciPortLimit Quirk along with the mapped kext and you can have more than 15 ports on the system, however, this may not work with all systems and there can be still a port limit.

Considering all these aspects, it is now more practical to make a plist-only (codeless) kext and is mandatory. The XhciPortLimit Quirk can be really helpful (up to macOS Big Sur 11.2.3) when combined with USBInjectAll and XHCIUnsupported (where applicable) to discover the ports for mapping. This will allow you to discover all ports in one go. However, this is limited up to macOS Big Sur 11.2.3 only. For the latter, you need to go through 2 rounds for mapping 2.0 and 3.0/3.1/Type-C ports respectively. Note that this combination should not be used in a production environment even if you're using (up to macOS Big Sur 11.2.3) but it is only intended for discovering ports for mapping purposes.

The XchiPortLimit Quirk patches several USB kexts (AppleUSBXHCI.kext, AppleUSBXHCIPCI.kext, IOUSBHostFamily.kext) to remove USB port count limit of 15 ports. Using XchiPortLimit Quirk, it can bypass the port limit, sounds amazing yeah? But let's see what could happen if you use XhciPortLimit Quirk. Technically, this Quirk can cause data corruption as this quirk tries to push the 0xF limit and therefore enters someone else's space. It is strongly recommended to avoid this quirk when possible.

USB port limit is imposed by the number of used bits in locationID format and there is no possible way of workaround without heavy OS modification. The only valid solution is to limit the number of used ports to 15 (discarding some).

QUICK INFO:

• Since Big Sur 11.3, the XHCIPortLimit patch is broken, so you need to have 2 rounds to map the ports. First with XHCIPortLimit disabled to map the USB 2.0 ports. Second with XHCIPortLimit enabled to map the USB 3.0/3.1/Type-C ports. If you don't want to have 2 rounds, use Big Sur 11.2.3 (max) to map all the ports at once.
• It is recommended to use Big Sur 11.2.3 for mapping the Ports due to the broken XhciPortLimit Quirk. By using Big Sur 11.2.3, you don't need to switch between the XhciPortLimit Quirk to discover the ports.
• Starting with OpenCore v0.9.3, the XhciPortLimit Quirk is improved and now it's possible to map the 2.0 and 3.0/3.1/3.2/Type-C ports in one go.

As some of the ports are not used at all and most of the time, the users don't have a need to utilize all the physical ports given in a particular system, it is recommended to map the ports under the limit of 15 only. You should only keep those ports enabled that you need to use and remove the rest of the working/non-working ports for a good cause. In addition, once the ports are mapped, you should disable the XhciPortLimit Quirk and avoid the use of USBInjectAll. As a reminder again, this combination should not be used in a production environment even if you're using (up to macOS Big Sur 11.2.3) but it is only intended for initial mapping purposes. This applies to macOS Big Sur 11.3 and later as well. For demonstration, this guide provides the mapping instructions with port limits bypassed (if a user needs them in a rare case) and under 15 port limits.

IV. Problematic USB Devices​

Some USB devices that do not have proper support in macOS due to a lack of drivers, may cause sleep issues. These USB Devices include Water Coolers with USB Addressable Control, Internal Hubs, and RGB/ARGB/FAN Controllers. A similar situation can be also seen with Smart Power Supplies (such as Corsair). In addition, Corsair Commander Pro appears as an Uninterruptible Power Supply (UPS) on macOS and thus prevents sleep. However, it can be used in conjunction with CommanderProFix. Note that Sleep may not even work when using the CommanderProFix. If you have a similar situation, we recommend excluding these devices from mapping.

Apart from these, there are several third party controllers which can cause sleep issues even when there is official support for such controllers. However, most of such third party does not have an official drivers. All such controllers must be excluded from mapping or you can also turn off such controllers from the BIOS itself, if the option is available.

Should I Map other USB Controllers?
Normally, the mapping is required for onboard USB Controller only. Any third-party USB Controllers (such as ASMedia or Fresco Logic) do not need to be mapped unless the controller has more than 15 ports (not physical), which is a rare case. This is also valid for Intel Thunderbolt USB Controllers. You just need a proper USB implementation using a Custom SSDT so that the macOS/OS X can recognize all the ports, ensuring proper speed and power properties. In terms of Thunderbolt USB Controllers, the ports are mapped via the Thunderbolt SSDT itself so you don't have to map it again via USB ACPI table.

Should I Map External USB Cards?
Normally, mapping isn't required for External USB Cards. However, if the controller has more than 15 ports (not physical) and if you plan to use Big Sur 11.3 and later, you must map your External USB Cards.

I have changed my PC Case. Do I need to remap the USB ports?
As the front panel layout will be changed, you need to re-map the USB ports. However, this is very easy for the ACPI method and requires very minimal effort and consumes very less time than the other available methods.

V. Advantages:​

Mapping the USB ports via native method has several advantages over other methods and is the preferred approach:

• Tool Independent
• Kext Independent. Only required for discovery.
• Can be reconfigured when the chassis changes, without having a need to remap all the ports
• Resolves port speed issues on AMD systems
• Robust and permanent
• SMBIOS Independent
• Does not affect after macOS Updates
• Universal across macOS versions

VI. Requirements​

Following are the requirements for enabling native USB Ports on macOS. Please ensure you meet the requirements before proceeding with this guide.



Enabling Native USB Ports on macOS
Following are the steps to enable Native USB Ports on macOS.

STEP 1: Extracting Native ACPI Tables​

The first step is to extract the native ACPI tables. To extract the native ACPI tables, you can either use Clover F4 method, or can boot into macOS and then extract it using MaciASL (if the OEM table is not dropped). You can also dump the ACPI tables via Linux as well. See Extracting ACPI Files for more information.

STEP 2: Verify Ports using Hackintool

STEP 3: Finding the USB Table​

The next step is to find which SSDT has the USB ports defined. You can either open each of the SSDTs and then look for HSXX or SSXX or can use a simple grep command:

1. Open Terminal
2. Execute the following commands in Terminal

#Move to working directory
cd Desktop/ACPI

#Search USB Table
grep -l HS01 *.aml

Which results:

Note down the DSDT and SSDT name. This is the DSDT and SSDT we're going to analyze and modify in the next step to enable/disable the particular USB ports we need and define the port type as well.

Open the SSDT that has USB ports defined.

STEP 4: Analyzing the Native ACPI Table​

After you know which ACPI table has the USB ports defined, its time to analyze them first to see how the ports are defined in the native ACPI table.

Let's have a closer look on the extracted ACPI tables (USB) from GIGABYTE AORUS B560 AORUS PRO AX which has been used an example for this guide. The DSDT usually only contains a basic XHCI device (which may also be XHC for some motherboards). Upon checking the Scope (_SB.PC00) address in the DSDT, we can see that the XHCI device was created with the address 0x00140000. This board has a single Intel USB controller which is located at PC00.XHCI address. The IORegistryExplorer also shows the device XHCI with the 0x00140000 as specified in DSDT. The XHCI device also has OperationRegion, DSM injection, PRW methods and power states for sleep/wake and a further RHUB device is created within the XHCI parent device that has the USB ports defined.

The motherboard B560 AORUS PRO AX from GIGABYTE is based on Intel B560 chipset and that provides upto 24 USB ports as per the Intel's B560 Chipset specification, as many other modern Intel chipsets. A typical USB Table from Intel SKL and above will likely have HS01-HS14, USR1-USR2, and then SS01-SS10 ports. The USR1-USR2 ports are defined within the DSDT itself and the purpose is not known. This becomes a total of 24-26 ports defined in the ACPI namespace. All these ports, whether physically present or not, are defined in the ACPI namespace. You can find more info on these port types below:

Port Name	Speed	Description
HSXX	480Mb/s	High Speed USB2, backwards compatible with USB1
SSXX	5Gb/s, 10Gb/s	Super Speed USB3. USB3.0, 3.1, 3.2, including Type-A and Type-C
USRX	-	Placeholders. Not used and not relevant for macOS

As you can see here in the picture below, there are no further information for these 26 defined ports in the DSDT. This is because, since the introduction of SKL, the USB ports information are present in a separate SSDT table (typically with the OEM Table ID xh_rksu4 for desktops). When taking a look at the extracted SSDT-xh_rksu4.dsl, we can clearly see that the XHCI ports are described in details. A typical USB SSDT from SKL and above will have HS01-HS14 ports (USB2) and then SS01-SS10 (USB3). Upon taking a closer look at our native SSDT, we can find the methods for "USB Port Capabilities" (USB2, USB3, Type-C, Internal, etc) and "Physical Location of Device" (rear right, left, etc). Although, there are several methods and declaration in the native ACPI table (SSDT), the only thing which of our use (for most of the cases) and important are the ports (HSXX and SSXX). If the OEM coded everything correctly, there is very little to do here as these are standards for defining the USB ports as per the ACPI specs. Of course, these are not Apple-specific as Apple's specific is only the port limit (upto 15 ports per controller). In general, the two methods, _UPC and _PLD are sufficient to map the ports and to use it under macOS.

Another example is from MSI X299 motherboard, an HEDT platform. Unlike the CML Desktop, the MSI X299 DSDT also has the basic XHCI device with the address 0x00140000 and the XHCI device also has OperationRegion, DSM injection, PRW methods and power states for sleep/wake and a further RHUB device is created within the XHCI parent device that has the USB ports defined. The MSI X299 Motherboard is based on Intel X299 chipset which provides upto 24 USB ports as per the Intel's X299 Chipset specification, as many other modern Intel chipsets. Unlike the B560, the DSDT has the HS01-HS14, USR1-USR2, and then SS01-SS10 ports. This becomes a total of 24-26 ports defined in the ACPI namespace and all these ports, whether physically present or not, are defined in the ACPI namespace.

This board has three USB controllers defined in the SSDT (SSDT-1 AMI) which are located at the following addresses: PC00.RP05.PXSX (ASMedia), PC00.RP07.PXSX (ASMedia) and PC00.XHCI (Intel). It is very likely possible that some of the motherboards may have more than one XHC controllers and in such a case, you'll have to map those as well. The controller info can be obtained either via lspci on Linux, or via Hackintool on macOS and the datasheet may also have information regarding that. In addition, the three controllers have different port naming style (HSXX, SSXX for Intel) and (HSSX, SSSX) for third party (ASMedia in this case). Motherboards with other controllers than Intel (ASMedia or FrescoLogic), may have SSSX and HSSX ports. This is just done for the sake of differentiation with the onboard Intel USB Controller but may not be the case always. When taking a closer look at the SSDT-1-AMI.dsl, we can find that the SSDT has a total of 26 ports defined, as many other HEDT chipsets including the _UPC and _PLD methods along with the following information as well:

The controller at PC00.RP05.PXSX (routed via chipset) has 4 ports defined and out of these four ports, three of them are enabled which are SSS1, SSS2, and HSS1.
The controller at PC00.RP07.PXSX (routed via chipset) has 4 ports defined and out of these four ports, three of them are enabled which are SSS1, SSS2, and HSS1.
The controller at PC00.XHCI has a total of 26 ports defined which are HS01-HS14, USR1-USR2 and SS01-SS10. Out of these 26 ports, are enabled.



Starting with 700 series, manufacturers are including Thunderbolt 4 with the Z790 chipset, (not on every board, but usually almost seen on most of the high end boards), there are three SSDTs that has ports defined which are: TbtTypeC, USBCTabl, xh_rps14 and the DSDT itself..

Taking a look at the current Z790 Pro Art WiFi Motherboard from ASUS, in a NZXT H7 Flow chassis, we can find the following:

The DSDT has the XHCI device defined with the address 0x00140000 that has HS01-HS14, USR1-USR2, and SS01-SS10 ports.

The TbtTypeC basically controls the TB Type-C ports. As this particular Motherboard has an onboard (built-in) TB chip, it is not clear why the OEM has 7 addresses defined for the TB which are PC00.RP01.PXSX (root port), PC00.RP05.PXSX, PC00.RP09.PXSX, PC00.RP13.PXSX, PC00.RP17.PXSX, PC00.RP21.PXSX, PC00.RP25.PXSX and each of these have SS01-SS04 ports. The actual real TB address is at PC00.RP05.PXSX and as the JHL85440 has two ports, only SS01 and SS02 respectively for 3.0 signals and the Intel XHC controller will have 2.0 signals when a 2.0 device is connected to either of these TB ports. The other ports defined in the TbtTypeC table will not be used in any manner.

The UsbCTabl looks like it controls all the rest Type-C ports and has CR01-CR0A ports defined. However, these devices do not appear under macOS.

The xh_rps14 table is the actual SSDT that controls the USB ports and has HS01-HS14, USR1-USR2, and SS01-SS10 ports like the previous Desktop boards discussed above.


Similar to 700 series, most of the manufacturers are including Thunderbolt 4 (single or dual ports) with the 800 series as well. Taking a look at the recent generation (Arrow Lake), Z890 AERO G Motherboard from GIGABYTE in a Corsair 5000D Chassis, has a total of 12 physical ports including USB 2.0, 3.0 and Type-C. However, this means at least 24 ports defined in the ACPI namespace which exceeds the port limit set by Apple.


In addition, as usually most of the Z890 Motherboards are equipped with Thunderbolt and upon taking a look at the Z890 AERO G Motherboard from GIGABYTE, it has basically three SSDTs that has ports defined which are: TbtTypeC, UsbCTabl, xh_mts2r, and the DSDT.

Notebooks
Before we move to AMD platform, If you're interested to know how the notebook has, let's have a look at the HP as an example.

Unlike the Intel Desktops, the Intel notebook DSDT also has the basic XHC device with the address 0x00140000 and the XHCI device also has OperationRegion, DSM injection, PRW methods and power states for sleep/wake and a further RHUB device is created within the XHC parent device that has the USB ports defined.
The HP 15s-du1065TU is based on Intel HXX chipset which provides upto 24 USB ports as per the Intel's X299 Chipset specification, as many other modern Intel chipsets. Unlike the Desktop, the DSDT has the HS01-HS14, USR1-USR2, and then SS01-SS10 ports. This becomes a total of 24-26 ports defined in the ACPI namespace and all these ports, whether physically present or not, are defined in the ACPI namespace. Despite having fewer USB ports (physical) as compared to Desktops, the ports are still defined.

The Laptop has a single intel onboard USB controller and is located at PCI0.XHC address and everything is defined in the DSDT instead of a separate SSDT for USB. When taking a closer look at the DSDT, we can find that the _UPC and _PLD methods are defined along with the following information as well:






AMD
The AMD platforms uses a different port structure to differentiate between the USB controllers (usually PRTX) and the ports are defined in the DSDT itself instead of SSDT. For example, let's take a look at the DSDT of ASRock B450 Steel Legend. The DSDT has XHC0 device with the address 0x03, XHC1 device with the address 0x04, and PTXH device with the address 0x0 (Zero) and the XHC0, XHC1 and PTXH devices also has PRW methods power states for sleep/wake function and a further RHUB device is created within the XHC0, XHC1 and PTXH parent device that has the USB ports defined. Unlike the Intel boards, the DSDT has the PRT1-PRT6 (XHC0), PRT1-PRT6 (XHC1), and SS01-SS04, HS01-HS06, HS11, HS12 (PTXH). The rest of the HSXX devices are not defined in the DSDT. This becomes a total of 20 ports defined in the ACPI namespace and all these ports, whether physically present or not, are defined in the ACPI namespace.

This board has three USB Controllers defined in the DSDT which are located at the following addresses: PCI0.GP17.XHC0, PCI0.GP17.XHC1, and PCI0.GPP3.PTXH. Unlike the Intel boards, the AMD boards have different naming style (HSXX, SSXX, PRTX). When taking a closer look at the DSDT, we can find that the _UPC and _PLD methods are defined along with the following information as well:

The controller at PCI0.GP17.XHC0 has 6 ports defined and out of these six ports, two of them are disabled. An interesting thing to see here is the USB ports are not in sorted order, but incorrect order. A correct sorted order usually begins like PRT1, PRT2, PRT3 and so on. But the ASRock B450 Steel Legend has the following order: PRT1, PRT5, PRT2, PRT6, PRT3, and PRT4.

The controller at PCI0.GP17.XHC1 has 6 ports defined and out of these six ports, two of them are disabled. An interesting thing to see here is the USB ports are not in sorted order, but incorrect order. A correct sorted order usually begins like PRT1, PRT2, PRT3 and so on. But the ASRock B450 Steel Legend has the following order: PRT1, PRT5, PRT2, PRT6, PRT3, and PRT4.

The controller at PCI0.GPP3.PTXH has 8 ports defined and out of these eight ports, all of them are enabled. An interesting thing to see here is the USB ports are not in sorted order, but incorrect order. A correct sorted order usually begins like HS01, HS02, SS01, SS02, SS03 and so on. But the ASRock B450 Steel Legend has the following order: SS01, SS02, SS03, SS04, HS06, HS01, HS11, and HS12.

Generally, the ports are defined in the sorted order in the ACPI table. However, some OEM may not code that way due to unknown reasons. Although, this does not create any performance issues as the order is just cosmetic. However, when defined in correct sorted order, things can be often easier, especially, during the debugging.
XHC0 device with the address 0x03 at S0D3.BR78

Another example is from ASRock TRX40, an HEDT platform Motherboard which can be a bit complex to understand due to the presence of multiple USB controllers. AMD has bit complex declarations and can be confusing sometimes but as long as you stick to the instructions, it should be all good. Unlike the B450 Steel Legend Desktop, the ASRock TRX40 DSDT has XHC0 device with the address 0x03 at PCI0.D0B8, XHC0 device with the address 0x03 at PCI0.S0D1.D1B8, S0D2.BR58, XHC1 device with the address 0x01 (One) at PCI0.S0D2.D2A0.BYUP.BYD8, XHC0 device with the address 0x03 at S0D2.D2A0.BYUP.BYD8, and BYS2 device with the address 0x0 (zero) at S0D2.D2A0.BYUP.BYD2.BYS2. A further RHUB device is created within the XHC0, and XHC1 parent device that has the USB ports defined. Similar to the AMD Desktop boards, the DSDT has the PRT1-PRT10 (XHC0), PRT1-PRT10 (XHC1). This becomes a total of 20 ports defined in the ACPI namespace and all these ports, whether physically present or not, are defined in the ACPI namespace.

This board has five USB Controllers defined in the DSDT which are located at the following addresses: PCI0.D0B8 (XHC0), PCI0.S0D1.D1B8 (XHC0), PCI0.S0D2.D2A0.BYUP.BYD8 (XHC1), S0D2.D2A0.BYUP.BYD8 (XHC0), and S0D2.D2A0.BYUP.BYD2.BYS2 (BYS2). Similar to the other AMD Desktop boards, the TRX40 has a usual naming style (PRTX). When taking a closer look at the DSDT, we can find that the _UPC and _PLD methods are defined along with the following information as well:

Apart from the rest of the devices (), the rest of the devices (D0B8, D1B8 and BYS2) do not have any RHUB and neither the ports are defined in the DSDT. However, when checking from the IORegistryExplorer, it appears that the D0B8 has 4xUSB ports, D1B8 has 4xUSB ports and BYS2 has 2xUSB ports. This means 10 extra ports that is not defined in the DSDT but the devices exists along with the other 20 ports that are defined properly in the ACPI namespace. The reason for this is not known and neither any of the other SSDT has these extra ports defined. This also means that one should double check with the IORegistryExplorer if the particular system in the question has more controllers. This is useful for cases where the OEM has not defined any RHUB and ports, but just have left the device created in the DSDT/SSDT.


Companion Ports
When its about XHCI controller, there is also companion ports which is used by devices like Thunderbolt. The concept of companion controllers was popular when USB3.0 was just started being adopted. Some XHCI controllers did not support legacy mode therefore OEMs intended to use a separate EHCI controller for most of their ports and added a XHCI controller for the one or two USB 3.0 ports. Because these 3.0 ports must support EHCI as well, they can be either physically wired to both the controllers or use some software hand off mechanism. The companion controller seems to have fallen out of favor as most XHCI controllers supports legacy mode and the complexity of companion controllers are painful to deal with.

As the Thunderbolt Technology is developed by Intel and Apple together, Intel decided to use companion controllers with the Thunderbolt 3 and above and Apple has implemented the same for the Intel Macs that are equipped with Thunderbolt technology. It doesn't seem like compatibility is the issue because the Alpine Ridge does support USB 2.0 on its own XHCI controller and other OEMs have designed it that way. Regardless of why, to support power management, the Ridge XHCI controller must know when the companion USB 2.0 port is idle. OSX handles this by some custom ACPI entries on both controllers.

If this sounds complex to you, understand that the Type-C ports on the Thunderbolt 3 and above (either onboard or AIC), are typically 10Gb/s-40Gb/s. These are pure USB 3.1/3.2 Gen2 based controllers and when a pure USB 3.0/3.1 (Gen1/Gen2) Type-C device is connected into either of these ports, it uses the onboard Intel XHC controller on the Thunderbolt card (on Motherboard, if onboard). However, when a USB 2.0 device is connected into either of the Thunderbolt ports, instead of using the onboard Intel XHC controller on the Thunderbolt card (on Motherboard, if onboard), it ties to the onboard Intel XHC controller on the Motherboard. This is the same XHC controller that has physical ports tied to. In addition, it is also possible that one of these companion ports might be connected via an internal HUB and some physical ports on the motherboard or the chassis might be tied to one of these ports. These are always the HSXX ports as the Type-C (USB 3.0) signals are handled within the onboard Intel XHC controller on the Thunderbolt card (on Motherboard, if onboard). Therefore, to manage the USB 2.0 signals, the HSXX ports are utilized which are tied to the onboard Intel XHC controller on the Motherboard.

If you plan to use the USB 2.0 devices with the Thunderbolt ports, you must take those companion ports into account when mapping the ports. Note that some USB device may have Type-C interface yet the signal will be USB 2.0.


Understanding the Motherboard USB Ports
A USB3 port has two internal ports (1xUSB2 and 1xUSB3). These are defined as (HSXX and SSXX) in the ACPI table. This can be also checked directly on the physical port (there are more pins on the USB3 port than on a pure USB2 port). See pictures for reference. The USB3 header on the motherboard (see picture below) for front panel connectors may have more ports. In addition, some motherboards (such as ASUS X99-WS/IPMI) may have more than one USB3 header. Sometimes, these are also routed via internal HUB. The pure USB2 header, generally have two ports per connector.

Most of the rear ports (back of the Motherboard where ports are located), can be either have a direct connection or some may have routed via internal hub. These ports can be either USB 2.0 or USB 3.0.
Due to this, simply counting the number of physical ports to determine the actual number of ports in use isn't sufficient as use of internal hubs can reduce this. Therefore, you should always check if the ports are connected via Internal HUB or not. To find out which of the ports are connected to the actual physical port, simply connect USB2 and USB3 device to each ports. Using the IOReg, you can see which port each device shows connectivity upon connecting.

Each physical port on the Motherboard and on the chassis corresponds to an HSXX or SSXX device in the ACPI namespace. Sometimes, it is possible that a physical port may have a different device name. For example, the physical port number 6 could have been HS06 but is HS12.



STEP 5: Modifying the SSDT
Before starting with the modification, there are a few terms that you should get to know first. Let's take a look at the sample SSDT (SSDT-XHC.aml). The USB ports are defined as the following:

In the sample SSDT (SSDT-XHC.dsl), we can see that we have both _UPC and _PLD methods which are a key for defining the USB port capabilities and physical location of device. These methods are not only recognized by macOS but other Operating Systems as well, including but not limited to Windows and Linux. As per the ACPI specification (6.3), the _UPC method has four return package which are described below:

Name (_UPC, Package (0x04)  // _UPC: USB Port Capabilities
{
    xxxx,
    yyyy,
    zero,
    zero
}

- The xxxx indicates whether the particular port is enabled or disabled and the possible values are 0xFF and Zero. Where, 0xFF means active and Zero means inactive. This allows us to control whether this particular port can be active or inactive at all.
- The yyyy represents the port type which can be changed as per the requirements and the valid port types are:

Port Types:

Type	Connector Info	Notes
0x00	USB Type-A
0x01	USB Mini-AB
0x02	USB Smart Card
0x03	USB 3 Standard Type A
0x04	USB 3 Standard Type B
0x05	USB 3 Micro-B
0x06	USB 3 Micro-AB
0x07	USB 3 Power-B
0x08	USB Type C (USB 2 only)
0x09	USB Type C (USB 2 and 3 with switch)
0x0A	USB Type C (USB 2 and 3 without switch)
0xFF	Built-in (Internal)	For Internal USB Ports such as Bluetooth and USB Audio. macOS always expects Bluetooth as Internal.

- The last two Zero are the reserved values for future use and must be set to Zero only.


Although, the sample SSDT may suffice to map USB ports on macOS, some of the users may have interest in knowing the additional packages in the sample SSDT. This includes _PLD method. In short, Physical Location of Device. As per the ACPI specification (6.3), the _PLD Method defines the location of the physical port and some other parameters.

Although, its not really necessary to have the _PLD package described as not only its time consuming and overwhelming but can be exhausting as well. In addition, its absolutely not mandatory but nice to have. Therefore, its treated as an optional package.


For example, to modify the HS01 port, which looks like the following in the sample SSDT, just pay attention to the xxxx and yyyy return package values. Change the xxxx to 0xFF to enable a port and Zero to disable. Change the yyyy to define the port type. That's basically how you enable/disable a particular port and define the port type.


Type-C Port and Switches
A Type-C device has two orientation (Side A and Side B). As you know, the Type-C is a reversible connector which means no matter which orientation you plug the device, the device will make a connection.

If a Type-C device is plugged into the Type-C port and it corresponds to the SSXX in both the orientations, this means the particular Type-C port has a switch. However, if a Type-C device is plugged into the

For example, using the SanDisk in a HP Type-C port, the Side A corresponds to the SS04 port and the Side B corresponds to the SS02 port. In addition, when using a USB 2.0 device with Type-C interface (such as Phone or Card Reader or USB Adapter or Audio Interface), it corresponds to HSXX port.

If either of these ports are not taken into account, connecting such device(s) into the Type-C port will not make a connection with the particular device and the device will not work.

In addition, a Type-C port carries both, USB 3 and USB 2 signals. This means if a Type-C device that is pure USB 3, it will typically connect to the SSXX port and will have 5-20Gb/s speeds (may vary dependong on device and port) and if a Type-C device is connected via an adapter or the actual device carries a USB 2 signal (just the interface is Type-C), it will typically connect to the HSXX and will have 10-480Mb/s speeds (may vary depending on device and port).

Similarly, not all Type-C devices are actually USB 3 device and carry USB 3 signals. Some devices may have Type-C interface but the actual signal is USB 2. For example, an Audio Interface (M-Track 2X4) from MOTU has a Type-C port but despite being Type-C, it carries a USB 2 signal instead. In such a case, you must map both the signals, i.e. USB 2 and USB 3 (HSXX and SSXX) or devices like this, may not make a connection and will have problem connecting it.

A USB 3 port carry both, USB 2 and USB 3 signals. This means if a USB 2.0 device is plugged into the USB 3 (Type-A) port, it will typically connect to the (HSXX) port and will have 10-480Mb/s speeds (may vary depending on device) and if a USB 3.0 device is plugged into the USB 3 (Type-A) port, it will typically connect to the (SSXX) port and will have 5-20Gb/s speeds (may vary depending on device and port).



Mapping Ports
Now that you know how to modify the sample SSDT, you can start mapping the ports. Before you start mapping the ports, you must know what physical ports and headers on the Motherboard corresponds to which device in the ACPI namespace. In addition, you would also need to know the port types and whether all the physical ports can be enabled (under 15 limit) or some has to be excluded to get fit.

NOTE: The Internal HUB (either USB2.0/2.1 or USB3.0/3.1) and Bluetooth port must be set to 255 (0xFF) as Internal and the port type must be set as (0x03).
The pure USB 2.0 ports Type-A (identified by black/white port or datasheet), must be set to (Zero)





Once you have obtained the ACPI path and the necessary details, you're ready to map the USB ports by modifying the sample SSDT. Typically, the modification consists of changing the ACPI path, Port enabled/disabled, and port type. To modify the SSDT, follow the steps below.

1. Open the SSDT-XHC.aml from the attachment.
2. Download the MaciASL.
3. Extract the MaciASL and move it to the Applications folder.
4. Open the downloaded SSDT-XHC.dsl using MaciASL.
5. Now you need to change a couple of things in the SSDT to match yours. You can either manually replace these values or you can also use Find and Replace option in MaciASL using Command+F or using the menu Edit>Find and Replace option.
6. Click on compile and look for errors in the Compiler Summary. If there's an error, fix it and again click on Compile.

7. Save the changes to the SSDT using File&gt;Save option.

Mapping Options

If you're new to USB mapping or attempting to use this guide for the first time, there's likely a chance that you're not aware of what device corresponds to which physical port on the Motherboard, chassis and some internal headers. To find out which physical port corresponds to the ACPI device (HSXX and SSXX), you'll have to discover the ports first. To discover the ports, you can use IORegistryExplorer (preferred) or Hackintool (preferred) or even USBMap tool. To discover the ports, follow the steps below:

1. Remove all USB devices from the system except for the Keyboard and Mouse.
2.

STEP 1: Ports Discovery​

The very first step is to discover the ports for mapping. To discover the ports, follow the steps below.

1. Download Hackintool.
2. Unlock Hackintool using the lock button.
3. Go to USB Tab and you'll see the number of ports currently available. The ports in green are the active ports that are being used.

As you can see, there are a total of 24 ports available. But those are not the actual physical ports. The physical ports are way less than that.

Before you start discovering the ports, click on the clean/wipe button to clear all the listed ports and then click on the reload button to reload the ports. This might be useful if you have used Hackintool to map the ports earlier.

4. Starting with USB 2.0 discovery, connect your USB 2.0 Flash Drive to each port of your system and wait for it to appear under Hackintool>USB. Once detected, eject the USB Flash Drive physically and plug it into the next available port.

NOTES:

• The active ports will be marked as "Green." You can also use Finder or Disk Utility to check if your USB Device appears or not.
• Ports connected to the Hub will not be recognized as an individual port in Hackintool as all such ports connected to a Hub will appear as a single USB Hub in Hackintool. You must use IOReg/Finder/Disk Utility to confirm the detection of the USB.

After discovering the USB 2.0 ports, you'll have some ports in green. Here is the USB 2.0 ports discovery.

5. Now, as the USB 2.0 ports have been discovered, it's time to discover the USB 3.0/USB 3.1/USB 3.2 ports. Connect your USB 3.0 Flash Drive to each port of your system and wait for it to recognize by Hackintool. Once detected, eject the USB Flash Drive physically and plug it into the next available port.

NOTES:

• The active ports will be marked as "Green." You can also use Finder or Disk Utility to check if your USB Device appears or not.
• Ports connected to the Hub will not be recognized as an individual port in Hackintool as all such ports connected to a Hub will appear as a single USB Hub in Hackintool. You must use IOReg/Finder/Disk Utility to confirm the detection of the USB.

After discovering the USB 3.0/USB 3.1/USB 3.2 ports, you'll have some more ports in green. Here is the USB 3.0 ports discovery.

6. Now, as the USB 3.0/USB 3.1/USB 3.2 ports have been discovered, it's time to discover the USB Type-C ports. Connect your USB Type-C Drive to each port of your system and wait for it to recognize by Hackintool. Once detected, eject the USB Flash Drive physically and plug it into the next available port.

NOTES:

• If you have any USB Device which uses USB 2.0 bus but still has a Type-C interface, you must map such Type-C ports as devices with USB 2.0 bus speed and Type-C interface will usually connect to the HSXX port.
• The active ports will be marked as "Green." You can also use Finder or Disk Utility to check if your USB Device appears or not.
• Ports connected to the Hub will not be recognized as an individual port in Hackintool as all such ports connected to a Hub will appear as a single USB Hub in Hackintool. You must use IOReg/Finder/Disk Utility to confirm the detection of the USB.

After discovering the USB Type-C ports, you'll have some more ports in green. Here is the USB Type-C ports discovery.

7. As all the ports have been discovered, it's time to calculate the total number of ports discovered. To calculate, simply count the ports in green. In our case, it is 18.

NOTES:

• For macOS Big Sur 11.3 and later, it is recommended to disable XhciPortLimit Quirk to discover USB 2.0 Ports and then enable XchiPortLimit Quirk to discover USB 3.0/3.1 and Type-C Ports. You must restart the system for changes.
• If a port is not detected/discovered, the particular port(s) will be skipped and the respective ports will not work.

Using USBPorts.kext from Hackintool as a base​

If you have mapped the ports using Hackintool and want to convert it into SSDT based native USB Mapping, you can do using the steps described below:

1. Open USBPorts.kext using Xcode or any PlistEditor.
2. Expand IOKitPersonalities and Locate ports section under IOProvideMergeProperties.
3. Take the note of all the defined ports. For example, in our case, its HS04, HS05, HS07, HS07, HS08, HS09, HS10, HS11, HS14, SS01, SS02, SS03 and SS04.
4. Open the sample SSDT-XHC.aml using MaciASL. Locate these ports in the SSDT-XHC.aml and define the port types and enable whatever the ports are defined in the USBPorts.kext.
5. Save the SSDT using Files>Save.

You can either have all the ports defined (HSXX and SSXX) and enable/disable it as required or you can only have the required ports enabled in the SSDT to keep the SSDT more clean.

Using USBMap.kext as a base​

If you have mapped the ports using Hackintool and want to convert it into SSDT based native USB Mapping, you can do using the steps described below:

1. Open USBPorts.kext using Xcode or any PlistEditor.
2. Expand IOKitPersonalities and Locate ports section under IOProvideMergeProperties.
3. Take the note of all the defined ports. For example, in our case, its HS04, HS05, HS07, HS07, HS08, HS09, HS10, HS11, HS14, SS01, SS02, SS03 and SS04.


Combining Multiple USB Controllers
If your system has multiple USB controllers, there are two ways to map them (i) use separate SSDTs for each controllers; (ii) combine all the controllers into one single SSDT for easier management.



STEP 5: Add SSDT to EFI

STEP 6: Drop OEM ACPI Table

For systems that has the ports defined in the DSDT and does not have any separate SSDT, the native ACPI table (DSDT) should not be dropped in such case. Please note that some native ACPI table may have extra spacings in the OEM Table ID. For example, the HP 15s-du1065TU notebook has a OEM Table ID as 85F1 . This can be also checked using MaciASL. Therefore, the extra spacings must be taken care of. Not using the spacings will have failure in dropping the native ACPI table.