Windows Portable Devices Team Blog : Tools

The MTP Device Simulator

wpdblog — Sat, 24 Oct 2009 00:52:25 GMT

The Media Transfer Protocol Device Simulator (MTP Simulator) is a fully-featured, self-contained device simulator that emulates an MTP device. Its primary purpose is to enable developers to exercise expected behavior based on the MTP specification by returning appropriate MTP response packets and generating MTP events. The tool’s graphical user interface (GUI) enables easy configuration of MTP parameters and presents MTP traffic and data in a friendly, human-readable format.

The MTP Simulator implements all MTP device capabilities, object properties, and operations that are based on the MTP Specification along with the major features in Windows 7. Additionally, the MTP Simulator also supports Device Stage and loading customizable device profiles.

For transport support, the MTP Simulator runs on multiple transport options such as USB, Software-Simulated USB (SoftSim), Bluetooth, and IP. Last, but not the least, the MTP Simulator runs on both Windows Vista and Windows 7.

Where to get the MTP Simulator

The MTP Simulator is publicly available as part of the Windows 7 Portable Device Enabling Kit for MTP (DEK). The kit also includes support documentation for the MTP Simulator and the MTP Specification Version 1.0 and MTP Device Services for Windows. Included in the DEK is the MTP Device Simulator User Guide which provides a detailed description of the MTP Simulator.

Installing the MTP Simulator

The MTP Device Simulator is installed as part of the Windows 7 Portable Device Enabling Kit for MTP (DEK). Before running the simulator for the first time, you may need to install the Device Simulation Framework (DSF).

To install DSF:

Browse to the folder where the DEK is installed (usually C:\Windows7DEK)
Navigate to the Tools\MTP Device Simulator\Dsf subfolder
Open an elevated command window (i.e. "Run as Administrator”) and launch install.cmd to start the DSF MSI package install.

Once DSF is installed, you can launch the MTP Simulator from C:\WindowsDEK\Tools\MTP Device Simulator\MTPSimUI.exe. Select your desired transport, and click “Connect” to launch an instance of the MTP Simulator. The next section gives an overview of the User Interface.

User Interface

The following screenshot shows the MTP Simulator UI with navigation buttons and configuration options.

MTP Simulator Configuration	Location	Purpose
Connection	Left control tabs and menu options.	Connect, disconnect, or restart MTP Simulator by using the currently selected configuration. You can change the transport type on the Transport tab and change the test mode on the Device Mode tab.
Transport	Left control tabs and menu options.	Select the transport to be used. To simulate a software-only USB device, select the “SoftUSB” transport.
Device mode	Left control tabs and menu options.	Normal Mode should be used. Test Mode is reserved for internal Microsoft testing.
Output windows	Lower-right output window.	This window displays redirected output from stdout. Any output from a printf statement, such as trace—from either MTP Simulator or a plug-in—appears in this window. The output is also saved as mtpsimui.log automatically under the MTP Simulator root directory.

Table 1. MTP Simulator User Controls

Command-Line Options

In addition to the GUI, you can control MTP Simulator at startup by using command-line parameters. This can be useful when you need to perform automated testing. For details, see Appendix C from the MTP Device Simulator User Guide.

Customizing the MTP Simulator

You can control the capabilities that the MTP Simulator reports to Windows by using an XML file (see Appendix F in the MTP Device Simulator User Guide for details). Device capabilities are controlled by DeviceSummary.xml, and service capabilities are controlled by Services.xml.

The DeviceSummary.xml file enables you to customize the contents of the DeviceInfo, StorageInfo, DevicePropDesc, and ObjectPropDesc datasets.

The Services.xml file enables you to specify configurations that are related to device services, including service-supported formats, methods, and events.

Device Profiles

The MTP Simulator also supports loading different device profiles. A device profile contains a set of customized configuration files (i.e. DeviceSummary.xml and Services.xml) describing a sample device. The DEK comes bundled with sample profiles representing each device class (Camera, Cellular Phone, Media Player, etc). Details of how to load the device profiles are outlined in the MTP Device Simulator User Guide.

Device Profile	Description
Fabrikam_Camera	Simulates a sample camera.
Fabrikam_Phone	Simulates a cellular phone.
Fabrikam_PMP	Simulates a portable media player.
MtpSim-FullEnumSync	Simulates a device that supports the Full Enumeration synchronization model, for example for contacts, calendar, tasks, and notes synchronization.
MtpSim-FullEnumSyncSimpleParticipant	Simulates a device that supports the Full Enumeration synchronization model (like MtpSim-FullEnumSync), with additional support for the simple participant feature.

Table 2: Sample MTP Simulator Device Profiles

Each of these profiles has a corresponding Device Stage package. Each of these packages supports the same set of standard Device Stage tasks, with the exception of the Ringtone task which is not supported by the Fabrikam_Camera and Fabrikam_PMP profiles. For more information on authoring Device Stage metadata, refer to the Windows 7 Device Stage Development Guide in the Microsoft Device Experience Development Kit.

Testing Device Stage Packages

The MTP Simulator can also be used to test custom Device Stage packages. The MTP Device Inspector tool can be used to generate a device profile which can be loaded into the Simulator (see the MTP Device Simulator User Guide for details). Once a custom Device Stage metadata package has been authored, the package contains all the files necessary to display a Device Stage experience in Windows 7. The package may be tested by copying it to the PC’s device metadata store and connecting the test device, in this case rapid development can be done using the MTP Simulator. In order to load (unsigned) custom Device Stage metadata the system will need to be boot into test mode. For more details, refer to page 40 of the Windows 7 Device Stage Development Guide document that is included in the Microsoft Device Experience Development Kit for details on testing Device Stage metadata packages.

Want to Learn More?

The MTP Device Simulator User Guide in the Documentation for the Device Enabling Kit contains more information on the features described above.

If you have general questions about the MTP Simulator contact AskMTP at Microsoft dot com.

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

Windows 7 Portable Device Development Kits

wpdblog — Sat, 12 Sep 2009 09:58:00 GMT

There are several different resources made available to portable device manufacturers to assist in device firmware and driver development, and to application developers wishing to create applications that interact with these portable devices. These resources are provided and maintained by members of the Windows Portable Devices team.

This post provides a description for the following development kits:

Windows 7 Portable Device Enabling Kit for MTP
Windows Portable Devices SDK
Windows Portable Devices Driver Kit
Windows Media Device Manager SDK
Microsoft Device Experience Development Kit
Windows Logo Kit

Windows 7 Portable Device Enabling Kit for MTP

This development kit is designed to assist portable device manufacturers in the development of Media Transfer Protocol (MTP) device firmware that is compatible with the various MTP device transports that Windows supports, and with Device Services. There are two packages provided for download:

Windows 7 Portable Device Enabling Kit for MTP - Tools
The tools kit includes design documentation and implementation guidelines, a Windows-based reference design, development tools, and the updated MTP Device Simulator.

Windows 7 Portable Device Enabling Kit for MTP - Reference Code
The reference code kit includes the core responder reference source code that is being made available under a separate Berkeley Software Distribution (BSD)–style license.

To download both packages of the Windows 7 Portable Device Enabling Kit for MTP, go to: http://www.microsoft.com/whdc/device/wpd/MTP-DEK_Win7.mspx

You are not required to license the reference code in order to use the tools and resources provided in the tools kit. This kit is free to download and use.

Windows Portable Devices SDK

The WPD SDK includes the WPD Application Programming Interface (API) that is supported in Windows 7, Windows Vista, and Windows XP operating Systems. Developers will use this API to write Windows applications in C++. Being a COM API, the WPD API is also accessible from Managed code, so C# .Net, and Visual Basic .Net applications can use COM Interoperability to invoke the same functionality that the C++ API provides. WPD applications can: explore a device, send and receive content, and even control the device, for example, take a picture or send a text message.

The WPD SDK includes two sample applications for C++/COM developers. The first, WpdApiSample, is a command-line desktop application that demonstrates how you would: enumerate connected devices, explore those devices, query device-objects for properties and attributes, send and retrieve data, and so on. The second sample, WpdServicesApiSample, is a command-line desktop application that demonstrates how you would explore a Contacts service on a device that is attached to your computer.

The WPD SDK also includes an Automation Object Model that is supported in Windows 7. Developers can use the Automation model to write web applications that accomplish tasks similar to those accomplished with the API. We provided an introduction to WPD Automation in this recent post.

The WPD SDK is included in the Windows SDK which can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyID=c17ba869-9671-4330-a63e-1fd44e0e2505&displaylang=en

The documentation for the WPD SDK (both the API and Automation Object Model) is found on MSDN at: http://msdn.microsoft.com/en-us/library/dd388998(VS.85).aspx

Windows Portable Devices Driver Kit

The WPD Driver Kit includes a Device Driver Interface (DDI) that is supported in Windows 7, Windows Vista, and Windows XP operating Systems. Developers will use this DDI to write drivers for devices that are not already supported by the MTP or Mass Storage class drivers that Microsoft distributes.

The WPD Driver Kit includes five sample device drivers which are described in the following table. In the next post, we covered each sample in more detail.

Sample Driver	Description
WpdHelloWorldDriver	This is the most basic WPD driver that emulates interaction with hardware. Supports four objects: device, storage, folder, and file. This provides the scaffolding or skeleton for developing a WPD driver.
WpdBasicHardwareDriver	Builds upon the WpdHelloWorldDriver and demonstrates interaction with simple hardware devices. Supports nine sensor devices: 2-axis accelerometer, 3-axis accelerometer, temperature/humidity sensor, pressure sensor, distance sensor, passive infrared sensor, compass, vibration sensor, and light sensor. These sensor devices are simple devices that are controlled by a Parallax BS2 microcontroller attached to the PC. If you plan to develop drivers that integrate sensors with Windows 7, we recommend using the Sensor API and Sensor Driver Model. If you need to develop drivers to integrate sensors with Windows Vista or Windows XP, WPD provides a viable solution.
WpdServiceSampleDriver	Demonstrates how a developer would extend the WpdHelloWorldDriver to support a simulated device with a Contacts device service.(Using this service, WPD applications can discover events, methods, and properties associated with the Contacts stored on the device. This sample emulates interaction with hardware.
WpdMultiTransportDriver	Demonstrates how developers can take advantage of the Windows 7 support for multiple transports. The sample emulates interaction with hardware and demonstrates support for the following transports: IP, Bluetooth, and USB. We covered an overview of Multi-transport support in Windows 7 here.
WpdWudfSampleDriver	A comprehensive sample driver that demonstrates what to enable in the WPD DDI for media transfer scenarios (such as music and photos). This sample supports media synchronization with Windows Media Player, and also emulates interaction with hardware.

The WPD Driver Kit is included in the Windows Driver Kit (WDK). For information about downloading the WDK, see: http://www.microsoft.com/whdc/devtools/wdk/WDKpkg.mspx

The documentation for the WPD Driver Kit is found on MSDN at: http://msdn.microsoft.com/en-us/library/dd419925.aspx

Windows Media Device Manager SDK

The Windows Media Device Manager (WMDM) SDK enables you to build desktop applications and components that can communicate with connected portable devices. WMDM enables your application or component to enumerate, explore, and exchange files with a device, query for metadata, and request play count information. Applications or components built on WMDM have a consistent API for communicating with a wide range of devices including Media Transfer Protocol (MTP), Mass Storage Class (MSC), RAPI, and other devices built on both the latest and previous versions of Windows Media technology.

The Windows Media Device Manager SDK is available at: http://msdn.microsoft.com/en-us/windows/bb190309.aspx.

Microsoft Device Experience Development Kit

The Microsoft Device Experience Development Kit provides detailed information and material that you would need to know in order to develop Device Stage™ experiences for Portable Devices. The development kit includes device development guides, planning worksheets, tutorials, and development samples that you can use when developing a Device Stage experience on Windows 7. For portable devices, Device Stage supports the industry-standard Media Transfer Protocol (MTP) 1.0 with device services that enable a new rich set of features in Windows 7.

The development kit along with other pertinent information to build a complete Windows Device Experience is available at: http://www.microsoft.com/whdc/device/DeviceExperience/default.mspx

The kit is free to download and use.

Windows Logo Kit

The primary use of the Windows Logo Kit (WLK) is for Windows Logo Program device certification. This kit can also be used for product development. We encourage its use during the product development cycle of hardware in order to ensure device compliance with both Windows and industry standards. The kit includes several tests designed to validate device implementation and behavior at multiple levels. There are tests for USB compliance, Media Transfer Protocol (MTP) compliance, and Windows Portable Devices (WPD) platform compliance that also cover device services validation.

There is a significant amount of information available about the WLK, including user guides and video tutorials. For more information about the WLK see: http://www.microsoft.com/whdc/winlogo/WLK/default.mspx

The kit is free to download and use.

Other Resources

Windows Portable Devices node on Windows Hardware Developer Central

http://www.microsoft.com/whdc/device/wpd/default.mspx

Windows Portable Devices on Microsoft Developer Network

http://msdn.microsoft.com/en-us/library/dd388998(VS.85).aspx

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

Driver Dev Guide: WPP Tracing in your WPD Driver

wpdblog — Sun, 01 Apr 2007 21:14:00 GMT

WPP Software Tracing is the recommended way to log trace and error messages in your WPD driver. WPP, short for Windows Software Trace PreProcessor, provides an efficient real-time event logging mechanism. In addition, WPP traces include the system timestamp and can be used as a way to measure performance, for example by calculating the elapsed time between function calls.

From OutputDebugString to WPP

The WPD sample drivers in the Windows Driver Kit (WDK) log error messages using a CHECK_HR function that wraps around OutputDebugString. While OutputDebugString is simple to use during development, it necessitates an active debugger connection in order to view the traces, and should be used minimally in shipping code. WPP tracing is much more lightweight, flexible, and preferable for a range of tracing applications: logging errors for diagnosing failures, tracing code execution during development, to name a few.

How to switch your WPD driver's tracing from OutputDebugString to WPP transparently:

Step 1. Remove the original CHECK_HR() function definition (it can be found in WpdHelloWorldDriver.cpp or WpdWudfSampleDriver.cpp for the WPD samples) and its declaration in stdafx.h.

Step 2. Add the following code (include the WPP config comment blocks) to stdafx.h:

// TODO: Choose a different trace ID for your WPD driver
#define MYDRIVER_TRACING_ID      L"Microsoft\\WPD\\MyWpdDriver"

// TODO: Choose a different trace control GUID for your WPD driver
// TODO: Define trace flag bits for your WPD driver

#define WPP_CONTROL_GUIDS                                                   \
    WPP_DEFINE_CONTROL_GUID(                                                \
        MyWpdDriverCtrlGuid, (da5fbdfd,1eae,4ecf,b426,a3818f325ddb),        \
                                                                            \
        WPP_DEFINE_BIT(TRACE_FLAG_ALL)                                      \
        WPP_DEFINE_BIT(TRACE_FLAG_DRIVER)                                   \
        WPP_DEFINE_BIT(TRACE_FLAG_DEVICE)                                   \
        )                             

//
// Prefer trace statement that is based on
//     - the standard trace LEVEL (evntrace.h), and
//     - specific flag bit.
//
#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
           WPP_LEVEL_LOGGER(flags)
               
#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
           (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

//
// This comment block is scanned by the trace preprocessor to define our
// Trace and TraceEvents function.
//
// begin_wpp config
// FUNC Trace{FLAG=TRACE_FLAG_ALL}(LEVEL, MSG, ...);
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

// MACRO: CHECK_HR
// Configuration block that defines trace macro. It uses the PRE/POST macros to include
// code as part of the trace macro expansion. CHECK_HR is equivalent to the code below:
//
// {if (hrCheck != S_OK){  // This is the code in the PRE macro
//     DoTraceMessage(TRACE_FLAG_ALL,  "%!STDPREFIX!" MSG " hr= %!HRESULT!", ..., hrCheck)
// ;}}                              // This is the code in the POST macro
//                                 

// begin_wpp config
// USEPREFIX (CHECK_HR,"%!STDPREFIX!");
// FUNC CHECK_HR{FLAG=TRACE_FLAG_ALL}(hrCheck, MSG, ...);
// USESUFFIX (CHECK_HR, " hr= %!HRESULT!", hrCheck);
// end_wpp

#define WPP_FLAG_hrCheck_PRE(FLAGS, hrCheck) {if(hrCheck != S_OK) {
#define WPP_FLAG_hrCheck_POST(FLAGS, hrCheck) ; } }
#define WPP_FLAG_hrCheck_ENABLED(FLAGS, hrCheck) WPP_FLAG_ENABLED(FLAGS)
#define WPP_FLAG_hrCheck_LOGGER(FLAGS, hrCheck) WPP_FLAG_LOGGER(FLAGS)

Step 3. Add a RUN_WPP directive to your sources file:

RUN_WPP= $(SOURCES) -scan:stdafx.h

Step 4. Add the WPP initialization and cleanup routines to DllMain:

// DLL Entry Point
extern "C" BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved)
{
    if(DLL_PROCESS_ATTACH == dwReason)
    {
        g_hInstance = hInstance;
      
        //
        // Initialize tracing.
        //
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);
    }
    else if (DLL_PROCESS_DETACH == dwReason)
    {
        //
        // Cleanup tracing.
        //
        WPP_CLEANUP();
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

Step 5. For each .cpp file, add a #include <filename>.tmh after the regular includes:

//
// WpdBaseDriver.cpp
//

#include "stdafx.h"
#include "WpdBaseDriver.h"

// Include the WPP generated Trace Message Header (tmh) file for this .cpp
#include "WpdBaseDriver.tmh"

...

Repeat Step 5 for all other .CPP files.

Step 6. Rebuild your driver. Since we replaced the CHECK_HR function with an equivalent WPP macro that has the same signature (our WPP changes were "under the hood"), no changes are needed for any code that uses CHECK_HR. You can continue to use CHECK_HR the same way as before :).

The WPP preprocessor will process stdafx.h for tracing macros, and generate a Trace Message Header (tmh) file for each cpp file in the obj folders.

Inspecting the preprocessor output for each .CPP file that calls CHECK_HR (generated using make WpdBaseDriver.pp), you will notice that all CHECK_HR trace statements have been wrapped by WPP function calls, while the tracing text and WPP functions are defined in WpdBaseDriver.tmh.

The most common WPP-related compilation errors you may encounter are due to mismatched format identifiers and parameters (e.g. if your format string contains an extra %d that does not match an argument) or missing entries in the WPP_CONTROL_GUIDS macro.

More WPP Tracing Macros

We've also defined TraceEvents and Trace functions in stdafx.h that are general purpose WPP trace macros wrapping DoTraceMessage. These can be used for both error and non-error trace logging using a combination of levels and flags. For examples on how to use them in your driver, refer to the UMDF sample drivers in the WDK.

To understand the WPP declarations used in stdafx.h, customize the CHECK_HR macro, or to define your own tracing macros, visit the WPP macros guide which describes the WDK tracedrv sample in detail.

Generating and Viewing Traces

To generate traces, you can use Traceview (UI) or Tracelog (command line). TraceView also allows you to view traces in real-time as they are logged. These are available in the WDK. A quick way to get started is to create a new log session from Traceview using the PDB file that contains the private symbols for your driver. Alternatively, you use a .CTL file that specifies your driver as a trace provider (replace own values below):

da5fbdfd-1eae-4ecf-b426-a3818f325ddb    MyWpdDriverCtlGuid

Converting Binary Traces to A Human-Readable Form

WPP traces log to a binary ETL format. To convert them to text, supply Trace Format (TMF and TMC) files that can be generated from the .PDB file using TracePDB. For more details, refer to the tracing tools section in the MSDN docs.

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

Driver Dev Guide: How to Post Events from your WPD Driver

wpdblog — Sat, 17 Mar 2007 01:57:00 GMT

DimeBy8 wrote a great post on how a WPD application can receive driver-initiated WPD PnP events; this post will describe the driver's side of our eventing story. While this mechanism is "under the covers" for most WPD application developers, it helps to get an end-to-end picture of how stuff works in WPD land, especially if you are thinking about writing a WPD driver and application for vertical scenarios that involve posting and receiving custom events.

Standard WPD Events and Parameters

Here is the list of standard WPD events. These GUIDs are defined in PortableDevice.h. When you begin accessing these events as a WPD application or driver), you may soon realize a missing piece of information: what/where are the parameters for these events? The Event parameters are described in more detail in the Basic WPD Device Driver Requirements WHDC whitepaper, under Requirements for Event Parameters.

A snippet from the whitepaper that describes the required parameters for WPD_EVENT_OBJECT_UPDATED:

WPD_EVENT_OBJECT_UPDATED

This event is sent after an object has been updated so that any connected client should refresh its view of that object.

Parameters

WPD_EVENT_PARAMETER_PNP_DEVICE_ID

Required.

WPD_EVENT_PARAMETER_EVENT_ID

Required.

WPD_OBJECT_PERSISTENT_UNIQUE_ID

Required.

WPD_EVENT_PARAMETER_OBJECT_PARENT_PERSISTENT_UNIQUE_ID

Required.

WPD_EVENT_PARAMETER_CHILD_HIERARCHY_CHANGED

Required if the object hierarchy at any level under this object has changed.

Event parameters matter when you're sending a standard WPD event from your driver. For example, when receiving WPD_EVENT_OBJECT_UPDATED, applications may utilize information such as WPD_OBJECT_PERSISTENT_UNIQUE_ID to determine which object's properties would need to be refreshed in their properties view.

*Aside: One consequence of supporting any WPD event that requires the Persistent Unique ID of objects is that your driver needs to support this property (but this is a required property anyway for most content objects). The list of required properties is also covered in Basic WPD Device Driver Requirements.

Posting a WPD Event from Your Driver

Now that you know what parameters to send with a WPD event, posting the event is a three step process:

Initialize an IPortableDeviceValues to hold the event parameters.
Serialize the IPortableDeviceValues to a BYTE buffer.
Call IWDFDevice::PostEvent with the EventGuid = WPD_EVENT_NOTIFICATION and the serialized buffer. Only WdfEventBroadcast events are supported, which means all WPD applications that call IPortableDevice::Advise can receive the event your driver posts.

BYTE* pBuffer  = NULL;
DWORD cbBuffer = 0;

// Populate the event parameters
hr = pIPortableDeviceValues->SetGuidValue(WPD_EVENT_PARAMETER_EVENT_ID, WPD_EVENT_OBJECT_UPDATED);

// Set other required event parameters here ....

if (hr == S_OK)
{
    // Serialize the event parameters to a buffer 
    hr = pWpdSerializer->GetBufferFromIPortableDeviceValues(pIPortableDeviceValues, &pBuffer, &cbBuffer);
}

// Send the event.
if (hr == S_OK)
{
    hr = pIWDFDevice->PostEvent(WPD_EVENT_NOTIFICATION, WdfEventBroadcast, pBuffer, cbBuffer);
}

// Cleanup ...
CoTaskMemFree(pBuffer);
pBuffer = NULL;

Defining a Custom WPD Event (and adding it to WpdInfo/WpdMon's Vocab!)

WPD's extensibility mechanism allows for custom events to be defined very easily. You define a new GUID for your custom event, and define PROPERTYKEYs for your event parameters (or reuse existing PROPERTYKEYs). On the application side, check for this custom event GUID the same way as you handle a WPD event, and process the event. Your driver should also report these new event(s) when responding to WPD_COMMAND_CAPABILITIES_GET_SUPPORTED_EVENTS and WPD_COMMAND_CAPABILITIES_GET_EVENT_OPTIONS.

Both the WPDInfo and WPDMon WDK tools can receive and display custom WPD events in the raw GUID form, which means you already have a handy way to validate your driver's event posting functionality without needing to write a WPD application.

You can even "teach" our tools to translate the custom event GUID to its symbolic name. This can be done by adding an entry to the WpdInfo.GUIDs file (this is a text file usually located in the same folder path as the tool exes), and restarting the tools to reload this file. In a similar way, symbolic names for your custom PROPERTYKEYs can go into WpdInfo.Properties file, custom commands in WpdInfo.Commands, etc.

It's important to note that updating these WpdInfo.* dictionary files only enables the WPD tools in your PC to translate custom GUIDs and PROPERTYKEYs to symbolic string like names, other WPD applications and drivers know nothing on these custom values that are specific to your driver and application.

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

WPDMon Gotchas

wpdblog — Tue, 06 Feb 2007 02:40:00 GMT

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.

Debugging Your WPD Driver with Visual Studio 8

wpdblog — Fri, 02 Feb 2007 00:12:00 GMT

WPD drivers are based on the Windows Driver Foundation (WDF) – User-Mode Driver Framework (UMDF) platform. UMDF drivers provide greater stability and security than kernel-mode drivers while providing comparable performance. And, UMDF drivers allow the use of user-mode debuggers such as Visual Studio 8. (Debugging a driver in user-mode tends to be faster than debugging in kernel-mode because an error only affects the current process rather than the entire computer.)

General Visual Studio 8 Debugging Tips
Once your driver is installed, you can create a debugging project in Visual Studio 8 by following these steps:

1. Open Visual Studio 8 and select “File/New/Project from Existing Code…” menu.

2. Follow the steps in the “Welcome to the Create Project form Existing Code Files Wizard” (specifying the language, the location of your driver source files, a project name, and so on).

3. Open your newly created project.

4. Select the “Debug/Attach to Process…” menu and then choose WudfHost.exe in the list of Available Processes that appears in the “Attach to Process” dialog.

Once you complete the above steps, you can begin setting breakpoints in your driver’s source code and debug your driver.

Tips for Debugging WPD Driver Initialization Code
A WPD driver’s initialization code (for example, the code found in WpdBaseDriver::Initialize() in the two WPD sample drivers that ship with the Windows Driver Kit), executes during the installation of your driver. In order to debug this initialization code, you’ll need to accomplish the following tasks:

1. Create a debugging project in Visual Studio 8 (as described in the previous section).

2. Open an instance of regedit.exe and specify a delay period (in seconds) for the WudfHost.exe process. This delay is specified using the following key: \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a…}\HostProcessDbgBreakOnStart

3. Force the WUDFHost.exe process to reload. This can be done in a couple of ways, depending on what your device configuration is:

a) From Device Manager, Disable and then Enable your device's WPD devnode

b) If your device has a physical connection to the PC, unplug and then re-reconnect your device.

4. Upon driver reload, start Visual Studio 8, open your debug project, and attach to the WudfHost.exe process. As a side effect, you may see Device Manager hanging when you reload the driver, while WudfHost.exe is waiting for a debugger to connect.

The delay which you set for the …\HostProcessDbgBreakOnStart value provides the necessary time to start the debugger prior to the installation of your driver. (For example, a value of 0x00000040 would delay the installation for 64 seconds.) This delay allows you time to attach to the process, set a breakpoint in your initialization code, and begin debugging.

For more information about the HostProcessDbgBreakOnStart value, refer to this MSDN topic.

Update [August 7, 2009]: The WDF team has provided an excellent tool that makes debugging both kernel mode and user mode WDF drivers much easier. The WDFVerifier is available in the Windows Driver Kit (WDK). For details, refer to the WDFVerifier MSDN page. In addition, we recommend these in-depth posts by Bob Kjelgaard, an SDET from the WDF team, covering basic and advanced usages of WdfVerifier:

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

Building Driver Samples from the WDK

wpdblog — Wed, 31 Jan 2007 10:37:00 GMT

Help! The WPD driver sample doesn't build!

Seeing this error while building the WPD driver samples using the Windows Driver Kit (WDK) build environment?

errors in directory c:\winddk\6000\src\umdf\wpd\wpdhelloworlddriver
NMAKE : fatal error U1073: don't know how to make 'C:\WinDDK\6000\lib\mfc\i386\atls.lib'
nmake.exe /nologo BUILDMSG=Stop. -i BUILD_PASS=PASS2 LINKONLY=1 NOPASS0=1 MAKEDLL=1 MAKEDIR_RELATIVE_TO_BASEDIR=src\umdf\wpd\wpdhelloworlddriver MAKEDIR_LOWERCASE=c:\winddk\6000\src\umdf\wpd\wpdhelloworlddriver failed - rc = 2

No worries, this is expected. The is because the WDK build environment provides an older version of the ATL libraries than what WPD needs.

To build the WPD driver samples provided with the WDK, follow these step-by-step instructions (MSDN library section: "Win32 and COM Development\Windows Driver Kit\Device and Driver Technology\Portable Devices\Windows Portable Devices\WPD Programming Guide\Familiarizing Yourself with the Sample Driver" ).

In a nutshell, you will need to install Visual Studio 2005, and reference the ATL libraries from there. This build environment configuration only needs to be done the first time, and you'll be good to go for building our sample drivers.

Update [August 7, 2009]: The ATL-related build issues in the first section have finally been addressed in the WDK for Windows 7 (a.k.a WDK 7.0.0). You can get the latest WDK here. To build the drivers, simply type "build -cZ" or "bcz" from the WDK command window for the target OS of your choice. See this WDK 7.0.0 RTM release note for the complete list of build environments and target operating systems applicable to the WPD driver samples.

Which sample should I use?

To get a running start on writing a WPD driver, we recommend using the WpdHelloWorldDriver as a template, it covers some basic driver functionality such as retrieving properties, enumeration, and reporting device capabilities.

More advanced driver functionality is demonstrated by the WpdWudfSampleDriver (a.k.a. the WPD Comprehensive Sample Driver), such as driver-initiated events, object management, and content transfer. On Windows Vista, this sample driver is also visible from Windows Image Acquisition (WIA) camera applications (using the WPD-WIA compatibility layer). More on WIA in future posts....

To develop a WPD driver that enumerates in Windows Media Player 11, you can start with the WpdWudfSampleDriver with a few extra modifications.

Update [August 7, 2009]: The WDK 7.0.0 now contains an updated WpdWudfSampleDriver sample that supports enumeration in Windows Media Player.

Known issues in the sample drivers

Both sample drivers do not enumerate in Windows Media Device Manager (WMDM) applications (such as Windows Media Player) by default. See the previous section for an example of enabling that with the comprehensive sample driver.

Both sample drivers install as "root enumerated" devices, i.e. they install using the Add Legacy Hardware option. Hence, they are shown as always connected in Device Manager. While this provides an easy way to install and test a device driver, this means that certain Plug-and-Play functionality may not be available (such as Autoplay in Windows Vista). To enable Autoplay, one way is to install and configure a bus driver for your device (for a sample, refer to the Toaster Bus Driver in the WDK).

What tools can I use?

During development, we highly recommend using the WpdInfo GUI tool, which uses the WPD API to access your driver. You can query driver capabilities, browse the object tree, send raw WPD commands, update properties, etc.

Other useful WPD tools:

All these tools are developed in-house, and used extensively by us for development and troubleshooting. :)

Basic driver requirements

This whitepaper lists basic requirements that your driver should satisfy to work well with most WPD applications, such as the required properties that a particular object content type should support. These requirements are also implemented as logo tests for the Windows Vista Cellular Handset Basic Logo for Windows Logo Program v3, but are generic enough to apply to any WPD driver.

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