| .TH OPANNOTATE 1 "@DATE@" "oprofile @VERSION@" |
| .UC 4 |
| .SH NAME |
| opannotate \- produce source or assembly annotated with profile data |
| .SH SYNOPSIS |
| .br |
| .B opannotate |
| [ |
| .I options |
| ] |
| [profile specification] |
| .SH DESCRIPTION |
| |
| .B opannotate |
| outputs annotated source and/or assembly from profile data of an OProfile |
| session. See oprofile(1) for how to write profile specifications. |
| |
| .SH OPTIONS |
| .TP |
| .BI "--assembly / -a" |
| Output annotated assembly. The binary file to be annotated does not need full debugging |
| information to use this option, but symbol information |
| .I is |
| required. Without symbol information, |
| .B opannotate |
| will silently refuse to annotate the binary. |
| If this option is combined with --source, then mixed |
| source / assembly annotations are output. |
| .br |
| .TP |
| .BI "--demangle / -D none|smart|normal" |
| none: no demangling. normal: use default demangler (default) smart: use |
| pattern-matching to make C++ symbol demangling more readable. |
| .br |
| .TP |
| .BI "--exclude-dependent / -x" |
| Do not include application-specific images for libraries, kernel modules |
| and the kernel. This option only makes sense if the profile session |
| used --separate. |
| .br |
| .TP |
| .BI "--exclude-file [files]" |
| Exclude all files in the given comma-separated list of glob patterns. |
| .br |
| .TP |
| .BI "--exclude-symbols / -e [symbols]" |
| Exclude all the symbols in the given comma-separated list. |
| .br |
| .TP |
| .BI "--help / -? / --usage" |
| Show help message. |
| .br |
| .TP |
| .BI "--image-path / -p [paths]" |
| Comma-separated list of additional paths to search for binaries. |
| This is needed to find modules in kernels 2.6 and upwards. |
| .br |
| .TP |
| .BI "--root / -R [path]" |
| A path to a filesystem to search for additional binaries. |
| .br |
| .TP |
| .BI "--include-file [files]" |
| Only include files in the given comma-separated list of glob patterns. |
| .br |
| .TP |
| .BI "--merge / -m [lib,cpu,tid,tgid,unitmask,all]" |
| Merge any profiles separated in a --separate session. |
| .br |
| .TP |
| .BI "--include-symbols / -i [symbols]" |
| Only include symbols in the given comma-separated list. |
| .br |
| .TP |
| .BI "--objdump-params [params]" |
| Pass the given parameters as extra values when calling objdump. If more than |
| one option is to be passed to objdump, the parameters must be enclosed in a |
| quoted string. |
| |
| An example of where this option is useful is when your toolchain does not |
| automatically recognize instructions that are specific to your processor. |
| For example, on IBM POWER7/RHEL 6, objdump must be told that a binary file may have |
| POWER7-specific instructions. The opannotate option to show the POWER7-specific |
| instructions is: |
| --objdump-params=-Mpower7 |
| |
| The opannotate option to show the POWER7-specific instructions, |
| the source code (--source) and the line numbers (-l) would be: |
| --objdump-params="-Mpower7 -l --source" |
| |
| .br |
| .TP |
| .BI "--output-dir / -o [dir]" |
| Output directory. This makes opannotate output one annotated file for each |
| source file. This option can't be used in conjunction with --assembly. |
| .br |
| .TP |
| .BI "--search-dirs / -d [paths]" |
| Comma-separated list of paths to search for source files. You may need to use |
| this option when the debug information for an image contains relative paths. |
| .br |
| .TP |
| .BI "--base-dirs / -b [paths]" |
| Comma-separated list of paths to strip from debug source files, prior to |
| looking for them in --search-dirs. |
| .br |
| .TP |
| .BI "--session-dir="dir_path |
| Use sample database from the specified directory |
| .I dir_path |
| instead of the default locations. If |
| .I --session-dir |
| is not specified, then |
| .B opannotate |
| will search for samples in |
| .I <current_dir>/oprofile_data |
| first. If that directory does not exist, the standard session-dir of /var/lib/oprofile is used. |
| .br |
| .TP |
| .BI "--source / -s" |
| Output annotated source. This requires debugging information to be available |
| for the binaries. |
| .br |
| .TP |
| .BI "--threshold / -t [percentage]" |
| Only output data for symbols that have more than the given percentage |
| of total samples. |
| .br |
| .TP |
| .BI "--verbose / -V [options]" |
| Give verbose debugging output. |
| .br |
| .TP |
| .BI "--version / -v" |
| Show version. |
| |
| .SH ENVIRONMENT |
| No special environment variables are recognised by opannotate. |
| |
| .SH FILES |
| .I <current_dir>/oprofile_data/samples |
| .RS 7 |
| Or |
| .RE |
| .I /var/lib/oprofile/samples/ |
| .LP |
| .RS 7 |
| The location of the generated sample files. |
| .RE |
| |
| .SH VERSION |
| .TP |
| This man page is current for @PACKAGE@-@VERSION@. |
| |
| .SH SEE ALSO |
| .BR @OP_DOCDIR@, |
| .BR oprofile(1) |