USB Mapping on Windows
USB Mapping with USBToolbox on Windows
Last updated
USB Mapping with USBToolbox on Windows
Last updated
This guide will explain how to do USB mapping on Windows with the excellent USBToolBox. If you have Windows already installed on the same system, you can 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 of doing this on Windows is the ability to see all ports at once and to map all ports in one go. You can 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 in its default mode 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.
Boot into Windows on the computer you want to hackintosh. Windows 10 or 11 (64-bit) are recommended.
Get USBToolbox from Releases · USBToolBox/tool by downloading Windows.zip and extracting it.
Launch USBToolBox/dist/Windows.exe and you will see the following terminal command window:
Pressing "B" will get you back to the main menu. Then press "D" to discover ports:
Plug in a USB device into each port. Wait for the listing to show your USB device before unplugging it and plugging it into another port.
Plug in a USB 2 device and a USB 3 device into each USB 3 port. (Theoretically you only need to plug in one USB 3 device into the USB 3 ports, because companion detection should be working on Windows, but I still had to use both types of devices.)
Plug in a USB-C device twice in each applicable port by reversing the direction of the plug.
Once mapping is done, go to the Select Ports screen, by pressing "S" in the main menu.
Select your ports and adjust port types as necessary. The most common types for USB mapping are:
Choose the port numbers which are applicable to you. In this guide I will illustrate the steps by using the port numbers as shown above.
To toggle the ports off that are unused or that you do not want to use, type the port numbers separated by commas
such as: 1,2,11,12,13,15,16
Since I can only use 15 ports I had to drop some. In this example I deactivated the companion USB 2 port of the USB 3.1 port, as well as the USB 2 companion of the USB-C port (number 1 and 2).
Note: Activation and de-activation of ports as well as the definition of physical port types is by default connected to the companion. For example, if you deactivate the USB 2 companion of a USB 3 port both will be deactivated. This may not always be what you want, like in my example, where I just want to deactivate the USB 2 functionality of two USB 3 ports. To decouple these ports you can go into settings to disable Bind Companions first.
Press "C" (and "Enter") to open and adjust settings.
Change Bind Companions to Disabled by pressing "C" so that you can define related port mappings independently of each other:
As soon as you explicitly define the ports, the "guessed" label will disappear.
For defining the physical USB 2 ports type: T:7,8,9,10:0
For defining the physical USB 3 ports type: T:3,4,5,6,19,20,21,22:3
For defining the physical USB C ports (here with switch) type: T:18:9
For defining the internal port type (without outside user access): T:17:255
Since the functional USB 2 companion ports (which are hosted on physical USB 3 ports) need to be described by their physical connector type, they should be set as USB 3 in the USB mapping.
I also recommend to add comments, for the purpose of long term maintainability. You may need to switch back and forth between the Select Ports screen and the Port Discovery screen after you have been able to determine the physical location of each displayed port.
You should name each port with a clear location Name. For this purpose type in a name such as: C:18:Middle-Left-USB-C and C:22:Up-Left-USB3 (As seen from the direction you are looking at them when the case is upright). - If you wish to see the port location names (saved in the comments of the generated file) when you check your ports in macOS, you can use the Hackintool > USB tab and observe where your devices get plugged in.
Press "K" to build the kext in the dist folder:
The UTBMap.kext will also require the companion USBToolBox.kext to be downloaded and added to your OpenCore EFI. The advantage of utilizing the USBToolBox.kext is among others, that it does not require the Model Identifier to be specified in the USB map. Read the USBToolBox documentation for details.
Using OCAuxiliaryTools you will now add USBToolBox.kext and UTBMap.kext to your OpenCore EFI/OC/Kexts in Kernel > Add. - Remove any other USB related kexts first. (see OCAuxiliaryTools Guide)
Note: XhciPortLimit - Enable was previously used to patch the XCHI port limit to a higher value than the 15 port maximum. Make sure to check that XhciPortLimitin Kernel > Quirks is disabled! After configuring a proper USB map, it is not needed any more, and since Big Sur 11.3 the XhciPortLimit Quirk is not used at all, because it has been causing boot loops for some people.
Thanks to the developer of this excellent tool Dhinak G who also pointed out some issues with the original version of this guide on r/hackintosh.
Current discussion and feedback can be found on r/hackintosh: GUIDE: Easy USB Mapping with USBToolbox on Windows
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.
USBToolBox Main MenuXhciPortLimit
