Technical Document #19

Technical Document #19
Debugging your driver code with WinDriver

When using the WinDriver tool-kit, you are developing in the user mode, and you can therefore use the regular user-mode debugging tools, such as the compiler's debugger.

The WinDriver tool-kit includes the Debug Monitor utility (a.k.a. Monitor Debug Messages, in earlier versions) to help you in the debugging process. This utility comes both in a GUI format — WinDriver/util/wddebug_gui (or /Applications/ on Mac OS X — in the WinDriver versions that support this OS) — and a console (CLI) format — WinDriver/util/wddebug.
For a detailed description of this utility, please refer to the WinDriver User's Manuals and to Technical Documents #12 (wddebug_gui), #13 (wddebug), and #14 (for VxWorks — last supported in WinDriver v5.2.2).

WinDriver also provides you with the WD_DebugAdd() API (available beginning with v5.0.3), which enables you to send your own debug messages from the code to the Debug Monitor log. For a description of this API, refer to the function reference in the WinDriver User's Manuals.
Note that this function can be called from both user-mode and kernel-mode code (created using WinDriver's Kernel PlugIn feature) and can also be called from within functions running at HIGH IRQL, such as the Kernel PlugIn KP_IntAtIrql() function.

You can also select to send the debug messages to a kernel debugger, instead of to the Debug Monitor log, as explained in Technical Document #44. This can enable you, for example, to log the debug message on another PC in case the system crashes or hangs on the development PC.

Beginning with version 6.0, most of the WinDriver functions have a return value to indicate success or a relevant error code, which can assist you in the debugging process. For USB, beginning with version 5.2.0 of WinDriver, the USB API also returns additional status information, which can help in determining the reason for a failed operation. This information is returned in the dwStatus field that was added to the USB structures. The return status codes are defined in the WD_USB_ERROR_CODES enum in WinDriver/include/windrvr.h).

When developing code in the kernel (using the Kernel PlugIn, you can also use any kernel debugger in the debugging process (e.g., WinDbg — which is distributed with the Windows Driver Kit (WDK) and is part of the Debugging Tools for Windows package, distributed via the Microsoft web site). As mentioned above, you can also select to direct the debug message from the Debug Monitor to a kernel debugger of your choice.

For more information regarding the debugging process with WinDriver, review the debugging chapters in the WinDriver User's Manuals.