This chapter describes how you can use Palm OS® Emulator to test and debug programs you have written for Palm OS.
- "Testing Software"
- "Using Gremlins to Automate Testing"
- "Setting Breakpoints"
- "Debugging with External Debug Tools"
- "Tracing Your Code"
- "Profiling Your Code"
Testing Software
Testing software is probably the most common use of Palm OS Emulator. This section provides a quick summary of the steps to load and test an application.
Debug Options
Palm OS Emulator monitors the actions of your application while it is emulating the operation of the handheld. When your application performs an action that does not strictly conform to Palm OS's programming guidelines, the Emulator displays a dialog box that explains what is happening.
The debugging options dialog box, which is shown in Figure 5.1, lets you enable or disable the monitoring activities applied to your application. Use Debug Options to display this dialog box.
Figure 5.1 Palm OS Emulator Debug Options Dialog Box

Table 5.1 describes each of the debugging options.
Table 5.1 Emulator Debugging Options
Monitors access to free memory chunks. |
|
Monitors accesses to hardware registers by applications. |
|
Monitors low-memory access by applications. |
|
Monitors access to the range of memory below the stack pointer. |
|
Monitors access to Memory Manager data structures, which is restricted to only the Memory Manager. Emulator allows no access to data structures for which there are PalmOSGlue accessor routine defined. |
|
Detects memory leaks. Emulator checks for memory leaks on If Emulator discovers any memory leaks, it writes information about the leaks to a log file, including memory location, memory contents, and a stack crawl of the context that allocated the leaked block of memory. It is a good idea to set your compiler's switch to embed debug symbols in your code so that you can easily interpret the stack crawl. With CodeWarrior, you should set the option Generate MacsBugs Debug Symbols. With GCC, you should use the Palm OS specific GCC option |
|
Monitors how long the Memory Manager semaphore has been acquired for write access using the |
|
This option controls a facility of Overlay Manager in the debug version of the ROM files. When this option is enabled, the |
|
Monitors calls to any of the functions on the proscribed function list. See Appendix B, "Unsupported Traps," for a list of functions. |
|
Monitors LCD screen buffer access by applications. |
|
Checks for any use of sizeless form objects (objects whose height or width is zero). |
|
Ensures that the stack pointer has not dipped below the space allocated for it by the kernel. |
|
Monitors access to system global variables by applications. |
|
Checks for any access of User Interface Manager data structures. |
|
Monitors read access to uninitialized portions of memory chunks that have been allocated by the |
|
Causes Emulator to beep every two seconds while a message dialog box is displayed. Emulator will stop beeping after one minute. |
Logging Options
Palm OS Emulator also logs various actions taken by your application to help you debug and performance tune your code. The logged information is automatically written to a text file that is saved in the same directory as the Emulator executable.
You can control the logging activity with the logging options dialog box, which is shown in Figure 5.2. Use Logging Options to display this dialog box.
Figure 5.2 Palm OS Emulator Logging Options Dialog Box

The logging options dialog box features radio buttons to indicate logging during normal operations (Normal), and logging while a Gremlin is running (Gremlins). Both offer the same options, which are described in Table 5.2
Table 5.2 Emulator Logging Options
Using Gremlins to Automate Testing
You can use Gremlins to automate testing of an application. A Gremlin generates a series of user input events that test your application's capabilities. You can have a Gremlin generate a specified number of events, or to loop forever, which lets you set up a Gremlin and allow it to run overnight to thoroughly test your application.
A Gremlin horde is a range of Gremlins that you want Palm OS Emulator to run. The Emulator generates a stream of events for each Gremlin and then moves onto the next Gremlin. The Emulator cycles through the Gremlins until the maximum number of events have been generated for the horde.
Palm OS Emulator generates a stream of events for each Gremlin in the horde until one of the following conditions occurs:
- An error such as a hardware exception or illegal memory access is generated.
- The maximum number of events for a single Gremlin have been generated.
- The maximum number of events for the horde have been generated.
- You stop the horde by choosing Stop or Step from the Emulator menu or from the Gremlin Status dialog box.
If a Gremlin generates an error, it is halted and Palm OS Emulator does not include it when cycling through the horde again.
Gremlin Characteristics
Each Gremlin has the following characteristics:
- It generates a unique, random sequence of stylus and key input events to step through the user interface possibilities of an application.
- It has a unique "seed" value between 0 and 999
- It generates the same sequence of random events whenever it is run.
- It runs with a specific application or applications.
- It displays a report immediately when an error occurs.
Gremlin Horde Settings
For each Gremlin horde, you specify the following:
- The number of the first Gremlin to run. This must be a value between 0 and 999.
- The number of the last Gremlin to run. This must be a value between 0 and 999.
- The switching depth of the Gremlin horde. This is the number of events to run for each Gremlin before switching to another Gremlin. After this many events have been generated for the Gremlin, it is suspended, and the next Gremlin in the horde starts running.
- The maximum number of events for each gremlin in the horde. The Emulator stops running each Gremlin after it posts this many events, or after it terminates with an error.
- The first application the Gremlins are to run.
- The set of applications the Gremlins are to run. You can select a single application, a group of applications, or all applications.
- Whether warnings and errors are displayed as message dialogs or as messages written to a log file. See "Logging while Gremlins Are Running" for more information.
When Palm OS Emulator runs a Gremlin horde, it actually maintains a separate stream for each Gremlin in the horde. When it starts a horde, the Emulator first saves the complete state of the emulation to a session (PSF
) file. Then, the Emulator:
- Starts the first Gremlin. When the Gremlin has posted a number of events equal to the specified switching depth, the Emulator saves its state to a new file and suspends the Gremlin.
- Reloads the original session state.
- Starts the second Gremlin and run it until it posts that number of events, at which time its state is saved to another file, and the Gremlin is suspended.
- Runs each Gremlin in the horde, until each has been suspended or terminated:
- Returns to the first suspended Gremlin in the horde, reloads its state from the saved file, and resumes its execution as if nothing else had happened in the meantime.
- Continues cycling through the Gremlins in the horde until each Gremlin has finished. A Gremlin finishes when either of these conditions occurs:
Running a Gremlin Horde
Select Gremlins>New... to start a Gremlin. The New Gremlin Horde dialog box displays, as shown in Figure 5.3. Use this dialog box to specify the characteristics of the Gremlin horde that you want to run.
TIP: If you wish to run a single Gremlin, simply set the Gremlin Start Number and Gremlin End Number fields to the same value.
Figure 5.3 New Gremlin Horde Dialog Box

When Palm OS Emulator runs the example shown in Figure 5.3, the horde will operate as follows:
- The Emulator will only run the Address application when generating key and stylus events for this horde.
- The Emulator will use a seed value of 2 for the first Gremlin in the horde and a seed value of 14 for the last Gremlin in the horde. It also runs all intervening Gremlins: numbers 3 through 13.
- The Emulator will generate 25 events for each Gremlin before switching to the next Gremlin in the horde.
- The Emulator will cycle through the Gremlins in the horde until a total of 1000 events have been generated for each Gremlin. Thus, a total of 13,000 events will be generated.
This means that the Emulator will generate the following sequence of Gremlin events:
- Gremlin #2 runs and receives twenty-five events, after which Gremlin 2 is suspended.
- Gremlin #3 runs and receives twenty-five events, after which Gremlin #3 is suspended.
- Similarly, each Gremlin (#4 through #14) runs and receives twenty-five events, after which it is suspended.
- The Emulator loops back to Gremlin #2 and runs it, sending it twenty-five events before again suspending it.
- Gremlin #3 runs again, receives twenty-five events, and suspends.
- This looping through the Gremlins and sending each events until the switch depth (25) is reached continues until the maximum number of horde events (1000) have been generated.
- All activity for the Gremlin horde completes.
NOTE: If an error occurs while a specific Gremlin is running, Palm OS Emulator halts that Gremlin rather than suspending it. This means that the Gremlin is not run when the Emulator next iterates through the horde.
Stepping and Stopping Gremlins
After the horde starts running, Palm OS Emulator displays the Gremlin control dialog box, which is shown in Figure 5.4. You can use the commands in this dialog box to stop, resume, and single-step a Gremlin. You can also use the Gremlins menu to perform these actions.
Figure 5.4 The Gremlin Control Dialog Box

Gremlin Snapshots
When you start a new Gremlin horde, you can specify that you want Palm OS Emulator to take a snapshot on a regular basis. You specify a frequency value, as shown in Figure 5.3, and the Emulator saves a session file each time that many Gremlins have run. Each snapshot is a PSF
file that captures the current state of the emulation. You can open the snapshot in the Emulator as a new session and begin debugging from that state.
Logging while Gremlins Are Running
Palm OS Emulator lets you specify separate logging options to use while Gremlins are running. Figure 5.5 shows the Gremlin logging options dialog box. Each of the options is described in "Logging Options".
Figure 5.5 Gremlin Logging Options Dialog Box

Using Gremlin Events
When Gremlins are running, all generated events are saved to a Palm event file (PEV
file). This event file contains a snapshot of the initial session state and a list of all of the events that Gremlins generated.
Replaying Gremlin Events
To replay the events stored in a Palm event file, use Gremlins>Replay... to select the PEV
file. Replaying events from a Palm event file is similar to running the same Gremlin on the same application over again; however, with the replay function, Emulator is reading the events from a file rather than generating the same random events to post to the application.
Minimizing Gremlin Events
Palm OS Emulator provides an event minimization function that takes events stored in a Palm event file (PEV
) and identifies the minimal set of events required to produce a crash.
To use the Gremlin minimization function, use Gremlins>Minimize... to select the PEV file. Emulator will open the Palm events file, and replay the events in it. The minimization function will go through an iterative process of removing ranges of events to see if the resulting subset of events still produces a crash.
If a crash still occurs with the subset of events, then those events are removed, and another range of events is similarly tested. If a crash does not occur, then the removed events are put back and the iterative process continues.
The end result is a minimal set of events that produces a crash. (The crash may not be exactly the same crash caused by the full set of events.) This minimized set of events is saved to a new Palm event file, which you can use with the Gremlins>Replay... function. The minimized set of events is also translated into a sequence of English instructions that you can use for debugging. This sequence list is written to a text in the same directory as the Palm events file.
Setting Breakpoints
You can set breakpoints in your code with the Emulator. When Palm OS Emulator encounters a breakpoint that you have set, it halts and takes one of the following actions:
- If you are running the Emulator connected to a debugger, the Emulator sends a message to the debugger, informing it that the breakpoint was hit. The debugger then handles that command as it sees fit.
- If the Emulator is not connected to a debugger, the Emulator displays an error message.
To set a breakpoint, select Breakpoints from the Settings menu. The Breakpoints dialog box is displayed, as shown in Figure 5.6.
Figure 5.6 Setting a Breakpoint

Setting the Data Breakpoint
You can set exactly one data breakpoint. While your program is executing, the Emulator watches the specified address range; if it is written to, the Emulator generates a break. You can specify both the address and number of bytes in either hexadecimal (0x
) or decimal.
Setting Conditional Breakpoints
You can set up to six independent conditional breakpoints. The Emulator generates a break for a conditional breakpoint when both of the following are true:
To set one of these breakpoints, select the breakpoint number in the list at the top of the dialog box, and click Edit. This displays the Code Breakpoint dialog box, which is shown in Figure 5.7.
Figure 5.7 Setting a code breakpoint

To set the breakpoint, specify an address and the break condition. You can specify the address in hexadecimal (0x) or decimal.
The condition that you specify must have the following format:
<register> <condition> <constant>Debugging with External Debug Tools
Palm OS Emulator provides an interface that external debugger applications can use to debug an application. For example, Metrowerks has developed a plug-in module that you can use to debug an application that Palm OS Emulator is running, in exactly the same manner as you would debug an application running on the handheld. This plug-in module is shipped with the latest version of CodeWarrior for Palm OS.
Connecting Emulator with Palm Debugger
You can use Palm Debugger with Palm OS Emulator to perform extensive debugging of your applications. To use Palm Debugger with the Emulator, follow these steps:
- Start Palm Debugger and Palm OS Emulator programs.
- In the Palm Debugger Communications menu, select Emulator. This establishes the emulator program as the "device" with which Palm Debugger is communicating.
- In the debugging window, type the
att
command.
You can now send commands from Palm Debugger to Palm OS Emulator.
Connecting Emulator with the GDB Debugger
You can use the gdb debugger with Palm OS Emulator to debug your applications. To use the gdb debugger with an emulator session, follow these steps:
- When you build your application, both compile and link with the
-g
option (that is, using "gcc -g ...
"). When you compile using the-g
option, the compiler generates the necessary symbol information. When you link using the-g
option, the linker forces the inclusion of a debug runtime routine that installs a breakpoint inPilotMain
. - Start Palm OS Emulator, and install your application in the emulator session.
- Start the gdb debugger, loading your application's symbol table (for example, using "
gdb myApp
"). Note that the file to be loaded is themyApp
file created by the gcc linker, not themyApp.prc
created by buildprc. - In the gdb debugger, enter "
target pilot localhost:2000
". The gdb debugger will respond with a message indicating that remote debugging is starting. - Start your application on Palm OS Emulator.
- Wait for the gdb debugger to see the initial breakpoint and prompt you, then start debugging.
Connecting the Emulator with External Debuggers
Palm OS Emulator can communicate with external debuggers using the methods shown in Table 5.3.
Table 5.3 Palm OS Emulator Connections
NOTE: Currently, Palm Debugger uses TCP only when running on Windows. The CodeWarrior plug-in uses TCP if you select
Use sockets
in the debugger preference panel.However, although you can configure the TCP port that Palm OS Emulator uses, you cannot configure which TCP port that either Palm Debugger or the CodeWarrior plug-in uses.
If you are communicating with a debugger using TCP, you can configure which socket port the debugger connects to by editing the value of the DebuggerSocketPort
preference setting in your preferences file. You can disable the TCP connection by setting the value of the DebuggerSocketPort
preference to 0
.
NOTE: In some versions of Palm OS Emulator, you may notice that an unwanted PPP dial-up starts whenever you begin a new emulation session. You can disable this behavior by disabling the use of TCP for communications, which you do by setting the
DebuggerSocketPort
preference to 0
.
Tracing Your Code
At times, regular debug tools can be disruptive to program execution or can require specific knowledge of where a bug is located. Tracing can be a less disruptive method for showing how a program is executing. Tracing functions write out information at the time the tracing functions are executed.
To use tracing in your code, you need to do the following:
- Install Palm Reporter.
Palm Reporter is a trace utility that can be used with Emulator. As an application runs on Palm OS Emulator, it can send information in real time to Reporter. This information can help pinpoint problems that might be hard to identify when executing code step-by-step or when specifying breakpoints.
- Add trace calls to your application. The tracing functions are listed in Table 8.16.
- Next, you need to specify where you want the tracing information to appear. Emulator's tracing options dialog box, which is shown in Figure 5.8, lets you specify the target for application trace information. Use Settings>Tracing... to display this dialog box.
Figure 5.8 Tracing Options Dialog Box without PalmTrace

If you do not have Palm Reporter's PalmTrace.dll
file on your system, then the default setting discards the tracing information.
When you have the PalmTrace.dll
installed on Windows, then you will see a tracing options dialog box that looks like Figure 5.9.
Figure 5.9 Tracing Options Dialog Box with PalmTrace.dll on Windows

With PalmTrace.dll
installed on Windows, you can set your tracing target to be either Palm Reporter or a text file.
When you have PalmTrace
library installed on Macintosh, then you have an additional tracing target: you can set the tracing target to be either Palm Reporter, a text file, or the DCON console.
Using Reporter to View Realtime Traces
To view the realtime traces, simply run Reporter at the same time as you run your application on Palm OS Emulator. For more information about using Palm Reporter, see Palm OS Programming Development Tools Guide.
Profiling Your Code
One of the features of Palm OS Emulator that is most useful for developers is the ability to profile your application while it is running, and to save the resulting data to a file that you can examine.
When the Emulator profiles your application, it monitors and generates statistics about where your code is spending its time, which enables you to focus your optimization efforts in the most productive manner.
NOTE: In order to use the profiling features, you must be using a version of Palm OS Emulator with profiling enabled.
On Windows and Macintosh, this means that you must be using the executable with "
profile
" in its name. See Table 2.1 for more information. On Unix, this means that you must build the executable with the configure switch "
--enable-palm-profile
". (See the _Building.txt
file mentioned in Table 2.1.)
You can start a profiling session by choosing Profiling Start. While profiling is active, Palm OS Emulator monitors which application and system functions are executed, and the amount of time executing each. The Emulator collects the timing information until you select Profiling Stop.
You can then save the profiling information to a file by selecting Profiling Dump. The information is saved to file in two different formats. Both of these files are stored in the directory in which the Emulator executable is located:
A text version of the profiling results. |
|
A Metrowerks Profiler version of the results. The The |
You do not have to prepare your code in any special way for Palm OS Emulator to profile it, because the Emulator can determine when functions are entered and exited on its own. And the Emulator performs its profiling calculations between cycles, thus the timing information is quite accurate.
NOTE: It is a good idea to set your compiler's switch to embed debug symbols in your code so that you can easily interpret the profiling results. With CodeWarrior, you should set the option Generate MacsBugs Debug Symbols. With GCC, you should use the Palm OS specific GCC option
-mdebug-labels
. With MacsBugs, you will get each function's name in the text section immediately after the function's code.