USBPorts

USBPorts (the USBToolBox kext) is a companion kext for USBToolBox maps that makes common USB mapping actions easier. It supports El Capitan and up, although only Catalina and up have been tested.

Overview

The USBToolBox kext works alongside USB maps created by the USBToolBox mapping tool. It provides several features that simplify USB mapping on Hackintosh systems, including the ability to ignore ACPI port definitions, override built-in Apple USB maps, and attach to controller instances in more flexible ways.

Features

• Flexible Matching: Attach to the controller instance or parent device, allowing for more ways to match
• ACPI Port Removal: Ignore port definitions from ACPI to force macOS to enumerate all ports manually
  • Bypasses broken ACPI as seen on some Ryzen motherboards and 400-series Intel motherboards
  • Replaces SSDT-RHUB
• Apple Map Override: Override built-in Apple USB maps that attach based on SMBIOS and controller name
  • Removes the need for controller renames in ACPI patches
• No Model Identifier Required: Does not require a model identifier specified in the USB map (if attaching to PCI device)
• Compatible: Very compatible with existing USB maps (port format is the same)
• No Hardcoded Maps: Does not hardcode any port maps, unlike USBInjectAll

Note: This kext does not patch the port limit.

Installation

Fresh Install Flow

1. Download the latest release from GitHub
2. Add USBToolBox.kext and UTBDefault.kext to EFI/OC/Kexts and update your config.plist
3. Install macOS
4. Map your ports using the USBToolBox tool
5. Remove UTBDefault.kext and add your newly created UTBMap.kext (or whatever your USB map is called) to EFI/OC/Kexts
6. Reboot and your USB map should be working

What’s Included

The release ZIP contains two kexts:

• USBToolBox.kext — The main kext. Always required when using USBToolBox maps.
• UTBDefault.kext — A codeless kext used for attaching USBToolBox to all PCIe USB controllers. Designed for use before you map, so all USB ports work (assuming no port limit) during the mapping process. Must be removed after mapping is complete.

config.plist Entry (USBToolBox.kext)

<dict>
    <key>BundlePath</key>
    <string>USBToolBox.kext</string>
    <key>Comment</key>
    <string>USBToolBox mapping kext</string>
    <key>Enabled</key>
    <true/>
    <key>ExecutablePath</key>
    <string>Contents/MacOS/USBToolBox</string>
    <key>MaxKernel</key>
    <string></string>
    <key>MinKernel</key>
    <string></string>
    <key>PlistPath</key>
    <string>Contents/Info.plist</string>
</dict>

Configuration

USBToolBox supports configuration using boot arguments, properties, or in the map. You can set the properties on either the PCI device or the AppleUSBHostController instance.

Boot Arguments

Argument	Property	Description
-utboff	utb-off	Disable USBToolBox completely
-utbacpioff	utb-acpi-off	Disable RHUB removal from ACPI plane (broken ACPI removal)
-utbappleoff	utb-apple-off	Disable existing ports and port-count removal
-utbmapoff	utb-map-off	Disable custom map (useful for testing)
utbwait=XXX	utb-wait (number)	Custom delay for waitForMatchingService, in seconds. Integer between 1-180, inclusive.

Properties can be any type — only existence is checked, not type (unless otherwise specified).

Converting Existing Maps

Converting existing USB maps to use the USBToolBox kext is straightforward:

For each IOKit personality, change the following:

• CFBundleIdentifier → com.dhinakg.USBToolBox.kext
• IOClass → USBToolBox
• IOMatchCategory → USBToolBox

Add a dictionary named OSBundleLibraries to the root item containing com.dhinakg.USBToolBox.kext with value 1.0.0.

FAQ

Do I need UTBDefault.kext?

Only during the initial setup phase before you’ve mapped your ports. UTBDefault.kext enables all USB ports so you can use them while running the USBToolBox mapping tool. Once mapping is complete, remove it and replace it with your custom UTBMap.kext.

USBToolBox kext vs USBInjectAll?

USBInjectAll hardcodes port maps for specific Intel controllers. The USBToolBox kext doesn’t hardcode any maps — it works with your custom map generated by the USBToolBox tool. It also provides features like ACPI port removal and Apple map overrides that USBInjectAll doesn’t have.

Can I use this without the USBToolBox tool?

Technically yes, if you create a compatible USB map manually. However, the USBToolBox tool is the recommended way to generate maps.

Related Kexts

• USBToolBox - USB mapping tool for creating custom maps
• USBInjectAll - Legacy USB port injection (Intel only)

Resources

• GitHub Repository
• Download Latest Release
• USB Mapping Guide