Write a KMDF Hello World driver

To write a Kernel-Mode Driver Framework (KMDF) driver, you can use Microsoft Visual Studio along with the Windows Driver Kit (WDK). You can download them from the Windows Hardware Dev Center.

Debugging Tools for Windows is included when you install the WDK.

Create and build a driver package

  1. Open Microsoft Visual Studio. On the File menu, choose New > Project.
  2. In the New Project dialog box, select WDF.
  3. In the middle pane, select Kernel Mode Driver, Empty (KMDF).
  4. In the Name field, enter "KmdfHelloWorld" for the project name.

    Note  When you create a new KMDF or UMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h.

  5. In the Location field, enter the directory where you want to create the new project.
  6. Check Create directory for solution. Click OK.

    Screen shot of the New Project dialog box

    Visual Studio creates two projects and a solution. You can see them in the Solution Explorer window, shown here. (If the Solution Explorer window is not visible, choose Solution Explorer from the View menu.) The solution has a driver project named KmdfHelloWorld and a driver package project named KmdfHelloWorld Package.

    Screen shot of the Solution Explorer window, showing the package project (KmdfHelloWorld Packages) and the empty driver project (KmdfHelloWorld)
  7. In the Solution Explorer window, right-click KmdfHelloWorld and choose Add > New Item.
  8. In the Add New Item dialog box, select C++ File. For Name, enter "Driver.c".

    Note  The file name extension is .c, not .cpp.

    Click Add. The Driver.c file is added under Source Files, as shown here.

    Screen shot of the Solution Explorer window, showing the Driver.c file added to the driver project
  9. Open Driver.c, and enter this code:

    
    
    #include <ntddk.h>
    #include <wdf.h>
    DRIVER_INITIALIZE DriverEntry;
    EVT_WDF_DRIVER_DEVICE_ADD KmdfHelloWorldEvtDeviceAdd;
    
    NTSTATUS DriverEntry(_In_ PDRIVER_OBJECT  DriverObject, _In_ PUNICODE_STRING RegistryPath)
    {
        NTSTATUS status;
        WDF_DRIVER_CONFIG config;
     
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "KmdfHelloWorld: DriverEntry\n" ));
        WDF_DRIVER_CONFIG_INIT(&config, KmdfSmallEvtDeviceAdd);
        status = WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, &config, WDF_NO_HANDLE);
        return status;
    }
    
    NTSTATUS KmdfHelloWorldEvtDeviceAdd(_In_ WDFDRIVER Driver, _Inout_ PWDFDEVICE_INIT DeviceInit)
    {
        NTSTATUS status;
        WDFDEVICE hDevice;
        UNREFERENCED_PARAMETER(Driver);
    
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "KmdfHelloWorld: KmdfHelloWorldEvtDeviceAdd\n" ));
        status = WdfDeviceCreate(&DeviceInit, WDF_NO_OBJECT_ATTRIBUTES, &hDevice);
        return status;
    }
    
    
  10. Save Driver.c.
  11. In the Solution Explorer window, right-click Solution 'KmdfHelloWorld' (2 projects) and choose Configuration Manager. Choose a configuration and platform for both the driver project and the package project. For this exercise, we choose Win 8.1 Debug and x64.

  12. In the Solution Explorer window, right-click KmdfHelloWorld and choose Properties. In Wpp Tracing > All Options, set Run Wpp tracing to No. Click OK.
  13. To build your driver and create a driver package, choose Build Solution from the Build menu. Visual Studio shows the build progress in the Output window. (If the Output window is not visible, choose Output from the View menu.)

    When you have verified that the solution built successfully, you can close Visual Studio.

  14. To see the built driver package, in File Explorer, go to your KmdfHelloWorld folder, and then to C:\KmdfHelloWorld\x64\Win8.1Debug\KmdfHelloWorld Package. The driver package has several files: and .

    • KmdfHelloWorld.sys -- the kernel-mode driver file
    • KmdfHelloWorld.inf -- an information file that Windows uses when you install the driver
    • KmdfHelloWorld.cat -- a catalog file that the installer uses to verify the test signature for the driver package

    The package might also contain a coinstaller file.

Deploy and install the driver

Typically when you test and debug a driver, the debugger and the driver run on separate computers. The computer that runs the debugger is called the host computer, and the computer that runs the driver is called the target computer. The target computer is also called the test computer.

So far you've used Visual Studio to build a driver on the host computer. Now you need to configure a target computer. Follow the instructions in Provision a computer for driver deployment and testing (WDK 8.1). Then you can deploy, install, load, and debug your driver:

  1. On the host computer, open your solution in Visual Studio. You can double-click the solution file, KmdfHelloWorld.sln, in your KmdfHelloWorld folder.
  2. In the Solution Explorer window, right-click KmdfHelloWorld Package, and choose Properties.
  3. In the KmdfHelloWorld Package Property Pages window, go to Configuration Properties > Driver Install > Deployment, as shown here.
  4. Check Enable deployment, and check Remove previous driver versions before deployment.
  5. For Remote Computer Name, select the name of the computer that you configured for testing and debugging. In this exercise, we use a computer named MyTestComputer.
  6. Select Hardware ID Driver Update, and enter the hardware ID for your driver. For this exercise, the hardware ID is Root\KmdfHelloWorld. Click OK.

    Screen shot showing the KmdfHelloWorld Package Property Pages window with the Deployment Driver Install selected

    Note  In this exercise, the hardware ID does not identify a real piece of hardware. It identifies an imaginary device that will be given a place in the device tree as a child of the root node. For real hardware, do not select Hardware ID Driver Update; instead, select Install and Verify.

    You'll see the hardware ID in your driver's information (INF) file. In the Solution Explorer window, go to KmdfHelloWorld > Driver Files, and double-click KmdfHelloWorld.inf. The hardware ID is located under [Standard.NT$ARCH$].

    
    [Standard.NT$ARCH$]
    %KmdfHelloWorld.DeviceDesc%=KmdfHelloWorld_Device, Root\KmdfHelloWorld
    
    
  7. On the Debug menu, choose Start Debugging, or press F5 on the keyboard.
  8. Visual Studio first shows progress in the Output window. Then it opens the Debugger Immediate window and continues to show progress.

    Wait until your driver has been deployed, installed, and loaded on the target computer. This might take a minute or two.

  9. On the Debug menu, choose Break All. The debugger on the host computer will break into the target computer. In the Debugger Immediate window, you can see the kernel debugging command prompt: kd>.

    Screen shot of the command prompt in the Debugger Immediate window
  10. At this point, you can experiment with the debugger by entering commands at the kd> prompt. For example, you could try these commands:

  11. To let the target computer run again, choose Continue from the Debug menu.
  12. To stop the debugging session, choose Stop Debugging from the Debug menu.

Related topics

Developing, Testing, and Deploying Drivers
Debugging Tools for Windows
Write your first driver

 

 

Send comments about this topic to Microsoft

Показ:
© 2014 Microsoft