blob: ee17f35d5685fb146746e5f3393af621500cbf3c [file] [log] [blame]
<html>
<head>
<title>The PTP Debug Perspective</title>
</head>
<body>
<!-- test -->
<h1>The PTP Debug Perspective</h1>
<ul>
<li><a href="#feat">PTP Debug Perspective </a> - main features
<li><a href="#pSets">Process Sets</a>
<li><a href="#pSetsOper">Operations on Process Sets</a>
<li><a href="#pSetsCreate">Creating Process Sets</a>
<li><a href="#bkpt">Breakpoints</a>
<li><a href="#cip">Current Instruction Pointer</a>
<li><a href="#reg">Process Registration </a> and the Debug view (including stack traces)
<li><a href="#ptpVar">PTP Variable View</a>
</ul>
<h2 id="feat">Main features of the PTP Debug perspective</h2>
<p>Here is a view of the PTP Debug perspective, showing
<ul>
<li>the Jobs view of currently running jobs, including
the processes in the current process set,
<li>the debug process view which shows the call stack
for any registered processes
<li>the source view (from CDT) which shows
the current instruction pointer of the process selected
in the debug process view
<li>the variables view that shows
the current values of variables for the currently selected
process in the debug process view
<li>the outline view (from CDT)
</ul>
<img src="images/ptpDebugOview.gif">
<h2>Launching a parallel debug session</h2>
<ul>
<li>Create a Parallel Application for Debug launch
similar to creating it for Run...
(See <a href="02pLaunchConfig.html">Launching parallel programs</a>,
but the necessary information is given below.)
</li>
<p>In the Debug launch dialog (Run -> Debug ... or use the Debug
icon on the eclipse toolbar)
<li>Select 'Debugger' tab..
<li>Select 'Stop in main' to automatically stop the job</li>
<li>Make sure the Debugger is set to "SDM" - use the pulldown menu.
<li>Change any other default settings (not normally required)</li>
<li>Select the Debug button (or hit "Apply" to save these settings
if you do not intend to launch immediately.)
<br><img src="images/parDebugConfig.gif">
<p>For existing Parallel Application launch configurations,
you can simply
launch using the debug button rather than the Run button
<p>
<img src="images/parDebugIcon.gif">
</li>
<li>Eclipse may ask you to switch to the PTP Debug perspective.
<br><img src="images/confirmPerspSwitch.gif">
<br>Answer yes; if you check "Remember my decision" it won't ask you this
for future launches. It will then
switch to the PTP Debug perspective.</li>
</ul>
<p>The Parallel Debug Perspective:
<p><img src="images/ptpDebugPersp.gif">
<br>The debug perspective appears as in the example above.
This is a launch with 32 processes set on the launch configuration.
The Parallel Debug view shows the 32 processes (yellow diamonds
indicate a stopped process); the Debug view shows process 0
stopped at main; the Source view shows the line at which process
0 is stopped.
<p>Note that the breakpoints view (upper right) is empty, since
no breakpoints are set. You can view the variables in this area
by selecting the tab on the Variables View
<br><img src="images/variablesViewSelect.gif">
<br>Note that most variables don't have valid values
yet since we haven't executed their initializations in the
program.
<br><img src="images/variablesViewDisplay.gif">
<h2 id="pSets">Process Sets</h2>
<p>Traditional debuggers apply operations to a single
process. Parallel debugging operations apply to a single process
<i>or to arbitrary collections of processes.</i>
<p>A <i>process set </i> is a means of simultaneously referring
to one or more processes.
<p>When a parallel debug session is first started, all processes are placed
in a set, called the 'Root' set. Sets are always associated with a single Job.
A job can have any number of process sets. A set can contain from 1 to the
number of processes in a job.
<p><img src="images/pSets.gif">
<h2 id="pSetsOper">Operations on Process sets</h2>
<p>Use the icons in the toolbar of the Parallel Debug view
to create, modify, and delete process sets, and to change
the current process set.
<br><img src="images/pSetOper.gif">
<p>Debug operations on the Parallel Debug View toolbar always apply to the current set.
<br><img src="images/pSetDebug.gif">
<h2 id="pSetsCreate">Creating Process Sets</h2>
<p>Select the processes to be placed in the set
by selecting a rectangular region with the mouse,
or click the mouse and shift-click or ctrl-click to
select a contiguous region, or separate processes, respectively.
<p>Selecting a rectangular set:
<br><img src="images/pSetSelect.gif">
<p>Create a process set from the group that was selected by
clicking on the <i>image</i> in the icon <img src="images/createProcessSetIcon.gif">..
<p><img src="images/selectProcessSetCreate.gif">
<p>Or, add the group of processes to an existing process set by clicking
on the <img src="images/downArrowSelect.gif"> down-arrow to the right of the icon:
<p><img src="images/selectProcessSetCreateAdd.gif">
<p>To change the current process set, select the icon
<img src="images/pSetChooseIcon.gif">
and choose from the list via the down-arrow <img src="images/downArrowSelect.gif">, or
click on the image in the icon itself to cycle through the sets.
<br><img src="images/pSetChange.gif">
<p>To remove processes from <i>the current set</i>, select the processes
as described above, and Click the
"Remove Elements" button.
<br><img src="images/pSetRemove.gif">
<p>Select the "Delete Set" icon to delete the current process set.
<br><img src="images/pSetDelete.gif">
<br><img src="images/pSetDeleteConfirm.gif">
<h2 id="bkpt">Breakpoints</h2>
<p>There are two main types of parallel breakpoints in PTP.
<ul>
<li><i>Global Breakpoints</i> apply to <i>all</i> processes in <i>any</i> job.
They are saved between jobs.
<br><img src="images/bkptGlobal.gif">
<p>
</li>
<li><i>Set Breakpoints </i> apply only to a process in a particular set
(which can include the root set) for a single job. When the job completes,
the breakpoints are no longer available.
<p>Green indicates the breakpoint is applied to the current set.
<br>Blue indicates the breakpoint is applied to some other set.
<br>Yellow indicates the breakpoint is applied to some process(es)
in the current set, which are also in some other set.
(In other words, the process sets overlap.)
<br><img src="images/bkptSet.gif">
</li>
</ul>
<h3>Setting Breakpoints</h3><p>
To create a breakpoint, double-click on the left edge of
an editor window, at the line on which you want to set the breakpoint.
Or, right click and use the context menu.
<br><img src="images/bkptSetContext.gif">
<p>A global breakpoint is created if no jobs are selected.
If a job is selected, the breakpoint will apply to the current set.
<h3>Breakpoint information</h3>
<p>Hover over a breakpoint to see more information.
<br><img src="images/bkptHover.gif">
<p>Use the Breakpoints view to see all breakpoints.
<br><img src="images/bkptsView.gif">
<p>Use the menu in the Breakpoints view to group breakpoints
by type.
<br><img src="images/bkptsViewMenu.gif">
<p>For example the above selection will list the breakpoints
by process set.
<br><img src="images/bkptsViewByProcessSet.gif">
<h2 id="cip">Current Instruction Pointer</h2>
<p>The current instruction pointer is used to show the current
location of <i>suspended</i> processes.
In traditional programs, there is a single instruction pointer.
(The exception to this is multi-threaded programs.)
In parallel programs, there is an instruction pointer for every process.
<p>The PTP debugger shows one instruction pointer for
<i>every group of processes at the same location</i>.
<blockquote><b>Note:</b> The group of processes represented by an instruction pointer
is not necessarily the same as a process set.</blockquote>
<p>In the normal debugger, the single instruction pointer
is indicated with the blue arrow icon. The current source line is also highlighted.
<br><img src="images/sip.gif">
<p>In the PTP (parallel) debugger, there are multiple instruction pointers.
The marker depends on the type of process stopped at that location.
<ul>
<li><img src="images/ipMult.gif">Multiple processes marker
<li><img src="images/ipReg.gif">Registered process marker
<li><img src="images/ipUnreg.gif">Un-registered process marker
</ul>
<p>The highlight color of the current instruction pointer
depends on the stack frame. In the following image,
the green background indicates a registered process; the brown background indicates an
unregistered process. The blue band behind the highlight color of the line tracks
the current stack frame.
<p><img src="images/ptpInstrPtr.gif">
<p>Hovering over the instruction pointer provides additional information.
<br><img src="images/cipHover.gif">
<h2 id="reg">Process Registration and the Debug View</h2>
<p>Process set commands apply to groups of processes.
For finer control and more detailed information, a process can be
<i>registered</i> and isolated in the Debug View.
<p>
Registered processes, including their stack traces, appear in the 'Debug' view.
Any number of processes can be registered,
and processes can be registered or un-registered at any time.
<p>To register a process, double-click its process icon in the Jobs view.
Note that the process "diamond" then is surrounded by a box.
The process appears in the debug view.
<br><img src="images/reg1.gif">
<p>To un-register a process, double-click on the same icon.
The box disappears, and the process is removed from the debug view.
<p>Note that the debug commands (icons including run, step, etc.)
in the toolbar of the Jobs view (tab title: Parallel Debug)
control the currently selected process set.
The debug commands in the toolbar of the Debug view
control the single process that is currently selected in that view.
<h2 id="ptpVar">PTP Variable View</h2>
<p>The PTP Variable view allows you to
view a particular variable's values across the various processes.
<p>If you open the PTP Variable View (Window -> Show View -> Other)
you can add a variable.
<br>
<img src="images/ptpVarAdd1.png">
<p>This opens the PTP Variable Dialog which allows you to select a variable or expression,
and a process set (use Root for all processes) for which to create the variable to watch for each process.
<br>
<img src="images/ptpVarAdd.png">
<p>
Then when you mouse over a process icon in the
Parallel Debug view, it will show the value of the variable in the tooltip.
<br>
<img src="images/ptpVarDisplay.png">
<h2>Putting it all together</h2>
<p>Note that with the above instructions, you should now be able to do the following:
<i>Answers are in italics.</i>
<ul>
<li>Set a global breakpont
<br><i>Make sure no job is selected, then double-click in the area to the left of the source line. You should see
the global breakpoint icon <img src="images/globalBkpt.gif"> appear. </i>
</li>
<li>Start a 100 process job
<br><i>Use the menu: Debug->Debug... Make a launch configuration (or reuse one).
On the Parallel tab, specify 100 processes.</i>
</li>
<li>When the breakpoint is reached,</li>
<ul>
<li>Create a process set containing processes 0-10 (set_1)
<br><i>In the Parallel Debug view, select a group of the process diamonds,
which should be yellow=stopped processes.
Select a rectangular region with the mouse, or click the mouse and shift-click
or ctrl-click to select a contiguous region, or separate processes, respectively.
Then click the <img src="images/createProcessSet.gif"> button and give
the process the name "set_1"
</i>
<li>Create a process set containing processes 20-30 (set_2)
<br><i>Same as above.</i>
<li>Single step all processes
<br><i>Use the step-over icon <img src="images/fromPTP/stepover_normal.gif"> in the toolbar of the
Parallel Debug View (near the top).</i>
<li>Single step processes in set_1
<br><i>Make sure the process set is selected via
<img src="images/selectProcessSet.gif">, then use the step-over icon <img src="images/fromPTP/stepover_normal.gif"> in the toolbar of the
Parallel Debug View (near the top).</i>
<li>Register a process
<br><i>Double-click on the process icon diamond. It should then have a rectangle around it. </i>
<li>Single step the registered process
<br><i>Select the process in the debug view (near the center of the screen), and Use the step-over icon <img src="images/fromPTP/stepover_normal.gif"> in the toolbar of the
Debug View (near the top).</i>
<li>Select a stack frame and view the variables
<br><i>Click on a line in the Debug view that includes a line number.</i>
</ul>
<li>Terminate execution
<br><i>Click on the terminate icon <img src="images/terminateAll.gif"> in the
Parallel Debug View. Note that the terminate icon in the Debug (Process)
view <img src="images/terminate.gif">will terminate a single process.</i>
</li>
</ul>
<p><a href="#top">Back to Top</a> | <a href="toc.html">Back to Table of Contents</a>
</body>
</html>