This chapter describes the debugger protocol, which provides an interface between a debugging target and a debugging host. For example, the Palm Debugger and the Palm OS® Emulator use this protocol to exchange commands and information.
IMPORTANT: This chapter describes the version of the Palm OS Debugger protocol that shipped on the Metrowerks CodeWarrior for the Palm™ Operating System, Version 6 CD-ROM. If you are using a different version, the features in your version might be different from the features described here.
This chapter covers the following topics:
- "About the Palm OS Debugger Protocol"
- "Constants"
- "Data Structures"
- "Debugger Protocol Commands"
- "Summary of Debugger Protocol Packets"
About the Palm OS Debugger Protocol
The Palm OS debugger protocol allows a debugging target, which is usually a handheld ROM or an emulator program such as the Palm OS Emulator, to exchange information with a debugging host, such as the Palm Debugger or the Metrowerks debugger.
The debugger protocol involves sending packets between the host and the target. When the user of the host debugging program enters a command, the host converts that command into one or more command packets and sends each packet to the debugging target. In most cases, the target subsequently responds by sending a packet back to the host.
Packets
There are three packet types used in the debugger protocol:
- The debugging host sends command request packets to the debugging target.
- The debugging target sends command response packets back to the host.
- Either the host or the target can send a message packet to the other.
Although the typical flow of packets involves the host sending a request and the target sending back a response, although there are a some exceptions, as follows:
- The host can send some requests to the target that do not result in a response packet being returned. For example, when the host sends the
Continue
command packet to tell the target to continue execution, the target does not send back a response packet. - The target can send response packets to the host without receiving a request packet. For example, whenever the debugging target encounters an exception, it sends a
State
response packet to the host.
Packet Structure
Each packet consists of a packet header, a variable-length packet body, and a packet footer, as shown in Figure 9.1.

The Packet Header
The packet header starts with the 24-bit key value $BEEFFD
and includes header information and a checksum of the header itself.
The Packet Body
The packet body contains the command byte, a filler byte, and between 0
and 270
bytes of data. See "_SysPktBodyCommon" for a description of the structure used to represent the two byte body header (the command and filler bytes), and see Table 9.1 for a list of the command constants.
The Packet Footer
The packet footer contains a 16-bit CRC of the header and body. Note that the CRC computation does not include the footer.
Packet Communications
The communications protocol between the host and target is very simple: the host sends a request packet to the target and waits for a time-out or for a response from the target.
If a response is not detected within the time-out period, the host does not retry the request. When a response does not come back before timing out, it usually indicates that one of two things is happening:
- the debugging target is busy executing code and has not encountered an exception
- the state of the debugging target has degenerated so badly that it cannot respond
The host has the option of displaying a message to the user to inform him or her that the debugging target is not responding.
Constants
This section describes the constants and structure types that are used with the packets for various commands.
Packet Constants
sysPktMaxMemChunk
The maximum number of bytes that can be read by the Read Memory
command or written by the Write Memory
command.State Constants
sysPktStateRespInstWords
The number of remote code words sent in the response packet for the State
command.Breakpoint Constants
dbgTotalBreakpoints
The total number of breakpoints in the breakpoints array, including the normal breakpoints and the temporary breakpoint.
Command Constants
Each command is represented by a single byte constant. The upper bit of each request command is clear, and the upper bit of each response command is set. Table 9.1 shows the command constants.
Table 9.1 Debugger protocol command constants
Data Structures
This section describes the data structures used with the request and response packets for the debugger protocol commands.
_SysPktBodyCommon
The _SysPktBodyCommon
macro defines the fields common to every request and response packet.
Fields
SysPktBodyType
The SysPktBodyType
represents a command packet that is sent to or received from the debugging target.
Fields
SysPktRPCParamType
The SysPktRPCParamType is used to send a parameter in a remote procedure call. See the RPC command for more information.
Fields
BreakpointType
The BreakpointType
structure is used to represent the status of a single breakpoint on the debugging target.
Fields
Debugger Protocol Commands
This section describes each command that you can send to the debugging target, including a description of the response packet that the target sends back.
Continue
Purpose
Tells the debugging target to continue execution.
Comments
This command usually gets sent when the user specifies the Go
command. Once the debugging target continues execution, the debugger is not reentered until a breakpoint or other exception is encountered.
Commands
The Continue
request command is defined as follows:
Request Packet
Fields
regs
The new values for the debugging target processor registers. The new register values are stored in sequential order: D0
to D7
, followed by A0
to A6
.stepSpy
A Boolean value. If this is TRUE
, the debugging target continues execution until the value that starts at the specified step-spy address changes. If this is FALSE
, the debugging target continue execution until a breakpoint or other exception is encountered.ssAddr
The step-spy starting address. An exception is generated when the value starting at this address, for ssCount
bytes, changes on the debugging target.Find
Purpose
Searches for data in memory on the debugging target.
Comments
Commands
The Find
request and response commands are defined as follows:
Request Packet
Fields
firstAddr
The starting address of the memory range on the debugging target to search for the data.searchData
The search string. The length of this array is defined by the value of the numBytes
field.Response Packet
Fields
found
A Boolean value. If this is TRUE
, the search string was found on the debugging target, and the value of addr is valid. If this is FALSE
, the search string was not found, and the value of addr is not valid.Get Breakpoints
Purpose
Retrieves the current breakpoint settings from the debugging target.
Comments
The body of the response packet contains an array with dbgTotalBreakpoints
values in it, one for each possible breakpoint.
If a breakpoint is currently disabled on the debugging target, the enabled field for that breakpoint is set to 0
.
If a breakpoint address is set to 0, the breakpoint is not currently in use.
The dbgTotalBreakpoints
constant is described in "Breakpoint Constants".
Commands
The Get Breakpoints
command request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
bp
An array with an entry for each of the possible breakpoints. Each entry is of the type BreakpointType.Get Routine Name
Purpose
Determines the name, starting address, and ending address of the function that contains the specified address.
Comments
The name of each function is embedded into the code when it gets compiled. The debugging target can scan forward and backward in the code to determine the start and end addresses for each function.
Commands
The Get Routine Name
command request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
address
The code address whose function name was determined. This is the same address
that was specified in the request packet.endAddr
The ending address in target memory of the function that includes the address. If a function name could not be found, this is the last address that was scanned.name
The name of the function that includes the address
. This is a null-terminated string. If a function name could not be found, this is the null string.Get Trap Breaks
Purpose
Retrieves the settings for the trap breaks on the debugging target.
Comments
Trap breaks are used to force the debugging target to enter the debugger when a particular system trap is called.
The body of the response packet contains an array with dbgTotalBreakpoints
values in it, one for each possible trap break.
Each trap break is a single word value that contains the system trap number.
Commands
The Get Trap Breaks
request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
trapBP
An array with an entry for each of the possible trap breaks. A value of 0
indicates that the trap break is not used.Get Trap Conditionals
Purpose
Retrieves the trap conditionals values from the debugging target.
Comments
Trap conditionals are used when setting A-Traps for library calls. You can set a separate conditional value for each A-Trap.
The body of the response packet contains an array with dbgTotalBreakpoints
values in it, one for each possible trap break.
Each trap conditional is a value; if the value of the first word on the stack matches the conditional value when the trap is called, the debugger breaks.
Commands
The Get Trap Conditionals
request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
trapParam
An array with an entry for each of the possible trap breaks. A value of 0
indicates that the trap conditional is not used. Message
Purpose
Sends a message to display on the debugging target.
Comments
Application can compile debugger messages into their code by calling the DbgMessage
function.
The debugging target does not send back a response packet for this command.
Commands
The Message
request command is defined as follows:
Request Packet
Fields
Read Memory
Purpose
Reads memory values from the debugging target.
Comments
This command can read up to sysPktMaxMemChunk
bytes of memory. The actual size of the response packet depends on the number of bytes requested in the request packet.
Commands
The Read Memory
command request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
data
The returned data. The number of bytes in this field matches the numBytes
value in the request packet.Read Registers
Purpose
Retrieves the value of each of the target processor registers.
Comments
The eight data registers are stored in the response packet body sequentially, from D0
to D7
. The seven address registers are stored in the response packet body sequentially, from A0
to A6
.
Commands
The Read Registers
command request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
RPC
Purpose
Sends a remote procedure call to the debugging target.
Commands
The RPC
request and response commands are defined as follows:
Request Packet
Fields
param
An array of RPC parameter structures, as described in SysPktRPCParamType. Note that the parameters should appear in the reverse order of how they appear in the function declaration. For example, if you have the following function declaration: SysPktRPCParamType
record to SysPktRPCType
for dbID
first and a SysPktRPCParamType
record for cardNo
second. Set Breakpoints
Purpose
Sets breakpoints on the debugging target.
Comments
The body of the request packet contains an array with dbgTotalBreakpoints
values in it, one for each possible breakpoint. If a breakpoint is currently disabled on the debugging target, the enabled field for that breakpoint is set to 0
.
The dbgTotalBreakpoints
constant is described in Breakpoint Constants.
Commands
The Set Breakpoints
command request and response commands are defined as follows:
Request Packet
Fields
bp
An array with an entry for each of the possible breakpoints. Each entry is of the type BreakpointType.Response Packet
Fields
Set Trap Breaks
Purpose
Sets breakpoints on the debugging target.
Comments
The body of the request packet contains an array with dbgTotalBreakpoints
values in it, one for each possible trap break. If a trap break is currently disabled on the debugging target, the value of that break is set to 0
.
The dbgTotalBreakpoints
constant is described in Breakpoint Constants.
Commands
The Set Breakpoints
command request and response commands are defined as follows:
Request Packet
Fields
trapBP
An array with an entry for each of the possible trap breaks. If the value of an entry is 0, the break is not currently in use.Response Packet
Fields
Set Trap Conditionals
Purpose
Sets the trap conditionals values for the debugging target.
Comments
Trap conditionals are used when setting A-Traps for library calls. You can set a separate conditional value for each A-Trap.
The body of the request packet contains an array with dbgTotalBreakpoints
values in it, one for each possible trap break.
Each trap conditional is a value; if the value of the first word on the stack matches the conditional value when the trap is called, the debugger breaks.
Commands
The Set Trap Conditionals
request and response commands are defined as follows:
Request Packet
Fields
trapParam
An array with an entry for each of the possible trap breaks. A value of 0
indicates that the trap conditional is not used. Response Packet
Fields
State
Purpose
Sent by the host program to query the current state of the debugging target, and sent by the target whenever it encounters an exception and enters the debugger.
Comments
The debugging target sends the State
response packet whenever it enters the debugger for any reason, including a breakpoint, a bus error, a single step, or any other reason.
Commands
The State
request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
inst
A buffer of the instructions starting at the current program counter on the debugging target.bp
An array with an entry for each of the possible breakpoints. Each entry is of the type BreakpointType.name
The name of the function that generated the exception. This is a null-terminated string. If no name can be found, this is the null string.trapTableRev
The revision number of the trap table on the debugging target. You can use this to determine when the trap table cache on the host computer is invalid.Toggle Debugger Breaks
Purpose
Enables or disables breakpoints that have been compiled into the code.
Comments
A breakpoint that has been compiled into the code is a special TRAP
instruction that is generated when source code includes calls to the DbgBreak
and DbgSrcBreak
functions.
Sending this command toggles the debugging target between enabling and disabling these breakpoints.
Commands
The Toggle Debugger Breaks
request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
newState
A Boolean value. If this is set to TRUE
, the new state has been set to enable breakpoints that were compiled into the code. If this is set to FALSE
, the new state has been set to disable breakpoints that were compiled into the code.Write Memory
Purpose
Writes memory values to the debugging target.
Comments
This command can write up to sysPktMaxMemChunk
bytes of memory. The actual size of the request packet depends on the number of bytes that you want to write.
Commands
The Write Memory
command request and response commands are defined as follows:
Request Packet
Fields
data
The bytes to write into target memory. The size of this field is defined by the numBytes
parameter.Response Packet
Fields
Write Registers
Purpose
Sets the value of each of the target processor registers.
Comments
The eight data registers are stored in the request packet body sequentially, from D0
to D7
. The seven address registers are stored in the request packet body sequentially, from A0
to A6
.
Commands
The Write Registers
command request and response commands are defined as follows:
Request Packet
Fields
Response Packet
Fields
Summary of Debugger Protocol Packets
Table 9.2 summarizes the command packets that you can use with the debugger protocol.
Table 9.2 Debugger protocol command packets