#
Palm Debugger Protocol

### Document Order | ### Alphabetical Order
Overview | Continue Command
State Command | Find Command
Read Memory Command | Get Breakpoints Command
Write Memory Command | Get Routine Name Command
Single Step Command | Get Trap Breaks Command
Get Routine Name Command | Get Trap Conditionals Command
Read Registers Command | Message Command
Write Registers Command | Overview
Continue Command | Read Memory Command
Get Breakpoints Command | Read Registers Command
Set Breakpoints Command | RPC Command
Toggle Debugger Breaks Command | Set Breakpoints Command
Get Trap Breaks Command | Set Trap Breaks Command
Set Trap Breaks Command | Set Trap Conditionals Command
Find Command | Single Step Command
Message Command | State Command
RPC Command | Toggle Debugger Breaks Command
Get Trap Conditionals Command | Write Memory Command
Set Trap Conditionals Command | Write Registers Command

### Overview

In this document, "target" refers to the object being debugged. This could be the Palm ROM, or Palm OS Emulator. "Host" refers to the debugger, which could be either the Metrowerks debugger or the Palm Debugger. The target side of the debugger communicates by sending command packets to the user interface on the host side. Basically, the target side acts as a slave to the host, carrying out commands and reporting back results.

The target side must be able to respond to some basic command types sent from the host side. These are: get state, display memory, set memory, single step, get routine name, display registers, set registers, continue, set breakpoint, clear breakpoint, set a-trap, clear a-trap, find, and remote procedure call. All high-level commands that a user enters from the host side are broken down into one or more of these basic target commands, which are then sent to the target.

A command packet can be a request packet, response packet, or message packet. Request packets are sent from the host to the target and must be answered by an appropriate response packet from the target. Message packets are sent from either the target or the host and merely report status information and do not require a response from the recipient.

There is no extensive protocol involved between the host and target. Basically, the host sends a request packet and waits for a response from the target, or a timeout. If a response is not detected by the timeout period, the host does not retry the request but could display a message to the user saying that the target is not responding. Usually, if the target does not respond, it means either that the target is currently executing code and has not encountered a breakpoint, or that the target is so messed up that it can't even run the debugger.

Figure 1 shows the structure of request, response, and message packets. Basically, every packet consists of a packet header, a variable length packet body, and a packet footer. The maximim size of a packet body is 272 bytes. The packet header starts with the key 24-bit value $BEEFED and includes packet header information and a checksum of just the header itself. The packet footer contains a 16-bit CRC of the header and body (not footer).

Following the 24-bit value $BEEFED at the start of the packet header is a destination socket ID byte, a source socket ID byte, a packet type byte, a 2 byte body size, a transaction ID byte, and an 8 bit checksum of the header. The destination and source socket IDs and the packet type bytes are always 0 for debugger packets. The bodySize field is the number of bytes that are in the body - which will depend on the particular command being sent. The transaction ID is an 8 bit value that gets incremented every time a command is sent from the host. In order for a response packet from the target to be recognized by the host, its transaction ID must match the transaction ID of the original request packet.

The packet body starts with a command byte immediately followed by a filler byte. The command byte encodes the particular command being sent or acknowledged. Request packets always have the upper bit of the command byte clear, response packets have the upper bit set. Each command has it's own specific structure following the command and filler bytes.

`+--------------------+
| $BE (1) |
| $EF (1) |
| $ED (1) |
| dest ID (1) | Header (10 bytes)
| src ID (1) |
| type (1) |
| bodySize (2) |
| transID (1) |
| checkSum (1) |
+--------------------+
| command (1) |
| filler (1) | Body (2-272 bytes)
| variable size data |
+--------------------+
| CRC (2) | Footer (2 bytes)
+--------------------+
`

Figure 1 - Structure of Packets

### State Command

Figure 2 shows the structure of the request and response bodies for the state command. The host sends this command in order to determine the current state of the target, including the current program counter, the values of all the registers, the reason why the target entered the debugger, the current breakpoints, and the name of the routine that the program counter is in. The target will also send a state response packet to the host whenever it encounters an exception and enters the debugger - whether due to a breakpoint, bus error, single step, etc. This is the only time a response packet is sent to the host without a corresponding request packet from the host.

    #define sysPktStateCmd    0x00
    #define sysPktStateRsp    0x80

>     Max length of a routine name

    #define sysPktMaxNameLen  32

>     Number of remote code words to send in the 'state response' packet

    #define sysPktStateRspInstWords  15
    #define dbgNormalBreakpoints     5
    #define dbgTempBPIndex           dbgNormalBreakpoints
    #define dbgTotalBreakpoints      (dbgTempBPIndex+1)
    typedef struct BreakpointType
    {
        Ptr      addr;        // address of breakpoint
        Boolean  enabled;     // true if enabled
        Boolean  installed;   // for alignment
    } BreakpointType;

    typedef struct SysPktStateCmdType
    {
        _sysPktBodyCommon;    // Common Body header
    } SysPktStateCmdCmdType;

>     Packet Body structure for the state command response packet

    typedef struct SysPktStateRspType
    {
        _sysPktBodyCommon;                      // Common Body header
        Boolean        resetted;                // true if target has just reset
        Word           exceptionId;             // exception which caused the
                                                // debugger to be entered.
        M68KregsType   reg;                     // current remote registers.
        Word           inst[sysPktStateRspInstWords];
                                                // instruction buffer for
                                                // code beginning at PC.
        BreakpointType bp[dbgTotalBreakpoints]; // current breakpoints
        void*          startAddr;               // start address of routine
        void*          endAddr;                 // end address of routine
        char           name[sysPktMaxNameLen];  // routine name (0 or more chars),
                                                // immediately follows the address range.
        Byte           trapTableRev;            // rev of trap table. Used to determine
                                                // when host's trap table cache is invalid
    } SysPktStateRspType;

Figure 2 - State Command

The resetted field is non-zero if the target has reset itself since the last time the debugger was entered. The host can use the exceptionID field to determine why the debugger on the target was entered because it contains the address of the exception vector: $8 for a bus error, $7C for a non-maskable interrupt, etc. The 8 data registers are stored in the packet body starting from D0. The 7 address registers are stored starting from A0. The instruction buffer contains the next 30 bytes of code starting from the current program counter. The breakpoint list contains the list of the current breakpoints on the device. This is a fixed length list of 6 breakpoints - unused entries will have 0 in the enabled and installed fields. The last breakpoint in the list (breakpoint #5) is used exclusively for temporary breakpoints installed by the debugger for implementing commands like GoTill (gt).

The routineStart, routineEnd, and routineName fields contain the starting and ending address and name of the current routine. The target side of the debugger determines this information. A routine name is placed at the end of every routine by the compiler and the target side of the debugger scans forward and backwards from the current program counter to determine this information.

### Read Memory Command

Figure 3 shows the structure of the request and response bodies for the read command. This command is sent by the host in order to read memory on the target. It can return up to 256 bytes of data. The size of the response body depends on the number of bytes requested in the request packet.

    #define sysPktReadMemCmd   0x01
    #define sysPktReadMemRsp   0x81

    typedef struct SysPktReadMemCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        void*  address;      // Address to read
        Word  numBytes;      // # of bytes to read
    } SysPktReadMemCmdType;

    typedef struct SysPktReadMemRspType
    {
        _sysPktBodyCommon;   // Common Body header
     // Byte  data[?];       // variable size
    } SysPktReadMemRspType;

Figure 3 - Read Command

### Write Memory Command

Figure 4 shows the structure of the request and response bodies for the write command. This command is sent by the host in order to write memory on the target. It can write up to 256 bytes of data. The size of the request packet depends on the number of bytes that need to be written.

    #define sysPktWriteMemCmd   0x02
    #define sysPktWriteMemRsp   0x82

    typedef struct SysPktWriteMemCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        void*  address;      // Address to write
        Word  numBytes;      // # of bytes to write
     // Byte  data[?];       // variable size data
    } SysPktWriteMemCmdType;

    typedef struct SysPktWriteMemRspType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktWriteMemRspType;

Figure 4 - Write Command

### Single Step Command

Figure 5 shows the structure of the request and response bodies for the singleStep command. This command is sent by the host to tell the target to execute the next instruction. This command and the continue command (see below) are unique in that they do not get a respective response back from the target. The host relies on the fact that when the target re-enters the debugger it will automatically send a state response packet. In this case, the target will re-enter the debugger immediately after executing the next instruction.

    #define sysPktSingleStepCmd   0x03

Figure 5 - Single Step Command

Note: there is no actual single step command implemented in either the ROM or the Palm OS Emulator. Instead, this functionality is performed by setting the trace bit in the Status Register and executing a sysPktContinueCmd.

### Get Routine Name Command

Figure 6 shows the structure of the request and response bodies for the getRoutineName command. The host sends this command to determine which routine a particular address is in. It will return the starting and ending address of the routine and the name. The name of each routine is imbedded into the code when it's compiled and the target can determine the starting and ending address and name of the routine by scanning forwards and backwards in the code for this information.

    #define sysPktGetRtnNameCmd   0x04
    #define sysPktGetRtnNameRsp   0x84

    typedef struct SysPktRtnNameCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        void*  address;      // -> address to query on
    } SysPktRtnNameCmdType;

    typedef struct SysPktRtnNameRspType
    {
        _sysPktBodyCommon;            // Common Body header
        void*  address;               // -> address to query on
        void*  startAddr;             // <- start address of routine
        void*  endAddr;               // <- end address of routine
        char  name[sysPktMaxNameLen]; // <- routine name, if any immediately
                                      //    follows the address range.
                                      //    The balance need not be sent.
    } SysPktRtnNameRspType;

Figure 6 - Get Routine Name Command

The address field in the response body is a copy of the address sent in the request. The startAddr and endAddr fields are the starting and ending address of the routine that includes address. The name field is the 0 terminated name of the routine. If the target can not determine which routine address is in, it will return 0 for the first byte of the name in the response body and endAddr will contain the last address that it scanned in trying to find out the routine name. Subsequent getRoutineName calls should use the endAddr from the previous call in order to look for more routines.

### Read Registers Command

Figure 7 shows the structure of the request and response bodies for the readRegisters command. This command is sent by the host to get the value of each of the processor registers on the target. The 8 data registers are stored in the packet body starting from D0. The 7 address registers are stored starting from A0.

    #define sysPktReadRegsCmd   0x05
    #define sysPktReadRegsRsp   0x85

    typedef struct SysPktReadRegsCmdTyp
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktReadRegsCmdType;

    typedef struct SysPktReadRegsRspType
    {
        _sysPktBodyCommon;   // Common Body header
        M68KRegsType reg;   // <- return registers
    } SysPktReadRegsRspType;

Figure 7 - Read Registers Command

### Write Registers Command

Figure 8 shows the structure of the request and response bodies for the writeRegisters command. This command is sent by the host to set the value of each of the processor registers on the target. The 8 data registers are stored in the packet body starting from D0. The 7 address registers are stored starting from A0.

    #define sysPktWriteRegsCmd   0x06
    #define sysPktWriteRegsRsp   0x86

    typedef struct SysPktWriteRegsCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        M68KRegsType reg;    // -> registers to write
    } SysPktWriteRegsCmdType;

    typedef struct SysPktWriteRegsRspType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktWriteRegsRspType;

Figure 8 - Write Registers Command

### Continue Command

Figure 9 shows the structure of the request and response bodies for the continue command. This command is sent by the host to tell the target to continue execution. This is usually sent as a result of the user entering the Go (g) command. The debugger on the target will not get re-entered again unless a breakpoint or other exception is encountered. The target does not send a response to this command. If the target does re-enter the debugger due to a subsequent exception, it will send a state response packet to the host.

    #define sysPktContinueCmd   0x07

    typedef struct SysPktContinueCmdType
    {
        _sysPktBodyCommon;        // Common Body header
        M68KregsType regs;        // registers
        Boolean      stepSpy;     // set true to do step spy
        DWord        ssAddr;      // step spy address
        DWord        ssCount;     // # of bytes
        DWord        ssCheckSum;  // checksum
    } SysPktContinueCmdType;

Figure 9 - Continue Command

### Get Breakpoints Command

Figure 10 shows the structure of the request and response bodies for the getBreakpoints command. This command is sent by the host to get the current settings of all target breakpoints. The response body has an array of 6 breakpoints in it. If the enabled field for a particular breakpoint entry is 0, it means that breakpoint is disabled. If the address field is 0, it means that breakpoint is not used. The installed field is currently never used.

    #define sysPktGetBreakpointsCmd  0x0B
    #define sysPktGetBreakpointsRsp  0x8B

    typedef struct SysPktGetBreakpointsCmdType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktGetBreakpointsCmdType;

    typedef struct SysPktGetBreakpointsRspType
    {
        _sysPktBodyCommon;   // Common Body header
        BreakpointType bp[dbgTotalBreakpoints];
    } SysPktGetBreakpointsRspType;

Figure 10 - Get Breakpoints Command

### Set Breakpoints Command

Figure 11 shows the structure of the request and response bodies for the setBreakpoints command. This command is sent by the host to set the target breakpoints. The request body has an array of 6 breakpoints in it. If the enabled field for a particular breakpoint entry is 0, it means that breakpoint is disabled. If the address field is 0, it means that breakpoint is not used.

    #define sysPktSetBreakpointsCmd  0x0C
    #define sysPktSetBreakpointsRsp  0x8C

    typedef struct SysPktSetTrapBreaksCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        Word  trapBP[dbgTotalTrapBreaks];
    } SysPktSetTrapBreaksCmdType;

    typedef struct SysPktSetTrapBreaksRspType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktSetTrapBreaksRspType;

Figure 11 - Set Breakpoints Command

### Toggle Debugger Breaks Command

Figure 12 shows the structure of the request and response bodies for the toggleDbgBreaks command. This command is sent by the host to enable or disable compiled-in breakpoints. A compiled in breakpoint is a special TRAP instruction that gets compiled into the code with the DbgBreak() and DbgSrcBreak() calls. The host can send this command to tell the target whether or not to ignore these breakpoints. The request toggles the state and the response returns the new state (non-zero for enabled, 0 for disabled).

    #define sysPktDbgBreakToggleCmd  0x0D
    #define sysPktDbgBreakToggleRsp  0x8D

    typedef struct SysPktDbgBreakToggleCmdType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktDbgBreakToggleCmdType;

    typedef struct SysPktDbgBreakToggleRspType
    {
        _sysPktBodyCommon;   // Common Body header
        Boolean  newState;
    } SysPktDbgBreakToggleRspType;

Figure 12 - Toggle Debugger Breaks Command

### Get Trap Breaks Command

Figure 13 shows the structure of the request and response bodies for the getTrapBreaks command. The host sends this command to get the current settings of all target trap breaks. The response body has an array of 5 traps in it. If the trap field is 0, it means that trap break is not used. Trap breaks are used to force the target to enter the debugger when a particular system trap is called. Up to 5 trap breaks can be set at any time.

    #define sysPktGetTrapBreaksCmd  0x10
    #define sysPktGetTrapBreaksRsp  0x90

    typedef struct SysPktGetTrapBreaksCmdType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktGetTrapBreaksCmdType;

    typedef struct SysPktGetTrapBreaksRspType
    {
        _sysPktBodyCommon;   // Common Body header
        Word  trapBP[dbgTotalTrapBreaks];
    } SysPktGetTrapBreaksRspType;

Figure 13 - Get Trap Breaks Command

### Set Trap Breaks Command

Figure 14 shows the structure of the request and response bodies for the setTrapBreaks command. The host sends this command to set the current settings of all target trap breaks. The request body has an array of 5 traps in it. If the trap field is 0, it means that trap break is not used. Trap breaks are used to force the target to enter the debugger when a particular system trap is called. Up to 5 trap breaks can be set at any time.

    #define sysPktSetTrapBreaksCmd  0x11
    #define sysPktSetTrapBreaksRsp  0x91

    typedef struct SysPktSetTrapBreaksCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        Word  trapBP[dbgTotalTrapBreaks];
    } SysPktSetTrapBreaksCmdType;

    typedef struct SysPktSetTrapBreaksRspType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktSetTrapBreaksRspType;

Figure 14 - Set Trap Breaks Command

### Find Command

Figure 15 shows the structure of the request and response bodies for the find command. This command is sent by the host to search for data on the target. The firstAddr and lastAddr fields of the request set the range of addresses to search through. The numBytes field contains the number of bytes in the search string. If the caseInsensitive byte is non-zero, a case-insensitive search will be made. The variable length search string follows the caseInsensitive field.

In the response body, addrFound contains the address of the found data. If the data was not found, the found field will be 0.

    #define sysPktFindCmd    0x13
    #define sysPktFindRsp    0x93

    typedef struct SysPktFindCmdType
    {
        _sysPktBodyCommon;       // Common Body header
        DWord   firstAddr;       // first address to search
        DWord   lastAddr;        // last address to begin searching
        Word    numBytes;        // number of data bytes to match
        Boolean caseInsensitive; // if true, perform a case-insensitive search
    } SysPktFindCmdType;

    typedef struct SysPktFindRspType
    {
        _sysPktBodyCommon;   // Common Body header
        DWord  addr;         // address where data was found
        Boolean  found;      // true if data was found
    } SysPktFindRspType;

Figure 15 - Find Command

### Message Command

Figure 16 shows the structure of the message packet body. This packet is sent by the target to display a message on the host. Debugger messages can be compiled into the source code through the DbgMessage() call. They can be used by applications on Palm devices for displaying application specific debugging messages during execution. There is no response sent back from the host to the target when it receives one of these packets.

    #define sysPktRemoteMsgCmd   0x7F

    typedef struct SysPktRemoteMsgCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        Byte  text[1];       // variable length text goes here
    } SysPktRemoteMsgCmdType;

Figure 16 - Message Command

### RPC Command

    #define sysPktRPCCmd    0x0A
    #define sysPktRPCRsp    0x8A

    typedef struct SysPktRPCParamInfo
    {
        Byte   byRef;    // true if param is by reference
        Byte   size;     // # of Bytes of paramData (must be even)
        Word   data[1];  // variable length array of paramData
    } SysPktRPCParamType;

    typedef struct SysPktRPCType
    {
        _sysPktBodyCommon;   // Common Body header
        Word   trapWord;     // which trap to execute
        Dword  resultD0;     // result from D0 placed here
        Dword  resultA0;     // result from A0 placed here
        Word   numParams;    // how many parameters follow

        // Following is a variable length array of SysPktRPCParamType's
        SysPktRPCParamType param[1];
    } SysPktRPCType;

Figure 17 - RPC Command

### Get Trap Conditionals Command (new in 3.0)

These are used to tell the debugger to conditionally break on a trap depending on the value of the first word on the stack. They are used when setting a-traps on library calls.

    #define sysPktGetTrapConditionsCmd  0x14
    #define sysPktGetTrapConditionsRsp  0x94

    typedef struct SysPktGetTrapConditionsCmdType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktGetTrapConditionsCmdType;

    typedef struct SysPktGetTrapConditionsRspType
    {
        _sysPktBodyCommon;   // Common Body header
        Word  trapParam[dbgTotalTrapBreaks];
    } SysPktGetTrapConditionsRspType;

Figure 18 - Get Trap Conditionals Command

### Set Trap Conditionals Command (new in 3.0)

These are used to tell the debugger to conditionally break on a trap depending on the value of the first word on the stack. They are used when setting a-traps on library calls.

    #define sysPktSetTrapConditionsCmd  0x15
    #define sysPktSetTrapConditionsRsp  0x95

    typedef struct SysPktSetTrapConditionsCmdType
    {
        _sysPktBodyCommon;   // Common Body header
        Word  trapParam[dbgTotalTrapBreaks];
    } SysPktSetTrapConditionsCmdType;

    typedef struct SysPktSetTrapConditionsRspType
    {
        _sysPktBodyCommon;   // Common Body header
    } SysPktSetTrapConditionsRspType;

Figure 19 - Set Trap Conditionals Command