Kernel-Mode Driver Framework
The Kernel-Mode Driver Framework (KMDF) is a Microsoft-developed software framework designed to simplify the creation and maintenance of kernel-mode device drivers for Windows operating systems, acting as an abstraction layer that automates common tasks such as Plug and Play (PnP) device enumeration, power management, and input/output (I/O) request handling.[1] By encapsulating boilerplate code typically required in lower-level driver models, KMDF enables developers to concentrate on device-specific logic while ensuring compatibility with Windows' kernel architecture.[2] Released in 2005 with version 1.0 as a downloadable component for Windows XP and subsequent releases, KMDF has been progressively integrated into Windows versions starting with 1.5 in Windows Vista (2007), evolving through updates like 1.9 for Windows 7 (2009) and reaching version 1.33 in Windows 11 (2021) and Windows Server 2022.[3] The source code for KMDF has been publicly available on GitHub since 2015.[4] This framework forms the kernel-mode component of the broader Windows Driver Frameworks (WDF), which also encompasses the User-Mode Driver Framework (UMDF) for less privileged, user-mode drivers that offer enhanced stability by isolating potential crashes from the kernel.[1] Unlike the foundational Windows Driver Model (WDM), which requires manual implementation of complex kernel interactions, KMDF provides a higher-level C-language interface with built-in support for features like direct memory access (DMA), interrupt handling, and multi-component power states, reducing development time and error proneness.[5][2] KMDF is recommended for most new kernel-mode drivers, particularly function and filter drivers that require direct hardware access or PnP/power awareness, as it supports a wide range of devices including USB, PCI, and software-only drivers across Windows 10, 11, and Server editions.[1][2] Key advantages include automatic resource management, simplified debugging through framework callbacks, and backward compatibility via versioned redistributables in the Windows Driver Kit (WDK), allowing drivers to target older systems without full recompilation.[3] While UMDF is preferred for simpler devices to minimize kernel risks, KMDF remains essential for performance-critical scenarios where user-mode limitations, such as restricted kernel data access, are prohibitive.[2]Overview
Definition and Purpose
The Kernel-Mode Driver Framework (KMDF) is a software development kit (SDK) and runtime environment developed by Microsoft to facilitate the creation of reliable kernel-mode device drivers for Windows operating systems with minimal code.[1][6] It forms part of the broader Windows Driver Frameworks (WDF) and provides an abstraction layer that encapsulates low-level kernel operations, automatically managing routine tasks such as input/output (I/O) request processing, power management, and synchronization mechanisms.[1][7] This design enables developers to concentrate on implementing device-specific functionality rather than handling intricate kernel interactions, thereby reducing development complexity and potential errors.[1][3] KMDF was introduced in the mid-2000s to address longstanding challenges in driver reliability, particularly following widespread system instability and crashes attributed to faulty third-party drivers in early 2000s Windows versions like Windows XP.[3][7] By promoting a structured, object-oriented approach to driver design, it aimed to enhance overall system stability and decrease the incidence of blue screen errors caused by driver bugs.[7] This framework builds upon the foundational Windows Driver Model (WDM) while offering higher-level APIs to mitigate common pitfalls in kernel-mode programming.[1] Development with KMDF is supported in the C and C++ programming languages through its device driver interface (DDI).[6][8] The framework itself is licensed under the MIT License, making its source code and samples openly available for use in driver projects.[4]Supported Platforms and Versions
The Kernel-Mode Driver Framework (KMDF) was initially released in version 1.0 in December 2005 as a download-only package, providing basic functionality for developing kernel-mode drivers and supporting Windows XP and later operating systems, including Windows Server 2003.[9][3] Version 1.1, also download-only, extended compatibility to Windows 2000 and later in 2006, enabling broader adoption on legacy systems while maintaining support for XP and newer.[3] As of November 2025, KMDF supports Windows Vista through Windows 11 (all editions) and Windows Server 2008 through Windows Server 2022, with compatibility depending on the framework version used during driver development. The latest version, 1.33, released in November 2021 with the Windows 11 version 21H2 Windows Driver Kit (WDK), is included natively in Windows 11 (versions 21H2 and later) and Windows Server 2022, focusing on newer platforms while allowing deployment on supported older systems via redistributable updates.[3][1] No major KMDF version updates have occurred since 1.33, though it remains integrated into the latest WDK version 10.0.26100 (released in 2024) for building and testing drivers targeting these platforms.[3][10] Key version milestones highlight the framework's evolution in compatibility and capabilities:| Version | Release Year | Key Features and Changes | Supported Platforms |
|---|---|---|---|
| 1.0 | 2005 | Initial release providing core abstractions for kernel-mode drivers | Windows XP and later |
| 1.5 | 2007 | Initial release with Windows Vista WDK; drivers run on Windows 2000 and later | Windows 2000 and later |
| 1.11 | 2012 | Released with Windows 8 WDK; enhanced support for USB I/O targets and related device handling | Windows Vista and later |
| 1.33 | 2021 | Includes security enhancements, performance optimizations, and power management improvements (e.g., refined idle-stop behavior and framework settings) | Windows 11 version 21H2 and later; Windows Server 2022 and later |
History
Initial Development
The Kernel-Mode Driver Framework (KMDF) originated as part of Microsoft's Windows Driver Frameworks (WDF) initiative, announced in 2004 to tackle the prevalent issue of system instability caused by faulty drivers. During the Windows XP era, device drivers were responsible for the majority of kernel-level crashes, with analysis of over 2,500 incidents revealing that drivers from just seven major organizations accounted for 75% of failures.[13] This high failure rate underscored the need for a more robust development model to minimize errors from poorly implemented code, particularly in areas like power management and plug-and-play operations that frequently triggered blue screen events. Key motivations for KMDF's creation centered on enforcing driver development best practices while significantly reducing the boilerplate code developers had to write manually under the existing Windows Driver Model (WDM). WDM required explicit handling of low-level details such as interrupt request levels (IRQLs) and resource management, which often led to subtle bugs due to the complexity of maintaining correct synchronization and memory allocation across varying hardware configurations.[1] By abstracting these elements into a higher-level framework, KMDF aimed to improve reliability and accelerate development for hardware vendors, allowing focus on device-specific logic rather than common infrastructure. Design influences for KMDF drew directly from WDM's shortcomings, incorporating object-oriented abstractions and callback mechanisms to automate routine tasks like IRQL transitions and resource cleanup, thereby preventing common pitfalls observed in field crashes. Microsoft collaborated closely with hardware vendors during the pre-launch phase, incorporating feedback through internal testing and vendor beta programs to refine the framework's compatibility with diverse peripherals.[14] A preview version was distributed at the WinHEC conference in May 2004 via a prerelease CD, enabling early adoption and iteration based on real-world input. The beta release followed later that year, with general availability in December 2005 as a downloadable component for Windows XP and later, marking KMDF's debut for enhancing driver stability on existing platforms.[3]Version History
The Kernel-Mode Driver Framework (KMDF) versions are closely tied to releases of the Windows Driver Kit (WDK), enabling developers to target specific Windows operating system versions while incorporating enhancements for stability, compatibility, and performance.[3] Each major version introduces support for new OS features or refines existing ones, with backward compatibility maintained through dynamic linking to the appropriate runtime library.[11] Since its inception, KMDF has undergone iterative updates, with the core library evolving to address driver development challenges in kernel-mode environments. The following table summarizes the major KMDF versions, their release contexts, supported operating systems, and key changes:| Version | Release Context | Supported OS | Key Changes |
|---|---|---|---|
| 1.0 | December 2005 (initial download release) | Windows XP and later | Introduced core I/O request handling, power management abstractions, and Plug and Play support to simplify kernel-mode driver development over WDM.[3][9] |
| 1.1 | May 2006 (download release) | Windows 2000 and later | Added compatibility for Windows 2000, expanding accessibility for legacy systems while retaining XP+ support.[3][15] |
| 1.5 | Windows Vista WDK (2006) | Windows 2000 and later | Integrated native support in Windows Vista, with refinements to power and I/O handling for improved reliability.[3] |
| 1.7 | Windows Server 2008 WDK (2008) | Windows 2000 and later (full on Vista SP1/Server 2008) | Enhanced stability for server environments and partial networking scenarios.[3] |
| 1.9 | Windows 7 WDK (2009) | Windows XP and later | Improved error diagnosis, recovery mechanisms, and verifier integration to reduce debugging complexity and driver crashes.[3][16] |
| 1.11 | Windows 8 WDK (2012) | Windows Vista and later | Added support for Windows 8 features, including better integration with modern hardware interfaces.[3] |
| 1.13 | Windows 8.1 WDK (2013) | Windows 8.1 and later | Optimized for touch and sensor drivers in Windows 8.1.[3] |
| 1.15 | Windows 10 WDK (2015) | Windows 10 version 1507 and later; Windows Server 2016 | Enabled universal driver support for Windows 10, with enhancements for networking and storage device handling.[3][17] |
| 1.31 | Windows 10 version 2004 WDK (2020) | Windows 10 version 2004 and later | Provided foundational support for Windows 10 May 2020 Update features, including improved device interface states.[3][18] |
| 1.33 | Windows 11 version 21H2 WDK (2021) | Windows 11 version 21H2 and later; Windows Server 2022 | Enhanced power framework settings (e.g., new members in WDF_POWER_FRAMEWORK_SETTINGS) and WdfDeviceStopIdle behavior for better idle management; included ARM64 optimizations and security mitigations for modern hardware.[3][1] |
Architecture
Core Components
The Kernel-Mode Driver Framework (KMDF) employs an object-based model to represent kernel entities such as devices, queues, and requests, providing a hierarchical structure where objects are created as children of parent objects, such as a queue under a device.[19] These objects are opaque handles, with primary examples including WDFDEVICE for device representation and WDFQUEUE for I/O queue management, allowing drivers to interact with the framework without direct calls to underlying kernel APIs.[20] The framework handles automatic lifetime management through reference counting, incrementing counts on object creation or reference and decrementing them upon release, ensuring resources are freed only when no longer in use to prevent leaks or premature deletion.[19] Central to I/O processing in KMDF are I/O request queues, which abstract the Windows Driver Model's (WDM) Interrupt Request Packet (IRP) handling by routing incoming requests to driver-defined queues.[19] Each device typically has a default queue created during device initialization, which can be configured for sequential or parallel dispatching; sequential queues process one request at a time, delivering the next only after the current one is completed or canceled, while parallel queues allow multiple requests to be dispatched concurrently for asynchronous handling.[21] Drivers create additional parallel or manual queues as needed using WdfIoQueueCreate, specifying dispatch modes and request types to optimize for device characteristics, such as overlapping operations in storage controllers.[21] KMDF operates in an event-driven manner through callbacks, which are driver-supplied functions registered for specific events, invoked by the framework at appropriate Interrupt Request Levels (IRQLs) to ensure thread safety and system stability.[19] For instance, the EvtDriverDeviceAdd callback is called at PASSIVE_LEVEL when a device is enumerated, allowing the driver to create and configure a WDFDEVICE object.[22] Other callbacks, such as those for I/O queue events like EvtIoRead, may execute at DISPATCH_LEVEL or lower, with the framework enforcing IRQL constraints via rules like KmdfIrql to verify compliance during development.[23][24]Key Abstractions and APIs
The Kernel-Mode Driver Framework (KMDF) offers a suite of high-level APIs and abstractions designed to shield developers from the intricacies of kernel programming, such as manual resource management and synchronization, while promoting an object-oriented, event-driven programming model. These abstractions encapsulate common driver tasks, enabling developers to focus on device-specific logic rather than boilerplate code for Windows kernel interactions. The framework's APIs are part of the Windows Driver Frameworks (WDF) library, which is dynamically loaded via wdfldr.sys, providing a robust set of functions to support driver lifecycle management, I/O processing, and system integration.[1][25] Key API categories in KMDF include those for device object creation, I/O handling, and memory management. For device creation,WdfDeviceCreate is used to instantiate a framework device object, which automatically handles Plug and Play notifications and power state transitions, replacing the manual IoCreateDevice calls required in traditional WDM drivers. I/O operations are managed through APIs like WdfIoQueueCreate for setting up request queues and WdfRequestComplete for finalizing requests with status and information, allowing drivers to process incoming I/O requests via registered callbacks rather than dispatch routines. Memory management is simplified with WdfMemoryCreate, which allocates contiguous buffers and associates them with framework objects, ensuring proper cleanup and integration with DMA operations when needed. These APIs collectively reduce development time by abstracting low-level kernel structures like IRPs and device objects into higher-level, reference-counted handles.[26][27]
KMDF's core abstractions emphasize automatic handling of synchronization and an event-driven paradigm to enhance reliability and performance. The framework provides built-in synchronization for callbacks using internal locks at the device or queue level, eliminating the need for developers to manually implement mutexes or spinlocks in most scenarios and preventing common concurrency issues like deadlocks. This automatic synchronization ensures that only one event callback executes at a time for a given scope, supporting both passive-level (non-DPC) and arbitrary-level operations. In the event-driven model, drivers register callback functions—such as EvtDriverDeviceAdd for device enumeration or EvtIoRead for read requests—instead of polling system state, which aligns with modern asynchronous programming patterns and reduces CPU overhead. Additionally, KMDF supports design patterns like passive-level callbacks for non-time-critical tasks, executed at PASSIVE_LEVEL IRQL to allow preemption and paging, and cancellable I/O through APIs such as WdfRequestMarkCancelable, enabling safe request cancellation during power transitions or user aborts without risking system instability. These features promote testability by allowing isolated unit testing of callbacks with mocked framework objects.[28][29][30][31]
KMDF's abstractions bear similarities to those in the User-Mode Driver Framework (UMDF), but they are tailored for kernel-mode execution with direct hardware access.[1]
Features
Power Management
The Kernel-Mode Driver Framework (KMDF) provides robust support for managing device power states, enabling drivers to handle transitions efficiently while conserving energy. Devices in KMDF operate in device power states D0 through D3, where D0 represents the fully operational working state and D1–D3 denote progressively lower-power states with reduced functionality. The framework acts as the power policy owner by default for function drivers, automatically managing transitions between these Dx states in response to system demands, thereby simplifying driver development compared to manual IRP handling.[32][33] KMDF facilitates Dx state transitions through event callbacks that drivers can implement for device-specific operations. For instance, theEvtDeviceD0Entry callback is invoked when the device enters D0, allowing drivers to perform tasks such as loading firmware or initializing hardware components. Conversely, EvtDeviceD0Exit is called prior to transitioning to a low-power state, enabling cleanup like saving context or shutting down peripherals. These callbacks are registered via WdfDeviceInitSetPnpPowerEventCallbacks during device initialization, ensuring the framework orchestrates the state machine while the driver focuses on hardware-specific logic.[34][32]
For idle handling, KMDF includes automatic detection mechanisms to power down devices when inactive, promoting energy efficiency in the system's working (S0) state. A device is deemed idle when no pending requests exist in power-managed I/O queues, no active WdfDeviceStopIdle calls are in effect, and—for bus drivers—no child devices require D0 power. The framework then initiates a transition to a low-power Dx state after a configurable idle timeout, set via WdfDeviceAssignS0IdleSettings in the driver's EvtDriverDeviceAdd callback, which specifies the target state (e.g., D3), timeout duration, and wake capabilities. Drivers can customize policies by calling WdfDeviceStopIdle to prevent power-down during critical operations and WdfDeviceResumeIdle to restart the idle timer, allowing fine-tuned control over power behavior without direct ACPI interaction.[35][36]
KMDF integrates with ACPI-defined system power states (S-states) to manage sleep transitions and selective suspend, particularly for power-sensitive devices like USB peripherals. In S0, selective suspend enables individual devices to enter low-power Dx states while the system remains active, with KMDF handling resume on wake signals or new I/O. For S1–S4 sleep states, the framework supports remote wake capabilities configured through WdfDeviceAssignSxWakeSettings, allowing devices to signal the system for resumption; USB bus drivers mediate hardware wake preparation in these scenarios. This integration ensures orderly power coordination, such as pausing operations during system sleep and restoring them upon S0 return.[37][38]
A key feature is the use of power-managed I/O queues, which align request processing with device power states to avoid unnecessary wake-ups. When configured with PowerManaged set to WdfTrue in WDF_IO_QUEUE_CONFIG, the framework holds incoming requests in such queues until the device reaches D0, automatically stopping the queue during low-power transitions and restarting it upon D0 entry. This prevents delivery of device-dependent requests in Dx states, reducing power consumption; non-power-managed queues, by contrast, deliver requests regardless of power state for control operations. In idle scenarios, pending requests in power-managed queues can trigger automatic device resumption, streamlining power-aware I/O handling.[39][40]
Plug and Play Support
The Kernel-Mode Driver Framework (KMDF) provides robust support for the Windows Plug and Play (PnP) model by abstracting much of the complexity involved in dynamic device detection, configuration, and removal. Through its event-driven architecture, KMDF handles PnP operations via callbacks that allow drivers to respond to system events without directly managing low-level IRPs. For instance, the framework processes WMI queries and resource allocation requests, including IOCTLs for bus relations, enabling seamless integration with the PnP manager. A key callback, EvtDevicePrepareHardware, is invoked after device enumeration to perform hardware-specific preparations, such as configuring interrupts or memory mappings from the provided resource list.[41][42] Device enumeration in KMDF is facilitated by automatic driver loading triggered by INF files, which specify hardware IDs and compatibility details to match devices during system startup or hot-plug events. When a device is detected—such as via bus enumeration—the PnP manager uses the INF to load the appropriate KMDF driver, creating a framework device object and invoking the EvtDriverDeviceAdd callback for initialization. This supports hot-plug scenarios, where the framework notifies the driver of insertion events, ensuring resources are allocated dynamically without manual intervention. KMDF also accommodates multi-function devices by allowing bus drivers to create multiple child device objects, each managed independently through the framework's PnP abstractions.[43][42][44] For unexpected disconnections, known as surprise removal, KMDF queues pending I/O requests to prevent data loss and invokes the EvtDeviceSurpriseRemoval callback, enabling the driver to release resources safely before the device is fully removed. The framework then proceeds with EvtDeviceReleaseHardware and power-down sequences, integrating PnP with power management to maintain system stability. This approach significantly simplifies PnP implementation compared to the Windows Driver Model (WDM), reducing the need for thousands of lines of boilerplate code to a handful of targeted callbacks, as the framework automates IRP handling and state transitions.[45][46][42]Relationship to Windows Driver Model
Integration with WDM
The Kernel-Mode Driver Framework (KMDF) integrates with the Windows Driver Model (WDM) by layering its runtime library, kmdf.sys, directly atop the WDM kernel infrastructure. This runtime acts as an intermediary, wrapping WDM interfaces and translating high-level WDF objects—such as device objects, queues, and requests—into underlying WDM IRPs and dispatch routines. For instance, when an I/O request arrives as a WDM IRP, the KMDF runtime converts it into a framework request object that the driver processes via event callbacks, thereby abstracting away direct IRP manipulation.[47] This layering enables hybrid driver development, where developers can mix KMDF abstractions with direct WDM code for unsupported features, such as certain USB isochronous transfers that require WDM-style URBs. KMDF provides APIs like WdfDeviceWdmGetDeviceObject to retrieve the associated WDM device object from a framework device handle, allowing seamless access to WDM structures and routines without fully reverting to pure WDM implementation.[48][49] The integration leverages WDM's established kernel stability and compatibility while introducing higher-level abstractions that simplify common tasks like I/O queuing and error handling, eliminating the need to rewrite existing WDM drivers for newer Windows versions. KMDF version 1.0 and later requires operating systems supporting WDM, such as Windows XP SP2 and Windows Server 2003 or newer, ensuring backward compatibility. Additionally, KMDF fully supports filter drivers in device stacks, including lower filters (positioned below the function driver) and upper filters (above it), via methods like WdfFdoInitSetFilter to configure stack positioning.[47][50]Differences from Pure WDM
The Kernel-Mode Driver Framework (KMDF) introduces a simplified programming model compared to the traditional Windows Driver Model (WDM), primarily by abstracting low-level kernel operations and reducing the boilerplate code developers must write. In WDM, drivers must manually allocate and manage I/O Request Packets (IRPs), implement completion routines, and handle synchronization primitives explicitly, which often leads to verbose code. KMDF, in contrast, encapsulates these tasks within its object-based architecture, eliminating the need for direct IRP manipulation and allowing drivers to focus on device-specific logic. This results in KMDF drivers typically requiring significantly fewer lines of code than equivalent WDM drivers, with Microsoft documentation noting that ported drivers exhibit a substantial reduction in overall code volume due to the framework's handling of common operations.[19][51] A key distinction lies in error handling and verification. WDM drivers demand custom implementations for error checks, such as validating IRP parameters or detecting resource leaks, which can be error-prone and inconsistent across drivers. KMDF integrates built-in verification through tools like KMDF Verifier (WdfVerifier), which automatically validates driver-supplied data, arguments to framework methods, and object states at runtime, catching common issues like memory leaks or invalid accesses before they cause system instability. For instance, KMDF's reference-counted object model prevents premature resource deallocation, a frequent source of bugs in WDM where developers must manually track references. This proactive verification not only simplifies development but also enhances overall driver robustness by enforcing consistency without additional custom code.[52][19] Reliability is further bolstered in KMDF through enforced thread safety and state management, areas where WDM exposes developers to crash-prone manual kernel calls. In WDM, drivers must implement their own locking mechanisms (e.g., using spinlocks or mutexes) to handle concurrent access, increasing the risk of deadlocks or race conditions. KMDF provides automatic synchronization for its objects, such as queues and devices, ensuring thread-safe operations without developer intervention, while built-in state validation prevents invalid transitions that could lead to system crashes. This framework-driven approach reduces the surface area for bugs, making KMDF drivers inherently more reliable for standard I/O scenarios.[19] In terms of specific I/O handling, WDM requires drivers to define StartIo and dispatch routines to process IRPs sequentially or via custom queues, often involving manual queue management with functions like IoCsqXxx or KeXxxDeviceQueue. KMDF replaces this with declarative I/O queues (WDFQUEUE objects) and event-driven callbacks, such as EvtIoRead or EvtIoWrite, where the framework automatically manages queuing, cancellation, and forwarding of requests. For example, a simple read/write driver in WDM might need dozens of lines for IRP dispatching and completion, whereas the KMDF equivalent uses a few callback functions to achieve the same functionality, streamlining development while maintaining compatibility with WDM stacks. KMDF also simplifies power management and Plug and Play support by providing default behaviors and callbacks, reducing the code needed for these common requirements compared to WDM's explicit handling.[19]Development
Building and Tools
Developing Kernel-Mode Driver Framework (KMDF) drivers requires the Windows Driver Kit (WDK), which integrates with Visual Studio to provide templates, build environments, and necessary headers and libraries. The latest WDK version, 10.0.26100.6584 released in September 2025, supports KMDF 1.33 and is essential for targeting Windows 11 version 24H2 and later. Installation involves downloading the WDK via NuGet or the Visual Studio Installer, selecting the "Windows Driver Kit" component alongside the "Desktop development with C++" workload.[10][53][3] The build process begins with creating a project in Visual Studio using a KMDF template, such as the Kernel Mode Driver, Empty (KMDF) or USB Client Driver (KMDF), which generates boilerplate code and an INF file for driver installation. Compilation occurs through Visual Studio's Build menu or MSBuild from the command line, invoking the C/C++ compiler (cl.exe) and linker (link.exe) with the /driver flag to produce a .sys file, alongside the INF file defining hardware IDs (e.g., Root\SampleDevice) and the co-installer for KMDF runtime. For example, the WDK includes the Echo sample driver template, which demonstrates queue management and I/O handling, serving as a starting point for custom drivers. The resulting package includes .cat files for signing, ensuring compatibility with Secure Boot.[6][54][55] Key tools for building and initial validation include the Static Driver Verifier (SDV), which performs static analysis on KMDF drivers to detect defects like race conditions or invalid memory access by modeling callbacks and applying rule sets such as the default KMDF rules. SDV integrates directly into Visual Studio via the Driver menu, requiring declaration of callback functions with role types for full verification support. Additionally, Device Console (DevCon.exe), included in the WDK, facilitates testing by installing, removing, or querying drivers from the command line, such as usingdevcon install with the INF file on a test machine.[56][57][58]
A fundamental step in any KMDF driver is implementing the DriverEntry routine, which initializes the framework by calling WdfDriverCreate to create the driver object and specifying an EvtDriverDeviceAdd callback for device addition events. In EvtDriverDeviceAdd, the driver creates a device object using WdfDeviceCreate, passing a WDFDEVICE_INIT structure configured with attributes like device name and power policy ownership. This sequence ensures proper framework integration without direct interaction with Windows Driver Model (WDM) objects.[6][59]