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

5    Testing Applications Using Palm OS Emulator

Using Palm OS® Emulator

Palm OS Developer Suite

This chapter describes how you can use Palm OS® Emulator to test and debug programs you have written for Palm OS.

Testing Software ^TOP^

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 ^TOP^

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 

Option

Description

Free chunk access

Monitors access to free memory chunks.

No process should ever access the contents of a chunk that has been deallocated by the MemChunkFree, MemPtrFree, or MemHandleFree functions.

Hardware register access

Monitors accesses to hardware registers by applications.

For example, Emulator monitors memory ranges reserved for external LCD controllers, USB controllers, and Programmable Logic Devices (PLD).

Low memory access

Monitors low-memory access by applications.

Low-memory access means an attempt to read from or write to a memory location in the range 0x0000 to 0x00FF.

Low stack access

Monitors access to the range of memory below the stack pointer.

MemMgr data access

Monitors access to Memory Manager data structures, which is restricted to only the Memory Manager.

Memory Manager data structures are the heap headers, master pointer tables, memory chunk headers, and memory chunk trailers.

Emulator allows no access to data structures for which there are PalmOSGlue accessor routine defined.

MemMgr leaks

Detects memory leaks. Emulator checks for memory leaks on SysAppExit.

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 -mdebug-labels. With MacsBugs, you will get each function's name in the text section immediately after the function's code.

MemMgr semaphore

Monitors how long the Memory Manager semaphore has been acquired for write access using the MemSemaphoreReserve and MemSemaphoreRelease functions.

Your applications should not be calling these functions; however, if you must call them, you should not hold the semaphore for longer than 10 milliseconds.

Offscreen form object

Checks for any use of offscreen form objects.

Overlay errors

This option controls a facility of Overlay Manager in the debug version of the ROM files. When this option is enabled, the omFtrShowErrorsFlag bit of the omFtrCreator feature is set to true. As a result, Overlay Manager reports the name of a database that it cannot validate and the reason why it did not validate.

Proscribed function call

Monitors calls to any of the functions on the proscribed function list. See Appendix B, "Unsupported Traps," for a list of functions.

Strict International checks

Checks for multibyte character display routines.

ROM access

Monitors ROM access by applications.

Screen access

Monitors LCD screen buffer access by applications.

LCD screen buffer access is defined as reading from or writing to the memory range indicated by the LCD-related hardware registers.

Sizeless form object

Checks for any use of sizeless form objects (objects whose height or width is zero).

Stack almost full

Ensures that the stack pointer has not dipped below the space allocated for it by the kernel.

When this option is enabled, Palm OS Emulator warns you when the application stack is getting close to full.

Note that you are always notified of a stack overflow, even if this option is disabled.

System global access

Monitors access to system global variables by applications.

System global variable access is defined as reading from or writing to a memory location in the range from 0x0100 to the end of the trap dispatch table.

UIMgr data access

Checks for any access of User Interface Manager data structures.

Unlocked chunk access

Monitors read access to uninitialized portions of memory chunks that have been allocated by the MemHandleNew function.

Warns about the case where you use a stale pointer from when a moveable chunk is locked and unlocked. Also catches cases of misusing a pointer to one chunk to access a subsequent chunk.

Beep every 2 seconds when a dialog is displayed

Causes Emulator to beep every two seconds while a message dialog box is displayed. Emulator will stop beeping after one minute.

Logging Options ^TOP^

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  

Option

Description

Error messages

Logs error messages that are generally fatal (messages where the Continue button is disabled in the dialog box containing the error message).

Examples: Address errors, divide-by-zero errors, calls to SysFatalAlert.

Warning messages

Logs any message that is displayed in a dialog box that can be dismissed by tapping the Continue button.

Examples: Low memory access, direct screen access, hardware register access.

Misc Gremlin info

Logs information about Gremlins that is mostly useful for debugging the Gremlins themselves.

Assembly opcodes

Logs assembly-level trace information, including registers, the program counter, opcodes, and related information.

This option is not yet implemented.

Posted events

Logs events that have entered into the system by way of calls to the EvtAddEventToQueue, EvtAddUniqueEventToQueue, EvtEnqueuePenPoint, and EvtEnqueueKey functions.

Received events

Logs events returned by calls to the EvtGetEvent, EvtGetPen, and EvtGetSysEvent functions.

System calls

Logs calls to Palm OS functions.

Application calls

Logs calls to functions in your application.

This option is not yet implemented.

Serial activity

Logs changes in serial port settings, and the opening and closing of the serial port.

NetLib activity

Logs calls to NetLib functions, including parameter and return values.

ExgMgr activity

Logs calls to ExgMgr functions.

RPC activity

Logs remote procedure calls.

High-level debugger activity

Logs messages received back from an external debugger, and the messages sent back to the debugger.

Low-level debugger activity

Traces the low-level mechanisms that receive raw data from external debuggers and send data back to external debuggers.

Serial data

Logs data sent and received over the serial port. Data is logged as it is being transferred over the host serial port

Incoming data follows this path:

  1. Serial port
  2. Emulated hardware registers
  3. Palm OS
  4. Palm OS application


Palm OS Emulator logs the serial port data.

Outgoing data follows this path:

  1. Palm OS application
  2. Palm OS
  3. Emulated hardware registers
  4. Serial port


Again, Palm OS Emulator logs the serial port data.

NetLib data

Logs data sent and received via NetLib calls.

ExgMgr data

Logs data sent and received via ExgMgr calls.

RPC data

Logs data sent and received via remote procedure calls.

High-level debugger data

Logs details of the messages sent to and received from an external debugger.

Low-level debugger data

Logs the raw data being sent to and received from an external debugger.

Using Gremlins to Automate Testing ^TOP^

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 ^TOP^

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 ^TOP^

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:
    • A Gremlin is terminated when an error occurs while the Gremlin is posting events.
    • A Gremlin is suspended when it has posted a number of events equal to the switching depth for the horde.
  • 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:
    • the Gremlin has terminated due to an error
    • the Gremlin has posted a total number of events equal to the maximum specified for the horde.

Running a Gremlin Horde ^TOP^

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:

  1. Gremlin #2 runs and receives twenty-five events, after which Gremlin 2 is suspended.
  2. Gremlin #3 runs and receives twenty-five events, after which Gremlin #3 is suspended.
  3. Similarly, each Gremlin (#4 through #14) runs and receives twenty-five events, after which it is suspended.
  4. The Emulator loops back to Gremlin #2 and runs it, sending it twenty-five events before again suspending it.
  5. Gremlin #3 runs again, receives twenty-five events, and suspends.
  6. 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.
  7. 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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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:

  • the program counter reaches the specifies address
  • the specified condition is 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>
register One of the registers: A0, A1, A2, A3, A4, A5, A6, A7, D0, D1, D2, D3, D4, D5, D6, or D7.
condition One of the following operators: ==, !=, <, >, <=, or >=.
constant A decimal or hexadecimal constant value.

IMPORTANT: All comparisons are unsigned.

Debugging with External Debug Tools ^TOP^

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 ^TOP^

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:

  1. Start Palm Debugger and Palm OS Emulator programs.
  2. In the Palm Debugger Communications menu, select Emulator. This establishes the emulator program as the "device" with which Palm Debugger is communicating.
  3. 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 ^TOP^

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:

  1. 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 in PilotMain.
  2. Start Palm OS Emulator, and install your application in the emulator session.
  3. Start the gdb debugger, loading your application's symbol table (for example, using "gdb myApp"). Note that the file to be loaded is the myApp file created by the gcc linker, not the myApp.prc created by buildprc.
  4. In the gdb debugger, enter "target pilot localhost:2000". The gdb debugger will respond with a message indicating that remote debugging is starting.
  5. Start your application on Palm OS Emulator.
  6. Wait for the gdb debugger to see the initial breakpoint and prompt you, then start debugging.

Connecting the Emulator with External Debuggers ^TOP^

Palm OS Emulator can communicate with external debuggers using the methods shown in Table 5.3.

Table 5.3 Palm OS Emulator Connections 

Connection type

Platforms

TCP

All

PPC Toolbox

Macintosh

Memory-mapped files

Windows


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 ^TOP^

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.


NOTE: Tracing is not available on Unix.

Using Reporter to View Realtime Traces ^TOP^

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 ^TOP^

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:

File name

Description

Profile Results_

<number>.txt

A text version of the profiling results. <number> is a four-digit number incremented each time the profiling results are saved.

Profile Results_

<number>.mwp

A Metrowerks Profiler version of the results. <number> is a four-digit number incremented each time the profiling results are saved.

The MWP file can be used with the MW Profiler application bundled with CodeWarrior Pro. The MW Profiler is only available on Macintosh computers.

The MWP file can also be used with other analysis tools. These tools are listed on the Emulator web page (http://www.palmos.com/dev/tools/emulator/).

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.