Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

2    Connecting Palm OS Debugger with a Target

Palm OS® Debugger Guide

Palm OS® Developer Suite

This chapter describes how to connect Palm OS Debugger with a debug target.

Overview of Debugger Communication
Debugging with Palm OS Garnet Devices
Debugging with Palm OS Garnet Simulator
Debugging with 68K-Based Devices
Debugging with Palm OS Emulator
Overview of Application Debugging

Overview of Debugger Communication ^TOP^

Palm OS Debugger enables debugging via a debugger plug-in through a communication plug-in connection to a debugger nub on a debug target. See Figure 2.1 for a graphical representation of this communication flow.

Figure 2.1  Palm OS Debugger Communication

Palm OS Debugger supports the following communications plug-ins:

  • Serial, used primarily to connect to a Palm OS device that supports a serial connection.
  • USB, used primarily to connect to a Palm OS device that supports a USB connection.
  • Sockets, used to communicate with Palm OS Emulator and Palm OS Garnet Simulator.

The debugger nub can be any of the following debug targets:

  • an ARM debugger nub, running on an ARM-based device. (Note: For some devices that use Palm OS Garnet, you need to install a device-specific ARM debugger nub. For devices that run Palm OS Cobalt, the ARM debugger nub is built into the device.)
  • a 68K debugger nub, built into PACE on an ARM-based device or on Palm OS Garnet Simulator. (PACE is the Palm OS Application Compatibility Environment. For more information about PACE, see Palm OS Simulator Guide.)
  • a 68K debugger nub, built into a 68K-based device.
  • a 68K debugger nub, built into Palm OS Emulator.

Debugging with Palm OS Garnet Devices ^TOP^

When debugging with Palm OS Garnet devices, the Palm OS Debugger's ARM Palm OS 5 Debug Nub plug-in communicates through the serial connection with the ARM Debugger Nub for Palm OS Garnet on the device.


NOTE: Each ARM-based device needs to have a custom-built debug nub. To use an ARM-based handheld not described here, contact your handheld manufacturer to see whether a debug nub is available for your ARM-based handheld.

The following devices have a supported ARM debugger nub (at the time this book was written).

For palmOne devices Tungsten C, Tungsten E, Tungsten T, Tungsten T2, Tungsten T3, Tungsten T5, Zire 71, and Zire 72: These debugger nubs are available from the PluggedIn program at http://pluggedin.palmone.com

For the Treo 600, the debugger nub is included on the device.

For the Tapwave Zodiac, the debugger nub is included on the device.

Installing the Debugger Nub ^TOP^

As an example, to install the debugger nub on a Tungsten T, follow this process:

  1. Using Palm Desktop's Install Tool, add the debugger nub file DebugNub5-PalmTT.prc to be installed using a HotSync® operation.
  2. Place the Tungsten T in a cradle, and press the HotSync button install the PRC file on the device.
  3. Once the HotSync operation has completed, press the reset button on the Tungsten T device to restart Palm OS and complete the installation.

Connecting Palm OS Debugger with a Palm OS Garnet Device ^TOP^

To connect Palm OS Debugger with a Palm OS Garnet device, complete the following setup steps:

  1. Set Palm OS Debugger's ARM Palm OS 5 Debug Nub protocol plug-in preferences.
  2. Test the connection between Palm OS Debugger and the device.

The following sections cover these steps in detail.

1. Setting the ARM Palm OS 5 Debug Nub Plug-In Preferences

To set the ARM Palm OS 5 Debug Nub plug-in preferences:

Figure 2.2  Import Preferences Dialog Box

  • Open the folder Preset Prefs, and select the file PalmOS5.x-DebugNub.xml in the dialog box. Then click Open to set the debugger preferences. If Palm OS Debugger displays a message dialog box asking whether to save modified preferences, click Yes.
  • To verify the serial communications port settings, select Edit > Preferences, expand the Communications category, and click Serial.

2. Testing the Connection

  • In Palm OS Debugger, open the Palm OS application (PRC file) to debug by selecting File > Open.
  • Place your Palm OS device in the cradle. Make sure that the cradle is connected properly to the computer.
  • Turn on the Palm OS device.
  • Enter the debugging shortcut, as shown below, in the input area to enable the debugger nub.

NOTE: To draw the debugging shortcut, follow these steps:

  1. Draw the lowercase, cursive "L" character.
  2. Tap the stylus twice, to generate a dot (a period).
  3. Draw the number 2.

For a more detailed description of application debugging, see "Overview of Application Debugging."

Removing the Debugger Nub from a Tungsten T Device ^TOP^

When you are finished using your Tungsten T to debug, you can delete the debug nub by following these steps:

  • Perform a "no-notify" reset by holding down the "Up" button on the device while simultaneously pressing the reset button.
  • From the Launcher application, select the Delete menu item.
  • From the Delete dialog, select DebugNub5-PalmTT and tap Delete.

Debugging with Palm OS Garnet Simulator ^TOP^

When debugging with Palm OS Garnet Simulator, the Palm OS Debugger's 68K Palm OS Debug Kernel protocol plug-in communicates through a socket connection with the 68K debugger nub on Palm OS Garnet Simulator.


NOTE: Palm OS Garnet Simulator includes PACE with the 68K debugger nub. You do not need to install a debug nub as part of the setup tasks for debugging with Palm OS Garnet Simulator.

Palm OS Garnet Simulator can be used to debug 68K-based Palm OS applications. You cannot use Palm OS Garnet Simulator to debug native ARM subroutines.

Connecting Palm OS Debugger with Palm OS Garnet Simulator ^TOP^

To connect Palm OS Debugger with Palm OS Garnet Simulator, complete the following setup steps:

  1. Set Palm OS Debugger's 68K Palm OS Debug Kernel protocol plug-in preferences.
  2. Set Palm OS Garnet Simulator's communication settings.
  3. Test the connection between Palm OS Debugger and Palm Garnet OS Simulator.

The following sections cover these steps in detail.

1. Setting the 68K Palm OS Debug Kernel Plug-In Preferences

To set the 68K Palm OS Debug Kernel plug-in preferences:

  • Open Palm OS Debugger.
  • Select Edit > Preferences.
  • Click Import to import the preset preferences. The dialog box shown in Figure 2.2 opens.
  • Open the folder Preset Prefs, and select the PalmOS.68KPoser.xml preset definition in the dialog box.

    Then click Open to set the debugger preferences. If Palm OS Debugger displays a message dialog box asking whether to save modified preferences, click Yes.

2. Setting Palm OS Garnet Simulator's Communication Settings

In Palm OS Garnet Simulator: Select Settings > Communication > Communication ports to bind the 68K debugger transport to localhost:2000.

3. Testing the Connection

  • In Palm OS Debugger, open the Palm OS application (PRC file) to debug by selecting File > Open.
  • Enter the debugging shortcut, as shown below, in the input area to enable the debugger nub.

NOTE: To draw the debugging shortcut, follow these steps:

  1. Draw the lowercase, cursive "L" character.
  2. Tap the stylus twice, to generate a dot (a period).
  3. Draw the number 2.

For a more detailed description of application debugging, see "Overview of Application Debugging."

Debugging with 68K-Based Devices ^TOP^

When debugging with 68K-based devices, the Palm OS Debugger's 68K Palm OS Debug Kernel protocol plug-in communicates through a serial or USB connection with the 68K debugger nub on the device.


NOTE: Some 68K-based devices do not support debugging over a USB connection. Contact your device manufacturer for more information about your device.

Current 68K-based devices are manufactured with the 68K debugger nub already included. You do not need to install a debug nub as part of the setup tasks for debugging with 68K-based devices.


NOTE: Remember that 68K-based devices can be used to debug only 68K-based Palm OS applications. You cannot use a 68K-based device to debug ARM code.

Connecting Palm OS Debugger with a 68K-Based Device ^TOP^

To connect Palm OS Debugger with a 68K-based device, complete the following setup steps:

  1. Set Palm OS Debugger's 68K Palm OS Debug Kernel protocol plug-in preferences.
  2. Test the connection between Palm OS Debugger and the 68K-based device.

The following sections cover these steps in detail.

1. Setting the 68K Palm OS Debug Kernel Plug-In Preferences

To set the 68K Palm OS Debug Kernel plug-in preferences:

  • Open Palm OS Debugger
  • Select Edit > Preferences
  • Click Import to import the preset preferences. The dialog box shown in Figure 2.2 opens.
  • Open the folder Preset Prefs\Debugger Plugins - 68K, and select the Palm OS 68K preset file dependent on your serial connection:
    • For serial port COM1, select PalmOS.68KDevice.Serial.COM1.xml in the dialog box.
    • For serial port COM2, select PalmOS.68KDevice.Serial.COM2.xml in the dialog box.
    • For serial port COM3, select PalmOS.68KDevice.Serial.COM3.xml in the dialog box.
    • For serial port COM4, select PalmOS.68KDevice.Serial.COM4.xml in the dialog box.
    • For USB, select PalmOS.68KDevice.USB.xml in the dialog box.

      Then click Open to set the debugger preferences. If Palm OS Debugger displays a message dialog box asking whether to save modified preferences, click Yes.

2. Testing the Connection


NOTE: Before debugging an application over USB, it is best to first perform a HotSync operation to test the USB communication with the device. After you have completed a HotSync operation, you should be able to follow the process described here.
  • In Palm OS Debugger, open the Palm OS application (PRC file) to debug by selecting File > Open.
  • Enter the debugging shortcut, as shown below, in the input area to enable the debugger nub.

NOTE: To draw the debugging shortcut, follow these steps:

  1. Draw the lowercase, cursive "L" character.
  2. Tap the stylus twice, to generate a dot (a period).
  3. Draw the number 2.

If you are using HotSync Manager 4.1 or earlier to debug a 68K application on a 68K device, note that whenever you have to soft reset the device, you will have to re-enter the debugging shortcut. Also, after a soft reset, the USB port does not work immediately and the first HotSync operation has to be cancelled and followed by a second HotSync operation. The second HotSync operation usually succeeds. Only after you are able to complete a HotSync operation will you be able to debug your application.

For a more detailed description of application debugging, see "Overview of Application Debugging."

Debugging with Palm OS Emulator ^TOP^

When debugging with Palm OS Emulator, the Palm OS Debugger's 68K Palm OS Debug Kernel protocol plug-in communicates through a socket connection with the 68K debugger nub on Palm OS Emulator.

Palm OS Emulator includes the 68K debugger nub. You do not need to install a debug nub as part of the setup tasks for debugging with Palm OS Emulator.


NOTE: Palm OS Emulator can be used to debug only 68K-based Palm OS applications. You cannot use Palm OS Emulator to debug ARM code.

Connecting Palm OS Debugger with Palm OS Emulator ^TOP^

To connect Palm OS Debugger with Palm OS Emulator, complete the following setup steps:

  1. Set Palm OS Debugger's 68K Palm OS Debug Kernel protocol plug-in preferences.
  2. Test the connection between Palm OS Debugger and Palm OS Emulator.

The following sections cover these steps in detail.

1. Setting the 68K Palm OS Debug Kernel Plug-In Preferences

To set the 68K Palm OS Debug Kernel plug-in preferences:

  • Open Palm OS Debugger
  • Select Edit > Preferences
  • Click Import to import the preset preferences. The dialog box shown in Figure 2.2 opens.
  • Open the folder Preset Prefs\Debugger Plugins - 68K, and select the PalmOS.68KPoser.xml preset definition in the dialog box.

    Then click Open to set the debugger preferences. If Palm OS Debugger displays a message dialog box asking whether to save modified preferences, click Yes.

2. Testing the Connection

  • In Palm OS Debugger, open the Palm OS application (PRC file) to debug by selecting File > Open.
  • Start Palm OS Emulator, and make sure Emulator is idle, showing the Launcher application.
  • Select Control > Run to start the debugging session.

For a more detailed description of application debugging, see "Overview of Application Debugging."

Overview of Application Debugging ^TOP^

To start debugging an application in Palm OS Debugger, open the Palm OS application (PRC file) to debug by selecting File > Open.

68K-Based Application Debugging ^TOP^

To debug a Palm OS 68K application, you need to first connect to a target that can run a 68K application:

Palm OS Debugger displays the application debugging session window, with the corresponding 68K symbolic file information for the Palm OS application you selected when you connected to the debugging target.

The symbolic information is automatically loaded for you if the symbolic file for the Palm OS application is in the same directory as the application's PRC file. (The symbolic file has the same filename as the PRC file but with the file extension PSYM.) If the symbolic file is moved or renamed, you can load it manually by selecting Target > Append Symbolics.

If the source files are available, you can set breakpoints in the source view. (Palm OS Debugger may not be connected to the debug target yet, so the breakpoints may be marked as unresolved.)

To connect Palm OS Debugger with the debug target, select Control > Run to start the debugging session:

  • If the 68K debug console is already active, Palm OS Debugger connects with the debug target.
  • If the 68K debug console is not active, Palm OS Debugger prompts you to activate the debug console by entering shortcut-2:

NOTE: To draw the debugging shortcut, follow these steps:

  1. Draw the lowercase, cursive "L" character.
  2. Tap the stylus twice, to generate a dot (a period).
  3. Draw the number 2.

Once Palm OS Debugger has connected with the debug console, Palm OS Debugger loads the application on the debug target. The debug target launches the application.


NOTE: Due to a problem in the 68K Serial Link Manager for the Palm m500 device, the stop and kill commands may not initially respond when you debug a 68K application using an m500 device. To correct this problem, turn off the m500 device and then turn it on again.

ARM Subroutine Debugging ^TOP^

ARM subroutines, also called PACE native objects (PNO), are typically built and written to files of the following form:

ARM*####.bin

where "*" is any character, and "####" is a hexadecimal representation of the ARM subroutine resource ID, or

ARM*####.sbin

for subroutines that are larger than 64 KB.

If Palm OS Debugger finds code resources of type "ARM*" in the Palm OS application, then Palm OS Debugger looks for corresponding symbolic file of the form ARM*####.bin.elf (or ARM*####.sbin.elf) in the same directory as the Palm OS application' PRC file. If Palm OS Debugger finds an ARM symbolic file, then Palm OS Debugger opens an ARM debug session window.

Interaction Between 68K and ARM Debug Windows

Palm OS Debugger presents debug information for 68K and ARM code in separate debug windows. To a certain extent, Palm OS Debugger treats the two components as if they are being run on two different CPUs, though they are not completely independent.

When a break or crash occurs, the debug session window corresponding to the code that received the break or crash becomes the front-most window. The status in the lower-right corner of the window indicates that the code execution is stopped.

The 68K debug window is a representation of PACE running on the debug target. PACE, the Palm Application Compatibility Environment, not only emulates a 68K processor executing the 68K code, but also provides support for all 68K debug services.

PACE is an ARM application. Any time the ARM session is stopped, the 68K session is implicitly stopped as well, even if the debug window status indicates that the 68K session is running. When the ARM session is resumed, PACE and the 68K session continue to execute starting from where the session was implicitly stopped.

When debugging with both 68K and ARM sessions, you should be able to stop either session by clicking the Stop icon in the toolbar or using the Stop menu item. For interactive debugging, it is best to stop and resume execution in only one session window at a time:

If your code causes a crash in the ARM debug nub but not the 68K debug console, you may be able to use the 68K session window to determine what the 68K code was doing prior to the crash. To investigate, select the 68K session window, stop execution, and examine the stack trace, variables, registers, and memory values displayed.

If you can recover from the crash in the ARM session by changing the program counter or a register, then you may be able to resume execution as well.

Palm OS Protein Application Debugging ^TOP^

To debug a Palm OS Protein application, you need to first connect to a target that can run a Palm OS Protein application. That is, you need to connect to a device that is running Palm OS Cobalt or later.

At the time this book was written, there were no targets that support running Palm OS Protein applications.