Awesome
USBToolBoxᵇᵉᵗᵃ
Making USB mapping simple(r)
The USBToolBox kext is a kext intended to make common actions for USB mapping easier. It supports El Capitan and up, although only Catalina and up have been tested.
Features
- Attach to the controller instance or parent device, allowing for more ways to match
- 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 not require model identifier specified in USB map (if attaching to PCI device)
- Very compatible with existing USB maps (port format is the same)
- Does not hardcode any port maps, unlike USBInjectAll
This does not patch the port limit.
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.
Properties can be any type and only existence, not type, is checked, unless otherwise specified.
-
-utboff
(propertyutb-off
): Disable USBToolBox completely -
-utbacpioff
(propertyutb-acpi-off
): Disable RHUB removal from ACPI plane (borked ACPI removal) -
-utbappleoff
(propertyutb-apple-off
): Disable existingports
andport-count
removal -
-utbmapoff
(propertyutb-map-off
): Disable custom map (useful for testing) -
utbwait=XXX
(propertyutb-wait
, type number): Custom delay forwaitForMatchingService
, in seconds. Integer between 1-180, inclusive.
Converting Existing Maps
Converting existing maps is fairly easy.
- For each IOKit personality, change the following:
CFBundleIdentifier
tocom.dhinakg.USBToolBox.kext
IOClass
toUSBToolBox
IOMatchCategory
toUSBToolBox
- Add a dictionary named
OSBundleLibraries
to the root item. It should containcom.dhinakg.USBToolBox.kext
, with value1.0.0
.
Usage
You can get the latest release from the GitHub releases tab.
The zip contains 2 kexts: the main USBToolBox.kext
, and UTBDefault.kext
, a codeless kext used for attaching USBToolBox to all PCIe USB controllers. This is designed for use before you map, so that you can have all USB ports working (assuming no port limit) before you map. However, it is not needed and must be removed if you choose to map from the start (ie. from Windows, using the USBToolBox tool).
A basic fresh install flow would be as follows:
- Add
USBToolBox.kext
andUTBDefault.kext
to yourEFI/OC/Kexts
folder, and make sure to update yourconfig.plist
. - Install macOS.
- Map your ports with the USBToolBox tool.
- Remove
UTBDefault.kext
and add your newly createdUTBMap.kext
(or whatever your USB map is called) toEFI/OC/Kexts
. - Reboot and you should have a USB mapped system!
Credits
@RehabMan for USBInjectAll, an inspiration for this project
@acidanthera for MacKernelSDK
My testing team (you know who you are) for testing