hpcstruct:
Recovery of Static Program Structure

The HPCToolkit Performance Tools

2018/07/05

Version 2020.06-develop

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: Parallel Usage
  • 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

hpcstruct analyzes an application binary or shared library for its loop structure and inline sequences. hpcstruct is designed to handle optimized binaries created from C, C++ and Fortran source code, including mixed code. Note: although the binary may be optimized, it must also be compiled with debug symbols for the results to be useful (normally -g flag).

By default, hpcstruct writes its results to the file basename(binary).hpcstruct. This file is then passed to hpcprof with the -S flag and may be used multiple times for several shared libraries.

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, --version

Print version information.

-h, --help

Print help message.

Options: Parallel Usage

-j num, --jobs num

Run hpcstruct with num threads.

--jobs-parse num

Use num threads for the parse phase of hpcstruct.

--time

Display the time and space usage per phase in hpcstruct.

Options: Structure recovery

--gpucfg yes/no

Compute loop nesting structure for GPU machine code. Currently, this applies only to NVIDIA CUDA binaries (cubins). Loop nesting structure is only useful with instruction-level measurements collected using PC sampling. {no}

-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. {basename(binary).hpcstruct}

--show-gaps

Developer option to 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.

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

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.