Skip to content

Debugging with WDF Source

Jump to bottom
J M Rossy edited this page Jun 19, 2015 · 5 revisions

This page describes how you can step through WDF source code in the debugger while debugging your WDF driver. This will help you get better understanding of the failure being triaged.

OS Requirements

In order to perform debugging with WDF source, your target machine must be running one of the Windows 10 builds available through the Windows Insider Pro gram. The build must be from March 2015 or later.

Debugging in WinDbg

If you haven't used WinDbg before, we strongly recommend you start your learning with the MSDN documentation.

If you're familiar with the basics of WinDbg usage, then you'll find that debugging with the WDF source is very simple.

Option 1: Configure WinDbg to Retrieve Source Code

When debugging a WDF driver running on a Windows 10 target machine, WinDbg can be configured to automatically retrieve the right source for the version of WDF you're debugging against. This is referred to as 'source-level debugging'. Follow these steps to configure the debugger:

  1. Set the default symbol path using .symfix. This sets the symbol path to point to Microsoft symbol server.

    kd> .symfix

  2. Set the default source path using .srcfix. This sets the source path to srv*. This tells the debugger to retrieve source files from locations specified in the target modules' symbol files.

    kd> .srcfix Source search path is: SRV*

  3. Reload symbols using .reload, and confirm that the Wdf01000.sys symbols (or Wudfx02000.dll for UMDF) are source-indexed. As shown in the output of !lmi below, the Wdf01000.sys PDB is source indexed. If yours is not, see the WinDbg Setup section later in this post.

    kd> .reload ...

    kd> !lmi wdf01000.sys Loaded Module Info: [wdf01000.sys] ... Load Report: private symbols & lines, source indexed C:\...\Wdf01000.pdb\...\Wdf01000.pdb

You're all set! For more details on how source-level debugging works or troubleshooting tips see the Hardware and Driver Developer Blog.

Option 2: Download the WDF Source Code Locally

Download the source from GitHub, either by cloning the repo or by downloading the repo as a zip and extracting it. In WinDbg, set the source path to point to your local copy of the WDF code. For example, if the source is located at c:\wdf-source, you can use the following command to set the source path.

.srcpath+ c:\wdf-source\src\framework

Now that the debugger is aware of the source, try breaking into a driver. If you see any WDF routines (those starting with wdf01000! or wudfx02000!) on the call stack, click one. A window with the source for that routine should appear.

That's it! Continue debugging as you normally would, but with the benefit of full transparency into WDF source.

Debugging in Visual Studio

Visual Studio 2015 supports a subset of the debugging functionality supported in WinDbg. You can use the same debugging commands in both Visual Studio and WinDbg.

Clone this wiki locally