hpcstruct:
Recovery of Static Program Structure

The HPCToolkit Performance Tools

2011/02/22

Version 2017.11

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

• Synopsis
• Description
• Arguments
  • Options: Informational
  • Options: Structure recovery
  • Options: Output
• Examples
• Notes
• Bugs
• See Also
• Version
• License and Copyright
• Authors

Synopsis

hpcstruct [options] binary

Typical usage:
      hpcstruct binary
which creates basename(binary).hpcstruct.

Description

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.

Arguments

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 {}.

Options: Informational

-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.

Options: Structure recovery

-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.

Options: Output

-o file, --output file

Write results to file. Use `-' for stdout. {basename(binary).hpcstruct}

--compact

Generate compact output, eliminating extra white space.

Examples

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

Notes

1. 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

2. 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.

3. C++ mangling is compiler specific. On non-GNU platforms, hpcstruct tries both platform's and GNU's demangler.

Bugs

1. 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.

See Also

hpctoolkit(1) .

Version

Version: 2017.11 of 2011/02/22.

License and Copyright

Copyright

© 2002-2018, Rice University.

License

See README.License.

Authors

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.