Driverkit driver hangs on macOS

Hello,

I have crated a DriverKit driver for macOS and iPad M-series if I ever get the mac driver working. I have the correct entittlements, and matching provisioning profile downloaded manually. The driver loads (no errors!), and is visible in ioreg below the usb device (when plugged).

The issue is that I never get any log from the driver, have reduced to minimal working code (below). When I debug with lldb, I load the symbols for my driver and break on init and Start - but lldb never triggers == never calls start or init. This is also why no logs. When I unplug the device, the driver process (ps aux) keeps running, causes a hard crash of the Mac with dext remove/or kill driver.dext process.

I have asked Claude - but its just running in circles: check Info.plist=ok, check entitlements=ok, check code (minimal)=ok, check iig=ok, check provisioning profile=ok, check build settings=ok, check ioreg=ok, check code signature=ok, start over

I don't get any log from my driver, which is consistent with init() not being called. All logs from kernel & friends (AMFI) do show the driver loading - no errors.

Any tips appreciated!

//  USBDriver.iig
#ifndef USBDriver_h
#define USBDriver_h
#include <USBDriverKit/IOUSBHostInterface.iig>

class USBDriver: public IOService
{
public:
    virtual bool init() override;
    virtual void free() override;
    virtual kern_return_t Start(IOService * provider) override;
    virtual kern_return_t Stop(IOService * provider) override;
};
// USBDriver.cpp
#include <os/log.h>
#include <DriverKit/DriverKit.h>
#include "USBDriver.h"

bool USBDriver::init()
{
    if (!super::init()) return false;
    os_log(OS_LOG_DEFAULT, "terminal.driver: init()");
    return true;
}
 
kern_return_t IMPL(USBDriver, Start) {
    os_log(OS_LOG_DEFAULT, "terminal.driver: Start()");
    
    kern_return_t ret = super::Start(provider);
    if (ret != kIOReturnSuccess) {
        os_log(OS_LOG_DEFAULT, "terminal.driver: super::Start failed: 0x%08x", ret);
        return ret;
    }
    os_log(OS_LOG_DEFAULT, "terminal.driver: Start() success");
    return super::Start(provider);
}

kern_return_t IMPL(USBDriver, Stop) {
    os_log(OS_LOG_DEFAULT, "terminal.driver: Stop()");
    return super::Stop(provider);
}

void USBDriver::free() {
    os_log(OS_LOG_DEFAULT, "terminal.driver: free()");
    super::free();
}

This is with: macOS 26.4.1, Xcode 26.3, MacStudio-M1

There is the message after the crash/reboot "Your computer restarted because of a problem" - but the stack trace is beingn - not my driver, nor the kernel/dextloder, there is no log in Console, no crash report in Console.

I have asked Claude - but it’s just running in circles: check Info.plist=ok, check entitlements=ok, check code (minimal)=ok, check iig=ok, check provisioning profile=ok, check build settings=ok, check ioreg=ok, check code signature=ok, start over

Fair warning, I wouldn't expect AI to be all that helpful when working with DriverKit. As far as I can tell, it works well enough that it will get something to build, but small details are what tend to go wrong and that's exactly what these AI systems tend to miss.

When I unplug the device, the driver process (ps aux) keeps running, causing a hard crash of the Mac with dext remove/or kill driver.dext process.

Please file a bug on this and post the bug number back here. I'm sure the problem is your driver (more on that below), but we also shouldn't be panicking. In the bug, please include the following:

  1. A copy of the panic log.
  2. A copy of your DEXT project and your built and signed DEXT.
  3. Two IORegistryExplorer snapshots, one taken after your device was attached and the driver loaded, the other after the device was removed.

Expanding on that last point, IORegistryExplorer.app is the GUI equivalent of ioreg and is, in my experience, a FAR better tool for understanding the system. See this forum post for download instructions as well as some general suggestions.

Bonus Tip: If you find IORegistryExplorer to be somewhat slow and/or "glitchy", go into its settings and disable auto updates.

Any tips appreciated!

So, my guess is that the problem here is with your IOKitPersonalities in your Info.plist. I have a post that goes through the load process here, but my guess is that your IOUserClass key has the wrong value. That would let the system create your process (using IOUserServerName) but it wouldn't be able to create your actual DEXT class. That would then explain this:

When I debug with lldb, I load the symbols for my driver and break on init and Start - but lldb never triggers == never calls start or init. This is also why no logs.

...since your code did not in fact ever run.

I think it would also explain this:

When I unplug the device, the driver process (ps aux) keeps running, causing a hard crash of the Mac with dext remove/or kill driver.dext process.

I'd need to see the registry state to confirm, but I think IOUserService ends up blocked in IOKit-start() if your DEXT doesn't complete "Start()". I'm not sure what the ultimate cause would be, but I'm not surprised that could then cause a panic.

In any case, that's my first guess based on the information at hand. Let me know what you find and if you're still having problems, I'll take a look at the files you uploaded to the bug and see if I can determine what the problem is.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Driverkit driver hangs on macOS
 
 
Q