5. Using a debugger

5.1 Building an application with debugging enabled
5.2 Palm OS-specific GDB features

5.1 Building an application with debugging enabled

As on any other platform, you instruct GCC to produce debugging information by compiling with the `-g' option.

Some debuggers targeting Palm OS, notably GDB, also need your application to have a special stub (called StartDebug) in its startup code so that they can attach to the running application successfully.

To include this stub, you also need to link with `-g'.

By default, the stub is disabled and your application runs normally. When the stub sees that a gdbS #0 feature exists and has the value 0x12BEEF34, it is enabled and will converse with the debugger, telling it where in memory to find the application.

There are two convenient ways to set this feature and enable the stub:

• The Palm OS Emulator (version 2.1d22 or greater) sets the feature automatically whenever there is a debugger connected to its debugger port. Thus there is no need to do anything yourself to enable debugging on Poser.

• GDB Panel, in the prc-tools samples, is a small Palm OS application which sets this feature. You need to use it or something similar when debugging on a real device or on the Palm OS Simulator.

5.2 Palm OS-specific GDB features

To debug Palm OS applications, GDB needs to load symbolic information from the bfd executable corresponding to your application, and to be connected to the Palm OS device where the application is running. You generally specify the bfd executable on the command line (for example, to debug an application `myapp.prc')

$ m68k-palmos-gdb myapp

and connect using the `target' command.

target palmos port

target pilot port

Connects the GDB host environment to a Palm OS device via port, using the Palm debugger protocol. The argument port may be a device such as `/dev/ttyS0' (Unix) or `COM1' (Windows) to connect to a real device over a serial line, or a socket such as `localhost:2000' to connect to the Palm OS Emulator.

Using pilot is equivalent to palmos, and is provided for compatibility with earlier releases. If port is omitted, GDB will attempt to connect to `localhost:2000' by default.

(The prc-tools 2.0 release only supported the pilot keyword, and port was not optional.)

After you have connected to the device, you should enable the debugger stub (see section 5.1 Building an application with debugging enabled), which is done automatically if you are connecting to Poser, and start your application, which you've compiled and linked with `-g'.

When your application starts up, GDB receives data from the debugger stub telling it how to correlate the bfd executable's debugging information with where in memory the application has been loaded. Because of this, you need to ensure that the debugging information has been loaded before the breakpoint is received--hence typically the bfd file of debugging information is specified on the GDB command line.

The debugger stub also causes execution to stop as if at a breakpoint at the start of PilotMain, giving you a chance to interact with the debugger before your program runs but after you're connected to it. However, PilotMain can be entered multiple times--for example, if your application is sublaunched with another launch code or if you (or a gremlin) switch to another application and back again--and you may not want to break into the debugger every time. You can control whether the debugger stops at this implicit breakpoint by changing the way GDB handles the SIGSTOP signal (see section `Signals' in Debugging with GDB).

There are some other features and limitations:

• As a last resort before printing `??' for a function name, GDB will try to get the (mangled) name by querying the target for a MacsBug symbol. For example, this makes backtraces containing the stack frames of functions in the Palm OS ROM more informative.

• At present, GDB won't work well with applications with multiple code resources.