Remote Debugging in Windows Embedded Standard 2009

4/24/2012

Microsoft Corporation

July 2009

Summary

This technical article contains information about how to configure your Windows Embedded Standard 2009 image and Microsoft Visual Studio 2008 project to remotely debug applications on your device.

Introduction

Developing Applications for Standard 2009

Debugging on a Device

Resolving Common Device Issues

Configuring Your Image for Remote Debugging

• Add Components
• Configure Components
• Add Visual Studio Remote Debugging Monitor

Configuring Your Visual Studio Project

• Configure a Native Code Project
• Configure a Managed Code Project

Preparing the Device

• Verify Network Connectivity
• Configure Permissions
• Run the Remote Debugging Monitor

Debugging the Remote Application

• Start the Debugger
• Debug the Application

Conclusion

Introduction

As every embedded software developer knows, you must debug an application on your device. Several factors make this task challenging:

• The device may, by design, have a significantly different hardware configuration than the development computer that the application was developed on.
• The embedded operating system on the device often has a very different configuration than the operating system on the development computer where the application was developed.
• Other applications that are running on the device may cause unanticipated issues.

Fortunately, you can debug applications directly on most devices by using Visual Studio 2008 and remote debugging.

Developing Applications for Standard 2009

The typical development cycle for an application targeting Windows Embedded Standard 2009 is as follows:

• Develop and debug your application on the development computer
  Because Standard 2009 is a componentized version of Windows XP Professional, the most efficient and effective way to begin application development is to use a development computer with a fully featured integrated development environment such as Visual Studio 2008.
  You can select from two development frameworks when you develop an application:
  • Native Win32 APIs
  • Microsoft .NET Framework
    Each framework requires a specific configuration to enable remote debugging. For more information, see Configuring Your Visual Studio Project.
• Componentize your application
  After you debug the application on the development computer OS, you can run it on a Standard 2009 device if you install the necessary application files and configure it correctly.
  Next, add the required components to the run-time image. Whether you use Component Designer to create a custom component for the application or another tool, this is required to configure the application and create the run-time image.
  You can use the following tools to help componentize your application:
  • Dependency Walker
    Dependency Walker lists all static dependencies of an application. You can use this tool to begin the componentization process of an application. You can also use it to log the loading of DLLs on a running application.
  • InCtrl5
    InCtrl5 takes a snapshot of the system before and after you install an application. This snapshot provides information about which files were copied and which registry entries were added.
  • Process Monitor
    Process Monitor monitors the runtime file and registry access of a process. This tool is useful for both initial componentization and for monitoring file and registry access failures on the device itself.
    For more information about how to create a custom component using Component Designer, see Creating Custom Components for Windows XP Embedded.
• Add the application to your run-time image
  You can add a custom component that contains your application in Target Designer, or use a USB Flash Device (UFD) to copy the files to your post-FBA (First Boot Agent) run-time image.
  The result is that the device contains your application files and is configured correctly for the application to execute as required.
• Test and debug your application on the device
  At this point, you can test your application on the device to make sure that it works as expected. As you find

Debugging on a Device

Debugging your application on a single-purpose embedded device can be challenging. When you debug application failures, start by checking the following areas:

• Different Device Hardware
  If the hardware of the device does not match the development computer, it may be an area of concern when you debug. For example, the device might have different boot media, CPU, storage devices, video card, and so on.
• Limited Computing Resources
  Keep in mind that the device may have limited resources compared to even the most modest desktop computer. As a cost consideration, many embedded devices use only enough hardware to get the job done. Therefore, the application might be constantly running under a "stress test" environment. Running out of system memory can put the application's error handling logic to the test. In addition, task synchronization may react differently with only one CPU core and a quarter of the processor speed. These are only some of the application issues that might manifest when the application runs on the device hardware.
• Different Peripherals
  The device will most likely have a different set of peripheral devices attached to it, and the set of peripherals plays a significant role in the function of the device. It can be especially challenging when the missing peripherals are the mouse and keyboard as is the case in a remotely-administered device. The peripherals that are attached must function flawlessly and any missing peripherals must not cause an issue.
• Debugging tools installed
  Even if the device has the storage, RAM, and CPU power to install and run the debugging tools, installing debugging tools may alter the device debugging environment with unnecessary process, resource consumers, frameworks, and so on. Although you must run an application on the device to support remote debugging, adding extra tools to the device can present a challenge in determining what exactly is causing a problem in the application.

Resolving Common Device Issues

There are several common device issues that you may have to resolve in a debugging session:

• Missing or Incorrect Drivers
  The application may be malfunctioning because of a missing or incorrect driver.
• Missing Dependencies
  Even the most thorough analysis process can miss a required, but undiscoverable, OS dependency.
• Incorrect Installation
  A configuration or file associated with the application may not have been set up or copied correctly to the device.
• Resource Allocation Issues
  The application may request more of a resource than is available or the resource allocation task may take longer than expected.
• Logic Error
  Despite the extensive testing of the application that was done prior to installing it on the device, a logic error may have been overlooked.

Configuring Your Image for Remote Debugging

In This Section:

Add Components

Configure Components

Add Visual Studio Remote Debugging Monitor

Add Components

To support remote debugging, your run-time image must contain the necessary components. In Target Designer, add and configure the following components:

• File Sharing
• Event Log
• Net.exe Utility
• TCP/IP Utilities
• Windows Firewall/Internet Connection Sharing (ICS)
• Administrator Account
• Domain Participation [Optional]
• Remote Registry Service [Optional]
• User Account

It is useful if these components are in a macro component. For more information about macro components, see Tutorial: Creating a Custom Component.

Configure Components

To debug remotely, you must configure the following components:

• Administrator Account
  Select the Settings of the Administrator Account component and verify that a password has been set. A password must exist before remote debugging can occur.
• User Account
  Select the Settings of User Account component and verify that the Username and Password have been set. The username and password must correspond to the user account that was used to log on to the development computer previously. Having a matching Username and Password simplifies the authentication process when debugging remotely.
• Windows Firewall/Internet Connection Sharing
  To debug remotely, the DCOM (TCP 135) and IPSEC (UDP 4500 / UDP 500) ports must be unblocked. If these ports are not unblocked when you try to start a remote debugging session by using Visual Studio 2008 or the Visual Studio Remote Debugging Monitor, the Configure Firewall for Remote Debugging dialog box appears. You can unblock the ports by changing the setting in this dialog box.
  

Add Visual Studio Remote Debugging Monitor

To achieve the most accurate debugging result, it is important that you preserve the original device configuration as much as possible. However, to debug remotely, you must run the Visual Studio Remote Debugging Monitor (MSVSMon) from the device, not the development computer. Fortunately, MSVSMon is a small application and does not have any installation prerequisites.

There are several options for putting MSVSMon on the device:

• Install MSVSMon
  If the run-time image on the device has the necessary components and you can run an installer, install MSVSMon on the device. The installer is located on the Visual Studio 2008 Install DVD at root\Remote Debugger\<architecture>.
• Create a custom component
  The recommended and least intrusive method for installing MSVSMon on the device is to create a custom component for MSVSMon and add the component to the run-time image.
  Be aware that the component exists only to contain the files. The only task that might cause an issue is that the directory structure for MSVSMon is not flat. The 1033 directory contains resource DLLs.
  
• Copy the application files
  Copying the MSVSMon files to the device is another method you can use. You can use any available mechanism for copying the MSVSMon files to the device, including file sharing, UFD, floppy disks, and so on.

Configuring Your Visual Studio Project

In This Section:

Configure a Native Code Project

Configure a Managed Code Project

To use your Visual Studio project for remote debugging, you must start the remote Windows debugger instead of the local debugger.

In addition, to simplify the remote debugging experience, you must change the output directory of the project to a directory location that the device can access. The easiest way to do this is to use a shared directory between the development computer and the device. For example, you can point the shared drive of both computers to <your server>\debug.

Alternatively, you can mirror the output directory from the development computer on the device. For example, if you set the output directory for the project to c:\debug, you must then copy the application files to c:\debug on the device. This method is less intrusive, but it requires you to copy the output directory to the device after each rebuild of the application.

Configure a Native Code Project

To configure a native code project for remote debugging

1. Select the debugger to start.

   1. On the Visual Studio menu, select Project, and then Properties.
   2. In the Property Pages dialog box, on the left side, under Configuration Properties, select Debugging, as shown in the figure below.
      
   3. In the Debugger to launch list, select Remote Windows Debugger.
   4. Set Remote Command to $(TargetPath).
   5. Set Remote Server Name to the name of your device (for example, "WES-TARGET").
   6. For No Authentication mode debugging, set Connection to Remote with no authentication (Native Only).
      See Configure Permissions for more information.

2. Change the output file.

   1. In the Property Pages dialog box, on the left side, under Configuration Properties, select Linker, as shown in the figure below.
      
   2. Under Linker, select General.
   3. Set the Output File to <shared drive>\debug\$(ProjectName)\$(ProjectName).exe.
   4. Click OK.

Configure a Managed Code Project

To configure a managed code project for remote debugging

1. Select the debugger to start.

   1. On the Visual Studio menu, select Project, and then Remote-Managed Properties.
   2. In the Remote-Managed dialog box, on the left side of the window, click Debug.
      
   3. Select the Use remote machine check box.
   4. Set the value for Use remote machine to the name of your device (for example, "WES-TARGET").

2. Change the output file.

   1. In the Remote-Managed dialog box, on the left side of the window, click Build.
      
   2. Under Output (you may have to scroll down), set the path to <shared drive>\debug\<project name>\.
   3. Click OK.

Preparing the Device

In This Section:

Verify Network Connectivity

Configure Permissions

Run the Remote Debugging Monitor

Verify Network Connectivity

The easiest way to check network connectivity is to ping the device from the development computer.

To verify network connectivity

• On the development computer, open a Command Prompt window, and at the command prompt, use the ping command to test the connection to your device.

  ping <your device name>
  

  If the ping is successful, the development computer and device are communicating.

Configure Permissions

MSVSMon runs in two different Authentication modes, Windows Authentication and No Authentication. Windows Authentication mode is required for debugging managed applications.

In Windows Authentication mode, the username and password of the user on the development computer must match the user on the device. In the case where the development computer is domain joined and the device is not, you must create a local account on the development computer with the same username and password as the domain account.

In No Authentication mode, user authentication is not performed. If you select this mode in MSVSMon, make sure that you configure the debugger for this mode in the Project Properties (see Configure a Native Code Project).

To select the MSVSMon authentication mode

1. On the device, start MSVSMon.

2. On the Tools menu, select Options.

   

3. In the Options dialog box, select Authentication mode.

4. Click OK.

Run the Remote Debugging Monitor

MSVSMon must be running on the device for remote debugging to function. There are several ways to run MSVSMon:

• Run at Startup
  Add MSVSMon.exe to the list of applications to run at startup. For the Windows Explorer shell, configure the "HKLM\Software\Microsoft\Windows\CurrentVersion\Run" registry key.
• Run as a Service
  You can select this option when you install MSVSMon. However, running MSVSMon as a service is the most intrusive method. You must add more components to your image configuration to enable starting and stopping of the service easily.
• Manually Start MSVSMon
  Start MSVSMon.exe from the device. If this is not possible, you can run MSVSMon at startup.

Debugging the Remote Application

In This Section:

Start the Debugger

Debug the Application

Start the Debugger

There are two methods you can use to start the debugger:

• Start
  On the Visual Studio menu, select Debug, then select Start Debugging. This method connects the device to the development computer, starts the application on the device, and connects the remote debugger.
• Attach
  On the Visual Studio menu, select Debug, then select Attach to Process. This method connects the device to the development computer and presents a list of the processes that are running on the device. You must use this method to start the debugger if the application being debugged runs at startup.
  

Debug the Application

When the remote debugging environment is set up correctly, you can determine the cause of the error by using standard debugging techniques. For example, you can:

• Set breakpoints
• Step through code
• Query variables

For more information about debugging techniques, see the book by Mario Hewardt and Daniel Pravat, Advanced Windows Debugging.

Conclusion

What you have learned

When testing your applications on your device, you can debug applications directly by using Visual Studio 2008 and remote debugging. You can use the debugging techniques in this technical article to examine how the application runs on the intended hardware.