|
|
| (8 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | NOTE: THIS DOCUMENT IS A DRAFT CURRENTLY UNDER DEVELOPMENT. THERE MAY BE SUBSTANTIAL CHANGES IN THE NEAR FUTURE.
| |
| − |
| |
| | == Overview == | | == Overview == |
| | | | |
| Line 22: |
Line 20: |
| | | | |
| | == [[PTP/designs/2.x/runtime_platform | Runtime Platform]] == | | == [[PTP/designs/2.x/runtime_platform | Runtime Platform]] == |
| | + | |
| | + | This [[PTP/designs/2.x/runtime_platform | section]] describes the runtime monitoring and control features of PTP. |
| | | | |
| | == [[PTP/designs/2.x/launch_platform | Launch Platform]] == | | == [[PTP/designs/2.x/launch_platform | Launch Platform]] == |
| | + | |
| | + | This [[PTP/designs/2.x/launch_platform | section]] describes the services for launching debug and non-debug jobs. |
| | | | |
| | == [[PTP/designs/2.x/debug_platform | Debug Platform]] == | | == [[PTP/designs/2.x/debug_platform | Debug Platform]] == |
| | | | |
| − | 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:
| + | This [[PTP/designs/2.x/debug_platform | section ]] describes the features and operation of the PTP parallel debugger. |
| − | | + | |
| − | * 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.
| + | |
| − | | + | |
| − | === 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.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |-
| + | |
| − | ! 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.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |-
| + | |
| − | ! 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.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | ! 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.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |-
| + | |
| − | ! 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.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |-
| + | |
| − | ! 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.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |-
| + | |
| − | ! 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.
| + | |
| − | |}
| + | |
| − | | + | |
| − | === Scalable Debug Manager ===
| + | |
| − | | + | |
| − | The Scalable Debug Manager (SDM) is an implementation of the PDI. The SDM comprises four main parts: a Java PDI implementation, a scalable communications infrastructure, a debug wire protocol, and a pluggable debug backend.
| + | |
| − | | + | |
| − | ==== Debugger Startup & Communication ====
| + | |
| − | | + | |
| − | The PTP debugger startup occurs in two phases. The first phase initializes the PDI debugger implementation, which then waits for an incoming connection. The second phase submits a debug job to the currently selected resource manager. A debug job contains additional information that allows the resource manager to establish the debug infrastructure necessary to debug the application program. The resource manager is responsible for starting both the debugger and the application program.
| + | |
| − | | + | |
| − | Communication between Eclipse and the external debug infrastructure is via TCP/IP sockets. When the PTP debugger is launched, the PDI debugger implementation listens on a randomly generated port number for incoming connections. The port number is passed to the resource manager as part of the debug launch. When the resource manager starts the debug infrastructure, it must pass this port number as a command-line option in order for the infrastructure to connect back to the PDI implementation. Once the connection is completed, all debugger communication occurs via this socket.
| + | |
| − | | + | |
| − | ==== SDM PDI implementation ====
| + | |
| − | | + | |
| − | The SDM PDI implementation is responsible for converting PDI commands and events into a wire protocol. Once the connection has been established, the PDI implementation receives commands that are created as a result of user interaction with the debug views (e.g. the user creates a breakpoint, or clicks a single step button). These PDI commands are converted into the wire protocol and sent via the socket. Events received on the socket are converted into PDI events and used to update the debug model state.
| + | |
| − | | + | |
| − | ==== Scalable Communications Infrastructure ====
| + | |
| − | | + | |
| − | The SDM implements a scalable communications infrastructure using a C program that uses the MPI programming model. ''NOTE: future versions of the SDM will not rely on MPI''. Typically, this infrastructure will be running on a machine (the ''parallel machine'') that is remote from the machine running Eclipse (the ''workstation''). When debugging a multi-process application, the SDM starts a server process for each application process, plus one additional process that acts as the master controller. Each of the server processes forms part of a binomial tree that broadcasts commands to minimize the message latency to each process. The infrastructure also performs message aggregation when receiving debugger events. Each command specifies a timeout period (possibly infinite) for message aggregation. A server process waits for this period before sending the aggregated message to it's parent. Message aggregation is achieved by computing a hash over the message body, and aggregating messages with identical hashes.
| + | |
| − | | + | |
| − | ==== 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 [[PTP/designs/debugger_protocol | 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.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |+ '''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.
| + | |
| − | |}
| + | |
| − | | + | |
| − | <p><br></p>
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |+ '''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.
| + | |
| − | | + | |
| − | ==== Backend Debugger ====
| + | |
| − | | + | |
| − | The SDM uses a native debugger to perform debug actions on the target processes. The native debugger interfaces to the SDM via a backend interface that converts the debugger commands into commands that can be understood by the native debugger. Native debugger responses are converted back to debugger events. The SDM currently supports gdb as a native backend debugger, and communicates to gdb via the MI interface.
| + | |
| − | | + | |
| − | == Remote Services ==
| + | |
| − | | + | |
| − | === Overview ===
| + | |
| − | | + | |
| − | Although some users are lucky enough to have a parallel computer under their desk, most users will be developing and running parallel applications on remote systems. This means that PTP must support monitoring, running and debugging applications on computer systems that are geographically distant from the user's desktop. The traditional approach take to this problem was to require the users to log into a remote machine using a terminal emulation program, and then run commands directly on the remote system. Early versions of PTP also took this approach, requiring the use of the remote X11 protocol to display an Eclipse session that was actually running on the remote machine. However this technique suffers from a number of performance and usability problems that are difficult to overcome. The approach taken in later versions of PTP (2.0 and higher) is to run Eclipse locally on the user's desktop, and provide a proxy protocol to communicate with a lightweight agent running on the remote system, as described in the preceding sections. In addition to the proxy protocol, there are a number of other remote activities that must also take place to transparently support remote development. PTP support for these activities is described in the following sections.
| + | |
| − | | + | |
| − | === Remote Services Abstraction ===
| + | |
| − | | + | |
| − | PTP takes the approach that the user should be spared from needing to know about specific details of how to interact with a remote computer system. That is, the user should only need to supply enough information to establish a connection to a remote machine (typically the name of the system, and a username and password), then everything else should be taken care of automatically. Details such as the protocol used for communication, how files are accessed, or commands initiated, do not need to be exposed to the user.
| + | |
| − | | + | |
| − | An additional requirement is that PTP should not be dependent on other Eclipse projects (apart from the platform). Unfortunately, while the Eclipse File System (EFS) provides an abstraction for accessing non-local resources, it does not support other kinds of services, such as remote command execution. The only alternative to EFS is the RSE project, but introducing such a dependency into PTP is not desirable at this time.
| + | |
| − | | + | |
| − | In order to address these requirements, PTP provides a remote services abstraction layer that allows uniform access to local and remote resources using arbitrary remote service providers. The following diagram shows the architecture of the remote services abstraction.
| + | |
| − | | + | |
| − | [[Image:remote_services.png|center]]
| + | |
| − | | + | |
| − | The top two layers (shown in orange) comprise the abstraction layer. The lower (green) layer are the actual service provider implementations. By providing this separation between the abstraction and the service providers, no additional dependencies are introduced into PTP.
| + | |
| − | | + | |
| − | Three primary service types are provided:
| + | |
| − | | + | |
| − | ; Connection management : Create and manage connections to the remote system. Once a connection has been established, it can be used to support additional activities.
| + | |
| − | | + | |
| − | ; File management : Provides services that allow browsing for and performing operations on remote resources, either files or directories.
| + | |
| − | | + | |
| − | ; Process management : Provides services for running commands on a remote system.
| + | |
| − | | + | |
| − | There is also support available for discovering and managing service providers.
| + | |
| − | | + | |
| − | === Implementation Details ===
| + | |
| − | | + | |
| − | The main plugin for remote services is found in the <tt>org.eclipse.ptp.remote</tt>. This plugin must be included in order to access the remote abstraction layer. The plugin provides an extension point for adding remote services implementations. Each remote services implementation supplies a <i>remote services ID</i> which is used to identify the particular implementation. The following table lists the current remote services implementations and their ID's.
| + | |
| − | | + | |
| − | {| style="width:75%" align="center" border="1"
| + | |
| − | |-
| + | |
| − | ! Plugin Name !! ID !! Remote Service Provider
| + | |
| − | |-
| + | |
| − | | <tt>org.eclipse.ptp.remote</tt> || <tt>org.eclipse.ptp.remote.LocalServices</tt> || Local filesystem and process services
| + | |
| − | |-
| + | |
| − | | <tt>org.eclipse.ptp.remote.rse</tt> || <tt>org.eclipse.ptp.remote.RSERemoteServices</tt> || Remote System Explorer
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | In addition to providing a remote services ID, each plugin must provide implementations for the three main services types: connection management, file management, and process management. The plugin is also responsible for ensuring that it is initialized prior to any of the services being invoked.
| + | |
| − | | + | |
| − | ==== Entry Point: PTPRemotePlugin ====
| + | |
| − | | + | |
| − | The activation class for the main remote services plugin is <tt>PTPRemotePlugin</tt>. This class provides two main methods for accessing the remote services:
| + | |
| − | | + | |
| − | ; <tt>IRemoteServices[] PTPRemotePlugin.getAllRemoteServices()</tt> : This method returns an array of all remote service providers that are currently available. A service provider for accessing local services is guaranteed to be available, so this method will always return an array containing at least one element.
| + | |
| − | | + | |
| − | ; <tt>IRemoteServices PTPRemotePlugin.getRemoteServices(String id)</tt> : This method returns the remote services provider that corresponds to the ID give by the <code>id</code> argument.
| + | |
| − | | + | |
| − | Typically, the remote service providers returned by <tt>getAllRemoteServices()</tt> will be used to populate a dropdown that allows the user to select the service they want to use. Once the provider has been selected, the <tt>getRemoteServices()</tt> method can be used to retrieve the remote services at a later date.
| + | |
| − | | + | |
| − | ==== Obtaining Services: IRemoteServices ====
| + | |
| − | | + | |
| − | The <tt>IRemoteServices</tt> interface represents a particular set of remote services, and is the main interface for interacting with the remote service provider. There are four main methods available:
| + | |
| − | | + | |
| − | ; <tt>boolean isInitialized()</tt> : This should be called to check that the service has been initialized. Other methods should only be called if this returns true.
| + | |
| − | | + | |
| − | ; <tt>IRemoteConnectionManager getConnectionManager()</tt> : Returns a connection manager. This is used for creating and managing connections.
| + | |
| − | | + | |
| − | ; <tt>IRemoteFileManager getFileManager()</tt> : Returns a file manager for a given connection. A file manager is responsible for managing operations on files and directories.
| + | |
| − | | + | |
| − | ; <tt>IRemoteProcessBuilder getProcessBuilder()</tt> : Returns a process builder for a given connection. A process builder is responsible for running commands on a remote system.
| + | |
| − | | + | |
| − | ==== Connection Managerment: IRemoteConnectionManager ====
| + | |
| − | | + | |
| − | Once the service provider has been selected, the first thing that typically needs to be done is create a new connection. This is done using the <tt>IRemoteConnectionManager.newConnection()</tt> method. This method will allow the user to create a new connection using whatever method the underlying service provider uses for this. Typically it will be some kind of dialog that allows the connection parameters to be entered (hostname, username, password, etc.) The result will be an <tt>IRemoteConnection</tt> object that represents the connection to the remote system.
| + | |
| − | | + | |
| − | ==== File Management: IRemoteFileManager ====
| + | |
| − | | + | |
| − | If file-type operations are required, then the next step would be to call <tt>IRemoteServices.getFileManager()</tt> specifying the newly create connection. The resulting <tt>IRemoteFileManager</tt> object has a number of methods for selecting and manipulating files:
| + | |
| − | | + | |
| − | ; <tt>IPath browseFile()</tt> : This will present the user with a dialog allowing them to select a file on the remote system. The returned path will be the path of the remote file relative to the remote system.
| + | |
| − | | + | |
| − | ; <tt>IPath browseDirectory()</tt> : Similar to browseFile() but the user can select a directory.
| + | |
| − | | + | |
| − | ; <tt>IRemoteResource getResource()</tt> : Given a path on the remote system, this will return an object that can be used to manipulate the remote file or directory.
| + | |
| − | | + | |
| − | ==== Process Manangement: IRemoteProcessBuilder ====
| + | |
| − | | + | |
| − | Coming...
| + | |
| − | | + | |
| − | ==== Other Services ====
| + | |
| | | | |
| − | Coming...
| + | == [[PTP/designs/2.x/remote_services | Remote Services]] == |
| | | | |
| − | == Tool Integration Services ==
| + | This [[PTP/designs/2.x/remote_services | section]] describes the remote services framework that PTP uses for communication with remote systems. |
The Parallel Tools Platform (PTP) is a portable, scalable, standards-based integrated development environment specifically suited for application development for parallel computer architectures. The PTP combines existing functionality in the Eclipse Platform, the C/C++ Development Tools, and new services specifically designed to interface with parallel computing systems, to enable the development of parallel programs suitable for a range of scientific, engineering and commercial applications.
This document provides a detailed design description of the major elements of the Parallel Tools Platform version 2.x.
The Parallel Tools Platform provides an Eclipse-based environment for supporting the integration of development tools that interact with parallel computer systems. PTP provides pre-installed tools for launching, controlling, monitoring, and debugging parallel applications. A number of services and extension points are also provided to enable other tools to be integrated with Eclipse an fully utilize the PTP functionality.
Unlike traditional computer systems, launching a parallel program is a complicated process. Although there is some standardization in the way to write parallel codes (such as MPI), there is little standardization in how to launch, control and interact with a parallel program. To further complicate matters, many parallel systems employ some form of resource allocation system, such as a job scheduler, and in many cases execution of the parallel program must be managed by the resource allocation system, rather than by direct invocation by the user.
In most parallel computing environments, the parallel computer system is remote from the user's location. This necessitates that the parallel runtime environment be able to communicate with the parallel computer system remotely.
The PTP architecture has been designed to address these requirements. The following diagram provides an overview of the overall architecture.
