Write a KMDF driver based on a template
To write a KMDF driver, you need the Windows Driver Kit (WDK), which is integrated with Microsoft Visual Studio 2012, and Debugging Tools for Windows. You can use a Microsoft Visual Studio template as a starting point.
To set up the integrated development environment, first install Visual Studio and then install the WDK. You can find information about how to get Visual Studio and the WDK here.
Debugging Tools for Windows is included when you install the WDK. For more information, see Download and Install Debugging Tools for Windows.
To create and build a KMDF driver from a template:
- Open Microsoft Visual Studio. On the File menu, choose New > Project. The New Project dialog box opens, as shown in the following screen shot.
- In the New Project dialog box, in the left pane, locate and select WDF.
- In the middle pane, select Kernel Mode Driver (KMDF).
- In the Name field, enter "KmdfHelloWorld" as the project name.
- In the Location field, enter the directory where you want to create the new project.
Check Create directory for solution. Click OK.
Visual Studio creates two projects and a solution. You can see the solution, the two projects, and the files that belong to each project in the Solution Explorer window, as shown in the following screen shot. (If the Solution Explorer window is not visible, choose Solution Explorer from the View menu.) The solution contains a driver project named KmdfHelloWorld and a driver package project named KmdfHelloWorld Package. If you want to look at the driver source code, you can open any of the files that appear under Source Files. Driver.c and Device.c are good places to start.
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. In this exercise, we choose Win7 Debug and x64, as shown in the following screen shot.
To build your driver and create a driver package, choose Build Solution from the Build menu. Visual Studio displays build progress in the Output window, as shown in the following screen shot. (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.
To see the built driver package, navigate in Windows Explorer to your KmdfHelloWorld folder, and then navigate to x64 > Win7Debug > KmdfHelloWorld Package. The driver package contains several files: KmdfHelloWorld.sys is the kernel-mode driver file, KmdfHelloWorld.inf is an information file that Windows uses when you install the driver, and KmdfHelloWorld.cat is a catalog file that the installer uses to verify the test signature for the driver package. The other file is a co-installer for the Windows Driver Frameworks (WDF). These files are shown in the following screen shot.
Typically when you test and debug a driver, the debugger and 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. For more information about debugging drivers, see Windows Debugging.
So far in this exercise, you've used Visual Studio on the host computer to build a driver. Next you need to configure a target computer. To configure a target computer, follow the instructions in Configuring a Computer for Testing and Debugging. After you've configured a target computer, you can deploy, install, load, and debug your driver by following these steps:
- On the host computer, open your solution in Visual Studio. One way to do this is to double-click the solution file, KmdfHelloWorld.sln, in your KmdfHelloWorld folder.
- In the Solution Explorer window, right-click KmdfHelloWorld Package, and choose Properties.
- In the KmdfHelloWorld Package Property Pages window, in the left pane, navigate to Configuration Properties > Driver Install > Deployment, as shown in the following screen shot.
- Check Enable deployment, and check Remove previous driver versions before deployment.
- 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.
Select Hardware ID Driver Update, and enter the hardware ID for your driver. In this exercise, the hardware ID is Root\KmdfHelloWorld. Click OK.
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, navigate to KmdfHelloWorld > Driver Files and double-click KmdfHelloWorld.inf. The hardware ID is located under [Standard.NT$ARCH$].
- On the Debug menu, choose Start Debugging, or press F5 on the keyboard.
Visual Studio first displays progress in the Output window. Then it opens the Debugger Immediate Window and continues to display progress, as shown in the following screen shot.
Wait until your driver has been deployed, installed, and loaded on the target computer. This might take a minute or two.
On the Debug menu, choose Break All. The debugger on the host computer will break into the target computer. As shown in the following screen shot of the Debugger Immediate Window, you'll see the kernel debugging command prompt: kd>.
On the Debug menu, choose Windows > Modules. Verify that KmdfHelloWorld.sys is in the list of modules that are loaded on the target computer, as shown in the following screen shot.
At this point, you can experiment with the debugger by entering commands at the kd> prompt. For example, you could try these commands:
- To let the target computer run again, choose Continue from the Debug menu.
- To stop the debugging session, choose Stop Debugging from the Debug menu.
- Developing, Testing, and Deploying Drivers
- Windows Debugging
- Writing a UMDF driver based on a template
- Writing a very small KMDF driver
- Writing your first driver
Build date: 11/23/2012