This chapter describes how to use the Palm OS debugging tools.
The Palm OS Developer Suite package provides the following debugging tools:
- "Using Integrated Debugging" describes how to use the debugging features that are integrated in Palm OS Developer Suite.
- "Using Palm OS Debugger" describes how to use the full-feature debugger, Palm OS Debugger.
Using Integrated Debugging
Palm OS Developer Suite provides integrated debugging support for all of the following:
- Application types:
- 68K applications compiled using the GNU 68K compiler
- 68K applications with PACE Native Objects
- Palm OS Protein applications, including applications compiled using the GNU x86 compiler to run on Simulator targets, and applications compiled using the Palm OS Protein C/C++ Compiler to run on devices targets
- Target types: applications running on Palm OS Emulator, Palm OS Garnet Simulator, Palm OS Cobalt Simulator.
- Device communications connections: 68K applications can be debugged over serial or USB connections; Palm OS Protein applications require devices connected over USB, including:
Integrated Debugging Overview
Integrated debugging makes full use of the functions provided by the C/C++ Development Toolkit (CDT 2.0) that is integrated with Developer Suite. This support provided by CDT includes functions like:
- Specifying execution arguments
- Setting environment variables
- Working with breakpoints and watchpoints
- Step execution of an application
- Watching variables, expressions, registers, and memory
This section provides an overview of some of the commonly used functions. For more information on these integrated tasks, see C/C++ Development Toolkit User Guide.
Setting a Breakpoint in an Application
You set a breakpoint on an executable line of a program. If the breakpoint is enabled when you debug, the execution suspends before that line of code executes.
To add a breakpoint point, double click the marker bar located in the left margin of the C/C++ Editor beside the line of code where you want to add a breakpoint. A dot is displayed in the marker bar and in the Breakpoints view, along with the name of the associated file.
Creating a Debug Configuration
To debug your application using Palm OS Emulator or a Simulator target, you first create a debug configuration.
To create a debug configuration:
- Select your project's icon in the C/C++ Projects view.
- Select Run > Debug to open the Debug dialog box.
- Click on the Palm OS Application icon and click New to create a configuration for the current project.
- By default, the configuration's name will be the same as your project's.
- Click the Project tab and be sure that your project is selected in the Files to Install list.
- Click on the Target tab to choose the debugger target for this configuration. The dropdown lists include the defined targets. (To create additional targets, see the section "Target Environment Settings Preferences.")
- For 68K projects, there is a single dropdown list that includes all of the defined targets that can run 68K applications (device targets, Emulator targets, and Simulator targets).
- For Palm OS Protein projects, there are two dropdown lists. The first is for device targets (applications compiled with Palm OS Protein C/C++ Compiler,
pacc.exe
), and the second is for Simulator targets (applications compiled with GNU x86 compiler).The reason for the differentiation is that Simulator builds create two files: a DLL that holds the code for your application (compiled as x86 code), and a PRC that holds your application's resources. For device (ARM) builds, only one file is created: the PRC, which holds everything, as with 68K applications.
- Click Debug to start the debugging process.
- The Workbench switches to the Debug perspective and stops at a temporary breakpoint inside
PilotMain()
. Click on the green Run arrow to begin execution. You can use the Step Over, Step Into and Step Out Of icons to control your debugging session (there are also commands in the Run menu, as well as keyboard equivalents). Note that the exact sequence of events that occur when you begin debugging depends on the target type (whether Simulator is already running, whether you are using Palm OS Garnet or Palm OS Cobalt Simulator, and so on). - When you are finished with the debugging session, click on the Palm OS Debugger line in the Debug view, then click the red square to stop the session.
- Once you've created a debug configuration, just click the debug button in the toolbar to start another session.
Using Palm OS Debugger
Palm OS Debugger is a full-function debug tool that you can use to debug your Palm OS applications and shared libraries. Palm OS Debugger provides support for multiple symbolic file debugging.
Palm OS Debugger provides the following features:
Full assembly and source level debugging
Support for shared library debugging in ARM environments
Support for debugging with multiple symbolic files
Fully customizable short cut keys
Setting and viewing breakpoints
Support for ELF/DWARF 1.1 and 2.0
Palm OS Debugger is a tool for debugging both 68K-based and ARM-based Palm OS applications.
- Debugging 68K-Based Applications: Palm OS Debugger supports connecting to the 68K debug nub of a 68K-based device and to the 68K debug nub built into the PACE component of an ARM-based device. Palm OS Debugger also connects to the 68K debug nub of Palm OS Emulator and Palm OS Simulator.
- Debugging ARM-Based Applications: Palm OS Debugger supports connecting to the ARM debug nub of an ARM-based device.
Launching Palm OS Debugger from the Workbench
Palm OS Debugger is integrated into the Developer Suite package. To launch Palm OS Debugger, select Run > Palm OS Debugger. This opens the Palm OS Debugger's main window, as shown in Figure 6.3.
Setting Palm OS Debugger Preferences
Palm OS Debugger preferences are dependent on the run target selected. As a result, you can view and change Palm OS Debugger preferences from the same dialog box where you set the run target preferences.
- Select Window > Preferences to open the Preferences dialog box.
- Expand the Palm OS Development category and select Target Environment Settings.
- Expand the category that matches the run target you are using, and select the specific run target. For example, in Figure 6.1 below, the run target Device (COM1) is selected.
Figure 6.1 Target Environment Settings dialog box

- Click Advanced to open the Advanced Preferences Editor dialog box, as shown in Figure 6.2.
Figure 6.2 Advanced Preferences Editor dialog box

You can open each of the properties listed in the Advanced Preferences Editor to view or change a specific Palm OS Debugger setting. For more information about the Palm OS Debugger settings, see the book Palm OS Debugger Guide.
Palm OS Debugger User Interface
You can use Palm OS Debugger to:
- View information about applications and their source files.
- Set breakpoints.
- Display a list of registers and their values.
- View information about variables.
- View information about memory address locations and their contents.
- View processes that Palm OS Debugger knows about.
- View the stack trace.
- Evaluate C expressions.
- View standard input and output operations (such as debug messages) in an STDIO console.
- Interact with your debugging session in a command line environment.
Figure 6.3 Palm OS Debugger user interface

You can open an instance any of the Palm OS Debugger tabs in its own separate window. To do this, select Windows in the Palm OS Debugger menu bar, and then select a view from the list of views.
Getting More Information
Palm OS Debugger is described in detail in the book Palm OS Debugger Guide.