Interactive debugging of OpenZDK applications

Until recently, the only way to debug applications built with OpenZDK has been “the hard way”: running the application over and over with message boxes inserted in strategic locations, something that is clearly not practical for software of any complexity. This is about to change. Client for Debugging finally makes it possible to debug OpenZDK applications just as you would Windows and XNA applications - right inside Visual Studio. Additionally, the filesystem and registry can now be accessed and manipulated directly using the remote tools included with Visual Studio.

Note that while it should be possible to implement a similar technique for debugging applications on classic Zune models, Client for Debugging is currently only compatible with the Zune HD.

Before you get started, make sure you have:

• A Zune HD
• A properly installed OpenZDK toolchain
• A wireless network that is compatible with the Zune HD firmware

Client for Debugging requires certain files from Visual Studio that must be copied from the host system; therefore, the installer must be run on a system that has Visual Studio 2008 Professional installed.

The original release of Client for Debugging (0.1) was nonfunctional. If you downloaded 0.1, please make sure to update to the latest version.

1. Download the Client for Debugging DeployKit installer
2. Attach your Zune HD to the computer
3. Close the Zune software
4. Run the installer and deploy Client for Debugging to your Zune

To bring up the debugging server on the Zune, follow the procedure below:

1. Ensure the Zune is disconnected from USB
2. Launch Client for Debugging from the Zune menu
3. Touch the screen to open the wireless network selector
4. Connect to the same network as the host system
   • Note that you will have to re-enter the WEP/WPA key for any network not originally connected to from an OpenZDK application
5. Wait until the Zune's IP address is displayed in a message box

The color of the four arrows on screen indicates the status of Client for Debugging:

• White: Not connected
• Red: Connected via USB (must detach to be able to debug)
• Alternating colors: Connected to network

Visual Studio must be configured with the IP address of the Zune in order to be able to connect.

1. Launch Visual Studio and open a OpenZDK project/solution
2. Click the second button to the right of the device dropdown (which typically reads OpenZDK ARMV4I Device)
3. Click Properties…, then Configure…
4. Select Use specific IP address: and enter the IP address displayed by Client for Debugging
5. Click OK three times to exit back out to Visual Studio
6. Click the first button to the right of the device dropdown to test the connection

Visual Studio provides a series of “remote tools” that can be used to access the Zune's registry, filesystem, and more.

1. Open the Start menu and navigate to All Programs > Microsoft Visual Studio 2008 > Visual Studio Remote Tools
2. Select one of the remote tools
   • Remote File Viewer
     Allows for browsing/manipulation of the filesystem on the Zune
   • Remote Heap Walker
     Allows for browsing of the memory heap on the Zune
   • Remote Process Viewer
     Similar to Task Manager, but for the Zune
   • Remote Registry Editor
     Similar to Registry Editor, but for the Zune
   • Remote Spy
     Enumerates the windows on the system
3. Select OpenZDK ARMV4I Device from the list of devices to connect to the Zune

Remote Zoom In, which captures a screenshot from a Windows CE device, yields only a blank image; screenshottr, documented below, is a Zune-specific replacement.

1. Launch Visual Studio 2008 and open the solution containing your OpenZDK application
2. Ensure that the Debug configuration has been selected from the dropdown in the toolbar
3. Select Configuration Manager… from the Build menu to open the configuration manager
4. Ensure that Build is checked for all projects
5. Ensure that Deploy is unchecked for the XNA exploit code project (normally exploiter) and checked for your main C++ project (often nativeapp)
6. Press Close, then right-click your C++ project in Solution Explorer and select Properties
7. Navigate to Configuration Properties > Deployment in the properties window
8. Set the Remote Directory to \Flash2\debug\$(SolutionName)\$(ProjectName)\
   • The above directory is merely a suggestion; however, ensure that you are deploying somewhere on \Flash2
9. Navigate to Configuration Properties > Debugging in the properties window
10. Set the Remote Executable to \Flash2\debug\$(SolutionName)\$(ProjectName)\$(TargetFileName)
    • If you choose a different remote directory, ensure that the path you set here matches
11. Press OK, right-click your C++ project again and select Set as StartUp Project

Once you have configured Visual Studio and your project for use with Client for Debugging, follow the steps below to begin using the debugger:

1. Launch Visual Studio 2008 and open the solution containing your OpenZDK application
2. Ensure that the Debug configuration has been selected from the dropdown in the toolbar
3. Launch Client for Debugging on your Zune and connect to your wireless network
4. Click the green Run button on the toolbar or press F5 to begin debugging

Debugging with Visual Studio works the same regardless of whether you are dealing with an XNA, OpenZDK, or ordinary Windows application. For more information on how to use the debugger, see the Debugger Roadmap on MSDN.

screenshottr provides a facility to take screenshots of OpenZDK applications through the Remote Tools Framework, a framework for building utilities that communicate through the debugging channel.

1. Install the Remote Tools Framework
2. Download screenshottr
3. Run the program you would like to take a screenshot of under the debugger
4. With the Remote Tools Framework installed, launch screenshottr.cetool and select OpenZDK ARMV4I Device (ARMV4I) Version 6000 from the list
5. Select Capture screenshot to take a screenshot
6. Press F5 to refresh the screenshot as necessary, or click Export… to save the screenshot as a PNG file

Note that the screenshots taken do not always accurately reflect the contents of the screen, especially when 3D is involved. The alpha channel is preserved when taking the screenshot, and applications that erroneously clear the screen with zero alpha will be captured without a background. The raw screenshots are alpha blended with a black background in the preview but are saved unmodified when exporting as a PNG file.

The Zune firmware will automatically disconnect from the wireless network after a period of about ten minutes of inactivity. This tends to frequently disrupt long debugging sessions. With any luck, this will be corrected in the next release.