hpcstruct:
Recovery of Static Program Structure

The HPCToolkit Performance Tools

2021/09/15

Version 2024.01.1-release

hpcstruct - recovers the static program structure of CPU or GPU binaries, as cited in a recorded measurements directory, or in a single CPU or GPU binary. A binary's static structure includes information about source files, procedures, inlined functions, loops, and source lines.

See hpctoolkit(1) for an overview of HPCToolkit.

Table of Contents

• Synopsis
• Description
• Arguments
  • Options: Informational
  • Options: Using the Cache
  • Options: Override parallel defaults
  • Options: override structure recovery defaults
  • Options to control output:
  • Options for Developers:
  • Options for internal use only
• Examples
• Notes
• See Also
• Version
• License and Copyright
• Authors

Synopsis

hpcstruct [options] measurement-directory

hpcstruct [options] binary

Description

hpcstruct generates a program structure file for each CPU and GPU binary referenced by a directory containing HPCToolkit performance measurements. hpcstruct is usually applied to an application's HPCToolkit measurement-directory, directing it to analyze all CPU and GPU binaries measured during an execution. Although not normally needed, one can apply hpcstruct to recover program structure for an individual CPU or GPU binary.

Program structure is a mapping from addresses of machine instructions in a binary to source code contexts; this mapping is used to attribute measured performance metrics back to source code. A strength of hpcstruct is its ability to attribute metrics to inlined functions and loops; such mappings are especially useful for understanding the performance of programs generated using template-based programming models. When hpcprof is invoked on a measurement-directory that contains program structure files, they will be used attribute performance measurements.

hpcstruct is designed to cache its results so that processing multiple measurement directories can copy previously generated structure files from the cache rather than regenerating the information. A cache may be specified either on the command line (see the -C option, below) or by setting the HPCTOOLKIT_HPCSTRUCT_CACHE environment variable. If a cache is specified, hpcstruct emits a message for each binary processed saying one of "Added to cache", "Replaced in cache", "Copied from cache", or "Copied from cache +". The latter indicates that although the structure file was found in the cache, it came from an identical binary with a different full path, so it was edited to reflect the actual path. "Replaced in cache" indicates that a previous version at that path was replaced. If the --nocache option is set, hpcstruct will not use the cache, even if the environment variable is set, and the message will say "(Cache disabled by user)". If no cache is specified, the message will say "Cache not specified", and, unless the --nocache option was set, an ADVICE message urging use of the cache will be written. Users are strongly urged to use a cache.

When an application execution is measured using hpcrun, HPCToolkit records the name of the application binary, and the names of any shared-libraries and GPU binaries it used. As a GPU-accelerated application is measured, HPCToolkit also records the contents of any GPU binaries it loads in the application's measurement directory.

When analyzing a measurement-directory, hpcstruct writes its results into a subdirectory of the directory. It analyzes the application and all the shared libraries and GPU binaries used during the run. When rerun against a measurement-directory, hpcstruct will reprocess only those GPU binaries that were previously processed with a different --gpucfg setting.

To accelerate analysis of a measurement directory, which contains references to an application as well as any shared libraries and/or GPU binaries it uses, hpcstruct employs multiple threads by default. A pool of threads equal to half of the threads in the CPU set for the process is used. Binaries larger than a certain threshold (see the --psize option and its default) are analyzed using more OpenMP threads than those smaller than the threshold. Multiple binaries are processed concurrently. hpcstruct will describe the actual parallelization and concurrency used when the run starts.

When analyzing a single CPU or GPU binary b, hpcstruct writes its results to the file 'basename(b).hpcstruct' in the current directory. When rerun against a single binary, it will reprocess that binary and rewrite its structure file.

hpcstruct is designed for analysis of optimized binaries created from C, C++, Fortran, CUDA, HIP, and DPC++ source code. Because hpcstruct's algorithms exploit the line map and debug information recorded in an application binary during compilation, for best results, we recommend that binaries be compiled with standard debug information or at a minimum, line map information. Typically, this is accomplished by passing a '-g' option to each compiler along with any optimization flags. See the HPCToolkit manual for more information.

Arguments

measurement directory

A measurement directory of an application, either GPU-accelerated or not. Applying hpcstruct to a measurement directory analyzes the application as well as all shared libraries and GPU binaries measured during the data-collection run.

binary

File containing an executable, a dynamically-linked shared library, or a GPU binary recorded by HPCToolkit as a program executes. Note that hpcstruct does not recover program structure for libraries that binary depends on. To recover that structure, run hpcstruct on each dynamically-linked shared library or relink your program with static versions of the libraries. Invoking hpcstruct on a binary is normally not used.

Default values for an option's optional arguments are shown in {}.

Options: Informational

-V, --version

Print version information.

-h, --help

Print help message.

-v num, --verbose num

Generate progress messages to stderr, at verbosity level num. {1}

Options: Using the Cache