# Parallel Debugging

This section describes the features of PTP that enable a developer to debug a parallel application. The topics that will be covered include:

- Supported Target System Configurations
- Creating a Debug Launch Configuration
- The Parallel Debug Perspective
- Process Sets
- Operations on Process Sets
- Managing Process Sets
- Breakpoints
- Current Instruction Pointer
- Process Registration and the Debug view (including stack traces)
- Terminating Execution

## Supported Target System Configurations

The PTP Parallel debugger has been implemented for a number of Target System Configurations (TSCs). For details and the most recent information, see the Release Notes and the PTP FAQ

For PTP 9.1, Parallel debugging is supported for

- Generic TSCs:
  - Generic OpenMPI Interactive
  - Generic MPICH2 Interactive
  - Generic Remote Interactive
  - IBM Parallel Environment
  - IBM Platform LSF Interactive
  - IBM Platform MPI
- Specific system TSCs:
  - Trestles Torque OpenMPI Interactive

## Creating a Debug Launch Configuration

In order to launch a debug job, the user must first create a Debug Configuration. The process for doing this is identical to that used to run a parallel program, with the exception of a single extra tab that needs to be completed. Only this extra tab will be described here.

To create a debug configuration, use the following steps:

1. Select the Run > Debug Configurations... menu.

2. Follow the same steps as described in running parallel programs for completing the other launch tabs, e.g. Resources, Application, Arguments, Environment, Synchronize.

3. Switch to the Debugger tab.

4. If no debugger is visible in the Debugger drop-down, select one. This is the debugger that will control the parallel debug session. Currently only SDM (Scalable Debug Manager) is supported, so select this.

5. If you wish the debugger to automatically suspend the application on launch, make sure Stop at main() on startup is checked

6. Under Debugger Options, make sure the Debugger backend is set to `gdb-mi`.

7. To use the built-in SDM in PTP, and have it copied to the remote target and executed, leave Use built-in SDM if available for the target platform checked. It uses the OS and architecture from the remote target to copy the correct SDM executable to the remote system.

   - If instead you want to specify the path of the debugger, uncheck the Use built-in SDM box and make sure that the Path to SDM executable is correct for your target system.

     If you are debugging on the local machine, this path should point to the `sdm` executable in your Ecilpse installation's `plugins/org.eclipse.ptp.os.arch_version/bin` directory, where `os.arch_version` is your operating system (`linux`, `macosx`, or `aix`), architecture (`x86`, `x86_64`, or `ppc`), and version number of the plugin (e.g. `5.0.0.201106080812`).

     Note: This may have required an extra step during installation to build this executable.

     If you are debugging remotely, then this path will be the path to where the `sdm` executable was installed on the remote machine.

8. (Optional) Advanced Options are accessed by clicking on the twistie. The advanced options allow you to set the Session address and the Path to gdb executable.

   The session address is the address that the debugger will connect to when it starts, and will depend on where you are launching the application:

   If you are launching onto the local machine, or onto a remote machine using port forwarding, use `localhost`. (Note that you will need to have the `GatewayPorts` option set to `yes` in the `sshd` configuration file on the remote system for this to work with port forwarding.)

   If you are launching onto a remote machine without using port forwarding, then this should be the address of the local machine (the one running Eclipse). This address must be accessible from the remote machine. If your local network configuration precludes the remote machine accessing your local machine, you will need to reconfigure the connection to use port forwarding.

   The path of gdb executable can be overridden if it is located in a non-standard directory, or you wish to use an alternative to gdb.

## The Parallel Debug perspective

The Parallel Debug perspective is used when debugging a parallel application. The default behavior is to switch to the perspective when a debug session is launched. Experienced Eclipse users will notice that many of the views are similar to those available in the CDT Debug perspective. Please refer to the C/C++ Development User Guide for a description of these views.

This image shows a typical debug session. In the upper left of the perspective is the Parallel Debug view which shows the processes associated with the job, and allows bulk control of the processes. Underneath this is the Debug view which is the standard view showing process threads and stack frames. The source window shows a current line marker, which represents the current location of all 64 processes. In the upper right, the Variables view is showing the variables from the processes currently selected in the Debug view. There are also a number of other views available for setting breakpoints, manipulating signals, etc. Below this is the standard Outline view. At the very bottom are the standard Problems, Console, and Memory views.

## Process Sets

A key concept for debugging parallel programs with PTP is the notion of a process set. Traditional debuggers apply operations to a single process. Parallel debugging operations apply to arbitrary collections of processes (including a single process). The PTP debugger calls these arbitrary collections process sets, and uses them as a means of simultaneously referring to one or more processes.

When a parallel debug session is first started, all processes are contained in a set, called the Root set. Sets are always associated with a single Job. A job can have any number of process sets, and a set can contain from 1 to the number of processes in a job. Process sets from the same job can contain overlapping sets of processes. This is shown in the following diagram.

Debug commands on the Parallel Debug view toolbar always apply to the current process set, which is the set of processes that is visible in the view.

## Operations on Process sets

PTP provides buttons on the toolbar of the Parallel Debug view to create, modify, and delete process sets, and to change the current process set.

## Managing Process Sets

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.

For example, to select a rectangular set of processes:

Once the processes have been selected, create a process set clicking on the Create Set button .

To add processes to an existing process set, select the processes you wish to add and click on the down-arrow to the right of the icon:

To change the current process set, select the Change Set button and choose from the list via the down-arrow , or click on the button itself to cycle through the sets.

To remove processes from the current set, select the processes as described above, and click the Remove Elements button.

Select the Delete Set button to delete the current process set:

## Breakpoints

PTP has a special type of breakpoint known as a parallel breakpoint. These breakpoints differ from normal breakpoints because they apply to a set of processes instead of a single process (or thread). There are two types of parallel breakpoints:

- Global breakpoints apply to all processes in any job. A global breakpoint remains in effect between job launches. Typically, a global breakpoint is used for gaining control of an application at a predetermined point. Global breakpoints are identified by a parallel breakpoint icon with a small `G` in the upper left corner:

- Set Breakpoints apply only to a specific set of processes (which can include the root set) for a single job. When the job completes, these breakpoints are removed.

Set breakpoints can be one of three colors:

- Green indicates the breakpoint applies to the current set.

- Blue indicates the breakpoint applies to some other set than the current set, but there are overlapping processes in the sets.

- Yellow indicates the breakpoint applies to some other set than the current set, and there are no overlapping processes in the sets.

### Setting a breakpoint

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. You can also right-click and use the Parallel Breakpoint > Toggle breakpoint context menu.

A global breakpoint is created if no jobs are selected in the Parallel Debug view. If a job is selected, the breakpoint will apply to the current set.

### Breakpoint information

There are a number of ways to find out more information about a breakpoint, such as the source file, line and process set it applies to. Placing the mouse over a breakpoint will display a tooltip popup:

The Breakpoints view can be used to see all breakpoints that have been created:

Use Show > Parallel Breakpoint Set in the menu on the Breakpoints view toolbar to group breakpoints by the process set they apply to:

For example the above selection will list the breakpoints by process set:

## Current Instruction Pointer

The current instruction pointer is used to show the current location of suspended processes. In traditional programs, there is only a single instruction pointer displayed at any one time. In parallel programs, there is an instruction pointer for every process.

The PTP debugger shows one instruction pointer for every group of processes at the same location. In the following example, there are processes suspended at three different locations in the program.

The group of processes represented by an instruction pointer is not necessarily the same as a process set.

Different markers are used to indicate the types of processes stopped at that location (the different types will be discussed below):

- Registered processes marker

- Un-registered processes marker

- Marker indicating a combination of registered and un-registered processes

Placing the mouse over an instruction pointer provides additional information about the processes suspended at that location:

## Process Registration and the Debug View

Once processes of a parallel job have been suspended, it is often desirable to obtain more detailed information about an individual process. In order to do this, a particular process must first be registered. Once a process is registered it's threads and stack frames appear in the Debug view. By selecting the stack frame in this view, detailed information about the local variables can be obtained in the Variables view.

Any number of processes can be registered, and processes can be registered or un-registered at any time. To register a process, double-click its process icon in the Parallel Debug view. A black box will be shown around the process icon to indicate that it has been registered. At the same time, the process will appear in the Debug view.

To un-register a process, double-click on the same process icon. The box disappears, and the process is removed from the debug view.

The Debug view also provides a set of debug commands (resume, pause, step over, etc.) that apply to the currently selected process in the view. This provides a convenient means of controlling individual processes.

## Terminating Execution

At the end of a debug session, it is necessary to terminate the execution of the job. To do this, click on the terminate icon in the Parallel Debug view. Note that the terminate icon in the Debug view will only terminate the currently selected process in that view.

Back to Top | Back to Table of Contents