Jump to: navigation, search

PTP/designs/2.x/debug platform

< PTP‎ | designs‎ | 2.x


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


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.


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.