hpcstruct:
Recovery of Static Program Structure
The HPCToolkit Performance Tools
2011/02/22
Version 2017.10
hpcstruct
recovers the static program structure of fully optimized
object code for use with an HPCToolkit
correlation tool.
In particular, hpcstruct,
recovers source code procedures and loop nests, detects inlining, and associates procedures and loops with object code addresses.
See hpctoolkit(1)
for an overview of HPCToolkit.
Table of Contents
hpcstruct
[options]
binary
Typical usage:
hpcstruct
binary
which creates basename(binary).hpcstruct.
Given an application binary or DSO binary,
hpcstruct
recovers the program structure of its object code.
Program structure is a mapping of a program's static source-level structure to its object code.
By default, hpcstruct
writes its results to the file basename().hpcstruct.
This file is typically passed to HPCToolkit's
correlation tool, hpcprof(1)
or hpcprof-flat(1)
.
hpcstruct
is designed primarily for highly optimized binaries created from C, C++ and Fortran source code.
Because hpcstruct's
algorithms exploit a binary's debugging information, for best results, binary
should be compiled with standard debugging information.
- binary
- An executable binary or dynamically linked library.
Note that hpcstruct
does not recover program structure for libraries that binary
depends on. To create such information, run hpcstruct on each dynamically linked library (or relink your program with static versions of the libraries).
Default values for an option's optional arguments are shown in {}.
- -v [n], --verbose [n]
-
Verbose: generate progress messages to stderr at verbosity level n.
{1}
- -V, --version
-
Print version information.
- -h, --help
-
Print help.
- --debug [n]
-
Debug: use debug level n.
{1}
- --debug-proc glob
-
Debug structure recovery for procedures matching the procedure glob glob.
- -I path, --include path
-
Use path
when resolving source file names.
This option is useful when a compiler records the same filename in different
ways within the symbolic information.
(Yes, this does happen.)
For a recursive search, append a '+' after the last slash, e.g., /mypath/+.
May pass multiple times.
- --loop-intvl yes|no
-
Should loop recovery heuristics assume an irreducible interval is a loop? {yes}.
- --loop-fwd-subst yes|no
-
Should loop recovery heuristics assume forward substitution may occur? {yes}.
- -N all|safe|none, --normalize all|safe|none
-
Specify normalizations to apply to program structure. {all}
- all: apply all normalizations
- safe: apply only safe normalizations
- none: apply no normalizations
- -R 'old-path=new-path', --replace-path 'old-path=new-path'
-
Substitute instances of old-path
with new-path;
apply to all paths (e.g., a profile's load map and source code) for which old-path
is a prefix. Use '
'to escape instances of '=' within a path. May pass multiple times.
Use this option when a profile or binary contains references to files that have been relocated, such as might occur with a file system change.
- -o file, --output file
-
Write results to file.
Use `-' for stdout.
{basename(binary).hpcstruct}
- --compact
-
Generate compact output, eliminating extra white space.
Assume we have collected profiling information for the (optimized) binary sweep3dsingle,
compiled with debugging information.
We wish to recover program structure in the file sweep3dsingle.hpcstruct
for use with hpcprof(1)
or hpcprof-flat(1)
.
To do this, execute:
hpcstruct sweep3dsingle
- For best results, an application binary should be compiled with debugging information.
To generate debugging information while also enabling optimizations, use the appropriate variant of -g for the following compilers:
- GNU compilers: -g
- Intel compilers: -g -debug inline_debug_info
- PathScale compilers: -g
- PGI compilers: -gopt
- While hpcstruct attempts to guard against inaccurate debugging information, some compilers (notably PGI's) often generate invalid and inconsistent debugging information.
Garbage in; garbage out.
- C++ mangling is compiler specific. On non-GNU platforms, hpcstruct
tries both platform's and GNU's demangler.
- hpcstruct may incorrectly infer the structure of loops contained within switch statements.
When reconstructing the control flow graph (CFG) of the object code, hpcstruct
currently ignores indirect jumps and does not add edges from the jump to possible target basic blocks.
The result is an incomplete CFG and a misleading loop nesting tree.
The workaround is to use an if/elseif/else statement.
hpctoolkit(1)
.
Version: 2017.10 of 2011/02/22.
- Copyright
- © 2002-2017, Rice University.
- License
- See README.License.
Nathan Tallent
John Mellor-Crummey
Rob Fowler
Rice HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.
Thanks to Gabriel Marin and Jason Eckhardt.