hpcstruct:
Recovery of Static Program Structure

The HPCToolkit Performance Tools

2018/07/05

Version 2020.03.01-release

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
• 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 code structure to its object code. By default, hpcstruct writes its results to the file basename(binary).hpcstruct. This file is typically passed to HPCToolkit's attribution tool hpcprof(1) .

hpcstruct is designed to handle highly optimized binaries created from C, C++ and Fortran source code. Because hpcstruct's algorithms exploit a binary's debugging information, binary should be compiled with options to produce as much debugging information as possible.

Arguments

binary

File containing a binary executable or dynamically linked library. Note that hpcstruct does not recover program structure for libraries that binary depends on. To recover that structure, 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]

Print debugging messages at debug level n. {1}

--debug-proc glob

Print debugging messages for structure recovery of procedures matching the shell glob glob.

Options: Structure recovery

--demangle-library libpath

Use a function from the library at libpath to demangle C++ names. By default the library function used is __cxa_demangle. A different function may be specified with the --demangle-function option.

--demangle-function funcname

Call the function named funcname in the specified demangler library to demangle C++ names. This option may only be given if the --demangle-library option is also given.

-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/+. This option may appear multiple times.

-R 'old-path=new-path', --replace-path 'old-path=new-path'

Replace instances of old-path with new-path in all paths with old-path is a prefix (e.g., a profile's load map and source code). Use '\' to escape instances of '=' within specified paths. This option may appear multiple times.

Use this when a profile or executable references 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 by eliminating extra white space.

--show-gaps

Write a text file describing all the "gaps" found by hpcstruct, i.e. address regions not identified as belonging to a code or data segment by the ParseAPI parser used to analyze application executables. The file is named outfile.gaps, which by default is appname.hpcstruct.gaps. A gaps file can't be written when outfile is stdout.

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) . To do this, execute:

    hpcstruct sweep3dsingle

By defult the output is placed in a file named sweep3dsingle.hpcstruct.

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
   • IBM compilers: -g -fstandalone-debug -qfulldebug -qfullpath
   • 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.

See Also

hpctoolkit(1) .

Version

Version: 2020.03.01-release

License and Copyright

Copyright

© 2002-2020, Rice University.

License

See README.License.

Authors

Rice University's HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.

Thanks to Gabriel Marin and Jason Eckhardt.