Palm OS Debugging

Developer Technical Services

February 2007
Agenda

• Debugging background information

• Simulator vs. on-device debugging
• CodeWarrior
• Palm OS Developer Suite
• DebugPrefs
• PalmDebugger

Palm, Inc. Confidential Date 2

Debugging Tools
This presentation will discuss the following debugging tools:
• Software:
– Simulators (Release Simulators and Debug Simulators, by device)
– CodeWarrior
– Palm OS Developer Suite by ACCESS
– DebugPrefs * (on Treo)
– PalmDebugger *
• Hardware:
– Treo serial cable
– Treo USB cable

* Available for download at https://pdn.palm.com

Palm, Inc. Confidential Date 3
Background – console mode

– Console mode is a Palm OS

background task
• The device works as usual
• Visual cue for console mode is the
blinking block in the lower-right
corner of the screen
– Ready to connect to
• CodeWarrior debugger
• PalmDebugger (68K debugging)

– To connect, enter shortcut-dot-two or

shift-HotSync
– To exit, soft reset the device

Palm, Inc. Confidential Date 4

Background – debug mode

– Debug mode
• There is no response to keyboard
and touch screen input
• Visual cue for console mode is a
blinking block in the lower-left
corner of the screen
– Ready to connect to PalmDebugger
and receive debugging commands
– To connect, enter shortcut-dot-one or
shift-option-HotSync
– To exit, soft reset the device

Palm, Inc. Confidential Date 5

Agenda

• Debugging background information

• Simulator vs. on-device debugging
– Simulator overview
– Debug Simulator
– Simulator vs. on-device debugging
– Debugging tips
• CodeWarrior
• Palm OS Developer Suite
• DebugPrefs
• PalmDebugger

Palm, Inc. Confidential Date 6

Simulator Overview

– The Simulator application name is

PalmSim.exe
– Combines Palm apps, carrier-specific
apps, Palm OS, and libraries
– Drag and drop the .prc file onto the
Simulator to start
– Runs native .prc files
– Simulates UI, 5-way navigation, and
basic functionality
– Network redirect to your local host
TCP/IP

Palm, Inc. Confidential Date 7

Simulator Overview

The Simulator includes the following views:

– Databases
– Heaps (Memory)
– Events

Palm, Inc. Confidential Date 8

Simulator Overview – Databases View
Displays the content of databases

Palm, Inc. Confidential Date 9

Simulator Overview – Heaps View
Displays heaps. To dump a heap, double click it.

Palm, Inc. Confidential Date 10

Simulator Overview – Events Views
Displays debugging events

Palm, Inc. Confidential Date 11

 Simulator Overview

Gremlins by ACCESS is useful for:

– Debugging applications that have been
developed from scratch
– Testing random events
– Basic functionality testing
For more information, refer to the
ACCESS website*

* http://www.access-company.com/developers/documents/docs/palm_os_garnet_simulator53.pdf

Palm, Inc. Confidential Date 12

Debug Simulator
The Debug Simulator displays more information than the “Release” Simulator.
It displays:
– Fatal errors
– Non-fatal alerts
– Other information hidden from end users
– Highly recommended for debugging

Palm, Inc. Confidential Date 13

Simulator vs. On-device Debugging
Use Simulator (on-PC) debugging for:
– Single stepping through 68K source code
– Finding memory leaks
– Checking basic functionality
– Checking quick changes, for example, to the UI
– Check to see if a crash is caused by an inappropriate API call. For
example, has the wrong parameter been passed?

Palm, Inc. Confidential Date 14

Simulator vs. On-device Debugging

Use on-device debugging for:

– Radio related issues, such as:
• Voice
• Data
• Wi-Fi
• Bluetooth
– Detecting memory corruption
– Watching variables
– Obtaining stack traces
– Testing speed

Palm, Inc. Confidential Date 15

Simulator Debugging Tips

– Ignore the error, “First-chance exception in PalmSim.exe

(SYSTEM.DLL): 0xC0000005: Access Violation.”
– If your interface hasn’t updated, drag the .prc onto the Simulator.
– If you see the “File already in use” error, kill all PalmSim.exe processes
in Task Manager.

Palm, Inc. Confidential Date 16

Agenda

• Debugging background information

• Simulator vs. on-device debugging
• CodeWarrior
• CodeWarrior overview
• Simulator debugging
• On-device debugging
• Debugging tips
• Palm OS Developer Suite
• DebugPrefs
• PalmDebugger

Palm, Inc. Confidential Date 17

CodeWarrior Overview
CodeWarrior is a useful development/debugging tool for:
• Source code debugging
• Pre-crash debugging

Use CodeWarrior to connect to

• Simulator
• Device via serial and USB

The PilRC Designer tool is useful for:

• UI design
• Debugging
Find the PilRC tool at ~\\Metrowerks\CodeWarrior\CW for Palm OS
Tools\PilRC Designer\pilrcdesigner.exe

Palm, Inc. Confidential Date 18

CodeWarrior Overview
Common CodeWarrior debugging functions:
• Setting application breakpoints
• Stepping through and into code
• Viewing memory
• Changing variable values
• Changing PC values
• Launching your application using different launch codes

Palm, Inc. Confidential Date 19

CodeWarrior Overview

CodeWarrior allows you to:

– Launch applications with different
launch codes:
• sysAppLaunchCmdNormalLaunch
• sysAppLaunchCmdFind
• sysAppLaunchCmdSystemReset
– Setup launch codes:
• Debug Settings > Palm OS
Debugging > Launch code
For more information on launch codes,
refer to the ACCESS Developer
Network
* http://www.access-company.com/developers/documents/docs/palmos/
PalmOSReference/AppLaunchCodes.html#1012458

Palm, Inc. Confidential Date 20

CodeWarrior – Simulator Debugging

– To use the Simulator, first, launch it

– To debug with the Simulator, navigate to:
• Settings > Palm OS Debugging > Connect to > Emulator >
Palm OS Simulator
– Next, enter RUN or F5
• Loading the binary – The .prc is loaded onto the Simulator when
the debugging session is initiated
• Loading the symbol – The debugger can only be initiated from the
from project build environment (.mcp)
– Start debugging: Step through code, step in, step out, set
breakpoints, etc.

Palm, Inc. Confidential Date 21

CodeWarrior – On-Device Debugging

Debugging with CodeWarrior produces accurate, real-time information

– Step 1: Debug with device:
• Settings > Palm OS Debugging > Connect to > Device >
COM1 or USB

– Step 2: Connect with USB or Serial port (USB is faster)

– Step 3: Put your device in Console mode

• CodeWarrior only works with console mode; shortcut-dot-two or
shift-HotSync
Note: The sequence of steps 1, 2, and 3 don’t matter.
– Step 4: Select RUN or F5. CodeWarrior loads .prc and resource files.
• Shortcut-dot-three prevents the device from going to sleep

Palm, Inc. Confidential Date 22

CodeWarrior – Debugging Tips

– If CodeWarrior can’t delete a database:

• Make sure that the application is not running
• Delete the existing .prc, if necessary

– If you cannot connect to CodeWarrior:

• Make sure the USB or serial cable is not being used by other
programs, such as Palm Desktop manager, PalmDebugger, etc.
• Check the COM port and baud rate (57600)
• Check usbport.dll (USB cable only). If necessary, move it from
c:\WINDOWS\system32 to c:\program files\palmOne (or Palm)
(Make sure to move the file, DO NOT just copy the file.)

Palm, Inc. Confidential Date 23

CodeWarrior – Debugging Tips

• If you cannot connect to CodeWarrior, check the following:

– Is it a large app slowing things down?
– Are you using the correct port, and is it configured correctly?
• If you still cannot connect:
– Shut down CodeWarrior and restart
– Reset the Treo smartphone
– Check the cable settings in DebugPrefs
• CodeWarrior limitations:
– The CW debugger cannot be used for post-crash debugging
– The CW debugger cannot be used to check CPU registers

Palm, Inc. Confidential Date 24

Agenda

• Debugging background information

• Simulator vs. on-device debugging
• CodeWarrior
• Palm OS Developer Suite
• DebugPrefs
• PalmDebugger

Palm, Inc. Confidential Date 25

Palm OS Developer Suite (PODS)

– Download PODS from ACCESS at:

http://www.access-company.com/developers/documents/tools/index.ht
ml
– PODS supports Palm Simulator and on-device debugging
• Connect to Palm Simulator by navigating to Window > Preferences >
Palm OS Development > Target Environment Setting > NEW
PODS is useful for:
– 68K source code debugging
– Visual UI design
– Checking variables, memory, registers, and databases
– PODS includes integrated documents, including tips and tricks from
ACCESS

Palm, Inc. Confidential Date 26

Palm OS Developer Suite (PODS)

Palm, Inc. Confidential Date 27

Agenda

• Debugging background information

• Simulator vs. on-device debugging
• CodeWarrior
• Palm OS Developer Suite
• DebugPrefs
• PalmDebugger

Palm, Inc. Confidential Date 28

DebugPrefs Overview

DebugPrefs is a Palm OS application that runs on Treo devices.

It is useful for:
– Setting debugging settings
– Disabling silent resets
– Post-crash debugging
– At crash time, DebugPrefs will display a fatal alert. Choose Debug, and
the keyboard will flash, indicating post-crash debugging
DebugPrefs is part of the Palm OS SDK, available for download from PDN
at https://pdn.palm.com

Palm, Inc. Confidential Date 29

DebugPrefs

Palm, Inc. Confidential Date 30

Agenda

• Debugging background information

• Simulator vs. on-device debugging
• CodeWarrior
• Palm OS Developer Suite
• DebugPrefs
• PalmDebugger
– PalmDebugger overview
– 68K source code debugging
– Post-crash debugging
– Debugging tips

Palm, Inc. Confidential Date 31

PalmDebugger Overview

PalmDebugger is an assembly-level debugger for Palm OS. It is useful for:

– Source-level debugging of GCC-compiled 68K code
– Post-crash debugging
– Importing .prc / .pdb file
– Exporting database file
– Heap dumps
– Listing the database
– Viewing the CPU register and memory
– Keyboard shortcuts are same with CodeWarrior
– Cannot use with CodeWarrior builds
PalmDebugger is part of the Palm OS SDK, available for download from
PDN at https://pdn.palm.com

Palm, Inc. Confidential Date 32

PalmDebugger Overview
• PalmDebugger uses both Serial and USB connections
• PalmDebugger does not includes the following features:
– Modifying variables
– Checking the CallStack (not enabled in 68K source level debugging)
– Stepping out to next function call
For more information on using PalmDebugger, refer to the ACCESS Developer
Network at:
http://www.access-company.com/developers/documents/docs/devguide/Usi
ngDebugger.html#997418

or refer to the Palm Developer Guide, Palm OS Platform, which is part of the
Palm OS SDK available for download at https://pdn.palm.com

Palm, Inc. Confidential Date 33

PalmDebugger – Connecting to the Device

• To load application symbols, navigate to Menu > Source > Load Symbols
<F12>

• Modes:
– Use console mode to load your .prc for source level debugging
– Use debug mode to break into the debugger for post-crashing
debugging

Palm, Inc. Confidential Date 34

PalmDebugger – connecting to the device
• To use PalmDebugger for 68K source code debugging:
– Compile your application with GCC compiler
– Load the .prc and .sym files (built with debugging information)
• Ignore the dialog that asks you to locate gdbstub.c
– Set breakpoints first, open the source file, setup breakpoints, and run
again
• If you can’t set breakpoints, close PalmDebugger and reopen or reset
• Your device will not respond keyboard/touch screen input until you
run your app again

• To use PalmDebugger for post-crash debugging:

– At the blue fatal screen, click Debug
– You will see a blinking keyboard and a blinking line at the top the screen
– Connect to PalmDebugger
– In the “Debug” window, enter the command “att”
Palm, Inc. Confidential Date 35
PalmDebugger Commands
– att – attach to the debugger
– dm <addr> <numBytes> – reads arbitrary memory addresses
– hd 0 – Dumps the dynamic heap (Slow)
– hd 1 – check the DBcache state (Very slow)
(45 minutes via serial)
– Help – console command list
– il pc-20 40 \bytes – disassembles around the current PC
– opened – shows opened databases
– Ping – in console window, check if the connection
is still valid
– reg – emulated CPU registers
– sc a6 20 – attempts a stack crawl
– wh \a pc – Tries to identify the database
containing the PC (Very slow)

Palm, Inc. Confidential Date 36

PalmDebugger – Heap dumps tips

– Palm Debugger heaps dumps are useful for:

• Finding memory leaks
• Analyzing memory corruption
– Use the “hd 0” command in the debugger window of PalmDebugger
– Shows all memory chunks allocated—there may be a lot
– If the heap structure is corrupted, the heap dump will usually report it

Palm, Inc. Confidential Date 37

PalmDebugger – Heap corruption tips
Heap corruption is commonly caused by:
– Buffer overruns / underruns
• If you write to a memory location either before or after your chunk, you
will corrupt the structure of the heap
• Chunks are sequential in memory, so a buffer overrun corrupts the
header for the next chunk, a buffer underrun corrupts the header of
your chunk.
– Uninitialized pointers
• Writing to a freed chunk of memory
• Writing to an unlocked, movable chunk

For more crash debugging information, refer to the Palm Developer Guide,
Palm OS Platform, which is part of the Palm OS SDK, available for
download from PDN at https://pdn.palm.com

Palm, Inc. Confidential Date 38