IOKit, driver execution, and libkern

Guide index · Architecture

IOKit connects discoverable devices and software services to drivers, gives those drivers execution and memory-transfer facilities, and exposes selected operations to user processes. libkern supplies the object runtime beneath this machinery. The central relationship is a provider and its clients: a provider describes a resource; clients attach to it, negotiate access, publish further services, and eventually detach. A storage controller can therefore participate in several layers without the generic IOKit code knowing the disk format or hardware command set. See IOService and IORegistryEntry.

This checkout contains the generic runtime, selected platform classes, DriverKit interfaces, and kernel-side DriverKit transport. It does not contain every driver family or device implementation shipped with an operating system. Follow an implemented virtual call to its concrete subclass before attributing device behavior to this repository.

The components and their connections

Mermaid source

flowchart TD
    R[IORegistryEntry: properties and plane links] --> S[IOService: provider/client lifecycle]
    C[IOCatalogue: driver personalities] --> S
    K[OSKext and OSMetaClass: loaded classes] --> S
    S --> W[IOWorkLoop and event sources]
    S --> P[IOServicePM and root power domain]
    S --> U[IOUserClient: process connection]
    U <--> IPC[Mach ports and messages]
    IPC <--> D[IOUserServer: DriverKit RPC]
    S --> M[IOMemoryDescriptor and IODMACommand]
    M <--> VM[VM maps, UPLs, device pager]
    M --> I[IOMapper and device-specific DMA]
    O[OSObject and libkern collections] --> R
    O --> K

The arrows show ownership or call relationships, not a boot sequence. Three graphs coexist: registry planes describe relationships, the C++ superclass chain describes implementation inheritance, and OSKext dependency lists describe executable dependencies. A service's provider is not necessarily its C++ superclass. The power plane can also differ from the service plane; joinPMtree delegates placement to the platform expert.

Reading routes

1. Start with bootstrap and BSD integration for framework initialization, device-tree import, platform matching and root-device discovery.
2. Read libkern and kext runtime, then object runtime and collections, for allocation, reference counts, metaclasses, casts and container ownership. Follow symbol interning for shared key identity, no-copy backing and delayed destruction.
3. Read registry and service lifecycle, then registry planes and properties, matching and termination, and notifications and arbitration. These connect object discovery to concurrent driver attachment, callbacks and removal.
4. Read workloops and power, callback protocols, and interrupt routing and command queues to follow execution context, wakeups, command ownership and handler teardown.
5. Read user clients and DriverKit, connection lifetime, DriverKit dispatch and actions, and shared queues and notifications for process-facing calls and asynchronous results.
6. Read memory and DMA, descriptors and CPU mappings, and DMA preparation and mapping. CPU virtual, physical and device-visible addresses have different owners and lifetimes.
7. Read power assertions and idle policy for the decisions that permit or defer sleep. Follow device power transitions into system sleep and wake, then hibernation creation and restore.
8. Read reporting and performance control for report channels, state residency, sample consistency and device-work attribution.
9. Follow kernel collections and OSKext loading, serialization and property transport, and NVRAM variables and persistence for executable dependencies, module start/unload, parser ownership, receiver policy, and V3/CHRP bank updates.

The focused implementation chapters extend those introductions:

External-method call lifecycle follows a concrete local user client from opening through selector admission, current-caller checks, scalar/structure buffers, dispatch, output and close. It distinguishes the opener, connection object, current caller and memory owner, then connects the common bridge to DriverKit asynchronous completion.

The queue chapter now compares classic, circular and DriverKit cursor/publication protocols, including reset, overwrite and callback limits. The matching and notification chapters follow catalogue-triggered rescans, deferred work, category replacement and callback selection/removal through concrete event orders. For operations that cross beyond IOKit, follow the user-buffer DMA walkthrough and the Skywalk task-mapping/channel walkthrough; both distinguish memory visibility, consumer progress and final resource release.

For surrounding machinery, use Mach IPC, kernel execution and locking, VM, and VFS/storage. Platform code owns processor startup and the low-level sleep boundary; security explains the authorization mechanisms called from IOKit.

Sources inspected and limits

“Deep” means selected function bodies, state definitions, and adjacent cleanup/error paths were read together. It does not mean every line of a large source file was reviewed. “Survey” means declarations, selected boundaries, or build/source inventories were checked.

The upstream startup guide, hibernation guide, and allocator guide provide useful context. Configuration guards such as CONFIG_KXLD, CONFIG_MACF, NO_KEXTD, HIBERNATION, XNU_TARGET_OS_*, and development/debug options select materially different paths. These pages describe source behavior; they do not infer which configuration a particular machine runs.