Creating Your First KMDF Driver

This guide will walk you through the process of creating a simple Kernel-Mode Driver Framework (KMDF) driver. KMDF simplifies driver development by providing a framework that handles many common driver tasks, allowing you to focus on the unique logic of your driver.

Prerequisites

• Windows SDK and WDK installed.
• Visual Studio with C++ development workload installed.
• Basic understanding of C/C++ programming.
• Familiarity with kernel-mode concepts is helpful but not strictly required for this introductory example.

Steps to Create Your First KMDF Driver

1. Create a New Driver Project in Visual Studio

1. Open Visual Studio.
2. Go to File > New > Project....
3. In the "Create a new project" dialog, search for "Kernel Mode Driver".
4. Select the "Kernel Mode Driver (KMDF)" template and click Next.
5. Enter a Project name (e.g., `MyFirstKmdfDriver`) and choose a Location.
6. Click Create.

2. Understanding the Project Structure

Visual Studio will create a basic project with several files:

• Driver.c: Contains the main driver entry points, such as DriverEntry and device creation callbacks.
• MyFirstKmdfDriver.vcxproj: The project file.
• Source.def: Module definition file.

3. Implementing the Driver Entry Point

The DriverEntry function is the first function that the operating system calls when your driver is loaded. In a KMDF driver, this function typically initializes the framework and creates a framework driver object.

Open Driver.c. You will find a function that looks like this:

NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    )
{
    NTSTATUS                        status;
    WDF_DRIVER_CONFIG               config;
    WDF_OBJECT_ATTRIBUTES           attributes;

    //
    // Initialize the Framework Driver Object attributes.
    //
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

    //
    // Framework does not use the DriverObject parameter.
    //
    UNREFERENCED_PARAMETER(DriverObject);

    //
    // Register the driver with the framework.
    //
    WDF_DRIVER_CONFIG_INIT(
        &config,
        NULL // No callback for AddDevice in this basic example
    );

    //
    // Create a framework driver object.
    //
    status = WdfDriverCreate(
        DriverObject,
        RegistryPath,
        &attributes,
        &config,
        WDF_NO_HANDLE
    );

    if (NT_SUCCESS(status)) {
        // TODO: Add code to create a device if needed
        // For a basic driver, it might not create a device on load.
    }

    return status;
}
            

4. Building and Signing the Driver

To build the driver:

1. Right-click on the project in Solution Explorer and select Properties.
2. Navigate to Configuration Properties > Driver Settings > General.
3. Ensure the Target OS is set to "Desktop".
4. In the Configuration Manager, select "Win7 Debug" or a similar target for building.
5. Build the solution (Build > Build Solution).

Kernel-mode drivers require signing to be loaded on most modern Windows versions. For development purposes, you can use a test certificate.

5. Loading and Testing the Driver

Loading a kernel-mode driver typically involves using tools like:

• sc.exe: The Service Control Manager command-line utility.
• devcon.exe: A command-line utility that acts as a SQL Server Data Tools (SSDT) command-line utility for managing devices and drivers.
• DriverTest.exe: Part of the Windows Driver Kit (WDK) for testing drivers.

A simple way to load is using sc.exe:

sc create MyFirstKmdfDriver type= kernel binPath= "C:\Path\To\Your\Driver.sys" displayname= "My First KMDF Driver"
sc start MyFirstKmdfDriver
            

Remember to replace C:\Path\To\Your\Driver.sys with the actual path to your built driver file (usually found in the project's output directory, e.g., `x64/Debug`).

Next Steps

• Implement the EvtDriverDeviceAdd callback to create a device object.
• Handle I/O requests by implementing dispatch routines for different I/O control codes (IOCTLs).
• Explore the various KMDF objects and methods for managing hardware resources, power states, and more.