[GUIDE] HOW-TO: Properly Map Your USB Ports for OpenCore/Big Sur 11.3.x

Raine

Active member
Joined
Sep 30, 2018
macOS
10.16.0
Mobo
Gigabyte Z370n WiFi
CPU
Core i5-8400
GPU
Radeon RX-570
#1


HOW-TO: Properly Map Your USB Ports for OpenCore/Big Sur 11.3 (works with 11.3.1)
If you're like me who uses your Hackintosh as your daily machine, you might have found out (or read) that the latest macOS Big Sur 11.3 update broke a lot of people's systems - mainly USB port functions. After seeing all kinds of solutions and workarounds all over the Internet in the last few days, I decided to write a guide on how I fixed my system so that I had full USB 2.0/3.0 functionality in macOS Big Sur 11.3 (OpenCore EFI) while sticking under the 15-port limit for MacOS/Hackintosh builds.


!!--IMPORTANT--!!
I DO NOT GUARANTEE THAT THIS WILL WORK WITH YOUR SYSTEM!

Due to the nature of how Hackintoshing works, nothing is a guarantee. Please be aware of this before you start, and understand that if you encounter any problems I might not be able to help you resolve them.​

PROCEEDING BEYOND THIS POINT YOU UNDERSTAND IT'S ALL ON YOU =)


------------------------------------------------------------------------------------------------------------------

NOTE: This was tested and confirmed working 100% on my Vanilla Hackintosh Deluxe i5-8400 z370n build, as well as two other completely different Intel-based Hackintosh machines. All 3 machines are using OpenCoreEFI’s, not Clover. Of the 3 machines we used for testing, Machine #1 was still on Big Sur 11.2.3. Machine #2 was already upgraded (using MacOS update) to Big Sur 11.3. Machine #3 (my Hackintosh) was a clean install of 11.3 after port mapping. I have also since updated to Big Sur 11.3.1 with no issues after port mapping using this method.

If you’ve already upgraded to Big Sur 11.3: If you already upgraded to 11.3 and are trying to get your ports fixed after the upgrade, this method did work on one of our set machines as mentioned above - but your results may vary. The best way to get to 11.3 with working USBs from the get-go is to start from an 11.2.3 system and map the USB ports beforehand.

If your machine isn’t using OpenCore (You’re still using Clover or something else): If you aren’t using OpenCore as your EFI, the method described here will be different for you. I’ve found that OpenCore is so much cleaner and easier to work with, so I cannot help if you’re still using a different EFI.

------------------------------------------------------------------------------------------------------------------​

I. What You'll Need
As stated above, ideally your current system would still be on Big Sur 11.2.3, though I've also used this method to "rescue" a 11.3 system. Before you start, gather everything you need. You will need a combination of software (all free) and some simple hardware to get the ports mapped.

SOFTWARE
1. Clover Configurator or MountEFI to access your EFI partitions
2. Hackintool to help you discover and identify your USB ports (much better than USBMap)
3. ProperTree app to edit your OpenCore config.plist file
4. USBInjectAll.kext to help with port discovery

HARDWARE
5. A USB 2.0-only device (i.e. flash drive, ethernet adapter, etc.)
6. A USB 3.0-specific device (like above, to physically test your ports)





Make sure you have easy access to all of your physical USB ports on your machine. Do not use any external USB hubs or other extension cables or peripherals. You need access to all of the physical USB ports on the motherboard (back panel) as well as any front or top panel USB ports. Unzip the downloaded files onto your Desktop for easy access. Also, I recommend that you do one Time Machine backup of your existing setup before you begin.


II. ACCESS THE EFI PARTITION ON YOUR MAIN HARD DRIVE
First, we need to gain access to your EFI folder to make some changes. For this part, I'll show the steps using Clover Configurator, but you can use MountEFI to do the same thing (with a more plain interface).

1. Open Clover Configurator:


2. On the left side column under Tools click MountEFI.


3. To the right, in the lower column under EFI Partitions there will be a list of all of your local drives. Find the entry for your main hard drive (the one with your current Big Sur 11.2.3 installed to it).

4. Click the Mount Partition button on the right (it may ask you for your system password). After mounting, click on the Open Partition button. You should see your main hard drive’s EFI directory show up in Finder.



III. COPY USBINJECTALL KEXT TO EFI
Next, we’ll temporarily modify the contents of your EFI folder so that you can properly map your USB ports.

1. Open the EFI>EFI>OC>Kexts directory.
2. Copy the USBInjectAll.kext file to the EFI/OC/Kexts folder.
3. IMPORTANT! YOU MUST REMOVE ANY OTHER USB map kexts (i.e. USBMap.kext) The only "USB…" kext you want in there is the USBInjectAll.kext file. Backup, then remove anything else "USB…" in there.

You should only have one USB-related kext (the USBInjectAll.kext file you just put in there) in the Kexts directory:



IV. EDIT OPENCORE CONFIG
Along with adding the USBInjectAll.kext, you’ll have to make some temporary edits to your OpenCore config.plist file.

1. Navigate to EFI/OC/ and right-click “open” your config.plist file with ProperTree.app
2. Use the OC Snapshot function by typing Command + R. This will refresh your config with the updated Kexts.
3. While still in ProperTree, scroll down in your config until you get to the Kernel>Add section.
4. Check if one of the entries is shows USBInjectAll.kext. If it does, then continue.
5. Scroll down to the Kernel>Quirks section and set XhciPortLimit Boolean to TRUE
6. Type COMMAND + S to save the current config.plist file.
7. Type COMMAND + Q to quit ProperTree.
8. Restart your system. **YOU MUST RESTART FOR THE EFI CHANGES TO TAKE EFFECT**

What you basically did was temporarily make 2 changes:
A. You inserted the USBInjectAll.kext file into your EFI, and
B. You activated the XhciPortLimit patch.


V. DISCOVER USB PORTS
Now for the part that, if you do this right the first time, you shouldn't have any USB issues going forward with every new Big Sur update. Before you begin this section, you'll want to draw a diagram or take some photos, or sketch on a piece of paper your USB port layout for your machine. For example, my system has a Gigabyte Z370N-WiFi motherboard, Silverstone case, and extra rear USB ports. Using Photoshop I came up with this to show all of my physical USB ports:


Looking at my setup, you will count 11 actual USB ports. Should be fine, since that's under the 15-port limit, right? Not exactly. When it comes to MacOS, Each USB 3.0 port actually counts as TWO USB ports in the total count (because the USB 3.0 port has to be backward compatible with USB 2.0 devices).

So look at my setup again: the back panel has 4 physical USB 3.0 ports at the top/left, but those count as eight USB ports that MacOS can see. Those 2 physical USB 3.0 ports under the ethernet ports also count as four USB ports to MacOS. Same with the 2 physical ports on the case. Same with the 1 physical USB-C port. So even though there are just 11 physical USB ports in my system, macOS actually will see TWENTY ports, way too high! Having anything over 15 can cause issues.

Your job then is to give your system a “Map” of only the ports you want to use. The map can only have no more than 15 ports total. To determine which ports to use is where Hackintool comes into play.

1. Double-click and open the Hackintool app, then click on the USB tab at the top:



In the USB Ports section at the lower part of the screen, you will see a list of detected USB ports in your system. This is where the fun part begins.

USB 2.0 DISCOVERY
1. Get your USB 2.0 device (mouse wireless receiver, flash drive, etc.)
2. Plug your USB 2.0 device into one of your physical USB ports.

The device should show up in the detected ports section of the Hackintool window under the Device column.

3. Write down the physical port location and the port name that matches in Hackintool.
4. Continue doing this with each physical USB port until you have discovered all of the USB 2.0 port names.

For example, I plugged a USB 2.0 Receiver into my computer and in Hackintool it showed that the receiver was plugged into "HS03" (see the photo above again for reference). The physical USB port I used was the lower port in the back panel under the Ethernet ports of my motherboard. I then moved the USB 2.0 receiver to a different physical port, saw which port showed up in Hackintool, and made a note of it as well.

USB 3.0 DISCOVERY
When you’re done discovering all of the USB 2.0 ports, it’s time to move to USB 3.0 ports. You basically do the same thing, with all of your USB ports again, making note of physical location and port names.

1. Get your USB 3.0 device (mouse wireless receiver, flash drive, etc.)
2. Plug your USB 3.0 device into one of your physical USB ports.

The device should show up in the detected ports section of the Hackintool window under the Device column.

3. Write down the physical port location and the port Name it matches in Hackintool.
4. Continue doing this with each physical USB port until you have discovered all of the USB 3.0 port names.

All USB 2.0 USB ports will show up as “HS__” in Hackintool.
All USB 3.0 USB ports will show up as “SS__” in Hackintool.
Try ALL of the USB ports in your system and note location and names for all of the ports..


VI. USB REFERENCE MAPPING
After doing the “Discovery” you should have a list of all of your USB physical ports and their names as shown in Hackintool. Looking at my system again, I added the names of each physical port to my image for reference:


The above image shows all TWENTY USB ports, per how MacOS sees them. I will have to reduce this number down to 15 or lower, which I have no problem with since the only USB ports I actually use are the following:

HS01/SS01 - front panel, right port (for quick access)​
HS02/SS02 - front panel, left port (for quick access)​
HS03/SS03 - rear panel center-lower port (for my webcam)​
HS04/SS04 - rear panel, center-upper port (for my mouse and keyboard wireless receiver)​
HS06/SS06 - rear panel, left-upper port (for my DJ controller)​
HS05/SS05 - rear panel, second port (for my Lightning cable)​
HS10/SS10 - rear panel USB-C port (for my external storage/Time Machine drive)​

Count the above, and I only need to use 14 ports out of the 20 detected. 14 is under the 15-port limit, so this is correct. After USB port mapping is complete, the HS07/SS07, HS08/SS08, HS11, and HS12 ports will not be active anymore.


VII. REDUCE USB PORT COUNT
It's time to reduce the number of USB ports that MacOS sees so that the total is 15 or less. Each USB port can be removed from the list by doing the following (example, to remove HS07):

1. Click on HS07 in the Hackintool window so that it is highlighted.
2. Click the MINUS icon to remove it from the list:

3. Repeat steps 1 & 2 until all ports to be removed are no longer shown in Hackintool.


VIII. GENERATE YOUR NEW USB KEXT

Once Hackintool only shows the ports I want to keep, the next step is to generate a new kext file for our USB port mapping. While still in the Hackintool interface, click on the EXIT DOOR icon:



This will generate some new files on your Desktop (or wherever Hackintool is located); you should see some new files like this:


The important file (and the only file you really need here) is the new USBPorts.kext. This is your USB map, and this is the map that MacOS will follow to allow only the USB ports you need. Delete the other files except for USBPorts.kext.


IX. ACCESS EFI TO ADD USB MAP AND RESTORE EFI EDITS
The hard part is done! Now we just need to access your EFI folder one more time to update it (same steps as SECTION II):

1. Open Clover Configurator.
2. Under Tools click MountEFI.
3. Find the entry for your main hard drive and click the Mount Partition button.
4. After mounting, click on the Open Partition button.
5. Open the EFI>EFI>OC>Kexts directory.
6. DELETE the USBInjectAll.kext file.
7. ADD the new USBPorts.kext file to the EFI/OC/Kexts folder.

Now, you should only have a single USB-related kext (the new USBports.kext file) in the Kexts directory:


X. EDIT OPENCORE CONFIG
Last step now! Finally, we just need to update your OpenCore config.plist file to include the new kext:

1. Navigate to EFI/OC/ and right-click “open” your config.plist file with ProperTree.app
2. Use the OC Snapshot function by typing Command + R. This will refresh your config with the updated Kexts.
3. While still in ProperTree, scroll down in your config until you get to the Kernel>Add section.
4. Check if one of the entries is shows USBPorts.kext. If it does, then continue.
5. Scroll down to the Kernel>Quirks section, and set XhciPortLimit Boolean to FALSE
6. Type COMMAND + S to save the current config.plist file.
7. Type COMMAND + Q to quit ProperTree.
8. Restart your system. **YOU MUST RESTART FOR THE EFI CHANGES TO TAKE EFFECT**

What you did here was make 3 final changes to your config.plist file:
A. You added in your new USBports.kext file;​
B. You removed the USBInjectAll.kext file and any reference to it; and​
C. You deactivated the XhciPortLimit patch.​

And you're done! After rebooting, your system will have its USB ports mapped, and macOS will allow only the ports you specified to be active and work properly!

From here, you can now go ahead and do an in-place update to Big Sur 11.3 using the system updater in System Preferences; or if you want to do a clean installation of Big Sur 11.3, use the USBports.kext file you made in the EFI folder of your OpenCore USB Installer! (NOTE: after this was initially written, Apple pushed out thr 11.3.1 update to Big Sur; I have upgraded to 11.3.1 and am happy to say that everything is intact, all of my specified USB ports are running at full speed!)


 
Last edited:
Joined
May 12, 2021
macOS
10.11.x
Mobo
Gigabyte Z490
CPU
10900
GPU
RX580
#3
After all this and you upgrade, physically check your Deactivated ports. Plug something into them and see if indeed they are disabled.

Using Hackintool or USBMap command and/or other utilities to check after the update may just report what is in kext (15).
 

Latest posts