opannotate(1)

1OPANNOTATE(1)               General Commands Manual              OPANNOTATE(1)
2
3
4

NAME

6       opannotate - produce source or assembly annotated with profile data
7

SYNOPSIS

9       opannotate [ options ] [profile specification]
10

DESCRIPTION

12       opannotate  outputs  annotated source and/or assembly from profile data
13       of an OProfile session. See oprofile(1) for how to write profile speci‐
14       fications.
15
16

OPTIONS

18       --assembly / -a
19              Output  annotated assembly. The binary file to be annotated does
20              not need full debugging information to use this option, but sym‐
21              bol information is required. Without symbol information, opanno‐
22              tate will silently refuse  to  annotate  the  binary.   If  this
23              option  is  combined with --source, then mixed source / assembly
24              annotations are output.
25
26       --demangle / -D none|smart|normal
27              none: no demangling. normal:  use  default  demangler  (default)
28              smart:  use  pattern-matching to make C++ symbol demangling more
29              readable.
30
31       --exclude-dependent / -x
32              Do not include application-specific images for libraries, kernel
33              modules and the kernel. This option only makes sense if the pro‐
34              file session used --separate.
35
36       --exclude-file [files]
37              Exclude all files in the given comma-separated list of glob pat‐
38              terns. This option is supported solely with the --source option.
39              It can be used to filter out source files in  the  output  using
40              the following types of specifications:
41
42              · filenames (basename -- i.e., no path)
43
44              · filename  glob  specifications  (all files whose base filename
45                matches the given pattern)
46
47              · directory segments (all source files located in the  specified
48                directory; e.g. "libio")
49
50              · directory segment glob specifications (e.g., "libi*")
51
52       --exclude-symbols / -e [symbols]
53              Exclude all the symbols in the given comma-separated list.
54
55       --help / -? / --usage
56              Show help message.
57
58       --image-path / -p [paths]
59              Comma-separated list of additional paths to search for binaries.
60              This is needed to find modules in kernels 2.6 and upwards.
61
62       --root / -R [path]
63              A path to a filesystem to search for additional binaries.
64
65       --include-file [files]
66              Only include files in the given  comma-separated  list  of  glob
67              patterns.   The  same  rules  apply  for  this option as for the
68              --exclude-file option.
69
70       --merge / -m [lib,cpu,tid,tgid,unitmask,all]
71              Merge any profiles separated in a --separate session.
72
73       --include-symbols / -i [symbols]
74              Only include symbols in the given comma-separated list.
75
76       --objdump-params [params]
77              Pass the given parameters as extra values when calling  objdump.
78              If  more than one option is to be passed to objdump, the parame‐
79              ters must be enclosed in a quoted string.
80
81              An example of where this option is useful is when your toolchain
82              does  not automatically recognize instructions that are specific
83              to your processor.  For example, on IBM POWER7/RHEL  6,  objdump
84              must  be  told  that  a  binary  file  may  have POWER7-specific
85              instructions. The opannotate option to show the  POWER7-specific
86              instructions is:
87                 --objdump-params=-Mpower7
88
89              The  opannotate option to show the POWER7-specific instructions,
90              the source code (--source) and the line numbers (-l) would be:
91                 --objdump-params="-Mpower7 -l --source"
92
93
94       --output-dir / -o [dir]
95              Output directory. This makes  opannotate  output  one  annotated
96              file for each source file. This option can't be used in conjunc‐
97              tion with --assembly.
98
99       --search-dirs / -d [paths]
100              Comma-separated list of paths to search for  source  files.  You
101              may  need  to  use this option when the debug information for an
102              image contains relative paths.
103
104       --base-dirs / -b [paths]
105              Comma-separated list of paths to strip from debug source  files,
106              prior to looking for them in --search-dirs.
107
108       --session-dir=dir_path
109              Use  sample  database  from  the  specified  directory  dir_path
110              instead of the default location. If --session-dir is not  speci‐
111              fied,   then   opannotate  will  search  for  samples  in  <cur‐
112              rent_dir>/oprofile_data first. If that directory does not exist,
113              the standard session-dir of /var/lib/oprofile is used.
114
115       --source / -s
116              Output  annotated source. This requires debugging information to
117              be available for the binaries.
118
119       --threshold / -t [percentage]
120              For annotated assembly, only output data for symbols  that  have
121              more  than  the  given percentage of total samples. For profiles
122              using multiple events, if  the  threshold  is  reached  for  any
123              event, then all sample data for the symbol is shown.
124
125              For  annotated  source,  only  output data for source files that
126              have more than the given percentage of total samples.  For  pro‐
127              files using multiple events, if the threshold is reached for any
128              event, then all sample data for the source file is shown.
129
130       --verbose / -V [options]
131              Give verbose debugging output.
132
133       --version / -v
134              Show version.
135
136

ENVIRONMENT

138       No special environment variables are recognised by opannotate.
139
140

FILES

142       <session_dir>/samples
143              The location of the generated sample files.
144
145

VERSION

147       This man page is current for oprofile-1.3.0.
148
149