Contribute
Register

The New Beginner's Guide to USB Port Configuration

The XHCI port limit quirk stopped working after 11.3.2 so you'd have to use an older Big Sur version or use Catalina to make your USB ports kext.
I've been using the USB Map Tool from CorpNewt described in the Dortania Install Guide, its definitely more complex but gets around needing the XHCI Port Limit Quirk.


I plagiarized the instructions below being they helped me understand better how the tool works. In the end I still needed to tweak the final kext using a plist editor, some of my internal ports were listed as USB3. It's a useful tool but no where near as easy as Hackintool.


List of Commands

Command Notes
D Used to Discover Ports
P Used to Edit and create USBMap.kext
You must discover the ports first.
R Reset all detected ports.
H Generate ACPI to reset RHUBs
Q Quit the script.

2. Type: R to Reset all the discovered ports. This might be useful, if you have used the script earlier.
3. Type: D to discover the ports. To discover the ports, follow the steps below.

4. Connect the USB Drives in each of the available ports one by one and wait for the drives to show up.

5. Once all the ports are discovered, press Q to quit the ports discovery and then press P to edit the plist.

USB Types

Type Connector Info Notes
0 USB 2.0 Type-A connector
3 USB 3.0 Type-A connector
8 Type C connector, USB 2.0 only
9 Type C connector, with USB 2.0 and USB 3.0 switch
10 Type C connector - USB 2.0 and USB 3.0 without Switch
255 Proprietary connector For Internal USB Ports such as Bluetooth.
macOS always expects Bluetooth as Internal.

Now, use T:x, x:3. Where,
  • x represents your discovered port.
  • 3 represents the connector type.
Type:
Code:
T:x:255
The x is the Bluetooth Controller and it has to be internal.


6. Press K to build the USBMap.kext.
7. Press M to go to Main Menu.
8. If it has an option to reset RHUBs, press A/H or both to create an SSDT.
9. Press Q to quit.

Notes:
  • The kext and the RHUB SSDT is located at Yourusername>USBMap>Results.
  • 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.
  • If a port is not detected/discovered, it will be skipped and the respective ports will not work.
Installing kexts
Now, as you've the kext ready, you'll need to install it to enable the mapping.

Mount your ESP.

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

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

Notes:
  • If there's a conflicting controller and SSDTs has been generated, copy the SSDTs to EFI/OC/ACPI. You'll also need to add the kext entry in ACPI>Add section of your config.plist.
  • In case, if you're using Clover, the directory to place the SSDT will be EFI/Clover/ACPI/patched.
Restart your System


After performing all the above steps, restart your system for the applied changes to take effect.
You can run the USBMap command and verify the ports mapped. You'll only see the discovered/mapped ports in list.
 
Hi all, I'm desperately trying to map the USB ports of my GA-Z87X-D3H with Clover in High Sierra and so far without any result. I have tried several methods, Rehabman's
this one, but whether it's in IORegistryExplorer, UsbMapTool, or Hackintool, I can't get the uSB ports to identify correctly. The problem is that, when I plug a USB stick, whether it's USB2 or USB3, in the ports that are supposed to be USB3 (6 on the back and 2 on the front) they always appear as HS09 and HS10.
The USB2 seem to work correctly and they appear as HS11, HS12, HS13, HS14

I have
USBInjectAll.kext in EFI/KEXTS/Others
EHC1->EH01 and EHC2->EH02 rename (in config.plist)
Port_limit Removal Patch for High Sierra

Thanks for your help
 

Attachments

  • Screen Shot 2021-10-03 at 09.16.52.png
    Screen Shot 2021-10-03 at 09.16.52.png
    180.5 KB · Views: 72
  • Screen Shot 2021-10-03 at 09.16.28.png
    Screen Shot 2021-10-03 at 09.16.28.png
    198.8 KB · Views: 73
Is the EHC1->EH01 and EHC2->EH02 rename necessary for both Opencore and Clover for older boards, Z97 Chipset for example?
...If your Bluetooth M.2 card (not on a PCIe slot carrier card) does not show in USB list in Hackintool. is not being detected by the OS? Should this be the case with a Fenvi card in the correct slot or are certain boards made only to detect Cnvi cards?
..There is a newer version of Usbinjectall 0.7.7 which has support for 500 series chipset boards, is there a problem with the version from Daliansky forked from Sniki 0.7.7? (Added 500-series chipset XHC controller, 8086:43ed)
....The question on the Bluetooth/WiFi card makes no sense to me as the card is detected under Windows 10 and works perfectly with both Bluetooth and WiFi, but not under the latest Catalina using opencore. (this [problem occurs on both an Asus Pro H410TM/ CSM and an Asrock H41TM ITX (BOTH THIN ITX BOARDS)
 
Last edited:
Curious if anyone else has had their USBMap.kext occasionally fail to load at a cold-start bootup? I setup my current Hack last month, tweaked USBMap and got it working as I liked, but about half of the time when I boot in the morning I will successfully get to the Big Sur 11.6 desktop but it's obvious the USBMap didn't kick in... external hard drives don't mount and even my (wired) mouse doesn't respond. My only option is pressing the reset button on top of the case and reboot, after which all is fine with my USB ports again. This only seems to happen occasionally but when it does, it's always after a cold start. USBMap is currently the 4th kext to load in my config.plist, I'm wondering if load-priority matters? Zipped EFI attached.
 

Attachments

  • EFI.zip
    5.8 MB · Views: 76
Load priorities only matter for Lilu.kext and its plugins. Your USBMap.kext won't have any dependancies in the /OC/Kexts folder so it shouldn't matter if it is injected 1st, last or anywhere in-between. It should load each time the system boots or reboots.

Having looked through your config.plist I noticed that a number of items are out of order, within their specific sections. I also noticed that the UEFI > AppleInput section is at the end of your config.plist, it should be positioned before the UEFI > Audio section. This is at odds with the sample.plist that was issued with OpenCore 0.7.4, which you are running.

What made me notice this disorder was looking for the Kernel > Quirks > XhciPortLimit entry, as this is one of the many entries that are in the wrong place in the config. It is set correctly, just out of position in the Quirks section, along with a few other entries.

You might fix the USBMap.kext issue by recreating your config.plist, or using the sample.plist as a base for sorting the entries and sections in your current config to the correct order.

Do you use a configurator to manage your config.plist? If yes, you might want to look at using a manual option for doing any edits in the future. Using the latest version of Corpnewt's ProperTree plist editor to run a Clean Snapshot, sorted your USBMap.kext to 2nd in the list of kexts. It didn't change any of the other disordered entries.
 
Curious if anyone else has had their USBMap.kext occasionally fail to load at a cold-start bootup? I setup my current Hack last month, tweaked USBMap and got it working as I liked, but about half of the time when I boot in the morning I will successfully get to the Big Sur 11.6 desktop but it's obvious the USBMap didn't kick in... external hard drives don't mount and even my (wired) mouse doesn't respond. My only option is pressing the reset button on top of the case and reboot, after which all is fine with my USB ports again. This only seems to happen occasionally but when it does, it's always after a cold start. USBMap is currently the 4th kext to load in my config.plist, I'm wondering if load-priority matters? Zipped EFI attached.
This guide does not use USBMap.kext...
 
Load priorities only matter for Lilu.kext and its plugins. Your USBMap.kext won't have any dependancies in the /OC/Kexts folder so it shouldn't matter if it is injected 1st, last or anywhere in-between. It should load each time the system boots or reboots.

Having looked through your config.plist I noticed that a number of items are out of order, within their specific sections. I also noticed that the UEFI > AppleInput section is at the end of your config.plist, it should be positioned before the UEFI > Audio section. This is at odds with the sample.plist that was issued with OpenCore 0.7.4, which you are running.

What made me notice this disorder was looking for the Kernel > Quirks > XhciPortLimit entry, as this is one of the many entries that are in the wrong place in the config. It is set correctly, just out of position in the Quirks section, along with a few other entries.

You might fix the USBMap.kext issue by recreating your config.plist, or using the sample.plist as a base for sorting the entries and sections in your current config to the correct order.

Do you use a configurator to manage your config.plist? If yes, you might want to look at using a manual option for doing any edits in the future. Using the latest version of Corpnewt's ProperTree plist editor to run a Clean Snapshot, sorted your USBMap.kext to 2nd in the list of kexts. It didn't change any of the other disordered entries.
Thanks so much for taking a look at my files. As it turns out, I have been using ProperTree since my first switch io OpenCore from Clover. Every month I've been updating when the new OC version is posted, but have just been creating any new entries with an “Add child…” command and so they've always slid into the last position of their respective sections. I'd notice they were positioned differently from the sample.plist but didn't think it mattered.

Shamed to admit I didn't even notice the little “gripper bar” at the right of OpenCore entries until now :) that allows dragging the entry to a new position.

I'll reoganize my config.plist as you recommend and hope that clears up my problem! Thanks again!
 
Back
Top