Developer Reference

  • 2020 Update 2
  • 07/15/2020
  • Public Content

gtool Options

-gtool
Use this option to launchsuch tools as Intel® VTune™ Amplifier XE, Intel® Advisor, Valgrind*, and GNU* Debugger (GDB*) for the specified processes through the
mpiexec.hydra
and
mpirun
commands. An alternative to this option is the
I_MPI_GTOOL
environment variable.

Syntax

-gtool "<command line for tool 1>:<ranks set 1>[=launch mode 1][@arch 1]; <command line for tool 2>:<ranks set 2>[=exclusive][@arch 2]; … ;<command line for a tool n>:<ranks set n>[=exclusive][@arch n]" <executable>
or:
$ mpirun -n <# of processes> -gtool "<command line for tool 1>:<ranks set 1>[=launch mode 1][@arch 1]" -gtool "<command line for a tool 2>:<ranks set 2>[=launch mode 2][@arch 2]" … -gtool "<command line for a tool n>:<ranks set n>[=launch mode 3][@arch n]" <executable>
In the syntax, the separator '
;
' and the
-gtool
option are interchangeable.

Arguments

<arg>
Parameters
<rank set>
Specify the range of ranks that are involved in the tool execution. Separate ranks with a comma or use the '
-
' symbol for a set of contiguous ranks. To run the tool for all ranks, use the
all
argument.
If you specify incorrect rank index, the corresponding warning is printed and the tool continues working for valid ranks.
[=launch mode]
Specify the launch mode (optional). See below for the available values.
[@arch]
Specify the architecture on which the tool runs (optional). For a given
<rank set>
, if you specify this argument, the tool is launched only for the processes residing on hosts with the specified architecture. This parameter is optional.
Rank sets cannot overlap for the same
@arch
parameter. Missing
@arch
parameter is also considered a different architecture. Thus, the following syntax is considered valid:
-gtool "gdb:0-3=attach;gdb:0-3=attach@hsw;/usr/bin/gdb:0-3=attach@knl"
Also, note that some tools cannot work together or their simultaneous use may lead to incorrect results.
The following table lists the parameter values for
[=launch mode]
:
[=launch mode]
Tool launch mode (optional). You can specify several values for each tool, which are separated with a comma '
,
'.
exclusive
Specify this value to prevent the tool from launching for more than one rank per host.
attach
Specify this value to attach the tool from
-gtool
to the executable. If you use debuggers or other tools that can attach to a process in a debugger manner, you need to specify this value. This mode has been tested with debuggers only.
node-wide
Specify this value to apply the tool from
-gtool
to all ranks where the
<rank set>
resides or for all nodes in the case of
all
ranks. That is, the tool is applied toa higher level than the executable (to the
pmi_proxy
daemon).
Use the
-remote
argument for ranks to use the tool on remote nodes only.
The tool attached to an MPI process may be executed without having access to stdin. To pass input to it, run a rank under the tool directly, for example:
-gtool "gdb --args:0"

Examples

The following examples demonstrate different scenarios of using the
-gtool
option.
Example 1
Launch the Intel® VTune™ Amplifier XE and Valgrind* through the
mpirun
command:
$ mpirun -n 16 -gtool "amplxe-cl -collect hotspots -analyze-system \ -r result1:5,3,7-9=exclusive@bdw;valgrind -log-file=log_%p:0,1,10-12@hsw" a.out
This command launches
amplxe-cl
for the processes that are run on the Intel® microarchitecture codenamed Broadwell. Only one copy of
amplxe-cl
is launched for each host, the process with the minimal index is affected. At the same time, Valgrind* is launched for all specified processes that are run on the Intel® microarchitecture codenamed Haswell. Valgrind's results are saved to the files
log_<process ID>
.
Example 2
Set different environment variables for different rank sets:
$ mpirun -n 16 -gtool "env VARIABLE1=value1 VARIABLE2=value2:3,5,7-9; env VARIABLE3=value3:0,11" a.out
Example 3
Apply a tool for a certain process through the
-machinefile
option.
In this example, suppose
m_file
has the following content:
$ cat ./m_file hostname_1:2 hostname_2:3 hostname_3:1
The following command line demonstrates how to use the
-machinefile
option to apply a tool:
$ mpirun -n 6 -machinefile m_file -gtool "amplxe-cl -collect hotspots -analyze-system \ -r result1:5,3=exclusive@hsw;valgrind:0,1@bdw" a.out
In this example, the use of
-machinefie
option means that processes with indices
0
and
1
are located on the
hostname_1
machine, process
3
is located on the
hostname_2
machine, and process
5
- on the
hostname_3
machine. After that,
amplxe-cl
is applied only ranks
3
and
5
(since these ranks belong to different machines, the
exclusive
option matches both of them) in case if
hostname_2
and
hostname_3
machines have Intel® microarchitecture codenamed Haswell. At the same time, the Valgrind* tool is applied to both ranks allocated on
hostname_1
machine in case if it has Intel® microarchitecture codenamed Broadwell.
-gtoolfile <gtool_config_file>
Use this option to specify the
-gtool
parameters in a configuration file. All the same rules apply. Additionally, you can separate different command lines with section breaks.
For example, if
gtool_config_file
contains the following settings:
env VARIABLE1=value1 VARIABLE2=value2:3,5,7-9; env VARIABLE3=value3:0,11 env VARIABLE4=value4:1,12
The following command sets
VARIABLE1
and
VARIABLE2
for processes 3, 5, 7, 8, and 9 and sets
VARIABLE3
for processes 0 and 11, while
VARIABLE4
is set for processes 1 and 12:
$ mpirun -n 16 -gtoolfile gtool_config_file a.out
The options and the environment variable
-gtool
,
-gtoolfile
and
I_MPI_GTOOL
are mutually exclusive. The options
-gtool
and
-gtoolfile
are of the same priority and have higher priority than
I_MPI_GTOOL
. The first specified option in a command line is effective and the second one is ignored. Therefore, use
I_MPI_GTOOL
if you do not specify
-gtool
or
-gtoolfile
.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804