PTP/designs/debugger protocol

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.

Proxy Protocol

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:

MESSAGE ⇒ LENGTH " " 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_EVENT ⇒ COMMAND | 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:

STRING ⇒ LENGTH ":" 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:

COMMAND ⇒ COMMAND_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_HEADER ⇒ COMMAND_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_BODY ⇒ STRING { " " STRING }

The following sections describe the currently defined commands.

BREAKPOINT_AFTER

Message Format

BREAKPOINT_AFTER_COMMAND ⇒ "0000:TID:00000000" " " 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 ⇒ "0001:TID:00000002" " " BITMAP " " COMMAND

Description 

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 ⇒ "0002:TID:00000000" " " BITMAP " " BREAKPOINT_ID " " EXPRESSION

Description 

Causes the breakpoint specified by BREAKPOINT_ID to only fire 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 fired.

Events 

OK, ERROR

DATA_READ_MEMORY

Message Format

DATA_READ_MEMORY_COMMAND ⇒ "0003:TID:00000000" " " 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

ADDRESS

FORMAT

WORD_SIZE

ROWS

COLS

AS_CHAR

Events 

OK, ERROR

DATA_WRITE_MEMORY

Message Format

DATA_WRITE_MEMORY_COMMAND ⇒ "0003:TID:00000000" " " BITMAP " " OFFSET " " ADDRESS " " FORMAT " " WORD_SIZE " " VALUE

Description 

Write a block of memory to the target processes.

Arguments

BITMAP specifies the processes this command applies to.

OFFSET

ADDRESS

FORMAT

WORD_SIZE

VALUE

Events 

OK, ERROR

DELETE_BREAKPOINT

Message Format

DELETE_BREAKPOINT_COMMAND ⇒ "0003:TID:00000000" " " 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 ⇒ "0003:TID:00000000" " " 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 ⇒ "0003:TID:00000000" " " 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 ⇒ "0003:TID:00000000" " " 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 ⇒ "0003:TID:00000000" " " BITMAP " " NAME " " KEY " " LIST_CHILDREN " " EXPRESSION

Description 

Arguments

BITMAP specifies the processes this command applies to.

NAME

KEY

LIST_CHILDREN

EXPRESSION is the expression to evaluate.

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:

EVENT ⇒ EVENT_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_HEADER ⇒ EVENT_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_BODY ⇒ STRING { " " 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

SHUTDOWN

Message Format

SHUTDOWN_EVENT ⇒ "0006:TID:00000000"

Description 

Indicates that the proxy has shut down in response to a QUIT command.

Arguments 

none

MESSAGE

Message Format

MESSAGE_EVENT ⇒ "00FA:TID:00000003" " " MSG_LEVEL_ATTRIBUTE " " MSG_CODE_ATTRIBUTE " " MSG_TEXT_ATTRIBUTE

Description 

A log message that will be displayed by the user interface.

Arguments

MSG_LEVEL_ATTRIBUTE is an attribute containing the message level. Valid levels are '"FATAL'", '"ERROR", "WARNING", and "INFO".

MSG_CODE_ATTRIBUTE is an attribute containing the message code

MSG_TEXT_ATTRIBUTE is an attribute containing a textual representation of the message

ATTR_DEF

Message Format

ATTR_DEF_EVENT ⇒ "00FB:TID:NUM_ARGS" " " NUM_DEFS { " " ATTRIBUTE_DEF }

Description 

Used to create new attribute definitions.

Arguments

NUM_DEFS is the number of attribute definitions to follow.

ATTRIBUTE_DEF is an attribute definition.

An attribute definition is defined as follows:

ATTRIBUTE_DEF ⇒ BOOLEAN_ATTR_DEF | DATE_ATTR_DEF | DOUBLE_ATTR_DEF | ENUM_ATTR_DEF | INT_ATTR_DEF | STR_ATTR_DEF

All attribute definitions begin with the following elements:

ATTR_DEF_START ⇒ NUM_ELEMENTS " " ID " " TYPE " " NAME " " DESCRIPTION " " DEFAULT

where:

NUM_ELEMENTS is the number of elements (separated by spaces) in this attribute definition.

ID is the unique definition ID.

TYPE is the type of the attribute. Legal values are: "ARRAY", "BOOLEAN", "DATE", "DOUBLE", "ENUMERATED", "INTEGER", and "STRING".

NAME is the short name of the attribute. This is displayed in property views as the name of the attribute.

DESCRIPTION is a description of the attribute. This is dispayed when more information about the attribute is requested.

DEFAULT is the default value of the attribute. There must be a legal conversion between this string and the actual attribute value.

A boolean attribute definition is simply:

BOOLEAN_ATTR_DEF ⇒ ATTR_DEF_START

A date attribute definition requires additional elements to be supplied for the definition:

DATE_ATTR_DEF ⇒ ATTR_DEF_START " " DATE_STYLE " " TIME_STYLE " " LOCALE [ " " MIN " " MAX ]

where:

DATE_STYLE is a Proxy String representing the date format. Legal values are: "SHORT", "MEDIUM", "LONG", and "FULL".

TIME_STYLE is a Proxy String representing the time format. Legal values are: "SHORT", "MEDIUM", "LONG", and "FULL".

LOCALE is a Proxy String represting a country code. See java.lang.Local for legal values.

MIN is the minimum date supported by the attribute.

MAX is the maximum date supported by the attribute.

A double attribute defintion has optional paramaters:

DOUBLE_ATTR_DEF ⇒ ATTR_DEF_START [ " " MIN " " MAX ]

where:

MIN is the minimum value supported by the attribute.

MAX is the maximum value supported by the attribute.

An enumerated attribute definition requires a sequence of enumerated values to be specified:

ENUM_ATTR_DEF ⇒ ATTR_DEF_START { " " VALUE }

where:

VALUE is a string representing an enumerated value.

Like double, integer attributes take optional parameters:

INT_ATTR_DEF ⇒ ATTR_DEF_START [ " " MIN " " MAX ]

where:

MIN is the minimum value supported by the attribute.

MAX is the maximum value supported by the attribute.

CHANGE_JOB

Message Format

CHANE_JOB_EVENT ⇒ "00E6:TID:NUM_ARGS" " " NUM_RANGES { " " JOB_RANGE }

Description 

Used to update attributes in a range of job model elements. Multiple attributes in multiple jobs can be updated simultaneously with this event.

Arguments

NUM_RANGES is the number of job ranges contained in this event.

JOB_RANGE represents the attributes that have changed for a given range of jobs.

A JOB_RANGE is formatted as follows:

JOB_RANGE ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number' of attributes associated with this range of jobs.

ATTR is an attribute that will be updated for each job in the range.

CHANGE_MACHINE

Message Format

CHANGE_MACHINE_EVENT ⇒ "00E7:TID:NUM_ARGS" " " NUM_RANGES { " " MACHINE_RANGE }

Description 

Used to update attributes in a range of machine model elements. Multiple attributes in multiple machines can be updated simultaneously with this event.

Arguments

NUM_RANGES is the number of machine ranges contained in this event.

MACHINE_RANGE represents the attributes that have changed for a given range of machines.

A MACHINE_RANGE is formatted as follows:

MACHINE_RANGE ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this range of machines.

ATTR is an attribute that will be updated for each machine in the range.

CHANGE_NODE

Message Format

CHANGE_NODE_EVENT ⇒ "00E8:TID:NUM_ARGS" NUM_RANGES { " " NODE_RANGE }

Description 

Used to update attributes in a range of node model elements. Multiple attributes in multiple nodes can be updated simultaneously with this event.

Arguments

NUM_RANGES is the number of node ranges contained in this event.

NODE_RANGE represents the attributes that have changed for a given range of nodes.

A NODE_RANGE is formatted as follows:

NODE_RANGE ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this range of nodes.

ATTR is an attribute that will be updated for each node in the range.

CHANGE_PROCESS

Message Format

CHANGE_PROCESS_EVENT ⇒ "00E9:TID:NUM_ARGS" " " NUM_RANGES { " " PROCESS_RANGE }

Description 

Used to update attributes in a range of process model elements. Multiple attributes in multiple processes can be updated simultaneously with this event.

Arguments

NUM_RANGES is the number of process ranges contained in this event.

PROCESS_RANGE represents the attributes that have changed for a given range of processes.

A PROCESS_RANGE is formatted as follows:

PROCESS_RANGE ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this range of processes.

ATTR is an attribute that will be updated for each process in the range.

CHANGE_QUEUE

Message Format

CHANGE_QUEUE_EVENT ⇒ "00EA:TID:NUM_ARGS" " " NUM_RANGES { " " QUEUE_RANGE }

Description 

Used to update attributes in a range of queue model elements. Multiple attributes in multiple queues can be updated simultaneously with this event.

Arguments

NUM_RANGES is the number of queue ranges contained in this event.

QUEUE_RANGE represents the attributes that have changed for a given range of queues.

A QUEUE_RANGE is formatted as follows:

QUEUE_RANGE ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this range of queues.

ATTR is an attribute that will be updated for each queue in the range.

NEW_JOB

Message Format

NEW_JOB_EVENT ⇒ "00DC:TID:NUM_ARGS" " " PARENT_ID " " NUM_JOB_DEFS { " " JOB_DEF }

Description 

Define new job model elements. Multiple jobs can be defined simultaneously with this event.

Arguments

PARENT_ID is the ID of the parent queue of this job.

NUM_JOB_DEFS is the number of job definitions contained in this event.

JOB_DEF represents the definition of a range of jobs and associated attributes.

A JOB_DEF is formatted as follows:

JOB_DEF ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number' of attributes associated with this job definition.

ATTR is an attribute that will be set for each newly created job.

NEW_MACHINE

Message Format

NEW_MACHINE_EVENT ⇒ "00DD:TID:NUM_ARGS" " " PARENT_ID " " NUM_MACHINE_DEFS { " " MACHINE_DEF }

Description 

Define new machine model elements. Multiple machines can be defined simultaneously with this event.

Arguments

PARENT_ID is the ID of the parent resource manager of this machine.

NUM_MACHINE_DEFS is the number of machine definitions contained in this event.

MACHINE_DEF represents the definition of a range of machines and associated attributes.

A MACHINE_DEF is formatted as follows:

MACHINE_DEF ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this machine definition.

ATTR is an attribute that will be set for each newly created machine.

NEW_NODE

Message Format

NEW_NODE_EVENT ⇒ "00DE:TID:NUM_ARGS" " " PARENT_ID " " NUM_NODE_DEFS { " " NODE_DEF }

Description 

Define new node model elements. Multiple nodes can be defined simultaneously with this event.

Arguments

PARENT_ID is the ID of the parent machine of this node.

NUM_NODE_DEFS is the number of node definitions contained in this event.

NODE_DEF represents the definition of a range of nodes and associated attributes.

A NODE_DEF is formatted as follows:

NODE_DEF ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this node definition.

ATTR is an attribute that will be set for each newly created node.

NEW_PROCESS

Message Format

NEW_PROCESS_EVENT ⇒ "00DF:TID:NUM_ARGS" " " PARENT_ID " " NUM_PROCESS_DEFS { " " PROCESS_DEF }

Description 

Define new process model elements. Multiple processes can be defined simultaneously with this event.

Arguments

PARENT_ID is the ID of the parent job of this processs.

NUM_PROCESS_DEFS is the number of process definitions contained in this event.

PROCESS_DEF represents the definition of a range of processes and associated attributes.

A PROCESS_DEF is formatted as follows:

PROCESS_DEF ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this process definition.

ATTR is an attribute that will be set for each newly created process.

NEW_QUEUE

Message Format

NEW_QUEUE_EVENT ⇒ "00E0:TID:NUM_ARGS" " " PARENT_ID " " NUM_QUEUE_DEFS { " " QUEUE_DEF }

Description 

Define new queue model elements. Multiple queues can be defined simultaneously with this event.

Arguments

PARENT_ID is the ID of the parent resource manager of this queue.

NUM_QUEUE_DEFS is the number of queue definitions contained in this event.

QUEUE_DEF represents the definition of a range of queues and associated attributes.

A QUEUE_DEF is formatted as follows:

QUEUE_DEF ⇒ ID_RANGE " " NUM_ATTRS { " " ATTR }

where:

ID_RANGE is a range of ID's in Range Set Notation

NUM_ATTRS is the number of attributes associated with this queue definition.

ATTR is an attribute that will be set for each newly created queue.

REMOVE_ALL

Message Format

REMOVE_ALL_EVENT ⇒ "00F0:TID:00000000"

Description 

Remove all model elements know by the RMS for this session.

Arguments

none

REMOVE_JOB

Message Format

REMOVE_JOB_EVENT ⇒ "00F1:TID:00000001" " " ID_RANGE

Description 

Remove job model elements from the model. Multiple jobs can be remove simultaneously with this event. All children of the jobs will also be removed from the model.

Arguments

ID_RANGE is a range of ID's to be removed in Range Set Notation

REMOVE_MACHINE

Message Format

REMOVE_MACHINE_EVENT ⇒ "00F2:TID:00000001" " " ID_RANGE

Description 

Remove machine model elements from the model. Multiple machines can be remove simultaneously with this event. All children of the machines will also be removed from the model.

Arguments

ID_RANGE is a range of ID's to be removed in Range Set Notation

REMOVE_NODE

Message Format

REMOVE_NODE_EVENT ⇒ "00F3:TID:00000001" " " ID_RANGE

Description 

Remove node model elements from the model. Multiple nodes can be remove simultaneously with this event. All children of the nodes will also be removed from the model.

Arguments

ID_RANGE is a range of ID's to be removed in Range Set Notation

REMOVE_PROCESS

Message Format

REMOVE_PROCESS_EVENT ⇒ "00F4:TID:00000001" " " ID_RANGE

Description 

Remove process model elements from the model. Multiple processes can be remove simultaneously with this event.

Arguments

ID_RANGE is a range of ID's to be removed in Range Set Notation

REMOVE_QUEUE

Message Format

REMOVE_QUEUE_EVENT ⇒ "00F5:TID:00000001" " " ID_RANGE

Description 

Remove queue model elements from the model. Multiple queues can be remove simultaneously with this event. All children of the queues will also be removed from the model.

Arguments

ID_RANGE is a range of ID's to be removed in Range Set Notation