# USB Port Mapping

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. 

![15 Ports mapped and named in Hackintool](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2Fsdj3YtSPNtiQ0pmhImaB%2FUSB%20ports%20mapped%20final.png?alt=media\&token=0222ee06-65fb-4ace-9992-446233477ca6)

### Preparation

* Download and install [Hackintool](https://github.com/headkaze/Hackintool/releases/latest).
* 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](https://dortania.github.io/OpenCore-Install-Guide/extras/big-sur/#known-issues).
* Check, if you need ACPI renames as explained in [System Preparation](https://dortania.github.io/OpenCore-Post-Install/usb/system-preparation.html) 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](https://dortania.github.io/OpenCore-Install-Guide/ktext.html#usb), for example: `8086:8D31, 8086:A2AF, 8086:A36D, 8086:9DED`.
  * If needed download and extract [XHCI-unsupported.kext](https://github.com/Sniki/OS-X-USB-Inject-All/archive/refs/heads/master.zip)
* 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.

### First round of mapping (USB3)

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

### Second round of mapping (USB2)

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

#### Define Connector Settings

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

#### Generate & install USBPorts.kext

* 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](https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KEXTConcept/KEXTConceptAnatomy/kext_anatomy.html#//apple_ref/doc/uid/20002364-SW8) 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`.

#### Cleanup

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

### Checking

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

### Notes

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

### Alternatives

If you have Windows already installed on the same system, you may prefer to use [USBToolBox](https://github.com/USBToolBox/tool), which is a new terminal based tool that improves upon [USBMap](https://github.com/corpnewt/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](https://github.com/USBToolBox/kext) 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](https://www.hirensbootcd.org) on a USB drive.

* The guide for USBToolBox is in the chapter [USB Mapping on Windows](https://chriswayg.gitbook.io/opencore-visual-beginners-guide/alternatives/usb-mapping-on-windows).

#### **Credits**

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

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FFgodoVfQ9J7nzfXa4rSu%2Fby-nc-license.svg?alt=media\&token=03a208c0-37c6-488e-b564-b57cd43c75c9) *Except where otherwise noted, content on this site is licensed under the* [*Creative Commons — Attribution-NonCommercial 4.0 International — CC BY-NC 4.0*](https://creativecommons.org/licenses/by-nc/4.0/) *license. Attribution by link to* [*chriswayg · GitHub*](https://github.com/chriswayg)*.*