Jump to: navigation, search

Difference between revisions of "PTP/designs/debugger protocol"

< PTP‎ | designs
(GET_PARTIAL_AIF)
(LIST_STACK_FRAMES)
Line 415: Line 415:
 
: ''BITMAP'' specifies the processes this command applies to.
 
: ''BITMAP'' specifies the processes this command applies to.
  
: ''LOW'' the low stack frame number.
+
: ''LOW'' is the low stack frame number.
  
: ''HIGH'' the high stack frame number.
+
: ''HIGH'' is the high stack frame number.
  
 
; Events : [[#OK|OK]], [[#ERROR|ERROR]]
 
; Events : [[#OK|OK]], [[#ERROR|ERROR]]

Revision as of 09:14, 10 May 2008

Overview

This document describes the debugger proxy communication protocol used by the PTP debugger. This protocol is used to communicate between the debugger front-end in Eclipse, and a debug server running on a target system. The primary purpose of the protocol is for controlling application processes for debugging purposes.

Terminiology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].

"PTP debugger" refers collectively to the Java plugins and external components that implement the Eclipse parallel debugger.

"Front-end" refers to the debug model, user interface and parallel debug interface (PDI) in Eclipse.

"Debug server" (or just "server") refers to an external (from Eclipse) component that interacts with the target application being debugged. In the case of the SDM, the "server" is actually made up of many separate processes.

Protocol Format

The communication protocol used between the front-end and the debug server is a simple text-based asynchronous command/event protocol. The front-end sends one or more commands to the server, which in turn will generate events that are returned to the front-end. One command may generate multiple events, but an event is always associated with a particular command. A command is not completed until either a corresponding event is received.

Transaction IDs

Transaction IDs (TIDs) are numbers that are used to match commands and events. Since one command may generate multiple events, TIDs are essential in order to determine which command generated an event. This means that every event MUST have a TID that matches a corresponding command.

TIDs are only unique for uncompleted commands, not necessarily for the whole session.

Servers SHOULD assume that a particular TID MAY be reused.

Servers SHOULD NOT assume anything about the numbering or ordering of TIDs.

Any events received with an invalid TID (i.e. with no corresponding command) SHALL be discarded.

Bitmaps

Bitmaps are key to communcation between the front-end and the server. The protocol assumes that the debugger is controlling a multi-process application. Each process in the application is identified by a number in the interval [0, N-1], where N is the total number of processes. Each bit in the bitmap corresponds to one of the processes being debugged. Process n | 0 <= n < N corresponds to the bit with value 2^n in the bitmap. Any number of bits can be set in a bitmap.

For example, processes 5,7,9-15 would be represented by the bitmap (assuming the right-most bit is 2^0):

1 1 1 1 1 1 1 0 1 0 1 0 0 0 0 0

Bitmaps are transmitted as a hex character strings, so the above bitmap would actually be represented by the string FEA0.

Bitmaps are used in both commands and events. When a debug command is sent, it includes a bitmap specifying which processes the command is intended for. When an event is received, it contains a bitmap indicating which processes generated the event.

Message Format

Commands and events consist of sequences of ASCII characters formatted into a message. A message is transmitted in the following format:

MESSAGELENGTH " " COMMAND_OR_EVENT

LENGTH and COMMAND_OR_EVENT are separated by a space (hex 20). The LENGTH is the length of the COMMAND_OR_EVENT portion of the message including the space. COMMAND_OR_EVENT is the actual text of the command or event.

COMMAND_OR_EVENTCOMMAND | EVENT

The COMMAND_OR_EVENT portion of the message contains a header part followed by a sequence of arguments separated by spaces. Each argument is a string formatted using the String Format described below. The command format is described in more detail in the Commands section. The event format is described in more detail in the Events section.

String Format

Strings are transmitted using the following format:

STRINGLENGTH ":" CHARACTERS

where LENGTH is a fixed length 8 digit hexadecimal representation of the length of the string, ':' is a colon character (hex 3A), and CHARACTERS are the actual ASCII characters in the string. No string terminating character (e.g. NULL) is ever transmitted.

For example, the string "A String" would be formatted as:

00000008:A String

A zero length string would be formatted as:

00000000:

Commands

Commands are formatted as simple ASCII text strings. A command consists of a header and a body, separated by a space (hex 20), as follows:

COMMANDCOMMAND_HEADER " " COMMAND_BODY

The command header consists of three fixed length hexadecimal numbers separated by colons (hex 3A), so it is itself fixed length. The format of the header is:

COMMAND_HEADERCOMMAND_ID ":" TID ":" NUM_ARGS

where

COMMAND_ID is a 4 digit hexadecimal number containing the command to be performed
TID is an 8 digit hexadecimal number containing the transaction ID assigned to this command
NUM_ARGS is an 8 digit hexadecimal number containing the number of space separated elements in the command body

The command body consists of NUM_ARGS strings separated by spaces.

COMMAND_BODYSTRING { " " STRING }

The following sections describe the currently defined commands.

BREAKPOINT_AFTER

Message Format

BREAKPOINT_AFTER_COMMAND ⇒ "0008:TID:00000003" " " BITMAP " " BREAKPOINT_ID " " COUNT
Description 
Causes breakpoint specified by BREAKPOINT_ID to be ignored for COUNT hits.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID of the breakpoint.
COUNT is the number of times the breakpoint will be ignored.
Events 
OK, ERROR

CLI

Message Format

CLI_COMMAND ⇒ "001C:TID:00000002" " " BITMAP " " COMMAND
Description 
Execute an arbitrary backend-specific command.

Arguments

BITMAP specifies the processes this command applies to.
COMMAND is an arbitrary command that will be passed directly to the backend debug engine.
Events 
OK, ERROR

CONDITION_BREAKPOINT

Message Format

CONDITION_BREAKPOINT_COMMAND ⇒ "0007:TID:00000003" " " BITMAP " " BREAKPOINT_ID " " EXPRESSION
Description 
Causes the breakpoint specified by BREAKPOINT_ID to only trigger if the expression specified by EXPRESSION evaluates to true.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID of the breakpoint.
EXPRESSION is an expression that will be evaluated to determine if the breakpoint event should be triggered.
Events 
OK, ERROR

DATA_READ_MEMORY

Message Format

DATA_READ_MEMORY_COMMAND ⇒ "0018:TID:NUM_ARGS" " " BITMAP " " OFFSET " " ADDRESS " " FORMAT " " WORD_SIZE " " ROWS " " COLS " " [ AS_CHAR ]
Description 
Read a block of memory from the target processes.

Arguments

BITMAP specifies the processes this command applies to.
OFFSET is an offset to add to ADDRESS before fetching memory
ADDRESS is an expression specifying the address of the first memory word to read.
FORMAT is the format used to print the memory words. See Output Formats
WORD_SIZE is the size of each memory word in bytes.
ROWS is the number of rows in the output table.
COLS is the number of columns in the output table.
AS_CHAR optionally specifies that each row should include an ASCII dump with this character as a padding character.
Events 
OK, ERROR

DATA_WRITE_MEMORY

Message Format

DATA_WRITE_MEMORY_COMMAND ⇒ "00019:TID:00000006" " " BITMAP " " OFFSET " " ADDRESS " " FORMAT " " WORD_SIZE " " VALUE
Description 
Write a value into a block of memory to the target processes.

Arguments

BITMAP specifies the processes this command applies to.
OFFSET is an offset to add to ADDRESS before writing memory
ADDRESS is an expression specifying the address of the first memory word to read.
FORMAT is not used.
WORD_SIZE is the size of each memory word in bytes.
VALUE is the value to be written into each memory location.
Events 
OK, ERROR

DELETE_BREAKPOINT

Message Format

DELETE_BREAKPOINT_COMMAND ⇒ "0004:TID:00000002" " " BITMAP " " BREAKPOINT_ID
Description 
Remove a breakpoint from the target processes.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID of the breakpoint to delete.
Events 
OK, ERROR

DISABLE_BREAKPOINT

Message Format

DISABLE_BREAKPOINT_COMMAND ⇒ "0006:TID:00000002" " " BITMAP " " BREAKPOINT_ID
Description 
Disable a breakpoint in the target processes. This prevents the breakpoint from firing, but does not remove it.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID of the breakpoint to disable.
Events 
OK, ERROR

ENABLE_BREAKPOINT

Message Format

ENABLE_BREAKPOINT_COMMAND ⇒ "0005:TID:00000002" " " BITMAP " " BREAKPOINT_ID
Description 
Enable a breakpoint that has been disabled in the target processes.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID of the breakpoint to enable.
Events 
OK, ERROR

EVALUATE_EXPRESSION

Message Format

EVALUATE_EXPRESSION_COMMAND ⇒ "0010:TID:00000002" " " BITMAP " " EXPRESSION
Description 
Evaluate an arbitrary expression in the target processes.

Arguments

BITMAP specifies the processes this command applies to.
EXPRESSION is the expression to evaluate.
Events 
OK, ERROR

GET_PARTIAL_AIF

Message Format

GET_PARTIAL_AIF_COMMAND ⇒ "001E:TID:00000005" " " BITMAP " " EXPRESSION " " NAME " " LIST_CHILDREN " " EXPRESS
Description 

Arguments

BITMAP specifies the processes this command applies to.
EXPRESSION is the expression to evaluate.
NAME specifies a name to use to refer to the expression. If the named expression already exists, this expression will be used instead of evaluating EXPRESSION.
LIST_CHILDREN specifies that full type traversal should be performed.
EXPRESS indicates that the minimum amount of information should be returned.
Events 
OK, ERROR

GET_TYPE

Message Format

GET_TYPE_COMMAND ⇒ "0011:TID:00000002" " " BITMAP " " EXPRESSION
Description 
Get the result type after evaluating the expression specified by EXPRESSION.

Arguments

BITMAP specifies the processes this command applies to.
EXPRESSION is the expression to evaluate.
Events 
OK, ERROR

GO

Message Format

GO_COMMAND ⇒ "000A:TID:00000001" " " BITMAP
Description 
Start or resume execution of the target processes.

Arguments

BITMAP specifies the processes this command applies to.
Events 
OK, ERROR

INTERRUPT

Message Format

INTERRUPT_COMMAND ⇒ "000D:TID:00000001" " " BITMAP
Description 
Suspend execution of the target processes. This command can be sent before a previous command has completed.

Arguments

BITMAP specifies the processes this command applies to.
Events 
OK, ERROR

LIST_ARGUMENTS

Message Format

LIST_ARGUMENTS_COMMAND ⇒ "0013:TID:00000003" " " BITMAP " " LOW " " HIGH
Description 
List the arguments from the stack frames between LOW and HIGH inclusively.

Arguments

BITMAP specifies the processes this command applies to.
LOW specifies the low stack frame number.
HIGH specifies the high stack frame number.
Events 
OK, ERROR

LIST_GLOBAL_VARIABLES

Message Format

LIST_GLOBAL_VARIABLES_COMMAND ⇒ "0014:TID:00000001" " " BITMAP
Description 
List all global (non-static) variables in the process.

Arguments

BITMAP specifies the processes this command applies to.
Events 
OK, ERROR

LIST_INFO_THREADS

Message Format

LIST_INFO_THREADS_COMMAND ⇒ "0015:TID:00000001" " " BITMAP
Description 
Obtain information about all threads in the current process.

Arguments

BITMAP specifies the processes this command applies to.
Events 
OK, ERROR

LIST_LOCAL_VARIABLES

Message Format

LIST_LOCAL_VARIABLES_COMMAND ⇒ "0012:TID:00000001" " " BITMAP
Description 
List all local variables in current stack frame of the current process.

Arguments

BITMAP specifies the processes this command applies to.
Events 
OK, ERROR

LIST_SIGNALS

Message Format

LIST_SIGNALS_COMMAND ⇒ "001A:TID:NUM_ARGS" " " BITMAP [ " " NAME]
Description 
List information about how the debugger handles signals. If a signal name is provided, then only information about that signal will be listed.

Arguments

BITMAP specifies the processes this command applies to.
NAME optionally specifies the signal.
Events 
OK, ERROR

LIST_STACK_FRAMES

Message Format

LIST_STACK_FRAMES_COMMAND ⇒ "000E:TID:00000003" " " BITMAP " " LOW " " HIGH
Description 
List the stack frames between LOW and HIGH inclusive.

Arguments

BITMAP specifies the processes this command applies to.
LOW is the low stack frame number.
HIGH is the high stack frame number.
Events 
OK, ERROR

SET_CURRENT_STACK_FRAME

Message Format

SET_CURRENT_STACK_FRAME_COMMAND ⇒ "000F:TID:00000002" " " BITMAP " " LEVEL
Description 
Set the current stack frames to LEVEL.

Arguments

BITMAP specifies the processes this command applies to.
LEVEL the stack frame number.
Events 
OK, ERROR

SET_FUNCTION_BREAKPOINT

Message Format

SET_FUNCTION_BREAKPOINT_COMMAND ⇒ "0003:TID:00000009" " " BITMAP " " BREAKPOINT_ID " " IS_TEMPORARY " " IS_HARDWARE " " FILE " " FUNCTION " " EXPRESSION " " IGNORE_COUNT " " THREAD_ID
Description 
Set the current stack frames to LEVEL.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID used to reference this breakpoint.
IS_TEMPORARY is a flag to indicate the breakpoint is temporary.
IS_HARDWARE is a flag indicating that a hardware breakpoint should be set.
FILE is the file name of the source file containing the function.
FUNCTION is the name of the function on which the breakpoint will be set.
EXPRESSION is a conditional expression.
IGNORE_COUNT is an ignore count.
THREAD_ID is not currently used.
Events 
OK, ERROR

SET_LINE_BREAKPOINT

Message Format

SET_LINE_BREAKPOINT_COMMAND ⇒ "0002:TID:00000009" " " BITMAP " " BREAKPOINT_ID " " IS_TEMPORARY " " IS_HARDWARE " " CONDITION " " LINE " " EXPRESSION " " IGNORE_COUNT " " THREAD_ID
Description 
Set the current stack frames to LEVEL.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID used to reference this breakpoint.
IS_TEMPORARY is a flag to indicate the breakpoint is temporary.
IS_HARDWARE is a flag indicating that a hardware breakpoint should be set.
FILE is the file name of the source file containing the function.
LINE is the line number on which the breakpoint will be set.
EXPRESSION is a conditional expression.
IGNORE_COUNT is an ignore count.
THREAD_ID is not currently used.
Events 
OK, ERROR

SET_THREAD_SELECT

Message Format

SET_THREAD_SELECT_COMMAND ⇒ "0016:TID:00000002" " " BITMAP " " THREAD_ID
Description 
Makes the thread specified by THREAD_ID the current thread.

Arguments

BITMAP specifies the processes this command applies to.
THREAD_ID is the thread number.
Events 
OK, ERROR

SET_WATCHPOINT

Message Format

SET_WATCHPOINT_COMMAND ⇒ "0009:TID:00000006" " " BITMAP " " BREAKPOINT_ID " " EXPRESSION " " IS_ACCESS " " IS_READ  " " IGNORE_COUNT
Description 
Set the current stack frames to LEVEL.

Arguments

BITMAP specifies the processes this command applies to.
BREAKPOINT_ID is the ID used to reference this breakpoint.
EXPRESSION is the expression on which the watchpoint will be set.
IS_ACCESS is a flag indicating that the watchpoint should trigger on any kind of access.
IS_READ is a flag indicating that the watchpoint should trigger only on read accesses.
IGNORE_COUNT is not used.
Events 
OK, ERROR

SIGNAL

Message Format

SIGNAL_COMMAND ⇒ "001B:TID:00000002" " " BITMAP " " SIGNAL_NUMBER
Description 
Resume execution of the target an immediately send the signal specified by SIGNAL_NUMBER.

Arguments

BITMAP specifies the processes this command applies to.
SIGNAL_NUMBER is the signal number to send to the target.
Events 
OK, ERROR

STACK_INFO_DEPTH

Message Format

STACK_INFO_DEPTH_COMMAND ⇒ "0017:TID:00000001" " " BITMAP
Description 
Return the stack frame depth of the target.

Arguments

BITMAP specifies the processes this command applies to.
Events 
OK, ERROR

START_SESSION

Message Format

START_SESSION_COMMAND ⇒ "0001:TID:NUM_ARGS" " " PROGRAM " " PATH " " DIRECTORY " [" ARG (" " ARG)+]
Description 
Start the debug session. Note that this command does not take a bitmap; it is assumed to be global.

Arguments

PROGRAM is the name of the executable being debugged.
PATH is the path to the executable.
DIRECTORY is the current working directory.
ARG is an argument that will be passed to the application program.
Events 
OK, ERROR

STEP

Message Format

STEP_COMMAND ⇒ "000B:TID:00000003" " " BITMAP " " COUNT " " TYPE
Description 
Return the stack frame depth of the target.

Arguments

BITMAP specifies the processes this command applies to.
COUNT is a repeat count.
TYPE is the type of the command. Options are "0" for step over, "1" for step into, and "2" for step return.
Events 
OK, ERROR

TERMINATE

Message Format

TERMINATE_COMMAND ⇒ "000C:TID:00000001" " " BITMAP
Description 
Terminate the target processes. The command can be set before the previous command is completed.

Arguments

BITMAP specifies the processes this command applies to.
Events 
OK, ERROR

Events

Events are used by the proxy agent to communicate the results of commands or other information back to the RMS. As mentioned previously, each event MUST contain a tid of a corresponding command.

Events, like commands, are formatted as simple ASCII text strings. A proxy event consists of a header and a body, separated by a space (hex 20), as follows:

EVENTEVENT_HEADER " " EVENT_BODY

The event header consists of three fixed length hexadecimal numbers separated by colons (hex 3A), so it is itself fixed length. The format of the header is:

EVENT_HEADEREVENT_ID ":" TID ":" NUM_ARGS

where

EVENT_ID is a 4 digit hexadecimal number representing the type of event
TID is an 8 digit hexadecimal number containing the transaction ID of the command that generated this event
NUM_ARGS is an 8 digit hexadecimal number containing the number of space separated elements in the event body

The event body consists of NUM_ARGS strings separated by spaces.

EVENT_BODYSTRING { " " STRING }

The following sections describe the currently defined events.

OK

Message Format

OK_EVENT ⇒ "0000:TID:00000000"
Description 
Indicates that the command with corresponding TID has been completed successfully
Arguments 
none

ERROR

Message Format

ERROR_EVENT ⇒ "0005:TID:00000002" " " ERROR_CODE_ATTRIBUTE " " ERROR_MSG_ATTRIBUTE
Description 
Indicates that the command with corresponding TID has not been completed successfully. The reason for the failure are provided in the attributes.

Arguments

ERROR_CODE_ATTRIBUTE is an attribute containing the error code
ERROR_MSG_ATTRIBUTE is an attribute containing a textual representation of the error