What options can be passed to IOService::Terminate in DriverKit

Question

virtual kern_return_t IOService::Terminate(uint64_t options) says you can pass a parameter with options. I wonder what the different options are? The documentation does not say anything.

Answer 1

The IOService.iig file from the XNU source code bundle (7195.50.7.100.1, macOS 11.0.1) contains the following:

    /*!
     * @brief       Start an IOService termination.
     * @discussion  An IOService object created with Create() may be removed by calling Terminate().
     *              The termination is asynchronous and will later call Stop() on the service.
     * @param       options No options are currently defined, pass zero.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
    virtual kern_return_t
    Terminate(
        uint64_t             options);

options No options are currently defined, pass zero.

On the kernel side, IOService::terminate does have a few valid options. I do not know if you can pass these through from DriverKit, however. They might be filtered:

• kIOServiceSynchronous:

kIOServiceSynchronous may be passed to cause terminate to not return until the service is finalized.

• kIOServiceRequired:

By default, if any client has the service open, terminate fails. If the kIOServiceRequired flag is passed however, terminate will be successful though further progress in the destruction of the IOService object will not proceed until the last client has closed it.

• kIOServiceTerminateWithRematch: I'm not quite clear on this one, it's not documented, but a cursory reading of the relevant code suggests that when an object is terminated this way, its provider will re-trigger I/O Kit matching.

There are a few more such as kIOServiceRecursing which are used internally when forwarding from terminate() itself to the various termination phase functions to keep track of termination status. These should normally not be used from kext code, and I very much doubt that they will be passed through if you use them from DriverKit.