Going Virtual II: Remote Debugging

  • Article

 

Mike Hall
Microsoft Corporation

July 2, 2004

Applies to:
    Microsoft® Windows® XP Embedded

Summary: Learn how to set up remote debugging when you are running the Windows XP Embedded image inside Virtual PC. (10 printed pages)

Contents

What You Need
Before You Start
Pinging from PC to Virtual PC
Remote Debugging
Building the Application
Debugging the Application

Last month we took a look at booting and running Windows XP Embedded in Microsoft Virtual PC. There are a number of advantages to booting and running Windows XP Embedded in the Virtual PC environment. First, you don't need additional hardware. Second, you can build and test your Windows XP Embedded image on your development PC without needing to dual-boot your development PC. The other really neat thing about running the Windows XP Embedded image inside Virtual PC is the ability to remote debug applications on your development PC, which is going to be the focus for this month's article.

Why would you need to debug an application running on Windows XP Embedded? Since XPE is a componentized version of Windows XP Professional there should be binary compatibility for the applications you are already running on the desktop, right? The answer is "yes," your applications 'should' run, unmodified, on Windows XP Embedded. This assumes that you have included all the required operating system components, and have added all the support files your application needs (DLLs, fonts, bitmaps, audio files, movie files, data files, etc.).

For this month's article we're going to write a fully featured Win32 application (a typical Hello World application) and build and deploy this application to a Windows XP Embedded operating system image, then debug the application.

The steps outlined in this article are of course applicable to a Windows XP Embedded image running on "real" hardware. Time to buckle up, let's get cracking with writing and debugging an application.

What You Need

Here's what you will need to follow along:

  • Windows XP Embedded tools (download from here)
  • Booted and running Windows XP Embedded operating system (take a look at April's Get Embedded article)
  • Visual Studio .NET 2003
  • Starbucks Grande Vanilla Latte and a slice of lemon pound cake (optional)

Before You Start

Before we get started building our application, there are some changes we need to make to our Windows XP Embedded operating system, specifically…

  • Set the Administrators Password (so we can connect remotely)
  • Include the "Net Command" component into the operating system
  • Include the Visual Studio .NET 2003 remote debug components in the operating system

Let's take each one of these in turn…

Setting the Administrator password
By default, the Administrator account has a blank password, this doesn't let us connect remotely to the device. We need to be able to remotely connect to a file share on the Windows XP Embedded device to copy the application from Visual Studio .NET 2003 to the running Windows XP Embedded image. Of course you could just remotely attach to an already running application, in which case you wouldn't need the file share.

The Administrator password is blank by default and can be changed in the project settings within Target Designer. To do this, locate and select the Administrator Account in your project workspace. In the configuration window, click Advanced. Select the cmiUserPassword property, and click Edit. Set a strong Administrator password.

Figure 1: Setting the Administrator password

Including the "Net Command" component into the operating system
We also want to be able to make sure the network connections are working from our Virtual PC. There are three components we should add to the platform. The first is TCP/IP Utilities component, which is a wrapper for applications such as "ping" (very useful). The second component is Net.exe Utility. We will use the net command to check on the exposed shares from our Virtual PC. And the third component is CMD – Windows Command Processor, since ipconfig, ping, and net are all command line tools, we will obviously need to include the command line component in the build. You can find each of the components by searching the catalog. It might actually be useful to create a 'debug' component that you can add to your platform when testing a build.

Including the Visual Studio .NET 2003 remote debug components in the operating system
The final step before building our Windows XP Embedded operating system image is to add the files we need for remote debugging Visual Studio .NET 2003. The main application file is called msvcmon.exe. This can be located in the following folder (assuming a default install of Visual Studio .NET 2003):

C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\Debugger\Native

Here's the list of files from the Visual Studio Native Debug folder:

  • msvcmon.exe
  • msvcr71.dll
  • NatDbgDM.dll
  • NatDbgTLLoc.dll
  • NatDbgTLNet.dll

I used Component Designer to create a component that includes the files from this folder. The component creates the folder \Program Files\NativeDebug on my target device. (You can, of course, decide to put the files anywhere on your target device.) For information on building Windows XP Embedded components, take a look at this article from Jon Fincher.

Pinging from PC to Virtual PC

Build and deploy your image to Virtual PC (take a look at April's Get Embedded article to see how this works). Note that the boot drive for our Windows XP Embedded "Virtual PC" image is Drive "D." This is important; you will see why in a few seconds…

Now that you have the Windows XP Embedded image booted and running (you do have the image booted and running, right? OK, good, just wanted to check, don't want you falling behind!), we need to make sure that our development PC and target can see each other.

On the Virtual PC device get the IP address by running cmd and then typing ipconfig. The IP address for my Virtual PC is 192.168.2.2. From your desktop PC, try to ping the Virtual PC. Again, to do this, open a command prompt, type: Ping 192.168.2.2 (substitute your Virtual PC's IP address here). You should be able to "see" the Virtual PC.

While you're at the command prompt on your development PC we might as well get its IP address. Type ipconfig. My IP address is 192.168.2.1. Now try pinging the desktop PC from the Virtual PC; if you can ping in both directions we're in good shape.

Remote Debugging

This is where life gets interesting…

There are a few hoops we need to jump through to get remote debugging working.

The first is to run the native code debug component msvcmon on the target. This is a command-line tool, and there are some "gotchas" when running it. Here's the command line I've been using:

 Msvcmon –tcpip –anyuser –timeout -1

Msvcmon defaults to using pipes, and also times out after 15 minutes (of no connections), so we want to set the timeout to infinite (-1). In this case I'm allowing any user to connect to the Virtual PC image, I could, of course, restrict the users I allow to connect.

Click here to see larger image

Figure 2: Screenshot of msvcmon (click picture to see larger image)

Our Virtual PC is now waiting for a remote debug connection. There are two ways to debug applications. I can either: connect to an already running application or compile/link/deploy a new application to the Virtual PC and debug this remotely. The second option is the one we're going to run with for this article.

So, here's the question, how do we get our remote application (and debug symbols) down onto the target? Visual Studio .NET 2003 isn't going to download the application to the Virtual PC when we build the application, the application will get built on our development PC; if we debug the application this will also launch and run on our development PC, right?

We need to make a link between our development PC and our target (Virtual PC). So, on your development PC, get to a command prompt and type the following:

Net use k: \\192.168.2.2\D$

Note that you could substitute K: for another drive if you prefer. You will be prompted for username (Administrator) and password (whatever your administrator password is) before the drive redirection works correctly.

Now K: points to the root of the D:\ drive (our boot drive) on the Virtual PC. I bet you can figure out where this is going … once we have a drive connection to the remote device we can then configure Visual Studio .NET 2003 to copy its output files (EXE, PDB) to the remote system. It's perhaps a good idea to create a temporary folder on the remote device. I'm going to call my temp folder NativeDebug. (Create the remote folder from your desktop by using md k:\NativeDebug).

Building the Application

Now, finally, it's time for Visual Studio .NET 2003. Let's go ahead and build a fully featured Win32 "Hello World" style application.

Figure 3 shows the application configuration in Visual Studio .NET 2003.

Figure 3: The application configuration in Visual Studio .NET 2003

We're building a Win32 GUI based project, called XPE_Hello. You can see that the default settings for this application has the application being built to C:\Demo\XPE_Hello. We need to change this in the project properties.

  1. In the application, from the Project menu, select Properties. The first page of the properties dialog box is the General settings; we need to change the Output Directory and the Intermediate Directory to point to our remote device. By default the Output and Intermediate files are built to the local 'Debug' folder, change this to K:\NativeDebug.

Figure 4: The Property Pages dialog box

The next tab we're interested in is the Debugging tab.

Figure 5: The Debugging tab

  1. There are a number of changes we need to make on the Debugging tab.
    • Change the connection from local to Remote via TCP/IP (Native Only).
    • Change the Remote Machine name from your desktop PC to the IP address of the remote PC: 192.168.2.2.
    • Change the Remote command to D:\NativeDebug\XPE_Hello.exe.
      Note: This is the command relative to the remote PC, not your desktop PC.
  2. Next comes the linker settings. There are two places we need to change the output location for our EXE and PDB files.
    • First, go to the Linker | General tab (see Figure 6). We need to change our output file to point to our remote location, in this case it's going to be K:\NativeDebug\XPE_Hello.exe.
    • Next, we need to change the output folder for the .PDB file, this can be found on the Linker | Debugging tab (see Figure 7). Change the Generate Program Database File option to point to the remote output folder, K:\NativeDebug\XPE_Hello.pdb

Figure 6: The Linker | General tab

Figure 7: The Linker | Debugging tab

Debugging the Application

We're now ready to debug the application. Since this is wizard-generated code, we could, perhaps, set a breakpoint on the line of code that shows the About Box for the application. (Of course we could do a whole lot more, but this is just an example of how to set a breakpoint and have our remote application launch/debug.)

In the Visual Studio Wizard generated source, locate the DialogBox call to show the About Box. Set a breakpoint by clicking F9 (or use the toolbar button).

Figure 8: Setting a breakpoint

Now let's run the application. In Visual Studio .NET 2003, select Debug | Go or press the F5 key.

When the application is built, the debug files and application are built in the remote NativeDebug folder. Here's a listing of the files for my application:

05/25/2004  02:45 PM             2,812 BuildLog.htm
05/25/2004  02:45 PM            71,394 stdafx.obj
05/25/2004  02:45 PM           166,912 vc70.idb
05/25/2004  02:45 PM           217,088 vc70.pdb
05/25/2004  02:45 PM           172,032 XPE_Hello.exe
05/25/2004  02:45 PM           450,800 XPE_Hello.ilk
05/25/2004  02:45 PM             9,044 XPE_Hello.obj
05/25/2004  02:45 PM         2,686,976 XPE_Hello.pch
05/25/2004  02:45 PM           560,128 XPE_Hello.pdb
05/25/2004  02:45 PM            48,228 XPE_Hello.res
              10 File(s)      4,385,414 bytes

And here's our super, Hello World, Windows XP Embedded Remote Debug application running inside Virtual PC. Notice that MSVCMON is showing that user mikehall now has a debug session running.

Click here to see larger image

Figure 9: Our application running inside the Virtual PC

If we select About from the Help menu in our (remote) application, the breakpoint should fire and our application should break. Let's make sure this works before we tuck into the lemon pound cake!

And here's the end result: our breakpoint fires, and we can single step through code, view variables, call stack etc., just like debugging on our desktop PC.

Figure 10: Our breakpoint fires!

That's about it for this month's article. If any of you are using Windows XP Embedded and Device Update Agent (DUA), then you will be pleased to know that Aaron Stebner and I have worked on a tool that makes the creation of DUA script files a snap. You can find a link to this download on our blogs:

https://blogs.msdn.com/astebner

https://blogs.msdn.com/mikehall

Next month is the Windows Embedded Developers Conference in San Diego, I'll hopefully see you there. At this point, I'm heads down working on lab content, demos, and session slides, and demos, so haven't thought as far as next month's Windows XP Embedded article … as always, comments and questions are welcome.

 

Get Embedded

Mike Hall is a Product Manager in the Microsoft Embedded and Appliance Platform Group (EAPG). Mike has been working with Windows CE since 1996—in developer support, Embedded System Engineering, and the Embedded product group. When not at the office, Mike can be found with his family, working on Skunk projects, or riding a Honda ST1100.