(prism all) show events

(1) trace

(2) when stopped { print board }

(prism all) disable 1

event 1 disabled

(prism all) show events

(1) trace (disabled)

(2) when stopped { print board }

Events and Deleted Psets

If you create an event that applies to a particular pset and subsequently delete the pset, the event continues to exist. Its printed representation, however, is changed so that it shows the processes that were members of the pset at the time you deleted the set.

---

Setting Breakpoints

A breakpoint stops execution of a program when a specific location is reached, if a variable or expression changes its value, or if a certain condition is met. This section describes the methods available in the Prism environment for setting a breakpoint.

You can set a breakpoint in the following ways:

• By using the line-number region
• By using the Event Table and the Events menu
• By issuing the command stop or when in the command window

The line-number region is easiest for setting simple breakpoints. However, the other two methods give you greater flexibility, such as in setting up a condition under which the breakpoint is to take place.

In all cases, an event is added to the list in the Event Table. If you delete the breakpoint using any of the methods described in this section, the corresponding event is deleted from the event list. If you set a breakpoint at a program location, a B appears next to the line number in the line-number region.

Using the Line-Number Region

To use the line-number region to set a breakpoint, the line at which you want to stop execution must appear in the source window. If it does not, you can scroll through the source window (if the line is in the current file) or use the File or Func selection from the File menu to display the source file you are interested in.

1. Position the mouse pointer to the right of the line numbers.

The pointer turns into a B.

2. Move the pointer next to the line at which you want to stop execution.

3. Left-click the mouse.

A B is displayed, indicating that a breakpoint has been set for that line.

A message appears in the command window confirming the breakpoint, and an event is added to the event list.

The source line you choose must contain executable code; if it does not, you receive a warning in the command window, and no B appears where you clicked.

4. Shift-click on the letter in the line-number region to display the complete event
(or events) associated with it.

See Using the Line-Number Region for more information on the line-number region.

Left-click on the B that represents the breakpoint you want to delete.

The B disappears; a message appears in the command window, confirming the deletion.

What Happens in a Split Source Window

As described in Moving Through the Source Code, you can split the source window to display source code and the corresponding assembly code.

You can set a breakpoint in either pane. The B appears in the line-number region of both panes, unless you set the breakpoint at an assembly code line for which there is no corresponding source line.

Deleting a breakpoint from one pane of the split source window deletes it from the other pane as well.

Using the Event Table and the Events Menu

1. Select Stop <loc> or Stop <var> from the Events menu.

These choices are also available as Common Events buttons within the Event Table itself; see Adding an Event.

2. Perform one of the following:

• Stop <loc> prompts for a location at which to stop the program. If you want to set the breakpoint at a particular line in the program, enter the line number. Or, to set the breakpoint at the first line of a function or procedure, enter the function or procedure name instead.

 FIGURE 4-3 Stop <loc> Dialog Box

• Stop <var> prompts for a variable name. The program stops when the variable's value changes. The variable can be an array, in which case execution stops whenever any element of the array changes. This slows execution considerably.
• Stop <cond> (available as a Common Events button on the Event Table) prompts for a condition, which can be any expression that evaluates to true or false. The program stops when the condition is met. This slows execution considerably.

See Writing Expressions in the Prism Environment for more information on expressions.

You can also use the Event Table to create combinations of these breakpoints; for example, you can create a breakpoint that stops at a location if a condition is met.
In addition, you can use the Actions field of the Event Table to specify the Prism commands that are to be executed when execution stops.

Perform one of the following:

• From the Events menu, select Delete.
• From the Event Table, click on the Delete button.

For more information about deleting events, see Deleting an Existing Event.

Setting a Breakpoint Using Commands

Type:

(prism all) stop

or

(prism all) when

The when command is an alias for the stop command.

The syntax of the stop command is also used by the stopi, when,trace, and tracei commands. The general syntax for these commands is:

command [variable | at line | in func] [if expr] [{cmd[; cmd...]}] [after n]

where

• command - Is the name of a command, which can be stop, stopi, when, trace, or tracei.
• variable - Is the name of a variable. The command is executed if the value of the variable changes. If the variable is an array, an array section, or a parallel variable, the command is executed if the value of any element changes. This form of the command slows execution considerably. You cannot specify both a variable and a program location.
• line - Specifies the line number where the stop or trace is to be executed. If the line is not in the current file, use the format:

at filename:line-number

• func - Is the name of the function or procedure in which the stop or trace is to be executed.
• expr - Is any language expression that evaluates to true or false. This argument specifies the logical condition, if any, under which the stop or trace is to be executed. For example, the following expression evaluates to true whenever variable a is greater than 1.

if a .GT. 1

This form of the command slows execution considerably, unless you combine it with the at line syntax. See Writing Expressions in the Prism Environment for more information on writing expressions in the Prism environment.

• cmd - Is any Prism command (except attach, core, detach, load, return, run, or step). This argument specifies the actions, if any, that are to accompany the execution of the stop or trace. For example, {print a} prints the value of a. If you include multiple commands, separate them with semicolons.
• n - Is an integer that specifies how many times a triggering condition is to be reached before the stop or trace is executed; see Overview of Events for a discussion of triggering conditions. This is referred to as an after count. The default is 1. Once the stop or trace is executed, the count is reset to its original value. Note that if there is both a condition and an after count, the condition is checked first.

The first option listed (specifying the location or the name of the variable) must come first on the command line. The other options, if you include them, can be in any order.

For the when command, you can use the keyword stopped to specify that the actions are to occur whenever the program stops execution.

When you issue the command, an event is added to the event list. If the command sets a breakpoint at a program location, a B appears in the line-number region next to the location.

Examples of the stop Command

To stop execution the tenth time in function foo and print a, type:

(prism all) stop in foo {print a} after 10

To stop at line 17 of file bar if a is equal to 0, type:

(prism all) stop at "bar":17 if a == 0

To stop whenever a changes, type:

(prism all) stop a

To stop the third time a equals 5, type:

(prism all) stop if a .eq. 5 after 3

To print a and do a stack trace every time the program stops execution, type:

(prism all) when stopped {print a; where}

Type:

(prism all) stopi at machine-address

For example, the following command stops execution at address 1000 (hex):

(prism all) stopi at 0x1000

The history region displays the address and the machine instruction. The source pointer moves to the source line being executed.

1. Type:

(prism all) show events

This prints out the event list. Each event has an ID number associated with it.

2. Type:

(prism all) delete ID [ID ...]

List the ID numbers of the events you want to delete; separate multiple IDs with one or more blank spaces. For example,this deletes the events with IDs 1 and 3. Use the argument all to delete all existing events:

delete 1 3

---

Tracing Program Execution

You can trace program execution by using the Event Table or Events menu or by issuing commands. All methods add an event to the Event Table. If you trace a source line, the Prism environment displays a T next to the line in the line-number region.

Tracing is essentially the same as setting a breakpoint, except that execution continues automatically after the breakpoint is reached. When tracing source lines, the Prism environment steps into procedures if they were compiled with the -g option; otherwise it steps over them as if it had issued a next command.

Using the Event Table and Events Menu

Select Trace, Trace <loc>, or Trace <var> from the Events menu.

These choices are also available as Common Events buttons within the Event Table itself.

• Trace displays source lines in the command window before they are executed.
• Trace <loc> prompts for a source line. The Prism environment displays a message immediately prior to the execution of this source line.
• Trace <var> prompts for a variable name. A message is printed when the variable's value changes. The variable can be an array, an array section, or a parallel variable, in which case a message is printed any time any element changes. This slows execution considerably.
• Trace <cond> (available as a Common Events button) prompts for a condition, which can be any expression that evaluates to true or false; see Writing Expressions in the Prism Environment for more information on writing expressions. The program displays a message when the condition is met. This also slows execution considerably.

For variations of these traces, you can create your own event in the Event Table. You can also use the Actions field to specify Prism commands that are to be executed along with the trace.

Choose the Delete selection from the Events menu, or use the Delete button in the Event Table.

For more information about deleting existing events, see Deleting an Existing Event.

Using the Command Window

Type:

(prism all) trace

Issuing trace with no arguments causes each source line in the program to be displayed in the command window before it is executed.

The trace command uses the same syntax as the stop command; see Setting a Breakpoint Using Commands. For example:

To trace and print a on every source line, type:

(prism all) trace {print a}

To trace line 17 if a is greater than 10, type:

(prism all) trace at 17 if a .GT. 10

In addition, the Prism environment interprets these two commands as being the same:

(prism all) trace line-number

(prism all) trace at line-number

Type:

(prism all) tracei address

When tracing machine instructions, the Prism environment follows all procedure calls down. The tracei command has the same syntax as the stop command; see Setting a Breakpoint Using Commands.

The history region displays the address and the machine instruction. The execution pointer moves to the next source line to be executed.

1. Type:

(prism all) show events

This obtains the ID associated with the trace.

2. Type:

(prism all) delete ID

For further information, see Setting a Breakpoint Using Commands.

---

Displaying and Moving Through the Call Stack

The call stack is the list of procedures and functions currently active in a program. The Prism environment provides you with methods for examining the contents of the call stack.

See Displaying the Where Graph for a discussion of displaying the call stack graphically in the Prism environment.

Perform one of the following:

• From the menu bar - Select Where from the Debug menu. The Where window is displayed; see FIGURE 4-4. The window contains the call stack. It is updated automatically when execution stops or when you issue commands that change the stack.

 FIGURE 4-4 Where Window

• From the command window - Type where on the Prism command line. If you include a number, it specifies how many active procedures are to be displayed; otherwise, all active procedures are displayed in the history region.
• From the command window - Type where on snapshot on the Prism command line to put the history-region output into a window.

Values of arguments in displayed procedures are shown in the default radix, which is decimal unless you change it via the set $radix command; see To Change the Default Radix.

Moving Through the Call Stack

Moving up through the call stack means heading toward the main procedure. Moving down through the call stack means heading toward the current stopping point in the program.

Moving through the call stack changes the current function and repositions the source window at this function. It also affects the scope that the Prism environment uses for interpreting the names of variables in expressions and commands. See Scope in the Prism Environment for more information.

Perform one of the following:

• From the menu bar - Choose Up or Down from the Debug menu. Up moves up one level in the call stack; Down moves down one level. These selections are available by default in the tear-off region.
• From the command window - Enter up or down on the command line to move up or down one level. To move more than one level, specify an integer argument.
• From the Where window - If the Where window is displayed, clicking on a function in it changes the stack level to make that function current.

Displaying the Where Graph

Selecting Where from the Debug menu displays the call stacks for the program being debugged. A multiprocess program can have multiple call stacks, one for each process. A threaded program can have a separate stack for each thread in each process.

To show the relationships among these call stacks, the Prism environment provides a Where graph; this window displays a snapshot of the dynamic call graph of the program. The Where graph displays information about all processes that are not running.

Perform one of the following:

• From the menu bar - Choose Where from the Debug menu.
• From the command line - Type where on dedicated.

A window like the one shown in FIGURE 4-5 is displayed.

 FIGURE 4-5 Where Graph

The Where graph centers on the current process of the current pset. That is, the processes related to it are lined up in a single column. In FIGURE 4-5, process 0 is the current process. If you change the current process, the Where graph rearranges itself. The default zoom level of the Where graph shows the arguments for the current process.

The line numbers at the bottom of each box indicate where processes branch.

Shift-click in each function's box.

This displays a pop-up window showing the numbers of the processes with this function in their call stack, along with their arguments.

Panning and Zooming in the Where Graph

As FIGURE 4-6 shows, the Where graph can get quite large, so the Prism environment provides methods for panning through it and zooming in and out.

The white box in the navigator rectangle at the top of the window shows the position of the display area relative to the entire Where graph.

Perform one of the following:

• Drag the box.
• Click at a spot in the navigator.

The box moves to that spot, and the window shows the Where graph in this area of the total display.

Click on the Zoom down arrow to the right of the navigator.

This reduces the size of the boxes representing the functions and removes information. FIGURE 4-6 shows the Where graph of FIGURE 4-5, zoomed out one level. Note that the information about the current process's arguments is gone.

As you zoom further out, the Where graph removes the line numbers, and one more level after that removes the function names, leaving only boxes connected by lines.

 FIGURE 4-6 Where Graph, Zoomed Out One Level

Shift-click on a box to display information about it.

If your program is multithreaded, its call stacks are not rooted at main. Thus, at maximum zoom, the Where graph displays the call stacks as multiple trees, as shown in FIGURE 4-7.

 FIGURE 4-7 Where Graph, Zoomed Out to the Maximum

Click on the Zoom up arrow.

This increases the size of the function boxes and includes more information in them. FIGURE 4-8 shows the Where graph of FIGURE 4-5, zoomed in. In this case, the Where graph shows, for each function, the processes that have that function in their call stack. As in the Psets window, the processes are represented as bitmaps of cells, with numbering starting at the upper left, increasing from left to right and then jumping to the next row.

If your Where graph displays a threaded program, you can zoom in to the level shown in FIGURE 4-9.

 FIGURE 4-8 Where Graph, Zoomed In

Zooming in another level shows all arguments for all processes.

 FIGURE 4-9 Where Graph of a Threaded Program, Zoomed in to Show Thread Stripes

Shift-click on the individual stripes.

This displays information about the corresponding threads.

You can shrink selected portions of the Where graph. This is useful if you want to see the overall structure of the graph but also want to focus on certain functions.

Perform one of the following:

• Middle-click on a function to iconify it and all of its children. Middle-click on an iconified function to re-expand it and its children to the current zoom level.
• Alternatively, you can click on the (De)iconify Node button next to the Zoom arrows at the top of the Where graph. This changes the mouse pointer to a target. You can then left-click on a function to iconify it and its children. If it is already iconified, left-clicking on it will re-expand it and its children. To cancel the operation, left-click anywhere outside of the boxes surrounding the functions.

When you first display the Where graph, the main function is highlighted.

Left-click on a function to highlight it. Or, move through the Where graph using the keyboard:

• Use the up arrow key to move to the parent of the highlighted function.
• If line numbers are visible in the highlighted function, by default the leftmost number is selected by having a box drawn around it. Use the left and right arrows to select other line numbers in the function. You can then use the down arrow key to highlight the function called at the selected line.

Press the spacebar while in the Where graph.

The following actions occur:

• The current function changes to the function that is highlighted in the Where graph.
• The highlighted function in the source window is displayed.
• A new current pset is created, with the same name as the function and containing the processes with this function in their call stack. The current process of this current set is the lowest-numbered process in the set.

---

Combining Debug and Optimization Options

When you use the Prism environment on programs that have been compiled with optimization options, Prism commands behave differently and the visibility of variables in the optimized programs changes.

Interpreting Interaction Between an Optimized Program and the Prism Environment

When the control flow is inside a routine that has been compiled with both -g and an optimization option (a debuggable optimized routine), the next and step commands change their behavior:

• next steps out of the current routine and stops in the next debuggable routine that differs from the original routine.
• step stops in the next debuggable routine (including recursive calls of the original routine).

You can set breakpoints using the stop at command inside debuggable optimized routines only at the first line of such a routine. If the routine name is foo and the first instruction in foo is ADDR_INSTR, then the breakpoint is set as if you had used stop in foo or stopi at ADDR_INSTR.

Note that the following commands are unaffected:

• nexti
• stepi
• stopi

When either return or stepout is used to return control flow to a debuggable optimized routine, the Prism environment assumes that the current position is at the first line of the current routine. The Prism environment makes the same assumption when the source file position is updated as a result of up or down commands that result in a debuggable optimized routine.

Accessing Variables in Optimized Routines

Due to the effects of optimization on variable locations in executable programs that have been compiled with optimization, the Prism environment cannot access all variables at all times.

The accessibility of variables can be defined by whether the variables can be used in expressions that require the right value of the variable (such as print X or call foo(X)) or the left value of the variable (such as assign X=1).

The limits of accessibility can be described by the flow of control in an optimized program. When the flow of control is in a routine compiled with both -g and an optimization flag, the following conditions apply:

• If the control flow is at the first machine instruction of the routine (which has not yet been executed), then all global variables and the routine's arguments are accessible. No other local variable is accessible.
• If the first machine instruction of the current routine has already been executed, then only the global variables are accessible. No local variable is accessible.

The following commands can use only accessible variables:

• assign
• call
• display
• dump
• print
• trace
• tracei
• varsave
• when
• where

The where command reports all active stack frames that have a stack pointer. The where command does not report routines that have no frame pointer and routines that have been inlined.

---

Debugging Spawned Sun MPI Processes

When debugging Sun MPI jobs that spawn other Sun MPI jobs, you should be especially careful to ensure that Sun MPI or Prism processes do not exit while other processes depend on communicating with them.

For example, suppose MPI job foo spawns MPI job bar, job foo uses MPI_Send to communicate with a process in job bar,and job bar uses MPI_Recv to handle a message from job foo.

If you are debugging both jobs in the Prism environment and you issue the Prism quit command in the primary Prism session (foo) before the process in foo calls the MPI_Send function, then job foo will exit. However, bar (which you are still debugging in a secondary Prism session) cannot continue past the MPI_Recv call, because foo has already exited.

If you issue a quit -all command in the primary Prism session while debugging a job that has many deeply nested MPI_Comm_spawn calls, it may not terminate all spawned secondary Prism sessions. To terminate a secondary debug session, you must manually issue the quit command in the secondary Prism session(s).

Debugging Spawned Sessions Using the Commands-Only Interface

When the Prism environment is started with the -CX option, it opens new X terminal windows in response to the spawning of new processes. It labels a new window with the title aout:jid, where jid is the job ID of the spawned process.

You must set the DISPLAY variable if you debug programs with calls to MPI_Comm_spawn() or MPI_Comm_spawn_multiple(), even when launching the Prism environment with the commands-only interface. For more information about the commands-only interface, see Appendix A.

Prism Commands With Special Functions in Spawned Sessions

Several Prism commands perform special functions in spawned Prism sessions.

• attach - The Prism attach command enables you to attach to an executable without issuing a prior load command. You can simply attach to the process ID or job ID, as follows:

(prism all) attach jid

The attach command will clean up the current session before attaching to the jid (job ID) specified in the command.

The attach command does not accept multiple job IDs.

However, if the specified job ID is a result of an MPI_Comm_spawn_multiple(), multiple Prism sessions get created.

• detach - The detach command only applies to the Prism session where it is invoked. If you issue the detach command in a primary session, it is not propagated down to secondary sessions.
• run and rerun - When you issue the run or rerun commands in the primary Prism session, the Prism environment will clean up all the secondary Prism sessions. That is, the Prism environment will shut down the secondary Prism sessions and the debuggees.

The run and rerun commands are not valid in the secondary Prism sessions.

• kill - If you issue a kill command in a primary Prism session, the command propagates to the secondary Prism sessions. That is, the Prism environment shuts down the secondary Prism sessions and the debuggees.
• quit - The quit command does not propagate down to the secondary sessions unless you issue the command with the -all option.

To quit all Prism sessions, you must type:

(prism all) quit -all

If the job was run by the primary Prism session, the command quit -all kills the debuggees in the primary as well as the secondary Prism sessions and close all the Prism sessions.

If you attached to the job in the primary Prism session, quit -all leaves the debuggees running and close all the Prism sessions.

The -all option is valid only in the primary Prism session.

For convenience, you can add the quit command with the -all option to the tear-off region of the Prism graphical interface. For example,

(prism all) pushbutton quitall "quit -all"

This creates a button labeled quitall in the tear-off region.

Error Conditions Arising From Spawned Sessions

TABLE 4-1 lists and explains error messages that may be displayed when error conditions are encountered in debugging spawned processes.

For more information about using the Prism environment with Sun MPI programs that issue calls to MPI_Comm_spawn() or MPI_Comm_spawn_multiple(), see Enabling Support for Spawned MPI Processes.

---

Examining the Contents of Memory and Registers

You can issue commands in the command window to display the contents of memory addresses and registers.

Specify the address on the command line, followed by a slash (/).

The following displays the memory contents at address 10000 (hex).

(prism all) 0x10000/

If you specify the address as a period, the Prism environment displays the contents of the memory address immediately following the one printed most recently.

Specify a symbolic address by preceding the name with an &. For example, this prints the contents of memory for variable x:

(prism all) &x/

The address you specify can be an expression made up of other addresses and the operators +, -, and indirection (unary *). For example, this prints the contents of the location 100 addresses above address 0x1000:

(prism all) 0x1000+100/

After the slash you can specify how memory is to be displayed. TABLE 4-2 lists the supported memory address formats.

d 

D

o

O

x

X

b

c

s

f 

F 

i 

The initial format is X. If you omit the format in your command, you get either X (if you haven't previously specified a format) or the format you specified previously.

You can print the contents of multiple addresses by specifying a number after the slash (and before the format). For example, this displays the contents of eight memory locations starting at address 0x1000:

(prism all) 0x1000/8X

These contents are displayed as hexadecimal long words.

You can examine the contents of registers in the same way that you examine the contents of memory.

Specify a register by preceding its name with a dollar sign.

For example, this prints the contents of the f0 register:

(prism all) $f0/

Specify a number after the slash to print the contents of multiple registers. For example, this prints the contents of registers f0, f1, and f2:

(prism all) $f0/3

The order in which the registers are displayed is that shown in TABLE 4-3.

You can also specify a format, as described above. The format specifier controls the display of the output; it doesn't affect how much of the register contents is displayed. Thus, this displays three registers:

$f0/3X

The output is displayed as hexadecimal longwords. The following table shows the names and descriptions of UltraSPARC registers