1. KMDF Supported Devices
KMDF was designed to replace the Windows Driver Model
(WDM). The initial KMDF release supports most of the same devices and
device classes as WDM, except in those that are currently supported by
miniport models. Table 1 lists the device and driver types that KMDF supports.
Table 1. Devices and Driver Types That KMDF Supports
Device or Driver Type | Existing Driver Model | Comments |
---|
Control and non-Plug and Play drivers | Legacy | Supported |
IEEE 1394 client drivers | Depends on device class | Supported for devices that do not conform to existing device class specifications |
ISA, PCI, PCMCIA, and secure digital (SD) devices | WDM driver | Supported, if device class or port drivers do not provide the driver dispatch functions |
NDIS protocol drivers | WDM upper edge and NDIS lower edge | Supported |
NDIS WDM drivers | NDIS upper edge and WDM lower edge | Supported |
SoftModem drivers | WDM driver with upper Edge support for TAPI Interface | Supported |
Storage class drivers and filter drivers | WDM driver | Supported |
Transport driver interface (TDI) client drivers | Generic WDM driver | Supported |
USB client drivers | Depends on device class | Supported |
Winsock client drivers | WDM driver with a callback interface for device-specific requests | Supported |
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.
Table 2. KMDF Component Names
Component | Location | Description |
---|
Header files | wdf/inc | Header files required to build KMDF drivers |
Libraries | wdf/lib | Libraries for x86, x64, and Intel Itanium architectures |
Sample drivers | wdf/src | Sample drivers for numerous device types; most are ported from Windows Device Kit (DDK) WDM samples |
Tools | wdf/bin | Tools for testing, debugging, and installing drivers, includes the redistributable KMDF co-installer, WdfConinstallernn.dll |
Debugging symbols | wdf/symbols | Public symbol database (.pdb) files for KMDF libraries and co-installer for checked and free builds |
Tracing format files | wdf/tracing | Trace format files for the trace messages generated by KMDF libraries and co-installer |
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.
Table 3. WDM-KMDF Statistics for Sample Drivers
Statistic | PCIDRV | Serial | OSRUSBFX2 |
---|
| WDM | KMDF | WDM | KMDF | WDM | KMDF |
---|
Total lines of code | 13,147 | 7,271 | 24,000 | 17,000 | 16,350 | 2,300 |
Lines of code required for Plug and Play and power management | 7,991 | 1,795 | 5,000 | 2,500 | 8,700 | 742 |
Locks and synchronization | 8 | 3 | 10 | 0 | 9 | 0 |
State variables required for Plug and Play and power management | 30 | 0 | 53 | 0 | 21 | 0 |
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.