usbtoolbox / kext

Kext

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 (property utb-off): Disable USBToolBox completely

• -utbacpioff (property utb-acpi-off): Disable RHUB removal from ACPI plane (borked ACPI removal)

• -utbappleoff (property utb-apple-off): Disable existing ports and port-count removal

• -utbmapoff (property utb-map-off): Disable custom map (useful for testing)

• utbwait=XXX (property utb-wait, type number): Custom delay for waitForMatchingService, in seconds. Integer between 1-180, inclusive.

Converting Existing Maps

Converting existing maps is fairly easy.

• For each IOKit personality, change the following:
  • CFBundleIdentifier to com.dhinakg.USBToolBox.kext
  • IOClass to USBToolBox
  • IOMatchCategory to USBToolBox
• Add a dictionary named OSBundleLibraries to the root item. It should contain com.dhinakg.USBToolBox.kext, with value 1.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:

1. Add USBToolBox.kext and UTBDefault.kext to your EFI/OC/Kexts folder, and make sure to update your config.plist.
2. Install macOS.
3. Map your ports with the USBToolBox tool.
4. Remove UTBDefault.kext and add your newly created UTBMap.kext (or whatever your USB map is called) to EFI/OC/Kexts.
5. 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

kext's Issues

USBtoolBox XHC0 waitForMatchingService failed or timed out

AMD laptop: Ryzen 7 5800h
Os: Monterey
I dont have this issues with USBMap mapping

help, I'm stuck on bug: USBToolBox: XHC: waitForMatchingService failed or timed out

Pare down controller finding methods

Should explore whether we can just use one method, instead of three.

USBToolBox: XHCI: waitforMatchingService failed or timed out

Hi,
What does this error exactly mean? Is it a timeout looking for a controller?

Bluetooth dongle

Hi, I'm not a developer so I don't know if it's related but since I started using this kext instead of usbinjectall, my external bluetooth dongle doesn't work anymore. I read that is because it's not seen as internal anymore, is it possible to do something about it? Thanks

Stuck on forcing cs_runtime for entitlement

Hi,
I am trying to install macOS 12, but every time I try to boot setup with usbtoolbox kext its stuck on "forcing cs_runtime for entitlement".
Of course, i tried without this kext it runs fine, except I have some issues with the USB.

Dell Haswell desktop

uia_exclude

Hiya,

Is it possible to use uia_exclude or add this as a feature? In some cases being able to temporarily disable a port, and/or not having to remake the USB map really helps.

In the Configuration part of Readme I only find how to turn off the map itself, but not a specific port.

Hope it could be(come) a thing :)

Cheers

Is Ventura supported by USBToolBox? Any known issues?

I have not upgraded yet, but I received the following comment in my USBToolBox guide thread:

USBtoolbox creating timeout issues in Ventura. Kexts needs an update from the developers.

Can you confirm this issue?

I would just like to make sure that USBToolBox still works before upgrading to Ventura

`OSDictionary::iterateObjects` does not exist on 10.13.6 and lower

After mapping from Windows, and including the UTBmap and USBToolbox in the EFI, I reboot and the ports that weren't working before RHUB fix aren't working again.

Just in case specs are:
B350M Mortar Arctic
Ryzen 5 1600
OpenCore 0.6.8
Mac OS X 10.13.6 High Sierra
Kext and USBTool are made with the latest release available

Also, mapping doesn't seem to be working at all.

stuck on boot, it shows "USBToolBox: XHC: waitForMatchingService failed or timed out "

Update USBToolBox Kext for Ventura.

Catalina booting is alright. Up to Monterey is okay. But, booting Ventura with UTB is creating timeout issues. Developers, please upgrade and update this kext(Driver) as soon/early as possible.

USBToolBox.kext not loading (Mojave) - "library kext com.apple.kpi.bsd not compatible with requested version 19.0.0"

Obviously, it links something from kernel 19, ie Catalina? I am on Mojave FIY.

Kext com.dhinakg.USBToolBox.kext - library kext com.apple.kpi.bsd not compatible with requested version 19.0.0.
localhost kernel[0]: Can't load kext com.dhinakg.USBToolBox.kext - failed to resolve library dependencies.
localhost kernel[0]: Kext com.dhinakg.USBToolBox.kext failed to load (0xdc00800e).
localhost kernel[0]: Failed to load kext com.dhinakg.USBToolBox.kext (error 0xdc00800e).
localhost kernel[0]: Couldn't alloc class "USBToolBox"