This chapter discusses Palm OS Debugger preferences.
The easiest way to set preferences is to import preset values from a preferences XML file. However, this chapter describes the preferences in detail in case you need to set specific preferences for debugging scenarios not covered by the preset value files.
This chapter covers the following topics:
- "How to Set Preferences"
- "Importing and Exporting Preferences"
- "Communications Preferences"
- "Debugger Plug-in Preferences"
- "Debugger UI Preferences"
- "Disassembler Preferences"
- "Download Plug-ins Preferences"
- "Protocols Preferences"
- "Runtime Helpers Preferences"
- "Symbolics Preferences"
How to Set Preferences
To set Palm OS Debugger preferences:
Figure 3.1 Debugger Preferences Dialog Box

- Select a category from the category tree, click the plus sign (+) next to it to expand it, and select a subcategory. This opens a preference panel for that subcategory.
Figure 3.2 Debugger Preferences dialog box with the Serial subcategory selected

- Edit the settings.
- Click Apply to save your changes, or click Revert to discard the changes. (You also have the option of clicking Cancel to discard the changes, but clicking Cancel also closes the Debugger Preferences window.)
- Select other categories and edit their preference panels.
- To return a panel to its default settings, open the panel and click Default.
- When you are finished setting preferences, click OK to close the Debugger Preferences dialog box.
NOTE: In the panel where the preference settings are displayed, you can resize the caption field and the value field. For example, if the field is too short and the contents of the field do not display completely, you can make the field longer. To do this, use the resize bar located between the caption field and the value field. Drag the resize bar to the left or right to expose the contents of either field.
Importing and Exporting Preferences
Palm OS Debugger offers pre-set preferences files, written in XML format, that you can use to set up the appropriate preferences for debugging. You can also create your own pre-set preferences files.
Importing
To use pre-set preferences, use the Import button in the Debugger Preferences window.
To import pre-set preferences:
- In the Debugger Preferences window, click the Import button. This opens a dialog box entitled Select an XML data file to import.
- Browse to the directory
Preset Prefs
and select the file whose name corresponds to the debug target you are using.
Exporting
You can create your own pre-set preferences files.
Exporting Preferences from One Preferences Panel
To create a pre-set preferences file containing the preferences from one preferences panel:
- In the Debugger Preferences window, select an item from the category tree to display the preferences panel containing the preferences you want to export.
- Click the Export button to open a Save as dialog box.
- Browse to the location for your preferences file.
- Type a name for the preferences file.
- Click Save to save your preferences in an XML file.
Exporting All Palm OS Debugger Preferences
To create a pre-set preferences file containing all your Palm OS Debugger preferences:
- In the Debugger Preferences window, click the Export All button to open a Save as dialog box.
- Browse to the location for your preferences.
- Type a name for the preferences file.
- Click Save to save all your Palm OS Debugger preferences in an XML file.
Communications Preferences
To set Communications Plug-in preferences, select Communications from the category tree, and then select Serial or Sockets.
The default settings in this panel are the correct settings for debugging with a Palm OS Garnet or Palm OS Cobalt device over a serial connection.
Serial Preferences
If you are connecting a device to Palm OS Debugger through a serial connection, set these preferences.
Port
Baud Rate
Data bits
Stop bits
Parity
DTR Enable
Default setting is false, which means that Data Terminal Ready (DTR) is not enabled.
CTS Enable
Default setting is false, which means that Clear To Send (CTS) is not enabled.
XON/XOFF Enable
Default setting is false, which means that XON/XOFF (special characters that you can insert into the byte stream) is not enabled.
XON Character
XOFF Character
Sockets Preferences
If you are connecting to Palm OS Debugger through a sockets connection, set these preferences. This plug-in communicates over standard sockets to the IP address and port that you specify here.
NOTE: These settings are available for connecting to Palm OS Simulator or Palm OS Emulator. Note that no Palm OS Emulator ROM is available for Palm OS Garnet or Palm OS Cobalt.
IP Address
Default setting is 127.0.0.1, which is the setting to use to connect to a Palm OS Emulator or Palm OS Simulator session running on the same computer that is running Palm OS Debugger.
Port
Debugger Plug-in Preferences
To set Debugger Plug-in preferences, select Debugger Plug-ins from the category tree, and then select 68K or ARM.
The Debugger Plug-in is a parent of the Protocols Plug-in (for information on Protocol settings, see "Protocols Preferences").
68K Preferences
Set these preferences for general 68K debugging settings that affect all 68K-related protocols. Currently, the only protocol available for 68K debugging is the 68K Palm OS Debug Kernel Protocol Plug-in.
This plug-in is used to communicate with 68K-based devices or with ARM-based devices through PACE. (PACE is the Palm OS Application Compatibility Environment. For more information about PACE, see Palm OS Simulator Guide.)
Protocol
Default setting is 68K Palm OS Debug Kernel Protocol Plug-in. This is the only valid setting for 68K debugging.
Max stack frames
When you are doing a stack trace, if the stack crawl is taking a long time, you can limit the maximum number of stack frames that get displayed to improve the stack crawl speed.
Cache stack backtrace
Default setting is false, which means the Stack Trace window (see "Stack Trace View") does not reuse information from the previous stack trace.
If you set this to true, the Stack Trace window may reuse information from the previous stack trace, if you are still in the same function the next time you stop someplace in the code.
Stop at entry point
Default setting is true, which means Palm OS Debugger stops at the entry point of your program, as if you had set a breakpoint there. (You can specify your application entry point under Protocol Preferences > 68K Palm OS Debug Kernel Preferences. See "Application Entry Point".)
ARM Preferences
Set these preferences if you are connecting to an ARM device.
NOTE: Rather than setting these preferences manually, you can import preset preferences for most protocols. For details, see "Importing and Exporting Preferences".
Protocol
Select the protocol that corresponds to the type of connector you are using. The only valid option is ARM Palm OS 5 Debug Nub.
Real Time OS Plug-in
Default setting is None. Palm OS Debugger uses the other values for JTAG debugging. These values are not valid for application debugging with debugging nubs such as the 68K-based Debug Manager, PACE, or the ARM-based Debug Manager.
Palm OS Cobalt users also have the option of selecting Palm OS 6.0, which means Palm OS Debugger keeps track of all the processes and threads currently running in Palm OS Cobalt.
Substitute SB for R9
Default setting is true. Do not change this setting if you are doing Palm OS development.
The true setting means that Static Base (SB) is substituted for register 9 (R9). Normally, when the symbolics file contains global variables, the global variables are reported as being in memory at R9 plus an offset. Because the ARM-based Palm OS shared library model relocates global variables using a complex expression, set this preference to true to substitute the Static Base for R9.
SB expression
Default setting for Palm OS Garnet is genreg_pc sect_base constu(8) plus deref dup constu(0xFFFF) and swap constu(16) ror constu(0xFFFF) and constu(5) rol plus genreg_gp1 deref plus deref.
Default setting for Palm OS Cobalt is genreg_pc sect_base constu(8) plus deref.
Do not change this setting if you are doing Palm OS development. This setting specifies the expression that Palm OS Debugger uses to compute the Static Base.
Max stack frames
When you are doing a stack trace, if the stack crawl is taking a long time, you can limit the maximum number of stack frames that get displayed to improve the stack crawl speed.
Cache stack backtrace
Default setting is false, which means the Stack Trace window (see "Stack Trace View") does not reuse information from the previous stack trace.
If you set this to true, the Stack Trace window may reuse information from the previous stack trace, if you are still in the same function the next time you stop someplace in the code.
Correct stack backtrace return address
When you are doing a stack crawl, the return address often points to the instruction following the instruction that called the current subroutine. Setting this preference to true will attempt to correct stack backtrace return addresses to show the actual instruction which called the stack function.
Setting this preference to false will disable this feature.
Launch action
This setting specifies what Palm OS Debugger does when you click Run for the first time.
- Set PC to entry point and halt
- Set PC to entry point and run
- Set PC to reset vector and halt (the reset vector = 0, or 0xffff0000)
- Set PC to entry point and run
- Soft reset
- Hard reset
- Nothing
For debugging applications with the Palm OS Garnet ARM debug nub, set Launch action to Nothing.
Skip downloading code to target
Default setting is false, though an imported setting may change this value to true.
If the code has already been downloaded to the target, you should set this to true so that Palm OS Debugger does not download ARM-based code to the ARM debug nub. (Downloading 68K-based code is handled by the 68K plug-in.)
Allow ROM address overriding
This setting is not used for application debugging.
Download Helper Plug-in
Default setting is None. This setting is not used for application debugging.
Default CPU when unknown
Default setting is ARM. The other option is Thumb.
Symbolics files generally tell Palm OS Debugger exactly which parts of the code are ARM and which parts of the code are Thumb. Palm OS Debugger needs to know which type of code is at a specific address to set breakpoints correctly (breakpoint instructions differ for ARM and Thumb).
This preference specifies how Palm OS Debugger treats code when there are no symbolics for a specific address.
Type/Creator section name
Default setting is .text. In most cases, you should not change this setting.
Palm OS Debugger uses this setting with the Type/Creator section offset setting.
Type/Creator section offset
Default setting is 20. Do not change this setting.
The Type/Creator section offset and Type/Creator section offset settings tell Palm OS Debugger where to find a shared library's type, creator ID, resource, and resource ID information in an ELF file. Palm OS Debugger uses these settings to process shared library load and unload notifications, and to enable and disable breakpoints in a shared library.
Each Palm OS shared library has unique shared library data in the initial bytes of the code section. By default, the code section in the ELF file is named .text
.
Auto symbolic load directory 1
Default setting is to leave this field blank.
Set this field to indicate which directory Palm OS Debugger should recursively scan first in order to find symbolic files.
Auto symbolic load directory 2
Default setting is to leave this field blank.
Set this field to indicate a subsequent directory Palm OS Debugger should recursively scan in order to find symbolic files.
Auto symbolic load directory 3
Default setting is to leave this field blank.
Set this field to indicate a subsequent directory Palm OS Debugger should recursively scan in order to find symbolic files.
Memory mapped register definition file
Default setting is to leave this field blank. If you have created a Memory Mapped Definition file, specify the name and path here.
A Memory Mapped Definition file is an XML file describing all memory mapped registers that are available for a target. These can also be used to describe statically located global variables that are not described in symbolics. For more information and complete XML format documentation, see the Readme file at:
SDK/tools/Palm OS Debugger/Memory Mapped Registers/ReadMe.txt
Also see the sample XML file at:
SDK/tools/Palm OS Debugger/Memory Mapped Registers/SampleDefs.xml
Debugger UI Preferences
To set UI preferences, select Debugger UI from the category tree, and then select Fonts or Session.
Fonts Preferences
Select a font for the data displayed in the Palm OS Debugger windows.
Source view
Default setting is Courier New, 10pt.
Files view
Default setting is MS Sans Serif, 9pt.
Breakpoints view
Default setting is MS Sans Serif, 9pt.
Registers view
Default setting is Courier New, 9pt.
Variables view
Default setting is Courier New, 9pt.
Global Variables view
Default setting is Courier New, 9pt.
Memory view
Default setting is Courier New, 9pt.
Stack Trace view
Default setting is Courier New, 9pt.
Consoles
This sets the font used to display output in the STDIO Console window and the Debug Console window.
Default setting is Courier New, 9pt.
Session Preferences
Automatically load last executable on application launch
Automatically run last executable on application launch
Automatically restore session settings for executables
Palm OS Debugger stores sessions settings (a list of symbolic files and breakpoints) for each executable. The session settings file has the same filename as the executable file with the file extension PUD
.
Using the value true for this setting means that the PUD
file for your executable is loaded automatically when you run the executable.
Automatically restore session window positions
Tab size
Disassembler Preferences
To set Disassembler Plug-in preferences, select Disassemblers from the category tree, and then select 68K or ARM.
68K Preferences
If you are debugging 68K code, set these preferences.
Disassembler engine
Default setting is Palm OS Debugger. The other option is Palm Debugger.
The Palm OS Debugger disassembler is the recommended disassembler for Palm OS Debugger users. If you have problems with the Palm OS Debugger disassembler, however, you can choose to use the Palm Debugger disassembler, which is the disassembler from the Palm Debugger tool. (For an explanation of the difference between Palm OS Debugger and the Palm Debugger, see "How Does Palm OS Debugger Compare to Palm Debugger?".
Uppercase opcodes hex bytes
Default setting is false, which means that alphabetic characters in hexadecimal opcode bytes are displayed as lowercase letters.
Use the option true to display alphabetic characters in hexadecimal opcode bytes as uppercase letters.
Uppercase mnemonics operands
Default setting is false, which means that operands in hexadecimal numbers are displayed as lowercase letters.
Use the option true to display operands in hexadecimal numbers as uppercase letters.
Show offset values in hex
Default setting is false, which means Palm OS Debugger displays offsets as decimal numbers.
The hexadecimal value of offsets are often directly visible in the opcode bytes, so signed decimal numbers is the default display type for offsets.
Set this preference to true to display offsets as hexadecimal numbers.
Show immediates values as hex
Default setting is false, which means Palm OS Debugger displays arithmetic immediates as decimal numbers.
The hexadecimal value of intermediates are often directly visible in the opcode bytes, so decimal numbers is the default display type for arithmetic intermediates.
Set this preference to true to display arithmetic immediates as hexadecimal numbers.
Lookup names for addresses
Default setting is true, which means that if you are branching to another function, Palm OS Debugger displays the function name rather than the address.
Set this preference to false for slightly faster performance.
ARM Preferences
If you are debugging ARM code, set these preferences.
Uppercase opcodes
Default setting is false, which means that alphabetic characters in hexadecimal opcode bytes are displayed as lowercase letters.
Use the option true to display alphabetic characters in hexadecimal opcode bytes as uppercase letters.
Uppercase operands
Default setting is false, which means that operands in hexadecimal numbers are displayed as lowercase letters.
Use the option true to display operands in hexadecimal numbers as uppercase letters.
Show offsets in hex
Default setting is false, which means Palm OS Debugger displays offsets as decimal numbers.
The hexadecimal value of offsets are often directly visible in the opcode bytes, so signed decimal numbers is the default display type for offsets.
Set this preference to true to display offsets as hexadecimal numbers.
ARM architecture version
Set this to the ARM architecture version that is appropriate for your ARM chip. The disassembler needs this information in order to disassemble the opcodes correctly.
Download Plug-ins Preferences
These preferences are used for debugging with prototype development boards, and are not used for Palm OS application debugging.
Protocols Preferences
To set Protocols Plug-in preferences, select Protocols from the category tree, and then select 68K Palm OS Debug Kernel or ARM Palm OS 5 Debug Nub.
68K Palm OS Debug Kernel Preferences
This is the kernel that talks to Palm OS Emulator or to a 68K device.
Debug target select
Default setting is Palm Device. You can select Poser to indicate Palm OS Emulator, but note that Palm OS Emulator cannot be used with ARM-based code.
Communications Plug-in
Default setting is Win32 Serial Communications Plug-in. This is currently the only supported value if you are connecting to a 68K device.
If you are connecting to Palm OS Emulator, you should set this option to Win32 Sockets Communications Plug-in. Make sure the Sockets communication plug-in preferences are set correctly to 127.0.0.1
on port 2000
.
Path to poser
Default setting is to leave this field blank; this preference is optional.
Palm OS Debugger uses this setting to automatically launch Palm OS Emulator, if Emulator is not already running.
Command line arguments to poser
Default setting is to leave this field blank.
If you are connecting to Palm OS Emulator, you can specify command line arguments here.
Application Entry Point
Default setting is PilotMain. You can set this to any valid function name.
ARM Palm OS 5 Debug Nub Preferences
These preferences are for connecting to an ARM device's debug nub.
Communications Plug-in
Default setting is Win32 Serial Communications Plug-in.
The other option is Win32 Sockets Communications Plug-in.
Log protocol details
Default setting is Log errors to Debug Console. This setting is not necessary, so you can disable it.
RTOS Plug-ins Preferences
These preferences are used for debugging with prototype development boards, and are not used for Palm OS application debugging.
To set real time operating system plug-in preferences, select RTOS Plug-ins from the category tree, and then select Palm OS 6.0.
Palm OS 6.0 Preferences
These preferences are for process- and thread-aware debugging of Palm OS Cobalt applications.
Stop on Thread Created
Setting this preference to true means Palm OS Debugger suspends program execution when a new thread is created.
Stop on Thread Faulted
Default setting is true. This setting means that Palm OS Debugger suspends program execution when a thread is faulted.
Stop on Thread Destroyed
Setting this preference to true means Palm OS Debugger suspends program execution when a thread is destroyed.
Stop on Process Created
Setting this preference to true means Palm OS Debugger suspends program execution when a new process is created.
Stop on Process Destroyed
Setting this preference to true means Palm OS Debugger suspends program execution when a process is destroyed.
Stop on Library Loaded
Setting this preference to true means Palm OS Debugger suspends program execution when a library is loaded.
Stop on Library Unloaded
Setting this preference to true means Palm OS Debugger suspends program execution when a library is unloaded.
Target CPU is XScale
Runtime Helpers Preferences
These preferences are used for debugging with prototype development boards, and are not used for Palm OS application debugging.
To set Runtime Helpers preferences, select Runtime Helpers from the category tree, and then select ARM Palm OS.
ARM Palm OS Preferences
These preferences are for ARM targets.
Enable Palm Runtime Helper
For Palm OS Garnet or Palm OS Cobalt, set this to true.
DbgPostLoad func name or address
Default setting is DbgPostLoad. Normally, you should not change this.
This lets Palm OS Debugger detect where shared libraries are loaded.
DbgPostUnload func name or address
Default setting is DbgPostUnload. Normally, you should not change this.
This lets Palm OS Debugger detect where shared libraries are unloaded.
DbgBreak func name or address
Default setting is HALDbgBreak. Normally, you should not change this. This is a function that is in a shared library in Palm OS; you can use it as a breakpoint. It is like a breakpoint that you can compile into your code.
Binary file 1
Default setting is to leave this field blank.
Binary file 1 address
Default setting is to leave this field blank.
Binary file 2
Default setting is to leave this field blank.
Binary file 2 address
Default setting is to leave this field blank.
Symbolics Preferences
Palm OS Debugger uses the DWARF symbolics format. Select Symbolics from the category tree, and then select DWARF 1.1 or DWARF 2.0.
DWARF 1.1 Preferences
Normally, you do not need to change any of these preferences. The ones you most like may change are Relocate Palm libraries and Type/Creator section name.
Byte size of FT_char, FT_signed_char, FT_unsigned_char
Default setting is 1. Do not change.
Byte size of FT_short, FT_signed_short, FT_unsigned_short
Default setting is 2. Do not change.
Byte size of FT_integer, FT_signed_integer, FT_unsigned_integer
Default setting is 4. Do not change.
Byte size of FT_long, FT_signed_long, FT_unsigned_long
Default setting is 4. Do not change.
Byte size of FT_long_long, FT_signed_long_long, FT_unsigned_long_long
Default setting is 8. Do not change.
Byte size of FT_point, FT_label
Default setting is 4. Do not change.
Byte size of FT_float
Default setting is 4. Do not change.
Byte size of FT_dbl_prec_float
Default setting is 8. Do not change.
Byte size of FT_ext_prec_float
Default setting is 10. Do not change.
Byte size of FT_complex
Default setting is 8. Do not change.
Byte size of FT_dbl_prec_complex
Default setting is 16. Do not change.
Byte size of FT_ext_prec_complex
Default setting is 32. Do not change.
Byte size of FT_void
Default setting is 1. Do not change.
Byte size of FT_boolean
Default setting is 1. Do not change.
Relocate PALM libraries
Default setting is true. This must be set to true in order for Palm OS Debugger to be able to debug shared libraries.
Type/Creator section name
Default setting is .text. In most cases, you should not change this setting.
Palm OS Debugger uses this setting with the Type/Creator section offset setting.
Type/Creator section offset
Default setting is 20. Do not change this setting.
The Type/Creator section offset and Type/Creator section offset settings tell Palm OS Debugger where to find a shared library's type, creator ID, resource, and resource ID information in an ELF file. Palm OS Debugger uses these settings to process shared library load and unload notifications, and to enable and disable breakpoints in a shared library.
Each Palm OS shared library has unique shared library data in the initial bytes of the code section. By default, the code section in the ELF file is named .text
.
DWARF 2.0 Preferences
The DWARF 2.0 plug-in omits any TAG_member
tags that do not have locations for the members.
Relocate PALM libraries
Default setting is true. This must be set to true in order for Palm OS Debugger to be able to debug shared libraries.
Type/Creator section name
Default setting is .text. In most cases, you should not change this setting.
This setting tells Palm OS Debugger where to find a shared library's type and creator ID. Each Palm OS shared library has a chunk of data at the beginning of a certain section; typically, this section is named *.text
.
Type/Creator section offset
Default setting is 20. Do not change this setting.
Omit artificial variables
Default setting is true. This makes the Variables view more compact; Palm OS Debugger does not display any artificial variables. For information on the Variables view, see "Variables View".
Omit variables that start with
Default setting is to leave this field blank. To not to display any variables that start with a particular string, specify that string here.