Contribute
Register

[HOW TO] USB ports map for macOS with USBToolBox

Joined
Dec 10, 2010
Messages
1,367
Motherboard
Gigabyte Z390 Aorus Elite
CPU
i9-9900K
Graphics
RX 6600 XT
Mobile Phone
  1. iOS
How to generate USB port map on Windows for use on macOS, which has a limit of 15 ports per USB controller, using dhinakg's USBToolBox. This is currently the easiest method of generating the USB port map for macOS with the only downside being that you need a Windows system on the same machine.

I have not found detailed instructions about it in this forum, if they are available somewhere please tell me so I don't duplicate the post.

Download the tool

On the GitHub site you have the tool for Windows (tool >> Releases >> Windows.zip). For now it is all you need.

Create the ports map

In the unzipped folder, run Windows.exe. A command window opens in which the entire process takes place.

toolbox1.png

Letter C to access the settings

Here I only enable 2 options: Show Friendly Types (facilitates the reading of the detected ports) and Add Comments to Map (allows adding identifying comments to each port such as "rear blue USB3").

toolbox2.png

Letter D to show all the ports detected by the tool

Almost all the motherboards that we have in the Hackintosh have more than 15 ports, which is the maximum limit tolerated by macOS. In my case, there are 26 ports. If I use macOS as-is, without port mapping, some will be enabled and some won't, some will probably run at the wrong speed and sleep will almost certainly not work well. For this reason, it is necessary to generate the map, to define the 15 ports that we are going to have active in macOS and that will be the only ones that we can use.
Notice that the ports that have any device connected are in green and the rest are in white.

In this phase you need a type 2 USB device and a type 3 USB device. I have used a USB3 external disk and 2 cables to connect it to the PC, one of which is USB2 and the other is USB3. You can also use 2 USB memories, one USB2 and one USB3.
  • Start with the USB2 device and at the end you repeat with the USB3 (or vice versa)
  • Connect it in each of the ports, whether USB2 or USB3, until you check that it appears in the list of ports
  • When you remove the device, it also disappears from the list but is saved for the next step
  • When finished with both devices, letter B to return to the previous menu.
Letter S to choose the ports and build the kext
  • In the list, each port you plugged a device into has the device associated with it. In addition to those who already had one connected (those in green)
  • Here you can give a name to the ports that you are going to choose, for this you write c:x:name where x is the number of the port and name is the name that you want to give it (it can be several words)
  • It is time to make the selection. The most comfortable is to use N to deselect all ports and then write the numerical list of those chosen in the way 1,2,3,4,5 without exceeding 15 ports.
  • At the end, the list shows which are the 15 ports chosen and the comment that we have written in each of them.
toolbox3.png

Letter K to generate UTBMap.kext

This is the kext that macOS will use. It does not work by itself but must be accompanied by USBToolBox.kext downloaded from the same GitHub site. Both together in the OpenCore or Clover Kexts folder. In the config.plist file, USBToolBox.kext has to be before UTBMap.kext.

toolbox4.png

An additional advantage that this method has over USBMap.kext from corpnewt or USBPorts.kext from Hackintool is that it does not depend on the SMBIOS model, in these you have to modify the Info.plist file of the kext when changing Mac models.
 
Last edited:
Thanx for the guide !

I can confirm the tool is very easy to use and the companion detection worked 100% in my case. Though, I stumbled upon a presentation of it on another forum, by the creator of the tool I think. It is stated :
  • Ignore port definitions from ACPI to force macOS to enumerate all ports manually
    • Bypasses borked ACPI as seen on some Ryzen motherboards and 400 series Intel motherboards
    • Replaces SSDT-RHUB
  • Override any built-in Apple USB maps attaching based on SMBIOS and controller name
    • Removes the need for controller renames in ACPI patches

Does that mean that after building the kext, putting both files in the EFi and including them in the .plist, one can remove the renames and SSDT-RHUB ? Not that these 2 items bother me especially, but simplifying a plist is always something I like. Any thoughts on that matter ?

Cheers!
 
Last edited:
@Bergier3K
SSDT-RHUB is required for Asus Z490 motherboards. USB ports map is a general task for every hackintosh.
The developer of the kexts indeed says that it replaces SSDT-RHUB. Their skills are much bigger than mine. This can make sense, the SSDT and the kext force to macOS to rebuild the USB ports list at boot so the SSDT, since this point of view, is redundant.
 
Last edited:
@miliuco I was wondering in general, not especially for my motherboard, for which, indeed, no SSDT-RHUB is needed. Maybe i'm polluting your thread - which by the way is great, I wanted to write a little guide on that topic as well, as soon as my mapping was done - but I have issues with my mapping using this method. I think it is related to 2 thunderbolt ports acting also as USB 3.2 gen2 (btw the usb classification is nowadays so convoluted I'm not sure to understand it perfectly).

Under windows USBToolbox show my 26 usb ports and 4 extra ports (so 2 controllers with oddly the same name, whereas ioreg and Hackintool show only one controller). 2 of these 4 extra light up when a USB3.1 type c is plugged into the 2 thunderbolt ports, but not the 2 other ones. These 4 extra ports seem to have 2 other companions each (USB2 and, I assume, USB3), located under the other controller. I confirm also after triple checking that all the USBc ports on this card have a switch even the internal header. If you have any ideas to shed some light on that, I'd love to understand how this works.

Thanx for the write up !
 

Attachments

  • 3.png
    3.png
    184.9 KB · Views: 303
@Bergier3K
I have no experience with thunderbolt ports. I dont’t have any idea for you.
If you disable the port 12, ITE device, to get the 15 ports, did the kext work fine on macOS?
 
A first version of the kext without any USB3 access to the thunderbolt ports worked perfectly. However, a second version including the TB ports and disabling a 3.2 rear port, was a bit glitchy (the USBC header was rebooting the system upon plugging, so abruptly it looked like a short). I might have made an error, I have yet to double check that new version when I have a bit of time.

Thanx anyway :)
 
@miliuco I was wondering in general, not especially for my motherboard, for which, indeed, no SSDT-RHUB is needed. Maybe i'm polluting your thread - which by the way is great, I wanted to write a little guide on that topic as well, as soon as my mapping was done - but I have issues with my mapping using this method. I think it is related to 2 thunderbolt ports acting also as USB 3.2 gen2 (btw the usb classification is nowadays so convoluted I'm not sure to understand it perfectly).

Under windows USBToolbox show my 26 usb ports and 4 extra ports (so 2 controllers with oddly the same name, whereas ioreg and Hackintool show only one controller). 2 of these 4 extra light up when a USB3.1 type c is plugged into the 2 thunderbolt ports, but not the 2 other ones. These 4 extra ports seem to have 2 other companions each (USB2 and, I assume, USB3), located under the other controller. I confirm also after triple checking that all the USBc ports on this card have a switch even the internal header. If you have any ideas to shed some light on that, I'd love to understand how this works.

Thanx for the write up !
I have exactly the same situation with Z690 Aero D, the same shows up in USBToolbox: Two controllers, one with the 26 ports and the other with thunderbolt/USB controller with four Type-c with switch ports, two connectors are in the back and I think that the other two are internal. Connecting a USB3 device to any of the Thunderbolt/Type-C in the back, it shows attached to the 4 port USB/Thunderbolt controller, but when an USB2 type-C is connected to any of the Thunderbolt/Type-C in the back, it shows attached to te 26 port controller. Very confusing
 
Last edited:
@Talanca Both controllers with same name also ? Now remains the question of trying a USB3 type A plugged onto the thunderbolt via an adapter. I bet it will show as a third option. I will get an adapter in a week or so and report on this situation.
@miliuco If you prefer your thread to remain a guide only type of thread, please say so and I would open another thread ;)
 
@Talanca Both controllers with same name also ? Now remains the question of trying a USB3 type A plugged onto the thunderbolt via an adapter. I bet it will show as a third option. I will get an adapter in a week or so and report on this situation.
@miliuco If you prefer your thread to remain a guide only type of thread, please say so and I would open another thread ;)

In fact I done the type-C connector mapping using a USB type A to type-C adapter. Heres a pic of the controllers and ports in USBToolbox
 

Attachments

  • Captura de pantalla 2023-02-01 095204.jpg
    Captura de pantalla 2023-02-01 095204.jpg
    235.3 KB · Views: 163
Humm then my hypothesis is to be discarded. Are your USBC ports with or without switches ?

I'll look into it a bit better when I have more time (after the week-end) But I advise you to make proper and clear names for all the ports, it will help you greatly and it will be clearer for everyone trying to help (cf. my picture with the blue names).
 
Back
Top