PTP/designs/2.x/debug platform

Overview

The debug platform comprises those elements relating to the debugging of parallel applications. The debug platform is comprised of the following elements in the architecture diagram:

• debug model
• debug views
• debug controller
• debug launch
• scalable debug manager

The debug model provides a representation of a job and its associated processes being debugged. The debug views allow the user to interact with the debug model, and control the operation of the debugger. The debug controller interacts with the job being debugged and is responsible for updating the state of the debug model. The debug model and controller are collectively known as the parallel debug interface (PDI), which is set of abstract interfaces that can be implemented by different types of debuggers to provide the concrete classes necessary to support a variety of architectures and systems. PTP provides an implementation of PDI that communicates via a proxy running on a remote machine. The Java side of the implementation provides a set of commands and events that are used for communication with a remote debug agent. The proxy protocol is built on top of the same protocol used by the runtime services. The scalable debug manager is an external program that runs on the remote system and implements the server side of the proxy protocol. It manages the debugger communication between the proxy client and low-level debug engines that control the debug operations on the application processes.

The scalable debug manager is described in more detail here.

Debug Model

The debug model represents objects in the target program that are of interest to the debugger. Model objects are updated to reflect the states of the corresponding objects in the target, and can be displayed in views in the user interface. They form the core of a model-view-controller design pattern. PDI provides a broad range of model objects, and these are summarized in the following table.

Model Object	Description
IPDIAddressBreakpoint	A breakpoint that will suspend execution when a particular address is reached
IPDIArgument	A function or procedure argument
IPDIArgumentDescriptor	Detailed information about an argument
IPDIExceptionpoint	An breakpoint that will suspend execution when a particular exception is raised
IPDIExpression	An expression that can be evaluated to produce a value
IPDIFunctionBreakpoint	A breakpoint that will suspend execution when a particular function is called
IPDIGlobalVariable	A variable that has global scope within the execution context
IPDIGlobalVariableDescriptor	Detailed information about a global variable
IPDIInstruction	A machine instruction
IPDILineBreakpoint	A breakpoint that will suspend execution when a particular source line number is reached
IPDILocalVariable	A variable with scope local to the current stack frame
IPDILocalVariableDescriptor	Detailed information about a local variable
IPDIMemory	An object representing a single memory location in an execution context
IPDIMemoryBlock	A contiguous segment of memory in an execution context
IPDIMixedInstruction	A machine instruction with source context information
IPDIMultiExpressions	Expressions in multiple execution contexts
IPDIRegister	A special purpose variable
IPDIRegisterDescriptor	Detailed information about a register
IPDIRegisterGroup	A group of registers in a target execution context
IPDIRuntimeOptions	Configuration information about a debug session
IPDISharedLibrary	A shared library that has been loaded into the debug target
IPDISharedLibraryManagement	A shared library manager
IPDISignal	A POSIX signal
IPDISignalDescriptor	Detailed information about a signal
IPDISourceManagement	Manages information about the source code
IPDIStackFrame	A stack frame in a suspended execution context (thread)
IPDIStackFrameDescriptor	Detailed information about a stack frame
IPDITarget	A debuggable program. This is the root of the PDI model
IPDITargetExpression	An expression with an associated variable
IPDIThread	An execution context
IPDIThreadGroup	A group of threads
IPDIThreadStorage	Storage associated with a thread
IPDIThreadStorageDescriptor	Detailed information about thread storage
IPDITracepoint	A point in the program execution at which data will be collected
IPDIVariable	A data structure in the program
IPDIVariableDescriptor	Detailed information about a variable
IPDIWatchpoint	A breakpoint that will suspend execution when a particular data structure is accessed

Debug Views

The debugger provides a number of views that display the state of objects in the debug model. The views provided by the PTP debugger are summarized in the following table.

View Name	Description
Breakpoints View	Displays the breakpoints for the program, and if the breakpoint is active or inactive. Active breakpoints will trigger suspension of the execution context.
Debug View	Displays the threads and stack frames associated with a process. Is used to navigate to different stack frame locations.
Parallel Debug View	Displays the parallel job and processes associated with the job. Allows the user to define groupings of processes for control and viewing purposes.
PTP Variable View	Registers variables that will be displayed in tooltip popups in the Parallel Debug View.
Signals View	Displays the state of signal handling in the debugger, and allows the user to change how signals will be handled.
Variable View	Displays the values of all local variables in the current execution context.

Debug Controller

The debug controller is responsible for maintaining the state of the debug model, and for communicting with the backend debug engine. Commands to the debug engine are initiated by the user via interaction with views in the user interface, and cause the debug controller to invoke the appropriate method on the PDI implementation. PDI then translates the commands into a format required by the backend debug engine. Events that are generated by the backend debug engine are converted by the PDI debugger implementation into PDI model events. The controller then uses these events to update the debug model.

Debug API

The debug controller uses an API (part of the parallel debug interface (PDI)) to communicate with a backend debug engine. A new PDI implementation is only required to support a different debug protocol than that used by the scalable debug manager (SDM).

Addressing

Most debugger methods and events require knowledge of which processes they are directed to, or where they have originated from. The BitList class is used for this purpose. Debugger processes are numbered from 0 to N-1 (where N is the total number) and correspond to bits in the BitList. For example, to send a command to processes 15 through 30, bits 15-30 would be set in the BitList. The PDI makes no assumptions how the BitList is represented once it leaves the PDI classes.

Data Representation

Unlike most debuggers, a PDI debugger does not use strings to represent data values that have been obtained from the target processes. Instead, PDI provides a first-class data type that represents both the type and value of the target data in an architecture independent manner. This allows Eclipse to manipulate data that originates from any target architecture, regardless of word length, byte ordering, or other architectural issues. The following table shows the classes that are available for representing both simple and compound data types.

Type Class	Value Class	Description
IAIFTypeAddress	IAIFValueAddress	Represents a machine address.
IAIFTypeArray	IAIFValueArray	Represents a multi-dimensional array.
IAIFTypeBool	IAIFValueBool	Represents a boolean value.
IAIFTypeChar	IAIFValueChar	Represents a single character.
IAIFTypeCharPointer	IAIFValueCharPointer	Represents a pointer to a character string (i.e. a C string type).
IAIFTypeClass	IAIFValueClass	Represents a class.
IAIFTypeEnum	IAIFValueEnum	Represents an enumerated value.
IAIFTypeFloat	IAIFValueFloat	Represents a floating point number.
IAIFTypeFunction	IAIFValueFunction	Represents a function object.
IAIFTypeInt	IAIFValueInt	Represents an integer.
IAIFTypeLong	IIAIFValueLong	Represents a long integer.
IAIFTypeLongLong	IIAIFValueLongLong	Represents a long long integer.
IAIFTypeNamed	IAIFValueNamed	Represents a named object.
IAIFTypePointer	IAIFValuePointer	Represents a pointer to an object.
IAIFTypeRange	IAIFValueRange	Represents a value range.
IAIFTypeReference	IAIFValueReference	Represents a reference to a named object.
IAIFTypeShort	IAIFValueShort	Represents a short integer.
IAIFTypeString	IAIFValueString	Represents a string (not C string).
IAIFTypeStruct	IAIFValueStruct	Represents a structure.
IAIFTypeUnion	IAIFValueUnion	Represents a union.
IAIFTypeVoid	IAIFValueVoid	Represents a void type.

Command Requests

The PDI specifies a number of commands that are sent from the UI to the backend debug engine in order to perform debug operations. Commands are addressed to destination debug processes using the BitList class. The following table lists the interfaces that must be implemented to support debug commands.

Interface	Description
IPDIDebugger	This is the main interface for implementing a new debugger. The concrete implementation of this class must provide methods for each debugger command, as well as some utility methods for controlling debugger operation.
IPDIBreakpointManagement	This interface provides methods for managing all types of breakpoints, including line, function, and address breakpoints, watchpoints, and exceptions.
IPDIExecuteManagement	This interface provides methods for controlling the execution of the program being debugged, such as resuming, stepping, and termination.
IPDIMemoryBlockManagement	This interface provides methods for managing direct access to process memory.
IPDISignalManagement	This interface provides methods for managing signals.
IPDIStackframeManagement	This interface provides methods for managing access to process stack frames.
IPDIThreadManagement	This interface provides methods for managing process threads.
IPDIVariableManagement	This interface provides methods for managing all types of variables (local, global, etc.) and expression evaluation.

Events

Every PDI command results in one or more events. An event contains a list of source addresses that are represented by a BitList class. Each event may also contain additional data that provides more detailed information about the event. The data in an event with multiple sources is assumed to be identical for each source. The following table provides a list of the available events.

Event	Description
IPDIChangedEvent	Notification that a PDI model object has changed.
IPDIConnectedEvent	Notification that the debugger has started successfully.
IPDICreatedEvent	Notification that a new PDI model object has been created.
IPDIDestroyedEvent	Notification that a PDI model object has been destroyed.
IPDIDisconnectedEvent	Notification that the debugger session has terminated.
IPDIErrorEvent	Notification that an error condition has occurred.
IPDIRestartedEvent	Not currently used.
IPDIResumedEvent	Notification that the debugger target has resumed execution.
IPDIStartedEvent	Notification that the debugger has successfully started.
IPDISuspendedEvent	Notification that the debugger target has been suspended.

Many events also provide additional information associated with the event result. The following table provides a list of these interfaces.

Interface	Description
IPDIBreakpointInfo	Information about a process when it stops at a breakpoint.
IPDIDataReadMemoryInfo	Result of a IPDIDataReadMemoryRequest
IPDIEndSteppingRangeInfo	Information about the process when a step command is completed.
IPDIErrorInfo	Additional information about the cause of an error condition.
IPDIExitInfo	Information about the reason that a target process exited.
IPDIFunctionFinishedInfo	Not currently implemented.
IPDILocationReachedInfo	Not currently implemented.
IPDIMemoryBlockInfo	Represents a block of memory in the target process.
IPDIRegisterInfo	Not currently implemented.
IPDISharedLibraryInfo	Not currently implemented.
IPDISignalInfo	Information about a signal on the target system.
IPDIThreadInfo	Represents information about a thread.
IPDIVariableInfo	Represents information about a variable.
IPDIWatchpointScopeInfo	Not currently implemented.
IPDIWatchpointTriggerInfo	Not currently implemented.

Debug Wire Protocol

The debugger uses a simple text-based protocol to communicate between the Eclipse-based debug controller and the SDM master process. The format of the protocol is described in more detail in Debugger Wire Protocol. The protocol consists of commands and events. A command instructs the SDM to perform some action on a group of processes. Each command results in one or more events. Commands are addressed to processes using a bitmap, where each bit represents a process in the binomial tree. Events resulting from commands are aggregated where possible, by waiting for a predetermined time (possibly infinite) before the event is sent. Events also carry a bitmap indicating which processes the event corresponds to. A command is completed when every process receiving a command has produced a corresponding event.

On the Java side, each command and event is represented by a class. When a command is initiated, it is transformed into the text-based protocol, and sent to the SDM master process. Incoming events are transformed into the corresponding class, and forwarded to the debug controller. The following tables list the available commands and their corresponding events.

Debugger Commands

Command Class	Command Description
ProxyDebugBreakpointAfterCommand	Set attributes on a breakpoint so the execution context will be suspended after the breakpoint is reached a predetermined number of times.
ProxyDebugCLICommand	Send a backend-specific command.
ProxyDebugConditionBreakpointCommand	Set a breakpoint that will only trigger when an expression evaluates to true.
ProxyDebugDataReadMemoryCommand	Read a block of memory.
ProxyDebugDataWriteMemoryCommand	Write a block of memory.
ProxyDebugDeleteBreakpointCommand	Remove a breakpoint.
ProxyDebugDisableBreakpointCommand	Temporarily disable a breakpoint.
ProxyDebugEnableBreakpointCommand	Re-enable a disabled breakpoint.
ProxyDebugEvaluateExpressionCommand	Evaluate an expression in the execution context and return the result.
ProxyDebugGetPartialAIFCommand	Return a partially evaluated AIF object.
ProxyDebugGetTypeCommand	Get the type of a variable.
ProxyDebugGoCommand	Resume (or begin) execution of a process.
ProxyDebugInterruptCommand	Interrupt an executing process.
ProxyDebugListArgumentsCommand	List the arguments of the current stack frame.
ProxyDebugListGlobalVariablesCommand	List all the global variables.
ProxyDebugListInfoThreadsCommand	List the threads of the process.
ProxyDebugListLocalVariablesCommand	List all local variables in the current stack frame.
ProxyDebugListSignalsCommand	Determine how signals are handled by the backend debugger.
ProxyDebugListStackframesCommand	List all stack frames in the current execution context.
ProxyDebugSetCurrentStackframeCommand	Set the current stack frame.
ProxyDebugSetFunctionBreakpointCommand	Set a breakpoint on a function.
ProxyDebugSetLineBreakpointCommand	Set a breakpoint on a source line.
ProxyDebugSetThreadSelectCommand	Select the current execution context.
ProxyDebugSetWatchpointCommand	Set a watchpoint on an expression.
ProxyDebugSignalInfoCommand	Set how a signal should be handled.
ProxyDebugStackInfoDepthCommand	Determine the stack depth in the execution context.
ProxyDebugStartSessionCommand	Start the debug session.
ProxyDebugStepCommand	Single step the execution context.
ProxyDebugTerminateCommand	Terminate the process being debugged.
ProxyDebugVariableDeleteCommand	Remove a debugger variable.

Debugger Events

Event Name	Description
IProxyDebugArgsEvent	Contains a list of arguments for the stack frame.
IProxyDebugBreakpointHitEvent	Generated when a breakpoint is hit.
IProxyDebugBreakpointSetEvent	Generated when a breakpoint has been successfully set.
IProxyDebugDataEvent	Contains the type and contents of a target data structure.
IProxyDebugDataExpValueEvent	Contains a string representation of an expression value.
IProxyDebugErrorEvent	Indicates that a debug error has occurred.
IProxyDebugExitEvent	Indicates that the target process has exited normally, and the exit value.
IProxyDebugInfoThreadsEvent	Contains a list of threads.
IProxyDebugInitEvent	Indicates that the debugger has successfully initialized.
IProxyDebugMemoryInfoEvent	Contains data from a block of memory.
IProxyDebugOKEvent	Acknowledges a successful command operation.
IProxyDebugPartialAIFEvent	Contains a partially evaluated AIF object.
IProxyDebugSetThreadSelectEvent	Indicates a thread was successfully selected.
IProxyDebugSignalEvent	Generated in response to a process receiving a signal.
IProxyDebugSignalExitEvent	Generated when a process exits due to a signal.
IProxyDebugSignalsEvent	Contains a list of signals and how they are handled by the backend debugger.
IProxyDebugStackframeEvent	Contains a list of stack frames.
IProxyDebugStackInfoDepthEvent	Contains the stack frame depth.
IProxyDebugStepEvent	Generated when an execution context completes a single step.
IProxyDebugSuspendEvent	Generated when an execution context is suspended (e.g. when hitting a breakpoint)
IProxyDebugTypeEvent	Contains the result of a request for a variable type.
IProxyDebugVarsEvent	Contains the result of a request for the contents of a variable.

On the SDM side, the master process receives commands from the debug controller and calls the associated handler routine. This routine forwards the command to the processes specified by the command bitmap. Event responses are aggregated where possible, converted into the text-base protocol, and then forwarded to the debug controller.