WPDMon Gotchas

  • Article

If you're developing a WPD driver or a WPD application, you may have come across the WPD Monitor tool (a.k.a. WpdMon).  

This is a tool that displays WPD traffic between applications and a WPD driver for diagnostic purposes.   Plug and Play (PnP) messages and Raw (DeviceIoControl) traffic are also viewable.    WpdMon is available in the Windows Driver Kits, e.g. c:\WinDDK\6000\tools\wpd\x86.  

Known issues in WpdMon

Issue #1 WPDMon.exe is not showing any traces

Make sure that you have installed WpdMon according to the instructions in WpdMon.htm (also found under e.g. c:\WinDDK\6000\tools\wpd\x86).  

1. Ensure that all WPD devices are unplugged
2. For 32-bit systems, copy the Shim DLL to the AppPatch directory (“copy WpdMonShim.dll %windir%\AppPatch”) from an Administrator Command Prompt.  On 64-bit systems, copy the Shim DLL to the AppPatch64 directory (“copy WpdMonShim.dll %windir%\AppPatch\AppPatch64”)
3. Register the shim (“Regsvr32 %windir%\AppPatch\WpdMonShim.dll” for 32-bit, or “Regsvr32 %windir%\AppPatch\AppPatch64\WpdMonShim.dll” for 64-bit) from an Administrator Command Prompt. 
4. Plug WPD devices back in
5. The WPD Monitor Application (WpdMon.exe) is now ready to capture WPD API/DDI traffic, and can be copied and run directly from any directory.  It requires administrator privileges, so you need to right click on WpdMon.exe from Explorer and select "Run Elevated", or launch WpdMon from an Administrator Command Prompt.

Issue #2 I've installed WpdMon according to the instructions in WpdMon.htm, but I still can't see any traces

Ensure that you've launched WpdMon with Administrator privileges.    Either right click on the WpdMon.exe from Explorer and select "Run Elevated", or launch WpdMon from an Administrator Command Prompt.

Ensure that you have Monitor -> API Traffic checked to enable WPD API tracing.

If you have a Root Enumerated WPD device (such as one of the WPD driver samples from the WDK) running before WpdMon was installed, the Windows User Mode Driver Framework (WUDF) driver process (WUDFHost.exe) is still running,    You'll need to force WUDFHost.exe process to restart so that the WpdMonShim dll can load:

1. Launch WpdMon.exe with Administrator privileges
2. From Device Manager, select the WPD device (under Portable Devices)
3. Right click "Disable" to disable the WPD device
4. Right click "Enable" to re-enable the WPD device
5. WpdMon.exe should now show traces

Issue #3 I see a lot of traces in WpdMon and would like to save them to a file, but the "File -> Save Viewer Output As" dialog keeps getting out of scope

WpdMon logs to both the window and a Wpdmon.htm file, both in the same directory as WpdMon.exe.   Sometimes when there is a lot of WPD API traffic going on, the WpdMon window would update rapidly and grab the window focus from the File->Save As dialog.

There are two ways to get around this:

1. Uncheck "Log to Viewer" from the Options menu to disable logging to Window, or

2. If you need the Viewer output, uncheck "Auto Scroll Viewer Output" from the Options menu to disable the scrolling.  You will have to scroll down manually to view the latest traces. 

Setting up WpdMon.ini

You can configure default WpdMon settings by modifying the WpdMon.ini file.   This is useful in situations where you want WpdMon to log to HTML silently, for example.

1. Close WpdMon
2. Open WpdMon.ini in a text editor (e.g. Notepad)
3. Under the [General] section, set the following options (0=disable, 1=enable).

LogToViewer=0
LogToHTMLFile=1

4. Reopen WpdMon 

WpdMon.ini also contains settings to disable/enable API, Raw and PnP tracing by default.  You can set Enabled=1 under each parser section (e.g. [APIParser]) to enable the WPD API traces.   Enabled=0 will disable the API tracing.   You can turn this on/off dynamically while WpdMon is running, to start and stop the tracing.

Issue #4 I lost the instructions since WpdMon.exe overwrote the tool readme:

WpdMon automatically saves traces to WpdMon.htm.  Unfortunately, this file bears the same name as the tool readme and will overwrite the readme when WpdMon.exe is launched.  You may want to save a copy of the original WpdMon.htm as backup before running WpdMon, or refer to an identical copy from a different OS architecture that was not overwritten, e.g. in c:\WinDDK\6000\tools\wpd\amd64\ wpdmon.htm).  

Issue #5 WpdMon keeps logging even after I've closed my WPD application

Sometimes when WpdMon captures and processes a lot of realtime WPD traffic, there can be a delay between the actual WPD operation and tracing display.    This is normal as the window may take some time to display all the traces.   You can speed things up by minimizing the WpdMon window, and then clicking on something else in Explorer so that the WpdMon is not in focus.   

Once the minimized WpdMon window stops flickering, restore the window, and scroll down to refresh it.

If you still see intermittent traffic, it is possibly because other WPD applications (e.g. Explorer via the WPD Shell Namespace Extension or Windows Media Player) are communciating with your driver/device.

 

Still can't get WpdMon to show API traces for debugging your driver?  

If you are developing a WPD driver and need tracing information, a good alternative is to convert your driver traces to WPP tracing.   This post describes how to migrate the CHECK_HR macro used in our sample drivers to use WPP traces "under the covers", and should provide you with a good start for adopting WPP for your driver logging needs.

 

This posting is provided "AS IS" with no warranties, and confers no rights.