Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "PTP/designs/2.x/debug platform"
(→Scalable Debug Manager) |
(→Backend Debugger) |
||
Line 575: | Line 575: | ||
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. | 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. | ||
− | |||
− | |||
− | |||
− |
Latest revision as of 14:49, 9 May 2008
Contents
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.
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. |
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.