USB Port Mapping
USB Port Mapping with Hackintool on macOS
Last updated
USB Port Mapping with Hackintool on macOS
Last updated
The GUI app Hackintool has many nice features which help with USB port mapping: devices are shown without delay as they are plugged in - including the connection speed - and its easy to add comments to describe the physical location of each USB port, which will make maintenance easier in the long run.
Currently there is no way on macOS to have all ports available to configure in one go. For this reason we will use the following workflow: Preparation, Two rounds of mapping (USB3, then USB2), Define Connectors, Cleanup and Checking. We use USBInjectAll.kext which includes boot flags for excluding groups of ports.
Download and install Hackintool.
Backup your current EFI or save it to a USB boot drive, to make sure you have a bootable EFI, if something goes wrong.
Set config.plist -> Kernel -> Quirks -> XhciPortLimit -> False - Do not set it to true, as it does not work any more on Big Sur and it may crash your system: Known Issues.
Check, if you need ACPI renames as explained in System Preparation and add those that are required.
Run Hackintool and go to the USB tab to check your USB Controllers list. Based on your USB Controller's Device ID you may need to install additional kexts:
XHCI-unsupported.kext - Needed for non-native USB controllers, for example: 8086:8D31, 8086:A2AF, 8086:A36D, 8086:9DED.
If needed download and extract XHCI-unsupported.kext
Download and extract USBInjectAll-0.x.y-RELEASE.zip
Temporarily add USBInjectAll.kext to EFI/OC/Kexts/
Unplug all USB devices except the essential ones, presumably Mouse and Keyboard plugged into USB 2 ports.
Launch Hackintool, go to the USB tab and click the “Clear All” button to remove any previously cached port mappings and then the “Refresh” button.
Look for the Port Name name of the mouse and keyboard; in this example they are HS07 and HS08.
We now disable all USB 2 ports except the mouse and keyboard ports, in order to keep us under the 15-port limit.
In config.plist -> NVRAM -> boot-args add -uia_exclude_hs uia_include=HS07,HS08
Change the HS07 and HS08 ports to the ones which actually have your mouse and keyboard attached!
Reboot for the first time.
Run Hackintool and go to the USB tab. Click the “Clear All” button again and then the “Refresh” button. You can now see only the USB 3 ports as well as the ports used for mouse and keyboard.
Plug and unplug a USB 2 and a USB 3 device into all ports on your system: and plug and unplug a USB Type-C device into all applicable ports (in both orientations).
As you observe the ports being highlighted, you should name each port with a clear location Comment. For this purpose right click the Comment field of the active port and type in a name such as: Up-Left-USB3, Middle-Left-USB-C or Low-Right-USB2on3. (As seen from the direction you are looking at them when the case is upright.)
Hackintool does not show the devices connected to motherboard hubs clearly even though it does provide limited feedback. If you have a lot of internal hubs, you can launch the macOS version of USBToolBox in Discover Ports mode to see additional info about devices connected to hubs.
The ports that are active will be highlighted green.
Select with the mouse and delete the ports that are not highlighted green, using the minus [-] button.
In config.plist -> NVRAM -> boot-args remove -uia_exclude_hs uia_include=HS07,HS08 and add -uia_exclude_ss instead. This will disable all USB 3 ports for the next reboot.
Reboot for the second time.
Run Hackintool again and activate the USB tab. You can now see the USB 3 ports which you cached from the first session and the additional available USB 2 ports.
Plug and unplug a USB 2 device into all ports on your system.
As you observe the ports being highlighted, you should name each port with a clear location Comment. For this purpose right click the Comment field of the active port and type in a name such as: Front-Low-Left-USB2 or UpMid-Right-USB2, etc.
The ports that are active will remain highlighted green.
Delete the ports that are not highlighted green.
Count the number of highlighted ports. You should now have a maximum of 15 ports. If you still have more, you will have to remove some USB 2 or USB 3 ports which you are unlikely to use.
Set each port to the appropriate Connector using the drop down list.
SSxx ports connected to USB 3 ports should be kept at "USB3".
HSxx ports connected to USB 2 ports should be set to "USB2".
HSxx ports connected to USB 3 ports can be set to "USB2" (some recommend USB3 and apparently both options work fine).
USB Type-C
If it uses the same HSxx/SSxx in both orientations, then it has an internal switch (use “TypeC+Sw”)
If it uses a different HSxx/SSxx in each orientation, then it has no switch (use “TypeC”)
USB ports with devices permanently attached (eg. a Bluetooth card) should be set to “Internal”.
Internal HUBs can be connected to ports such as PRxx, HSxx or SSxx . They should be set to “Internal”.
Arrange your Desktop files into folders, so you will easily see the files generated by Hackintool.
Click on the “Export” button to generate files, which you will find on your Desktop.
We only use one of the generated files: Copy USBPorts.kext to EFI/OC/Kexts.
The generated USBPorts.kext is a Codeless Kernel Extension used to inject the USB port mappings. You will need to regenerate this kext or edit the plist file inside it, after you change your SMBIOS Model Indentifier for example from iMac20,1 to iMacPro1,1.
You can now perform a clean up and remove unnecessary settings and files:
Remove the generated files from your Desktop.
In Config.plist -> NVRAM -> boot-args remove -uia_exclude_ss
Remove (or disable) USBInjectAll.kext.
Reboot for the third time.
Run Hackintool and go to the USB tab.
Click the “Clear All” button and then the “Refresh” button.
Now you can check all ports are working correctly by plugging various USB devices into each port.
If you need to change a Connector type you will need to export a new USBPorts.kext and replace the current one in EFI/OC/Kexts.
If you made a mistake, delete EFI/OC/Kexts/USBPorts.kext and start from the beginning of the instructions again.
If your system has an unusually large number of ports, you may need to do more than two rounds of mapping, hiding different port ranges each time.
Depending on your use case, you may prefer to map USB 2 ports first and then USB 3 ports.
Even though enabling XhciPortLimit is officially not recommended any more for recent versions of Big Sur (and newer versions of macOS), it did seem to work in Big Sur 11.6.4 on Haswell for me and did not cause boot loops.
If you have Windows already installed on the same system, you may prefer to use USBToolBox, which is a new terminal based tool that improves upon USBMap in various ways. It has the technically most advanced solution to USB mapping and it in active development. One advantage over Hackintool is the ability to see all ports and to map all ports in one go. You will quickly have a ready made port map even before installing macOS. It also solves some technical issues, such as removing the need for controller renames in ACPI patches and it does not require the Model Identifier (for example iMac20,1) to be specified. This ensures better maintainability. If you do not have Windows installed, you can also utilize USBToolBox on Windows PE by running the free Hiren's BootCD PE on a USB drive.
The guide for USBToolBox is in the chapter USB Mapping on Windows.
This guide is loosely based on the USB mapping help file found inside Hackintool v3.8.4. I adapted it from Clover to OpenCore, changed the workflow and made some minor corrections.
Except where otherwise noted, content on this site is licensed under the Creative Commons — Attribution-NonCommercial 4.0 International — CC BY-NC 4.0 license. Attribution by link to chriswayg · GitHub.
