Windows 7 Kernel Mode Drivers Overview and Operations (part 1)

1. KMDF Supported Devices

In general, KMDF supports drivers that conform to WDM, supply entry points for the major I/O dispatch routines, and handle I/O request packets (IRPs). For some device types, device class and port drivers supply driver dispatch functions and call back to a miniport driver to handle specific I/O details. Such miniport drivers are essentially callback libraries and are not currently supported by KMDF. In addition, KMDF does not support device types that use the Windows imaging architecture (WIA).

2. KMDF Components

KMDF is distributed as part of the Windows Driver Kit (WDK) and consists of header files, libraries, sample drivers, development tools, public debugging symbols, and tracing format files. By default, KMDF is installed in the WDF subdirectory of the WDK root installation directory. KMDF-based drivers are built in the WDK build environment. Table 2 lists the KMDF components that are installed as part of WDF.

To aid in debugging, KMDF is distributed with free and checked builds of the run-time libraries and loader, along with corresponding symbols. However, Microsoft does not provide a checked version of the redistributable co-installer itself.

3. KMDF Driver Structure

A KMDF driver consists of a DriverEntry function that identifies the driver as based on KMDF, a set of callback functions that KMF calls so that the driver can respond to events that affect its device, and other driver-specific utility functions. Nearly every KMDF driver must have the following:

• A DriverEntry function, which represents the driver’s primary entry point

• An EvtDriverDeviceAdd callback, which is called when the Plug and Play manager enumerates one of the driver’s devices (not required for drivers that support non-Plug and Play devices)

• One or more EvtIo* callbacks, which handle specific types of I/O requests from a particular queue

Drivers typically create one or more queues into which KMDF places I/O requests for the driver’s device. A driver can configure the queues by type of request and type of dispatching.

A minimal Kernel Mode Driver for a simple device might have these functions and nothing more. KMDF includes code to support default power management and Plug and Play operations, so drivers that do not manipulate physical hardware can omit most Plug and Play and power management code. If a driver can use the default, it does not require code for many common tasks, such as passing a power IRP down the device stack. The more device-specific features a device supports and the more functionality the driver provides the more code the driver requires.

4. Comparing KMDF and WDM Drivers

The KMDF model results in drivers that are much simpler and easier to debug than WDM drivers. KMDF drivers require minimal common code for default operations because most such code resides in the framework, where it has been thoroughly tested and can be globally updated.

Because KMDF events are clearly and narrowly defined, KMDF-based drivers typically require little code complexity. Each driver callback routine is designed to perform a specific task. Therefore, compared to WDM drivers, KMDF-based drivers have fewer lines of code and virtually no state variables or locks.

As part of the WDF development effort, Microsoft has converted many of the sample drivers that shipped with the Windows DDK from WDM drivers to KMDF drivers. Without exception, the KMDF drivers are smaller and less complex.

Table 3 shows “before-and-after” statistics for the PCIDRV, Serial, and OSRUSBFX2 drivers.

The PCIDRV sample supports the Intel E100B NIC card. The WDM and KMDF versions are functionally equivalent. The Serial sample supports a serial device. In this case, the WDM sample supports a multiport device, but the KMDF sample supports only a single port. However, the statistics for the WDM driver do not include code, locks, or variables that are required solely to support multiport devices, so the statistics are comparable. The OSRUSBFX2 sample supports the USB-FX2 board built by OSR. The WDM and KMDF versions are functionally equivalent.

As the table shows, converting these drivers from WDM to KMDF resulted in significant reductions in the lines of code, particularly for Plug and Play and power management. The KMDF samples also require fewer locks and synchronization primitives and state variables. The following information shows more detail with respect to these requirements:

• Lines of code— The KMDF drivers require significantly fewer lines of code both overall and to implement Plug and Play and power management. Less code means a less complex driver with fewer opportunities for error and a smaller executable image.

• Locks and synchronization primitives— Not only are the KMDF drivers smaller, but in all three cases the number of locks and synchronization primitives has been reduced significantly. This change is important because it eliminates a common source of driver problems. WDM drivers use locks to synchronize I/O queues with Plug and Play and power operations and often supply locks to manage I/O cancellation. The locking scenarios typically involve one or more race conditions and can be difficult to implement correctly. KMDF drivers can be implemented with few such locks because the framework provides the locking.

• State variables— The number of state variables that are required for Plug and Play and power management is a measure of the complexity of the Plug and Play and power management implementation within the driver. A WDM driver receives Plug and Play and power management requests from the operating system in the form of IRPs. When such a driver receives a Plug and Play or power IRP, it must determine the current state of its device and the system and, based on those two states, must determine what to do to satisfy the IRP. Drivers must handle some IRPs immediately upon arrival as they travel down the device stack, but must handle others only after they have been acted upon by drivers lower in the stack. Consequently, a WDM driver must keep track of numerous details about the current state of its device and of current Plug and Play and power management requests. Tracking this information requires 30 variables in the WDM PCIDRV sample, 53 in the Serial sample, and 21 in the OSRUSBFX2 sample.

The KMDF versions of the three sample drivers require no state variables. The KMDF drivers do not maintain such information because the framework does so on their behalf. The framework implements an extensive state machine that integrates Plug and Play and power management operations with I/O operations. A driver provides callbacks that are invoked only when its device requires manipulation. For example, a driver for a device that supports a wake-up signal can register a callback that arms the signal, and KMDF invokes the callback at the appropriate time. By contrast, a WDM driver must determine which power management IRPs require it to arm the signal and at which point in handling those IRPs it should do so.