KMDF Driver Structure

What Is KMDF?

The Kernel-Mode Driver Framework (KMDF) is a Microsoft-provided framework that simplifies kernel-mode driver development. It handles many of the tedious and error-prone tasks in WDM – like IRP routing, memory management, and Plug and Play – so you can focus on your driver's logic.

KMDF follows an event-driver model: instead of manually handling every IRP, you register callbacks for the events your are interested in (e.g., I/O requests, device arrival, etc.).

Key Components of a KMDF Driver

Let's break down the fundamental structure of a KMDF driver into three major areas:

1 DriverEntry: The Driver's Main Entry Point

Every driver starts with DriverEntry(), the kernel-mode equivalent of main() in C programs. It initializes the driver and registers its main configuration.

Responsibilities:

• Initializes the WDF driver object
• Register event callbacks (like device addition)
• Return a status code (e.g., STATUS_SUCCESS)

Example:

NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath) {
    WDF_DRIVER_CONFIG config;
    WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd);
    return WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, &config, WDF_NO_HANDLE);
}

Key Point:

EvtDriverDeviceAdd is the most important callback in KMDF – it's called when your device is detected or manually created.

2 EvtDriverDeviceAdd: Creating the Device Object

This is where your driver creates the device, allocates resources, sets up queues, and prepares for I/O operations.

Responsibilities:

• Call WdfDeviceCreate() to create the logical device
• Optionally create symbolic links for use-mode access (e.g., \\.\MyDevice)
• Initialize I/O queues and event handlers

Example:

NTSTATUS EvtDriverDeviceAdd(WDFDRIVER Driver, PWDFDEVICE_INIT DeviceInit) {
    WDFDEVICE device;
    WdfDeviceCreate(&DeviceInit, WDF_NO_OBJECT_ATTRIBUTES, &device);
    WdfDeviceCreateSymbolicLink(device, &symbolicLinkName);
    return STATUS_SUCCESS;
}

Key Point:

This function defines what your driver is and what it can do. Failing to set up this callback properly means your driver won't work.

3 Driver Unload (Optional)

Unlike WDM, KMDF drivers do not require an explicit unload routine in most cases. KMDF automatically handles cleanup of WDF objects. However, if you need to perform manual cleanup (e.g., unregistering symbolic links, releasing global resources), you can define an EvtDriverUnload callback.

Example:

VOID EvtDriverUnload(WDFDRIVER Driver) {
    // Optional cleanup code
}

Supporting Concepts

Symbolic Links

Symbolic links allow user-mode apps to access the device using APIs like CreateFile().

• Defined using WdfDeviceCreateSymbolicLink()
• Target format: \\.\DeviceName

Object Lifetime

KMDF uses reference-counted objects. When you create a WDFDEVICE, it's automatically cleaned up when the driver or OS unloads it – reducing memory leaks and bugs.

Configuration Structure

KMDF uses initialization macros like WDF_DRIVER_CONFIG_INIT() to simplify object setup. These structures tell the framework what callbacks to expect and how to behave.