EliteMacx86

Administrator
Staff member
Joined
Jul 22, 2018
Messages
3,424
Motherboard
Supermicro X11SPA-T
CPU
Intel Xeon W-3275 28 Core
Graphics
2xAMD RX 580 8GB
OS X/macOS
11.0.x
Bootloader
  1. OpenCore
Mac
  1. Mac mini
  2. MacBook Pro
Mobile Phone
  1. Android
  2. iOS
How to Map your USB Ports on macOS

An EliteMacx86 Exclusive Guide - This guide covers the mapping of USB Ports on macOS.

Overview


Often, the USB ports are not well recognized or have certain issues. To fix that, USBInjectAll.kext from Rehabman was serving the purpose along with the USB port limit patch. Later on, for more performance and to avoid conflicts, and issues, a custom SSDT-UIAC was introduced. Later on, when Hackintool was introduced, USBPorts.kext served the purpose for a while as the USBInjectAll.kext was no longer maintained from RehabMan and new SMBIOS were introduced where the maximum support was till MBP15,2 and iMacPro1,1. However, when it comes to AMD systems, USBInjectAll.kext isn't supported at all. A new method was introduced from corpnewt with the name of "USBMap" which is basically a python script for mapping USB ports on macOS and creating a custom USB injector kext.

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.
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, where the Motherboard since 100 series and newer began to have 26 ports in total. These are not the actual physical ports but are declared in ACPI tables 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.
A workaround was discovered back then, which was Kernel Patch to increase the port limit to 26. This worked well till Catalina. Since High Sierra, OpenCore was introduced and the Kernel Patches were replaced by XhciPortLimit Quirk and it worked 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. 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. However, this caused problems on Bluetooth and HID devices which use pure USB 2.0 to function. However, a workaround was to map the USB ports and use XchiPortLimit 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.

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 amount of used bits in locationID format and there is no possible way of a workaround without heavy OS modification. The only valid solution is to limit the amount of used ports to 15 (discarding some).

It is recommended to use Big Sur 11.2.3 for mapping the Ports due to the broken XhciPortLimit Quirk. By using 11.2.3, you don't need to switch between the XhciPortLimit Quirk to discover the ports.

As most of the users don't need to utilize all the physical ports provided in the 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. 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 in a rare case) and under 15 port limits.

Should I Map External USB Cards?
Normally, mapping isn't required for External USB Cards. However, if you plan to use Big Sur 11.3 and later, you must map your External USB Cards.

Available Methods for Mapping


Following are the methods available for USB Mapping. All these methods have been described below.

MethodNotes
Hackintool
  • Easy to map
  • No External USB Card mapping Support
  • Can set nicknames to ports
USBMap
  • Can be difficult to map when compared with Hackintool
  • No dependency on USBInjectAll
  • Can map XHCI (chipset, third party, and AMD), EHCI, OHCI, and UHCI ports
  • Can map USB 2 HUBs currently disabled
  • Matches based on class name, not port or controller name
  • Allows setting nicknames to the last-seen populated ports in discovery
  • Aggregates connected devices via session id instead of the broken port addressing
  • Can use best-guess approaches to generate ACPI to rename controllers or reset RHUB devices as needed
  • External USB Card mapping Support


NOTE:
  • None of the above methods bypasses the port limit.

Which is the Best USB Mapping Tool?

Well, you might have this question and there is nothing wrong with it. All the above methods give the same results, however, each has its own advantages and way to map. Depending on the user, and how familiar is the user with working with community-based tools and knowledge, some may consider Hackintool as the easiest option and the advanced users may consider USBMap. As long as the mapping is done correctly, both methods will serve the purpose.

Requirements


1xUSB 2.0 Flash Drive
1xUSB 3.0 Flash Drive
1xUSB Type-C Flash Drive

Before you start mapping your USB Ports, all the ports must be detected under macOS. To fix your USB ports, follow the guide linked below

Mapping USB Ports


Currently, there are two ways to Map the USB ports. Hackintool, which is very easy, and the other one is USBMap from Corpnewt.

Method #1: USB Ports Mapping using Hackintool
Using Hackintool, you can configure the ports and map the USB ports as required. To map your USB ports using Hackintool, follow the steps below.

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.
Screen Shot 2022-06-27 at 10.34.39 AM-min.png

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.

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.

NOTE:
  • 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.

After discovering the USB 2.0 ports, you'll have some ports in green. Here is the USB 2.0 ports discovery.
Screen Shot 2022-06-27 at 10.37.54 AM-min.png


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.

NOTE:
  • 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.

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.

Screen Shot 2022-06-27 at 10.39.21 AM-min.png

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.

NOTE:
  • 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.

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

Screen Shot 2022-06-27 at 10.39.52 AM-min.png

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 2.0 ports and then enable XchiPortLimit Quirk. You must restart the system for changes.
  • If a port is not detected/discovered, it will be skipped and the respective ports will not work.

STEP 2: Removing Unused Ports​

Now, as we have the total number of discovered ports, it's time to remove the unused ports.

1. To remove the unused ports, simply select the unused ports and click on the delete button. The unused ports are non-green ports.

Screen Shot 2022-06-27 at 10.42.58 AM-min.png


2. Now, you should see only the active ports. To verify the active ports, match the ports count from Step 7, and what's left are the final ports we need.
Screen Shot 2022-06-27 at 10.43.10 AM-min.png

STEP 3: Changing Connector Types​

Changing connector types can be required. It varies from system to system. This is necessary for USB devices such as Bluetooth and Hubs. A few issues can be solved such as slow speed, crashes, and kernel panics. Changing connector types is very simple and it basically involves identifying the ports and changing them within Hackintool, without the need for anything extra. In addition, changing the connector type for Bluetooth is a must.

Connector Info

TypeConnector InfoNotes
0USB 2.0 Type-A connector
3USB 3.0 Type-A connector
8Type C connector, USB 2.0 only
9Type C connector, with USB 2.0 and USB 3.0 switch
10Type C connector - USB 2.0 and USB 3.0 without Switch
255Proprietary connector
  • For Internal USB Ports such as Bluetooth.
  • macOS always expects Bluetooth as Internal.
  • For Internal USB Audio
  • This can also fix Sleep/Wake.

If you're using Bluetooth, you need to change the connector type for your USB Port. As macOS always expects Bluetooth as Internal, it's best to change the connector type. As per the connector table, we need to set it as Internal which is 255. You'll have to find what port is connected to Bluetooth. Normally, you can determine in Hackintool, just look in the Device column next to the USB port. However, this is not always the case. Like ours, we have the USB connected to the internal Hub and that's where our Bluetooth is. If you're having such a scenario, you can use IOReg to determine what port is connected to Bluetooth. To find the connector type for Bluetooth, follow the steps below.

1. Download IOReg
2. Open your IOReg and type Bluetooth in the search bar. You'll see something like this.

Screen Shot 2022-06-28 at 5.21.10 PM-min.png

3. If you check the above screenshot, you can see that Bluetooth is connected to HS12. Note down the port number.
4. Once you have determined the port, you can simply change the connector type as per the connector info table. Select HS12 and from the connector column, click on the arrows and select Internal and you should have something like below.

Screen Shot 2022-06-27 at 10.52.27 AM-min.png

Before changing:
Screen Shot 2022-06-28 at 7.09.38 PM-min.png

After changing:

Screen Shot 2022-06-28 at 7.10.18 PM-min.png

STEP 4: Creating USB Mapping Kext​

Now, the next step is to create the mapped kext which has everything set. To create the kext, you just need to export the kext using Hackintool. To export, simply click on the Export button and it will generate Kext and SSDTs to your Desktop.

STEP 5: Installing Mapped Kext​

Now, as you have mapped the ports, you'll need to install the mapped kext to enable the USB mapping. To install the kext, follow the steps below.

1. Mount your ESP.

For Clover:
If you're using Clover, copy the USBPorts.kext to EFI/Clover/Kext/Others

For OpenCore:
If you're using OpenCore, copy the USBPorts.kext to EFI/OC/Kexts. You'll also need to add the kext entry in the Kernel section of your config.plist

2. Save your config.plist

STEP 6: Restart your System​

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

STEP 7: Verifying USB Ports​

The next step is to verify the ports mapped. To verify the ports, follow the steps below.

1. Open Hackintool
2. Go to USB Tab and click on the Clear button and then click on Reload to refresh the ports list.
3. Now, you'll only see the discovered/mapped ports in the list. Make sure to count the ports to ensure you have no ports missed.

Here is what we have

Screen Shot 2022-06-27 at 10.52.27 AM-min.png

4. Now, the last step would be to verify the ports. To verify, simply repeat STEP #1 and ensure that each and every port is working.

Screen Shot 2022-06-27 at 10.54.52 AM-min.png


On macOS Big Sur 11.6.5​


Screen Shot 2022-06-29 at 7.34.38 AM-min.png


NOTE:
  • If you change the SMBIOS, you must change the SMBIOS model in the mapped kext or the system will throw a Kernel Panic. Therefore, it is strongly recommended to set appropriate SMBIOS before mapping.

Method #2: USB Ports Mapping using USBMap

STEP 1: Ports Discovery​

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

1. Install Command Line Tools, if you haven't already.
2. Open Terminal and type the following commands one by one. When prompted, enter your password.

Code:
git clone https://github.com/corpnewt/USBMap
cd USBMap
chmod +x USBMap.command
./USBMap.command

3. Type R and press enter key to reset all the discovered ports. This might be useful if you have used the script earlier.

Screen Shot 2022-06-27 at 11.07.37 AM-min.png


4. Type D and press enter key to discover the ports.

Screen Shot 2022-06-27 at 11.07.44 AM-min.png

and you'll see something like below.
Screen Shot 2022-06-27 at 11.08.47 AM-min.png

5. 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 USBMap. Once detected, eject the USB Flash Drive physically and plug it into the next available port.

After discovering the USB 2.0 ports, you'll have some ports in green. Here is the USB 2.0 ports discovery.
Screen Shot 2022-06-27 at 11.11.52 AM-min.png

6. 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.

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.
Screen Shot 2022-06-27 at 11.13.30 AM-min.png

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

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

Screen Shot 2022-06-27 at 11.14.11 AM-min.png

8. Once all the ports are discovered, type Q and press enter key to quit the discovery of the port

Screen Shot 2022-06-27 at 11.15.47 AM-min.png


NOTES:
  • For macOS Big Sur 11.3 and later, it is recommended to disable XhciPortLimit Quirk to discover 2.0 ports and then enable XchiPortLimit Quirk. You must restart the system for changes.
  • If a port is not detected/discovered, it will be skipped and the respective ports will not work.

STEP 2: Edit and Create Kext​

The next step is to edit the USB configuration and create USBMap.kext. To edit and create kext, follow the steps below.

1. Press P to edit and create USBMap.kext

Screen Shot 2022-06-27 at 11.16.06 AM-min.png


and you'll see something like below

Screen Shot 2022-06-27 at 11.16.13 AM-min.png

2. Now, we need to set the connector types first. Changing connector type in USBMap is a bit different than Hackintool. However, changing the connector type is still simple even in the USBMap tool. For more info on Connector Info, see Changing Connector Types in STEP #3 of the Hackintool Method.

The connector type can be changed using the syntax

T:X,X:Y, where

X represents the discovered port number Y represents the connector type you want to set

Except for the Bluetooth, which has to be set as 255, as that's what macOS expects, we can set the connector types for the rest of the ports. Using the above syntax, change the connector type. It's always recommended to set one connector at one time, for X number of ports and then after different connectors for the rest of the ports. In our case, the command would be

T:2,3,4,7,8,9,10,11,13,17,18,19,20,21,22,23,24:3
Screen Shot 2022-06-28 at 9.19.07 PM-min.png

Once you have determined the Bluetooth port, you can simply change the connector type as per the connector info table. In our case, #12.
Using the above syntax, change the connector type. In our case, the command would be

T:12:255
Screen Shot 2022-06-27 at 11.24.53 AM-min.png

Once changed, the connector type will reflect
Screen Shot 2022-06-27 at 11.25.01 AM-min.png

3. Press P to enable all populated ports

Screen Shot 2022-06-27 at 11.25.29 AM-min.png

4. Press D to disable all empty ports
Screen Shot 2022-06-27 at 11.25.39 AM-min.png

5. Finally, press K to build USBMap.kext
Screen Shot 2022-06-27 at 11.26.26 AM-min.png


Screen Shot 2022-06-28 at 9.20.14 PM-min.png

When prompted, click on OK to allow access
Screen Shot 2022-06-28 at 9.20.20 PM-min.png

Now, the USBMap tool will generate the final kext. You can find the kext at yourusername/USBMap>Results
Screen Shot 2022-06-28 at 9.20.44 PM-min.png

6. Press enter key to return to the main menu.
Screen Shot 2022-06-28 at 9.20.58 PM-min.png

Type M and press enter key.

STEP 3: Create SSDT​

Type H and press enter key to generate SSDT to reset RHUBs.
Screen Shot 2022-06-28 at 9.21.13 PM-min.png

Screen Shot 2022-06-28 at 9.21.22 PM-min.png


Type Q and press enter key to quit the USBMap tool.

Screen Shot 2022-06-28 at 9.21.31 PM-min.png



Screen Shot 2022-06-28 at 9.21.37 PM-min.png


NOTE:
  • You can find the RHUB SSDT at Yourusername>USBMap>Results.

STEP 4: Compile SSDT​

The next step is to compile the SSDT. To compile the SSDT, follow the guide linked below.

STEP 5: Installing Mapped Kext​

Now, as you have mapped the ports, you'll need to install the mapped kext to enable the USB mapping. To install the kext, follow the steps below.

1. Mount your ESP.

For Clover:
If you're using Clover, copy the USBPorts.kext to EFI/Clover/Kext/Others

For OpenCore:
If you're using OpenCore, copy the USBPorts.kext to EFI/OC/Kexts. You'll also need to add the kext entry in the Kernel section of your config.plist

2. Save your config.plist

STEP 6: Installing SSDT​

The next step is to install the SSDT. This is required for users who have a conflicting controller and require SSDT-RHUB. To install the SSDT, follow the steps below.


NOTES:
  • Do NOT use SSDT-UIAC or USBInjectAll.kext along with USBMap.kext.
  • If your system needs XHCI-unsupported.kext along with USBMap.kext, you can use it.

STEP 7: Restart your System​

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

STEP 8: Verifying USB Ports​

The next step is to verify the ports mapped. To verify the ports, follow the steps below.

1. Run the USBMap command and type R and press enter key.
Screen Shot 2022-06-28 at 9.29.24 PM-min.png

2. Type D and press enter key to discover the ports.

Screen Shot 2022-06-27 at 11.07.44 AM-min.png

2. Now, you'll only see the discovered/mapped ports in the list. Make sure to count the ports to ensure you have no ports missed.

Here is what we have

Screen Shot 2022-06-28 at 9.33.18 PM-min.png

On macOS Big Sur 11.6.5​

Screen Shot 2022-06-29 at 7.37.07 AM-min.png


NOTE:
  • If you change the SMBIOS, you must change the SMBIOS model in the mapped kext or the system will throw a Kernel Panic. Therefore, it is strongly recommended to set appropriate SMBIOS before mapping.
 
Last edited:

Davidm71

New member
Joined
May 13, 2022
Messages
1
Motherboard
Asus Z270-Ws
CPU
6700K
Graphics
Vega 64
OS X/macOS
10.15.x
Bootloader
  1. OpenCore
Mac
  1. iMac
Mobile Phone
  1. iOS
The Usbmap instructions state to install the dummy usbmap kext first. So you don’t need to do that?

Also this is confusing:

Now, use T:x, x:3. Where,
  • x represents your discovered port.
  • 3 represents the connector type.
Thanks
 

EliteMacx86

Administrator
Staff member
Joined
Jul 22, 2018
Messages
3,424
Motherboard
Supermicro X11SPA-T
CPU
Intel Xeon W-3275 28 Core
Graphics
2xAMD RX 580 8GB
OS X/macOS
11.0.x
Bootloader
  1. OpenCore
Mac
  1. Mac mini
  2. MacBook Pro
Mobile Phone
  1. Android
  2. iOS
The Usbmap instructions state to install the dummy usbmap kext first. So you don’t need to do that?
No, you need to discover ports first.
Now, use T:x, x:3. Where,
  • x represents your discovered port.
  • 3 represents the connector type.
The guide has been updated!
 
Last edited:

Similar threads

Forum statistics

Threads
673
Messages
7,057
Members
5,909
Latest member
testingboi