Debugging code with TotalView: A primer
last update: 03/05/2003

Introduction to TotalView and how you use it to perform common debugging tasks

This section provides the information you need to:

  1. Examine core files
  2. Debug a simple serial code
  3. Examine program variables that may be related to program bugs
  4. Obtain more detailed information about the program by "diving"

Examining core files with TotalView

When an executing code halts with a cryptic message such as "segmentation error," you should examine the core file to find the specific line in the code where the error occured and to see the values of the variables that caused the error to occur.

The following Fortran code, it.f, was compiled on the IBM SP system with
xlf_r -g -qarch=auto -qrealsize=8 -o ./it ./it.f

Compiling with the -g option provides symbol tables that the debugger can read, and it allows TotalView to display the source code as you step through it. The it.f code was executed with ./it, and it produced a Segmentation fault (core dumped) message.


program main
implicit none
integer i,j
real x(2)
do i=1,4
   j=x(i)+x(i)/(i-1)
   x(j)=x(j)-1
end do
print*,'x(j)=',x(j)
stop
end

The command totalview it core produced a TotalView window containing a source listing with an "arrow" pointing to the line of source code that produced the segmentation error (see Figure 1). This use of TotalView also works for parallel codes that generate multiple core files. The example in the next section explains how to use the TotalView window that displays the source code to also determine the contents of the other variables in the code plus other useful information about the code.

Core file display
Figure 1. Core file display in TotalView.

Debugging a simple serial code

You can reference and execute the following run script to follow and demonstrate the features described in this section:


#! /bin/csh
# Very simple serial code set up to execute under TotalView control:
cat << 'EOF' > ./it.f
   program main
   implicit none
   integer i
   real sum
   common sum
   sum=0.0
   do i=1,1000000
      sum=sum+exp(.00000001*i)
   end do
   print*,'sum=',sum
   stop
   end
'EOF'

# Compile and build program "it" from it.f; use -g option and no
# optimization to support source debugging of all Fortran statements:

xlf_r -g -qarch=auto -qrealsize=8 -o ./it ./it.f

# Execute program "it" in TotalView:

totalview ./it

# Clean up working directory:

rm it*

TotalView session

The TotalView session in the example above started with the totalview ./it statement. This displays two windows: a small root window and a large process window.

The root window

The root window initially displays the attached pane and tells you what processes are currently attached to TotalView (see Figure 2).

Root window
Figure 2. Root window.

The process window

The process window is the main window used for working and debugging in TotalView. It consists of five sub-panes.

Figure 3 shows the process window after the run script has been started. The source code pane displays the code, but the other panes display little information because the code has not started executing.

Process window
Figure 3. Process window.

Examining program variables

You can execute the code by clicking the "Go" button on the second row of the process window or by typing "g". However if a stop point in the code is not set, the code will continue to completion, and TotalView will exit. Since the object of this exercise is to stop and debug, we first need to set a stop point. Before typing g, set the code to stop at line 8.

In the following discussion, more will be said about the types of stop points. However, in the interest of showing you useful content (such as program variables, program stack trace, action points, etc.) in the other process window panes, please follow these steps:

  1. Select the rectangle containing the "8" in line 8 using the left mouse button. This creates a red stop bar.
  2. Type "g".

The program runs through to line 8 and displays a yellow arrow over the red stop bar indicating that the program has executed to "i=1" of the do loop and is stopped, waiting to execute statement 8 (see Figure 4). Typing "n" repeatedly will step the do loop forward with increasing values of "i" and "sum."

Program stopped at stop point
Figure 4. Program stopped at stop point.

Note that you can now find useful information about the executing program in the other panes of the process window. The stack frame pane now contains information about the contents of the program variables. Note that sum is not a program variable because it is in a common block. To find the current value of "sum," read the next paragraph on "Diving."

Obtaining more detailed information about the program by "diving"

Some variables, such as arrays or fields of derived types, can be viewed by diving. In the source pane and the stack frame pane, you can dive on variables using the center mouse button (or the right mouse button), which raises a popup window showing the variable. If you click on an array variable, the popup window will display the contents of the entire array. If you dive on a subprogram-function call, TotalView will shift focus to that subprogram. It then displays in the center pane the source for the program, provided that the subprogram was compiled with "-g."

Next page | Table of contents - TotalView primer

If you have questions about this document, please contact SCD Customer Support. You can also reach us by telephone 24 hours a day, seven days a week at 303-497-1278. Additional contact methods: consult1@ucar.edu and during business hours in NCAR Mesa Lab Suite 39.

© Copyright 2003. University Corporation for Atmospheric Research (UCAR). All Rights Reserved.

Address of this page: http://www.scd.ucar.edu/docs/totalview/tasks.html