USBDriverKit extension to fix USB Passthrough for SCSI/UAS devices
- Dominant language
- Swift
- Stars
- 35.5k
- Forks
- 1.8k
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 7
Description
Hello
Many modern external USB storage devices (especially SSDs using NVMe-to-USB bridges and UAS protocol) fail to pass through to the VM on macOS hosts. As far as I know QEMU currently relies on libusb, which on macOS often cannot obtain exclusive access, resulting in errors or the device not appearing in the VM. This affects a vast number of USB 3.0+ devices released in recent years that rely on SCSI/UAS protocols.
I propose implementing a System Extension based on USBDriverKit to handle USB arbitration. This extension could act as a "dummy" or bridge driver that claims priority over the default macOS drivers (like IOUSBMassStorageDriver) for specific Vendor/Product IDs selected by the user. By claiming the device at the DriverKit level, it would prevent the macOS kernel from mounting the drive, leaving the device "raw" and accessible for QEMU to pass through directly to the guest VM.
Currently, the only workarounds I've read about seem to be:
- Using USB 2.0 hubs to force the slower BOT protocol (bypassing UAS), which severely bottlenecks modern SSDs.
- Passing the raw block device (/dev/diskX) instead of the USB controller, which loses device-specific USB features (like firmware updating tools inside the VM)
I'm not really sure any of these actually work, but the reason why I'm proposing this feature is because my own external ssd doesn't really work on UTM, yet it works like a charm through Parallels.
Regarding the Entitlements concern: I understand that developing a driver requires the com.apple.developer.driverkit.transport.usb entitlement from Apple. However, since the signature validates the binary integrity rather than just the code logic, UTM (as a legitimate and widely used virtualization tool) could ideally apply for and obtain this entitlement for the official releases. This would allow the distribution of a signed "UTM USB Driver" component for modern devices which need advanced passthrough capabilities sometimes even just to mount.
Contributor guide
Assessment
This issue has not been assessed yet.