dbx Functionality Available for OpenMP Code

In addition to the usual functionality for debugging multithreaded programs, dbx provides functionality for debugging an OpenMP program.

Single-stepping Into a Parallel Region

dbx can single step into a parallel region. Because a parallel region is outlined and called from the OpenMP runtime library, a single step of execution actually involves several layers of runtime library calls that are executed by threads created for this purpose. When you single step into the parallel region, the first thread that reaches the breakpoint causes the program to stop. This thread might be a slave thread rather than the master thread that initiated the stepping.

For example, refer to the Fortran code inHow Compilers Transform OpenMP Code, and assume that master thread t@1 is at line 10. You single step into line 12, and slave threads t@2, t@3, and t@4 are created to execute the runtime library calls. Thread t@3 reaches the breakpoint first and causes the program execution to stop. So the single step that was initiated by thread t@1ends on thread t@3.This behavior is different from normal stepping in which you are usually on the same thread after the single step as before.

Printing Variables and Expressions

dbx can print all shared, private, and thread-private variables. If you try to print a thread private variable outside of a parallel region, the master thread’s copy is printed. The whatis command prints data sharing attributes for shared and private variables within a parallel construction. It prints data sharing attributes for thread-private variables whether or not they are within a parallel construction. For example:

(dbx) whatis p_a
# OpenMP first and last private variable
int p_a;

The print -s expression command prints the value of expression expression for each thread in the current OpenMP parallel region if the expression contains private or thread private variables. For example:

(dbx) print -s p_a
thread t@3: p_a = 3
thread t@4: p_a = 3

If the expression does not contain any private or thread private variables, only one value is printed.

Printing Region and Thread Information

dbx can print a description of the current parallel region or a specified parallel region, including the parent region, parallel region id, team size (number of threads), and program location (program counter address). For example:

(dbx) omp_pr
parallel region 127283434369843201
    team size = 4
    source location = test.c:103
    parent = 127283430568755201

It can also print descriptions of all the parallel regions along the path from the current parallel region or specified parallel region to its root. For example:

(dbx) omp_pr -ancestors
parallel region 127283434369843201
    team size = 4
    source location = test.c:103
    parent = 127283430568755201

    parallel region 127283430568755201
        team size = 4
        source location = test.c:95
        parent = <no parent>

And it can print the whole parallel region tree. For example:

(dbx) omp_pr -tree
parallel region 127283430568755201
    team size = 4
    source location = test.c:95
    parent = <no parent>

    parallel region 127283434369843201
        team size = 4
        source location = test.c:103
        parent = 127283430568755201

For more information, see omp_pr Command.

dbx can print a description of the current task region or a specified task region, including the task region id, state (spawned, executing, waiting), executing thread, program location (program counter address), unfinished children, and parent. For example:

(dbx) omp_tr
task region 65540
    type = implicit
    state = executing
    executing thread = t@4
    source location == test.c:46
    unfinished children = 0
    parent = <no parent>

It can also print descriptions of all the task regions along the path from the current task region or specified task region to its root.

(dbx) omp_tr -ancestors
task region 196611
    type = implicit
    state = executing
    executing thread = t@3
    source location - test.c:103
    unfinished children = 0
    parent = 131075

    task region 131075
        type = implicit
        state = executing
        executing thread = t@3
        unfinished children = 0
        parent = <no parent>

And it can print the whole task region tree. For example:

(dbx) omp_tr -tree
task region 10
    type = implicit
    state = executing
    executing thread = t@10
    source location = test.c:103
    unfinished children = 0
    parent = <no parent>
task region 7
    type = implicit
    state = executing
    executing thread = t@7
    source location = test.c:103
    unfinished children = 0
    parent = <no parent>
task region 6
    type implicit
    state = executing
    executing thread = t@6
    source location = test.c:103
    unfinished children = 0
    parent = <o parent>
task region 196609
    type = implicit
    state = executing
    executing thread = t@1
    source location = test.c:95
    unfinished children = 0
    parent = <no parent>

    task region 262145
        type = implicit
        state = executing
        executing thread = t@1
        source location = test.c:103
        unfinished children - 0
        parent = 196609
 

For more information, see omp_tr Command.

dbx can print a description of the current loop, including the scheduling type (static, dynamic, guided, auto, or runtime), ordered or not, bounds, steps or strides, and number of iterations. For example:

(dbx) omp_loop
    ordered loop: no
    lower bound: 0
    upper bound: 3
    step: 1
    chunk: 1
    schedule type: static
    source location: test.c:49

For more information, see omp_loop Command.

dbx can print all the threads on the current team or the team of a specified parallel region. For example:

(dbx) omp_team
team members:
    0: t@1 state = in implicit barrier, task region = 262145
    1: t@6 state = in implicit barrier, task region = 6
    2: t@7 state = working, task region = 7
    3: t@10 state = in implicit barrier, task region = 10

For more information, see omp_team Command.

When you are debugging OpenMP code, the thread -info prints the OpenMP thread id, parallel region id, task region id, and OpenMP thread state, in addition to the usual information about the current or specified thread. For more information, see thread Command.

Serializing the Execution of a Parallel Region

dbx can serialize the execution of the next encountered parallel region for the current thread or for all threads in the current team. For more information, see omp_serialize Command.

Using Stack Traces

When execution is stopped in parallel region, a where command shows a stack trace that contains the outlined subroutine.

(dbx) where
current thread: t@4
=>[1] _$d1E48.main(), line 52 in "test.c"
  [2] _$p1I46.main(), line 48 in "test.c"

--- frames from parent thread ---
current thread: t@1
  [7] main(argc = 1, argv = 0xffffffff7fffec98), line 46 in "test.c"

The top frame on the stack is the frame of the outlined function. Even though the code is outlined, the source line number still maps back to 15.

When execution is stopped in a parallel region, a where command from a slave thread prints the master thread's stack trace if the relevant frames are still active. A where command from the master thread has a full traceback.

You can also determine how execution reached the breakpoint in a slave thread by first using the omp_team command to list all the threads in the current team, and then switching to the master thread (the thread with the OpenMP thread id 0) and getting a stack trace from that thread.

Using the dump Command

When execution is stopped in a parallel region, a dump command may print more than one copy of private variables. In the following example, the dump command prints two copies of the variable i:

[t@1 l@1]: dump
i = 1
sum = 0.0
a = ARRAY
i = 1000001

Two copies of variable i are printed because the outlined routine is implemented as a nested function of the hosting routine, and private variables are implemented as local variables of the outlined routine. Since a dump command prints all the variables in scope, both the i in hosting routine and the i in the outlined routine are displayed.

Using Events

dbx provides events you can use with the stop, when, and trace commands on your OpenMP code. For information about using events with these commands, see Setting Event Specifications.

Synchronization Events

omp_barrier [type] [state]

Tracks the event of a thread entering a barrier.

type can be:

• explicit , meaning track explicit barriers

• implicit, meaning track implicit barriers

If you do not specify type, then only explicit barriers are tracked.

state can be:

• enter, meaning report the event when any thread enters a barrier

• exit, meaning report the event when any thread exits a barrier

• all_entered, meaning report the event when all threads have entered a barrier

If you do not specify state, the default is all_entered.

If you specify enter or exit, you can include a thread id to specify tracking only for that thread.

omp_taskwait [state]

Tracks the event of a thread entering a taskwait.

state can be:

• enter, meaning report the event when a thread enters a taskwait

• exit , meaning report the event when all child tasks have finished

If you do not specify state, then exit is the default.

omp_ordered [state]

Tracks the event of a thread entering an ordered region.

state can be:

• begin, meaning report the event when an ordered region begins

• enter, meaning report the event when a thread enters a ordered region

• exit, meaning report the event when a thread exits an ordered region

If you do not specify state, then the default is enter.

omp_critical

Tracks the event of a thread entering a critical region.

omp_atomic [state]

Tracks the event of a thread entering an atomic region.

state can be:

• begin, meaning report the event when an atomic region begins

• exit, meaning report the event when a thread exits an atomic region

If you do not specify state, then the default is begin.

omp_flush

Tracks the event of a thread executing a flush.

Other Events

omp_task [state]

Tracks the creation and termination of tasks.

state can be:

• create, meaning report the event when a task has just been created and before its execution begins

• start, meaning report the event when a task starts its execution

• finish, meaning report the event when a task has finished its execution and is about to be terminated

If you do not specify state, the default is start.

omp_master

Tracks the event of the master thread entering the master region.

omp_single

Tracks the event of a thread entering a single region.