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

Revision as of 22:15, 9 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.

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 ⇒ "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

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 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 ⇒ "0018:TID:00000008" " " 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 ⇒ "00019:TID:00000006" " " 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 ⇒ "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 " " 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

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:00000001" " " 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 the low stack frame number.

HIGH 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 use.

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 use.

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:00000000" " " 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:

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

@@ Line 97: / Line 97: @@
 <b>Message Format</b>
-  ''BREAKPOINT_AFTER_COMMAND'' &rArr; "0000:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''COUNT''
+  ''BREAKPOINT_AFTER_COMMAND'' &rArr; "0008:''TID'':00000003" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''COUNT''
 ; Description : Causes breakpoint specified by ''BREAKPOINT_ID'' to be ignored for ''COUNT'' hits.
@@ Line 115: / Line 115: @@
 <b>Message Format</b>
-  ''CLI_COMMAND'' &rArr; "0001:''TID'':00000002" " " ''BITMAP'' " " ''COMMAND''
+  ''CLI_COMMAND'' &rArr; "001C:''TID'':00000002" " " ''BITMAP'' " " ''COMMAND''
 ; Description :
@@ Line 131: / Line 131: @@
 <b>Message Format</b>
-  ''CONDITION_BREAKPOINT_COMMAND'' &rArr; "0002:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''EXPRESSION''
+  ''CONDITION_BREAKPOINT_COMMAND'' &rArr; "0007:''TID'':00000003" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''EXPRESSION''
 ; Description : Causes the breakpoint specified by ''BREAKPOINT_ID'' to only fire if the expression specified by ''EXPRESSION'' evaluates to true.
@@ Line 149: / Line 149: @@
 <b>Message Format</b>
-  ''DATA_READ_MEMORY_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''OFFSET'' " " ''ADDRESS'' " " ''FORMAT'' " " ''WORD_SIZE'' " " ''ROWS'' " " ''COLS'' " " ''AS_CHAR''
+  ''DATA_READ_MEMORY_COMMAND'' &rArr; "0018:''TID'':00000008" " " ''BITMAP'' " " ''OFFSET'' " " ''ADDRESS'' " " ''FORMAT'' " " ''WORD_SIZE'' " " ''ROWS'' " " ''COLS'' " " ''AS_CHAR''
 ; Description : Read a block of memory from the target processes.
@@ Line 177: / Line 177: @@
 <b>Message Format</b>
-  ''DATA_WRITE_MEMORY_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''OFFSET'' " " ''ADDRESS'' " " ''FORMAT'' " " ''WORD_SIZE'' " " ''VALUE''
+  ''DATA_WRITE_MEMORY_COMMAND'' &rArr; "00019:''TID'':00000006" " " ''BITMAP'' " " ''OFFSET'' " " ''ADDRESS'' " " ''FORMAT'' " " ''WORD_SIZE'' " " ''VALUE''
 ; Description : Write a block of memory to the target processes.
@@ Line 201: / Line 201: @@
 <b>Message Format</b>
-  ''DELETE_BREAKPOINT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID''
+  ''DELETE_BREAKPOINT_COMMAND'' &rArr; "0004:''TID'':00000002" " " ''BITMAP'' " " ''BREAKPOINT_ID''
 ; Description : Remove a breakpoint from the target processes.
@@ Line 217: / Line 217: @@
 <b>Message Format</b>
-  ''DISABLE_BREAKPOINT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID''
+  ''DISABLE_BREAKPOINT_COMMAND'' &rArr; "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.
@@ Line 233: / Line 233: @@
 <b>Message Format</b>
-  ''ENABLE_BREAKPOINT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID''
+  ''ENABLE_BREAKPOINT_COMMAND'' &rArr; "0005:''TID'':00000002" " " ''BITMAP'' " " ''BREAKPOINT_ID''
 ; Description : Enable a breakpoint that has been disabled in the target processes.
@@ Line 249: / Line 249: @@
 <b>Message Format</b>
-  ''EVALUATE_EXPRESSION_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''EXPRESSION''
+  ''EVALUATE_EXPRESSION_COMMAND'' &rArr; "0010:''TID'':00000002" " " ''BITMAP'' " " ''EXPRESSION''
 ; Description : Evaluate an arbitrary expression in the target processes.
@@ Line 265: / Line 265: @@
 <b>Message Format</b>
-  ''GET_PARTIAL_AIF_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''NAME'' " " ''KEY'' " " ''LIST_CHILDREN'' " " ''EXPRESSION''
+  ''GET_PARTIAL_AIF_COMMAND'' &rArr; "001E:''TID'':00000005" " " ''BITMAP'' " " ''NAME'' " " ''KEY'' " " ''LIST_CHILDREN'' " " ''EXPRESSION''
 ; Description :
@@ Line 287: / Line 287: @@
 <b>Message Format</b>
-  ''GET_TYPE_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''EXPRESSION''
+  ''GET_TYPE_COMMAND'' &rArr; "0011:''TID'':00000002" " " ''BITMAP'' " " ''EXPRESSION''
 ; Description : Get the result type after evaluating the expression specified by ''EXPRESSION''.
@@ Line 303: / Line 303: @@
 <b>Message Format</b>
-  ''GO_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP''
+  ''GO_COMMAND'' &rArr; "000A:''TID'':00000001" " " ''BITMAP''
 ; Description : Start or resume execution of the target processes.
@@ Line 317: / Line 317: @@
 <b>Message Format</b>
-  ''INTERRUPT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP''
+  ''INTERRUPT_COMMAND'' &rArr; "000D:''TID'':00000001" " " ''BITMAP''
-; Description : Suspend execution of the target processes. This is the only command that can be sent before a previous command has completed.
+; Description : Suspend execution of the target processes. This command can be sent before a previous command has completed.
 <b>Arguments</b>
@@ Line 331: / Line 331: @@
 <b>Message Format</b>
-  ''LIST_ARGUMENTS_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''LOW'' " " ''HIGH''
+  ''LIST_ARGUMENTS_COMMAND'' &rArr; "0013:''TID'':00000003" " " ''BITMAP'' " " ''LOW'' " " ''HIGH''
 ; Description : List the arguments from the stack frames between ''LOW'' and ''HIGH'' inclusively.
@@ Line 349: / Line 349: @@
 <b>Message Format</b>
-  ''LIST_GLOBAL_VARIABLES_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP''
+  ''LIST_GLOBAL_VARIABLES_COMMAND'' &rArr; "0014:''TID'':00000001" " " ''BITMAP''
 ; Description : List all global (non-static) variables in the process.
@@ Line 363: / Line 363: @@
 <b>Message Format</b>
-  ''LIST_INFO_THREADS_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP''
+  ''LIST_INFO_THREADS_COMMAND'' &rArr; "0015:''TID'':00000001" " " ''BITMAP''
 ; Description : Obtain information about all threads in the current process.
@@ Line 377: / Line 377: @@
 <b>Message Format</b>
-  ''LIST_LOCAL_VARIABLES_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP''
+  ''LIST_LOCAL_VARIABLES_COMMAND'' &rArr; "0012:''TID'':00000001" " " ''BITMAP''
 ; Description : List all local variables in current stack frame of the current process.
@@ Line 391: / Line 391: @@
 <b>Message Format</b>
-  ''LIST_SIGNALS_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' [ " " ''NAME'']
+  ''LIST_SIGNALS_COMMAND'' &rArr; "001A:''TID'':00000001" " " ''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.
@@ Line 407: / Line 407: @@
 <b>Message Format</b>
-  ''LIST_STACK_FRAMES_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''LOW'' " " ''HIGH''
+  ''LIST_STACK_FRAMES_COMMAND'' &rArr; "000E:''TID'':00000003" " " ''BITMAP'' " " ''LOW'' " " ''HIGH''
 ; Description : List the stack frames between ''LOW'' and ''HIGH'' inclusive.
@@ Line 425: / Line 425: @@
 <b>Message Format</b>
-  ''SET_CURRENT_STACK_FRAME_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''LEVEL''
+  ''SET_CURRENT_STACK_FRAME_COMMAND'' &rArr; "000F:''TID'':00000002" " " ''BITMAP'' " " ''LEVEL''
 ; Description : Set the current stack frames to ''LEVEL''.
@@ Line 441: / Line 441: @@
 <b>Message Format</b>
-  ''SET_FUNCTION_BREAKPOINT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''IS_TEMPORARY'' " " ''IS_HARDWARE'' " " ''FILE'' " " ''FUNCTION'' " " ''EXPRESSION'' " " ''IGNORE_COUNT'' " " ''THREAD_ID''
+  ''SET_FUNCTION_BREAKPOINT_COMMAND'' &rArr; "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''.
@@ Line 471: / Line 471: @@
 <b>Message Format</b>
-  ''SET_LINE_BREAKPOINT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''IS_TEMPORARY'' " " ''IS_HARDWARE'' " " ''CONDITION'' " " ''LINE'' " " ''EXPRESSION'' " " ''IGNORE_COUNT'' " " ''THREAD_ID''
+  ''SET_LINE_BREAKPOINT_COMMAND'' &rArr; "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''.
@@ Line 501: / Line 501: @@
 <b>Message Format</b>
-  ''SET_THREAD_SELECT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''THREAD_ID''
+  ''SET_THREAD_SELECT_COMMAND'' &rArr; "0016:''TID'':00000002" " " ''BITMAP'' " " ''THREAD_ID''
 ; Description : Makes the thread specified by ''THREAD_ID'' the current thread.
@@ Line 517: / Line 517: @@
 <b>Message Format</b>
-  ''SET_WATCHPOINT_COMMAND'' &rArr; "0003:''TID'':00000000" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''EXPRESSION'' " " ''IS_ACCESS'' " " ''IS_READ''  " " ''IGNORE_COUNT''
+  ''SET_WATCHPOINT_COMMAND'' &rArr; "0009:''TID'':00000006" " " ''BITMAP'' " " ''BREAKPOINT_ID'' " " ''EXPRESSION'' " " ''IS_ACCESS'' " " ''IS_READ''  " " ''IGNORE_COUNT''
 ; Description : Set the current stack frames to ''LEVEL''.
@@ Line 534: / Line 534: @@
 : ''IGNORE_COUNT'' is not used.
+; Events : [[#OK|OK]], [[#ERROR|ERROR]]
+=== SIGNAL ===
+<b>Message Format</b>
+ ''SIGNAL_COMMAND'' &rArr; "001B:''TID'':00000002" " " ''BITMAP'' " " ''SIGNAL_NUMBER''
+; Description : Resume execution of the target an immediately send the signal specified by ''SIGNAL_NUMBER''.
+<b>Arguments</b>
+: ''BITMAP'' specifies the processes this command applies to.
+: ''SIGNAL_NUMBER'' is the signal number to send to the target.
+; Events : [[#OK|OK]], [[#ERROR|ERROR]]
+=== STACK_INFO_DEPTH ===
+<b>Message Format</b>
+ ''STACK_INFO_DEPTH_COMMAND'' &rArr; "0017:''TID'':00000001" " " ''BITMAP''
+; Description : Return the stack frame depth of the target.
+<b>Arguments</b>
+: ''BITMAP'' specifies the processes this command applies to.
+; Events : [[#OK|OK]], [[#ERROR|ERROR]]
+=== START_SESSION ===
+<b>Message Format</b>
+ ''START_SESSION_COMMAND'' &rArr; "0001:''TID'':00000000" " " ''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.
+<b>Arguments</b>
+: ''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|OK]], [[#ERROR|ERROR]]
+=== STEP ===
+<b>Message Format</b>
+ ''STEP_COMMAND'' &rArr; "000B:''TID'':00000003" " " ''BITMAP'' " " ''COUNT'' " " ''TYPE''
+; Description : Return the stack frame depth of the target.
+<b>Arguments</b>
+: ''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|OK]], [[#ERROR|ERROR]]
+=== TERMINATE ===
+<b>Message Format</b>
+ ''TERMINATE_COMMAND'' &rArr; "000C:''TID'':00000001" " " ''BITMAP''
+; Description : Terminate the target processes. The command can be set before the previous command is completed.
+<b>Arguments</b>
+: ''BITMAP'' specifies the processes this command applies to.
 ; Events : [[#OK|OK]], [[#ERROR|ERROR]]

Breadcrumbs

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

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

Revision as of 22:15, 9 May 2008

Contents

Overview

Terminiology

Proxy Protocol

Transaction IDs

Bitmaps

Message Format

String Format

Commands

BREAKPOINT_AFTER

CLI

CONDITION_BREAKPOINT

DATA_READ_MEMORY

DATA_WRITE_MEMORY

DELETE_BREAKPOINT

DISABLE_BREAKPOINT

ENABLE_BREAKPOINT

EVALUATE_EXPRESSION

GET_PARTIAL_AIF

GET_TYPE

GO

INTERRUPT

LIST_ARGUMENTS

LIST_GLOBAL_VARIABLES

LIST_INFO_THREADS

LIST_LOCAL_VARIABLES

LIST_SIGNALS

LIST_STACK_FRAMES

SET_CURRENT_STACK_FRAME

SET_FUNCTION_BREAKPOINT

SET_LINE_BREAKPOINT

SET_THREAD_SELECT

SET_WATCHPOINT

SIGNAL

STACK_INFO_DEPTH

START_SESSION

STEP

TERMINATE

Events

OK

ERROR

SHUTDOWN

MESSAGE

ATTR_DEF

CHANGE_JOB

CHANGE_MACHINE

CHANGE_NODE

CHANGE_PROCESS

CHANGE_QUEUE

NEW_JOB

NEW_MACHINE

NEW_NODE

NEW_PROCESS

NEW_QUEUE

REMOVE_ALL

REMOVE_JOB

REMOVE_MACHINE

REMOVE_NODE

REMOVE_PROCESS

REMOVE_QUEUE