USB Port Mapping
macOS only uses the first 15 ports of each USB controller, and it needs to know
what kind of connector each port is. A USB map tells it which ports exist and how
they're connected. Hackintool builds the map as a codeless USBPorts.kext.
Before you start
- To see every port while mapping, temporarily lift the 15-port limit:
OpenCore's Kernel > Quirks > XhciPortLimit works up to macOS 11.2.
On macOS 11.3 and later it no longer works, so map with USBToolBox.kext
(or USBInjectAll.kext) loaded, or map the controller in two passes
(USB 2 ports first, then USB 3).
- If Hackintool flags a controller name as reserved (for example XHC1,
EHC1 or EHC2), use Add Renames… to add the ACPI renames to your
config.plist, then reboot.
Mapping
- Open the USB section. Use Clear All and then Refresh to start
from a fresh list of the ports macOS can see.
- Plug a USB 2 device and a USB 3 device into every port. For Type-C
ports, plug in both orientations. Ports in use turn green, and the
device's name and speed are shown.
- Click Remove Unused to remove ports that never had a device
plugged in (or select ports and click Delete).
- Set each port's connector type:
- Internal for ports with a device permanently attached, such
as Bluetooth modules and internal hubs.
- USB3 for both the HSxx and SSxx ports of a USB 3 Type-A port.
- TypeC+Sw if a Type-C port uses the same ports in both
orientations (it has a switch), TypeC if it uses different
ports in each orientation.
- Keep each controller at 15 ports or fewer. Hackintool warns you
when a controller has too many.
- Click Export. Hackintool writes USBPorts.kext and SSDT-USBX.aml
(USB power properties) to the folder you choose.
Installing
- OpenCore: copy USBPorts.kext to EFI/OC/Kexts and SSDT-USBX.aml to
EFI/OC/ACPI, then add both to config.plist.
- Clover: copy USBPorts.kext to EFI/CLOVER/kexts/Other and
SSDT-USBX.aml to EFI/CLOVER/ACPI/patched.
- Remove USBToolBox.kext / USBInjectAll.kext and disable XhciPortLimit,
then reboot.
Making changes later
Use Import to load an existing USBPorts.kext (or a map made by
USBMap), change it, and export it over the old one.
Q. What is USBPorts.kext?
A. It's a
codeless kernel extension that tells macOS which ports exist and what
type they are. It needs no other kexts.
Q. Do I need SSDT-UIAC.aml?
A. Only if you still use USBInjectAll.kext. File > Export > USB SSDT-UIAC…
creates it, but USBPorts.kext is the recommended method.