Match your DriverKit drivers with the right USB device
March 15, 2021
Software drivers help your system communicate with hardware peripherals like mice, keyboards, headphones, and more. When matching your DriverKit driver to a USB device, there are a few different ways to go about it, and determining the right match type can be difficult. To help you find your perfect match a bit more quickly, we’ve put together a quick start guide for matching your driver to the right USB devices.
Learn more about the USB Common Class Specification
Learn more about USB device architecture
Explore the I/O Registry
The I/O Registry is the quickest way to find the correct plist keys for the physical devices you want to support in your driver. Apple provides an app called I/O Registry Explorer that you can download as part of the “Additional Tools for Xcode” package. You can also access the I/O registry through Terminal using the ioreg command.
Download I/O Registry Explorer
The I/O Registry provides information about a device, interfaces you can hook into, as well as all the possible keys you can use to match. You can use this command within Terminal to query the Registry and get all of the information you need:
// -b bolds the object name, nice to have
// -n lets us specify the name of the device we are trying to match
// -r shows us all of the sub-interfaces advertised under our device
// -l shows us all of the details for those sub-interfaces
ioreg -b -n "My Device Name" -r -lIf you don’t already know the name of the device you’d like to support, connect it to your computer and go to the Apple menu in the menu bar and select Apple > About this Mac > System Report. Once the report is open, go to the USB section.
Some devices may display multiple root entries: one with the class AppleUSBDevice, and the other with the class IOUSBHostDevice. For the purposes of creating your driver, you’ll need the information present under IOUSBHostDevice. Make a note of the entries under the classes IOUSBHostInterface and IOHIDInterface, as you’ll need that information a bit later on.
Learn more about the I/O Registry
How to identify and match with HID devices
When matching devices to your driver, you can match them on USB properties or, if your device is HID-compliant, through HID matching keys. HID properties provide more generic access and can allow your driver to support more devices with less work. For example, you could write a driver so generic that supports all HID-compliant mice, or so specific that it supports only a single mouse. Matching to USB properties, in contrast, would require you to provide specific information for each existing mouse you want to support.
You can find out whether the device you wish to support is HID-compliant by checking the I/O Registry. If a device supports HID, it will display the IOHIDInterface class, along with a variety of keys and values you can use to match to your driver. These can include items like VendorID, ProductID, PrimaryUsagePage, and PrimaryUsage. The vendor and product IDs are keys that specifically identify a device, whereas the primary usage page and usage keys are generic identifiers for types of devices.
Using the example mentioned earlier, if you wanted to create a driver that supports all HID-compliant mice connected to your computer, you might match any devices that have a PrimaryUsagePage of 1 (generic desktop) and a PrimaryUsage of 2 (mouse). If your wanted to match to a specific mouse, however, you might want to match solely on its VendorID and ProductID combination.
Note: While the USBDriverKit framework requires you request access to a specific VendorID in order to match with it, this is only needed for non-HID devices. You are free to match on any vendor ID when connecting to a HID device.
How to match with non-HID USB devices
If you’re building a driver for a non-HID USB device, you’ll instead need to match to the IOUSBHostDevice and IOUSBHostInterfaces classes.
For IOUSBHostDevices, you must follow a specific matching scheme and provide one of the exact combination of keys listed — otherwise the match won’t occur and your driver won’t function. Matches are listed in descending priority, so a driver with vendor and product ID combination will have higher priority to match a device than one than one that matches based on device class and subclass.
Learn more tips for matching USB drivers with macOS
Remember that if you plan to use a vendor ID to match on a non-HID USB device, you will need to specify access to that vendor ID when requesting DriverKit entitlements from Apple.