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

Raine

Active member
Joined
Sep 30, 2018
macOS
10.16.0
Mobo
Gigabyte Z370n WiFi
CPU
Core i5-8400
GPU
Radeon RX-570
#1
UPDATE 05.24.2021: I have since updated to Big Sur 11.4 with no issues after port mapping using the USB port mapping method shown below.



HOW-TO: Properly Map Your USB Ports for OpenCore/Big Sur (UPDATED: works with 11.4!)

If you're like me who uses your Hackintosh as your daily machine, you might recall when the last 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 and now Big Sur 11.4 (OpenCore EFI) while sticking under the 15-port limit for MacOS/Hackintosh builds. [Note: most of the text below references the upgrade to Big Sur 11.3, but it works for Big Sur 11.4 as well]

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

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-11.4 using the system updater in System Preferences; or if you want to do a clean installation of Big Sur 11.4, use the USBports.kext file you made in the EFI folder of your OpenCore USB Installer!




UPDATED 05.24.2021: Confirmed working perfectly with the latest macOS Big Sur 11.4:

 
Last edited:

DMFO

New member
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).
 

Raine

Active member
Joined
Sep 30, 2018
macOS
10.16.0
Mobo
Gigabyte Z370n WiFi
CPU
Core i5-8400
GPU
Radeon RX-570
#5
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).
Pretty sure I checked this when I wrote the guide, but I just checked again right now and yes - all deactivated ports are deactivated.

I tested my HS07/SS07, HS08/SS08, HS11, and HS12 ports (which are the ones I deactivated in the guide above) and nothing happens. I checked all ports with a USB 2.0 flash drive, a USB 3.0 flash drive, a USB 2.0 audio adapter, a USB 2.0 ethernet adapter, and a USB 3.0 SD card reader.
 

DMFO

New member
Joined
May 12, 2021
macOS
10.11.x
Mobo
Gigabyte Z490
CPU
10900
GPU
RX580
#6
Interesting... Thank you.

I had created a clone of 11.2.3 then upgraded the main drive to 11.3 then 11.3.1. This included having done port mapping but however XhciPortLimit was set to true. After the update, I lost USB 3.0 ports, so I set XhciPortLimit to false and ALL ports were usable even the disabled ones in the port mapping kext. My mapping kext is what I have been using since Catalina.

So maybe the issue is what XhciPortLimit is set to before update or certain mobo's.

I have to test again with another 11.2.3 disk.
 

Raine

Active member
Joined
Sep 30, 2018
macOS
10.16.0
Mobo
Gigabyte Z370n WiFi
CPU
Core i5-8400
GPU
Radeon RX-570
#7
Interesting... Thank you.

I had created a clone of 11.2.3 then upgraded the main drive to 11.3 then 11.3.1. This included having done port mapping but however XhciPortLimit was set to true. After the update, I lost USB 3.0 ports, so I set XhciPortLimit to false and ALL ports were usable even the disabled ones in the port mapping kext. My mapping kext is what I have been using since Catalina.

So maybe the issue is what XhciPortLimit is set to before update or certain mobo's.

I have to test again with another 11.2.3 disk.
The port mapping you said you did beforehand, was it a "USBmap.kext"?
 

DMFO

New member
Joined
May 12, 2021
macOS
10.11.x
Mobo
Gigabyte Z490
CPU
10900
GPU
RX580
#8
USBPorts.kext which was automatically named out of Hackintool at the time. Just like in your screen shot above.

I am just cloning my 11.2.3 on a spare disk before attempting an update test.
 
Last edited:

Raine

Active member
Joined
Sep 30, 2018
macOS
10.16.0
Mobo
Gigabyte Z370n WiFi
CPU
Core i5-8400
GPU
Radeon RX-570
#9
USBPorts.kext which was automatically named out of Hackintool at the time. Just like in your screen shot above.

I am just cloning my 11.2.3 on a spare disk before attempting an update test.
I just asked because I already had a working "USBmap.kext" file from when I mapped my build way back in Mojave, and that worked perfectly up to Big Sur 11.2.3. But once I went to Big Sur 11.3.0 that's when the issue started, so I decided to do a fresh mapping (as described in this guide) using Hackintool instead of the USBMap script I used last time. Not sure what was going on, or if there's really a difference between having a "USBmap.kext" and having a "USBports.kext" (shouldn't be since we specify the filename in the config.plist anyways) but the new port map is working 100%.
 
Likes: Railgun

DMFO

New member
Joined
May 12, 2021
macOS
10.11.x
Mobo
Gigabyte Z490
CPU
10900
GPU
RX580
#10
I just asked because I already had a working "USBmap.kext" file from when I mapped my build way back in Mojave, and that worked perfectly up to Big Sur 11.2.3. But once I went to Big Sur 11.3.0 that's when the issue started, so I decided to do a fresh mapping (as described in this guide) using Hackintool instead of the USBMap script I used last time. Not sure what was going on, or if there's really a difference between having a "USBmap.kext" and having a "USBports.kext" (shouldn't be since we specify the filename in the config.plist anyways) but the new port map is working 100%.
OK after some testing and thinking about what you said, It looks like since my mapping kext was created back in Catalina (last summer) it dose not work for Big Sur (I never noticed as XhciPortLimit was set to true and then broke with 11.3 update). So I just booted in Big Sur 11.2.3 (my backup) and re-did USB port mapping using the lates injectall and hackintool. I updated my config file in ProperTree and set XhciPortLimit to false and now the mapping sticks. My deactivated ports are indeed deactivated. This is also working in 11.3.1

One odd note. With these changes and back into Big Sur 11.3.1, using hackintool shows more ports (not as much as with injectall but some that I had deleted because I don't think my mobo has them)... then I tested with USBMap.command script which shows the correct amount of ports (15). This is as well as physically testing all the ports.

Anyway, I will call it fixed. Thanks for your help and time (y)
 
Last edited:
Likes: Railgun

Raine

Active member
Joined
Sep 30, 2018
macOS
10.16.0
Mobo
Gigabyte Z370n WiFi
CPU
Core i5-8400
GPU
Radeon RX-570
#11
OK after some testing and thinking about what you said, It looks like since my mapping kext was created back in Catalina (last summer) it dose not work for Big Sur (I never noticed as XhciPortLimit was set to true and then broke with 11.3 update). So I just booted in Big Sur 11.2.3 (my backup) and re-did USB port mapping using the lates injectall and hackintool. I updated my config file in ProperTree and set XhciPortLimit to false and now the mapping sticks. My deactivated ports are indeed deactivated. This is also working in 11.3.1

One odd note. With these changes and back into Big Sur 11.3.1, using hackintool shows more ports (not as much as with injectall but some that I had deleted because I don't think my mobo has them)... then I tested with USBMap.command script which shows the correct amount of ports (15). This is as well as physically testing all the ports.

Anyway, I will call it fixed. Thanks for your help and time (y)
Good to hear! :)

About what you mentioned, I do recall seeing some "new" USB ports show up in Hackintool when I was mapping in Big Sur that weren't even in my old notes from Catalina... so maybe that's just what happens with Big Sur.

So anyways... in hindsight, the USBmap I made back in Mojave just seemed to work in Catalina all the way to Big Sur 11.2.3 so I never bothered checking up on it. Lesson learned, a simple "remap" with every new MacOS might be the right way to do it from now on (y)
 
Likes: Railgun

playmo

New member
Joined
Jul 8, 2018
macOS
10.16.0
Mobo
Gigabyte Z370N WIFI
CPU
Coffee Lake i5-8400 2.80GHz
GPU
Radeon RX470 8GB + Intel UHD 630 1536 MB
#12
hi everyone, my HW configuration is very similar, almost identical, to yours, for this reason, for study purposes, I would ask you if you are interested in swapping: the entire EFI folder (compressed) + your BIOS (version with settings) because I think that only with these files you can make a complete comparison.
I had already performed the procedure for mapping the USB ports with Hackintool and the passage from 11.2 to 11.3.1 did not create any problems in the USB ports, I tried to boot with USBInjectAll instead of my USPPorts and I confirm that the USB are all deactivated
looking at the images you have attached I noticed some differences in the Kext we use, so I wanted to ask you for a comparison
moreover: if I execute the verbose boot I see some errors that I would like to solve, if through the debug options I write a report txt file several errors related to the RT.GV and RT.SV images are recorded that I don't know what they are, last but very important (at least I think) I have both VGAs (Intel + Radeon) active and recognized by the system
I would like to see how you configured your Config.plist and your BIOS
I start by attaching my files, I hope to be able to read your reply with the attached files soon
Thank you in advance
Playmo



Attached:
- HackOS info.txt - detailed machine report
- EFI.zip - included TXT boot report files
- BIOS.zip - profile file, i'm running the ver. F14.a
- USB scheme.zip - USB mapping reference (infographic images)
 

Attachments

Last edited:

DMFO

New member
Joined
May 12, 2021
macOS
10.11.x
Mobo
Gigabyte Z490
CPU
10900
GPU
RX580
#13
Yes, Hackintool shows a couple more USB and even shows USB-C port which my motherboard dose not physically have. I am guessing it just in the controller.
 
Last edited:
Joined
Jun 3, 2021
macOS
10.15.7, 10.16.0
Mobo
ASUS STRIX H270I-Gaming
CPU
i5-7500
GPU
RX580X
#15
@Raine Nice job! This is exactly what I needed help with. Thank you!

I am using Apple Wired USB Keyboard with Number KeyPad (MB110FB) which includ 2 USB ports (build-in USB 2.0 Hub) .
The keyboard is connected on HS08 (with-in 15 ports limitation).

in XhciPortLimit patch enable,
Only the USB 2.0 devices connected on Keyboard USB 2.0 port could be access.

in XhciPortLimit patch disabled with customized USBports.kext,
Reduces ports counts which are less than 15, then I could access USB 2.0 devices on physical ports.

Thanks for your great post, thank you.
 
Likes: Raine