EliteMacx86

Administrator
Staff member
Joined
Jul 22, 2018
Motherboard
Supermicro X11SPA-T
CPU
Intel Xeon W-3275 28 Core
Graphics
2xAMD RX 580 8GB
OS X/macOS
11.0.x
Bootloader
  1. OpenCore
Mac
  1. MacBook Pro
Mobile Phone
  1. Android
  2. iOS
How to Map your USB Ports on macOS

An EliteMacx86 Exclusive Guide - This guide covers mapping of USB Ports on macOS

Overview


Often, the USB ports are not well recognised or have certain issues. To fix that, USBInjectAll.kext from Rehabman was serving the purpose along with USB port limit patch. Later on, for more performance and to avoid conflicts, issues, a custom SSDT-UIAC was introduced. Later on, when Hackintool was introduced, USBPorts.kext served the purpose for a while as the USBInjectAll.kext was no longer maintained from RehabMan and new SMBIOS were introduced where the maximum support was till MBP15,2 and iMacPro1,1. However, when it comes to AMD systems, USBInjectAll.kext isn't supported at all.

And a new method was introduced from corpnewt with the name of "USBMap" which is basically a python script for mapping USB ports on macOS and creating a custom USB injector kext. The USBMap includes several features which have been outlined below.
  • No dependency on USBInjectAll
  • Can map XHCI (chipset, third party, and AMD), EHCI, OHCI, and UHCI ports
  • Can map USB 2 HUBs currently disabled
  • Matches based on class name, not port or controller name
  • Allows setting nicknames to the last-seen populated ports in discovery
  • Aggregates connected devices via session id instead of the broken port addressing
  • Can use best-guess approaches to generate ACPI to rename controllers or reset RHUB devices as needed
Why USB Mapping is necessary?


USB Mapping is necessary because of the following reasons which has been mentioned below.
  • macOS is unable to recognise the USB ports and their type.
  • Few ports running at a lower speed than the rated speed.
  • Bluetooth or Webcam not working.
  • Broken Sleep/Wake function.

Requirements


The requirements for mapping USB ports and fixing of USB ports has been described in a previous thread linked below.

Fixed USB Ports

1xUSB 2.0 Flash Drive
1xUSB 3.0 Flash Drive
1xUSB Type-C Flash Drive


Mapping USB Ports


Currently, there are two ways to Map the USB ports. Hackintool, which is very easy and the other one is USBMap from Corpnewt.

USB Ports Mapping using Hackintool

This method is very easy. Follow the steps below to map your USB ports.

1. Download Hackintool.
2. Unlock Hackintool using the lock button.
3. Go to USB Tab
4. Starting with USB 2.0 mapping, connect your USB 2.0 Flash Drive into each port of your system and wait for it to appear under Hackintool>USB. The active ports will be marked as "Green."
5. Connect your USB 3.0 Flash Drive into each port of your system and wait for it to appear.
6. Connect your USB Type-C Flash Drive into each port of your system and wait for it to recognize by Hackintool.
7. Once, each and every port of your system is checked with the USB 2.0, 3.0 and Type-C Flash Drives, count the total number of active ports.
8. To remove unused ports, simply select the unused ports and click on delete button. Now, you should see only the active ports. To verify the active ports, match the ports count from step 8.
9. Once you're done with removing unused ports, it's time to export. To export the Kext and SSDTs, click on Export.
10. All the files will be placed at your Desktop.

Possible Configurations

ConfigurationSSDTKextsXhciPortLimitNotes
Configuration 1SSDT-UIAC.aml
  • USBInjectAll.kext
  • Additional Kext(s)
NO
  • When using this configuration, the SSDT-UIAC.aml, XhciPortLimit and USBInjectAll.kext must be enabled for OpenCore and Clover bootloader.
Configuration 2None
  • USBPorts.kext
NO
  • When using this configuration, the XhciPortLimit must be disabled for OpenCore and Clover bootloader.
  • With this configuration, USBInjectAll.kext and XHCIUnsupported.kext must be removed

Notes:
  • Configuration 2 is the preferred configuration.
  • The guide assumes you're using SSDT-EC-USBX for OpenCore and Clover bootloader.
  • Do not use both the configurations together.

USB Ports Mapping using USBMap

Before you start mapping your USB ports, you need to download the tool. To download the USB Mapping Tool, follow the steps below.

1. Open Terminal and type the following commands one by one. When prompted, enter your password.

Code:
git clone https://github.com/corpnewt/USBMap
Code:
cd USBMap
Code:
chmod +x USBMap.command
Code:
./USBMap.command

List of Commands

CommandNotes
DUsed to Discover Ports
PUsed to Edit and create USBMap.kext
You must discover the ports first.
RReset all detected ports.
HGenerate ACPI to reset RHUBs
QQuit 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

TypeConnector InfoNotes
0USB 2.0 Type-A connector
3USB 3.0 Type-A connector
8Type C connector, USB 2.0 only
9Type C connector, with USB 2.0 and USB 3.0 switch
10Type C connector - USB 2.0 and USB 3.0 without Switch
255Proprietary connectorFor 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.
 
Last edited:

Similar threads

Forum statistics

Threads
505
Messages
4,680
Members
4,265
Latest member
echozerimad1212