Name

report — generate a report from a sample file

Synopsis

report [-h, --help] [--version] [--verbose] -i, --in-file FILENAME [-t, --title TITLE] [-o, --report NAME]
[-s, --source-dir DIRECTORY...] [-D, --debug-dir DIRECTORY...] [-b, --binary BINARY...] [--debug-symbol-level LEVEL] [--c++filt[=FILTER]]
[-p, --percent PERCENT] [-d, --depth FRAMES] [--new-hwpf-algorithm]
[--cpu CPU] [--number-of-cpus NUM] [--level LEVEL]
[-c, --cache-size SIZE] [-l, --line-size SIZE] [-r, --replacement POLICY] [-n, --number-of-caches NUM]

Description

report generates a report based on an existing sample file.

Options

-h, --help

Print help message.

--version

Print version information.

--verbose

Show which filenames are tried when searching for debug information and source code.

-i, --in-file FILENAME

Specifies the input file.

-t, --title TITLE

Title of report.

-o, --report NAME

Name of the generated report file, defaults to report.tsr.

-s, --source-dir DIRECTORY

Additional directories to look for source code in.

-D, --debug-dir DIRECTORY

Additional directories to look for external debug information in. The report tool will by default look in the system global debug directory (/usr/lib/debug), the .debug directory in the same directory as the binary and the same directory as the binary.

-b, --binary BINARY

Specifies an additional binary containing debug information to use if the sampled binary with the same file name can not be found.

--debug-symbol-level

(experimental) Balance debug symbol detail and processing speed.

0

no debug symbols

1

line number

2

line number and public symbols

3

full debug info (default)

--c++-filt[=FILTER]

Specify an external symbol demangler program to translate the symbols for presentation. Useful for c++ code compiled with the 'stabs' debugging format.

If --c++filt is given without a program, the external program c++filt is used.

If --c++filt=FILTER is specified, use the program FILTER.

Default is to not translate symbols.

-p, --percent PERCENT

Percent of total fetches, upgrades or write-backs required for advice to be reported. The default is 1.

-d, --depth FRAMES

Stack depth to use for separating issues caused by different calls to the same function. Default 1. Use 0 to merge all different call paths into a function for analysis.

--new-hwpf-algorithm

Use a new experimental version of the hardware prefetch analysis algorithm, that more diligently captures complex patterns. It consumes more memory and takes longer for some input sets than the default algorithm.

--cpu CPU

Selects the processor model to use in the analysis. CPU is specified as vendor-id/cpu-id. Default is to 'auto'.

The following special processor models are defined:

help

Lists available processor models.

auto

Auto-detects the processor model of the computer the report is being generated on.

--number-of-cpus NUM

Number of physical processors to include in the analysis. Each physical processor may have multiple logical processors (cores/threads). The special value '0' may be used to indicate that auto-detection should be used, which is also the default.

--level LEVEL

Selects the cache level to analyze. The number of available cache levels depend on the selected processor model. Default is to analyze the highest cache level.

-c, --cache-size SIZE

Overrides the cache size specified in the processor model.

-l, --line-size SIZE

Overrides the cache line size specified in the processor model. Must be power of two.

-r, --replacement POLICY

Cache replacement policy. Must be 'random' or 'lru'. The default is 'random'.

-n, --number-of-caches NUM

Total number of caches to assign threads to. Should match the number of caches of the desired cache level for the intended processor/architecture. Default: Determined by the processor model, cache level and the number of physical processors.

The special value '0' may be used to assign one private cache to each thread in the application.

Examples

Example 8. Analyzing sample files using autodetected CPU models

Perform an analysis of sample.smp for the currently running processor on cache level 2:

$ report --level 2 -i sample.smp

The report tool will create a report file named report.tsr by default.


Example 9. Specifying a CPU model

If you are running a different processor than you are analyzing for, you may specify the --cpu model option.

First, use --cpu help to get a list of available CPUs.

$ report --cpu help

Find the processor you want to perform analysis for, for example the Intel Quad-Core Xeon E5345 which has the model name 'clowertown_4_8'.

Use the manufacturer name together with the model name like this when calling report:

$ report --cpu intel/clovertown_4_8 -i sample.smp


Exit Status

0

Successful program execution.

>0

An error occured.

Environment

RW_LICENSE_FILE

Environment variable pointing to the license file. Should only be used to override default license locations.

Files

$HOME/.threadspotter/license

Directory containing per-user license files. ThreadSpotter looks for license files here if no system wide license file can be found.