| 1 |
README for GPROF |
| 2 |
|
| 3 |
This is the GNU profiler. It is distributed with other "binary |
| 4 |
utilities" which should be in ../binutils. See ../binutils/README for |
| 5 |
more general notes, including where to send bug reports. |
| 6 |
|
| 7 |
This file documents the changes and new features available with this |
| 8 |
version of GNU gprof. |
| 9 |
|
| 10 |
* New Features |
| 11 |
|
| 12 |
o Long options |
| 13 |
|
| 14 |
o Supports generalized file format, without breaking backward compatibility: |
| 15 |
new file format supports basic-block execution counts and non-realtime |
| 16 |
histograms (see below) |
| 17 |
|
| 18 |
o Supports profiling at the line level: flat profiles, call-graph profiles, |
| 19 |
and execution-counts can all be displayed at a level that identifies |
| 20 |
individual lines rather than just functions |
| 21 |
|
| 22 |
o Test-coverage support (similar to Sun tcov program): source files |
| 23 |
can be annotated with the number of times a function was invoked |
| 24 |
or with the number of times each basic-block in a function was |
| 25 |
executed |
| 26 |
|
| 27 |
o Generalized histograms: not just execution-time, but arbitrary |
| 28 |
histograms are support (for example, performance counter based |
| 29 |
profiles) |
| 30 |
|
| 31 |
o Powerful mechanism to select data to be included/excluded from |
| 32 |
analysis and/or output |
| 33 |
|
| 34 |
o Support for DEC OSF/1 v3.0 |
| 35 |
|
| 36 |
o Full cross-platform profiling support: gprof uses BFD to support |
| 37 |
arbitrary, non-native object file formats and non-native byte-orders |
| 38 |
(this feature has not been tested yet) |
| 39 |
|
| 40 |
o In the call-graph function index, static function names are now |
| 41 |
printed together with the filename in which the function was defined |
| 42 |
(required bfd_find_nearest_line() support and symbolic debugging |
| 43 |
information to be present in the executable file) |
| 44 |
|
| 45 |
o Major overhaul of source code (compiles cleanly with -Wall, etc.) |
| 46 |
|
| 47 |
* Supported Platforms |
| 48 |
|
| 49 |
The current version is known to work on: |
| 50 |
|
| 51 |
o DEC OSF/1 v3.0 |
| 52 |
All features supported. |
| 53 |
|
| 54 |
o SunOS 4.1.x |
| 55 |
All features supported. |
| 56 |
|
| 57 |
o Solaris 2.3 |
| 58 |
Line-level profiling unsupported because bfd_find_nearest_line() |
| 59 |
is not fully implemented for Elf binaries. |
| 60 |
|
| 61 |
o HP-UX 9.01 |
| 62 |
Line-level profiling unsupported because bfd_find_nearest_line() |
| 63 |
is not fully implemented for SOM binaries. |
| 64 |
|
| 65 |
* Detailed Description |
| 66 |
|
| 67 |
** User Interface Changes |
| 68 |
|
| 69 |
The command-line interface is backwards compatible with earlier |
| 70 |
versions of GNU gprof and Berkeley gprof. The only exception is |
| 71 |
the option to delete arcs from the call graph. The old syntax |
| 72 |
was: |
| 73 |
|
| 74 |
-k fromname toname |
| 75 |
|
| 76 |
while the new syntax is: |
| 77 |
|
| 78 |
-k fromname/toname |
| 79 |
|
| 80 |
This change was necessary to be compatible with long-option parsing. |
| 81 |
Also, "fromname" and "toname" can now be arbitrary symspecs rather |
| 82 |
than just function names (see below for an explanation of symspecs). |
| 83 |
For example, option "-k gprof.c/" suppresses all arcs due to calls out |
| 84 |
of file "gprof.c". |
| 85 |
|
| 86 |
*** Sym Specs |
| 87 |
|
| 88 |
It is often necessary to apply gprof only to specific parts of a |
| 89 |
program. GNU gprof has a simple but powerful mechanism to achieve |
| 90 |
this. So called {\em symspecs\/} provide the foundation for this |
| 91 |
mechanism. A symspec selects the parts of a profiled program to which |
| 92 |
an operation should be applied to. The syntax of a symspec is |
| 93 |
simple: |
| 94 |
|
| 95 |
filename_containing_a_dot |
| 96 |
| funcname_not_containing_a_dot |
| 97 |
| linenumber |
| 98 |
| ( [ any_filename ] `:' ( any_funcname | linenumber ) ) |
| 99 |
|
| 100 |
Here are some examples: |
| 101 |
|
| 102 |
main.c Selects everything in file "main.c"---the |
| 103 |
dot in the string tells gprof to interpret |
| 104 |
the string as a filename, rather than as |
| 105 |
a function name. To select a file whose |
| 106 |
name does contain a dot, a trailing colon |
| 107 |
should be specified. For example, "odd:" is |
| 108 |
interpreted as the file named "odd". |
| 109 |
|
| 110 |
main Selects all functions named "main". Notice |
| 111 |
that there may be multiple instances of the |
| 112 |
same function name because some of the |
| 113 |
definitions may be local (i.e., static). |
| 114 |
Unless a function name is unique in a program, |
| 115 |
you must use the colon notation explained |
| 116 |
below to specify a function from a specific |
| 117 |
source file. Sometimes, functionnames contain |
| 118 |
dots. In such cases, it is necessary to |
| 119 |
add a leading colon to the name. For example, |
| 120 |
":.mul" selects function ".mul". |
| 121 |
|
| 122 |
main.c:main Selects function "main" in file "main.c". |
| 123 |
|
| 124 |
main.c:134 Selects line 134 in file "main.c". |
| 125 |
|
| 126 |
IMPLEMENTATION NOTE: The source code uses the type sym_id for symspecs. |
| 127 |
At some point, this probably ought to be changed to "sym_spec" to make |
| 128 |
reading the code easier. |
| 129 |
|
| 130 |
*** Long options |
| 131 |
|
| 132 |
GNU gprof now supports long options. The following is a list of all |
| 133 |
supported options. Options that are listed without description |
| 134 |
operate in the same manner as the corresponding option in older |
| 135 |
versions of gprof. |
| 136 |
|
| 137 |
Short Form: Long Form: |
| 138 |
----------- ---------- |
| 139 |
-l --line |
| 140 |
Request profiling at the line-level rather |
| 141 |
than just at the function level. Source |
| 142 |
lines are identified by symbols of the form: |
| 143 |
|
| 144 |
func (file:line) |
| 145 |
|
| 146 |
where "func" is the function name, "file" is the |
| 147 |
file name and "line" is the line-number that |
| 148 |
corresponds to the line. |
| 149 |
|
| 150 |
To work properly, the binary must contain symbolic |
| 151 |
debugging information. This means that the source |
| 152 |
have to be translated with option "-g" specified. |
| 153 |
Functions for which there is no symbolic debugging |
| 154 |
information available are treated as if "--line" |
| 155 |
had not been specified. However, the line number |
| 156 |
printed with such symbols is usually incorrect |
| 157 |
and should be ignored. |
| 158 |
|
| 159 |
-a --no-static |
| 160 |
-A[symspec] --annotated-source[=symspec] |
| 161 |
Request output in the form of annotated source |
| 162 |
files. If "symspec" is specified, print output only |
| 163 |
for symbols selected by "symspec". If the option |
| 164 |
is specified multiple times, annotated output is |
| 165 |
generated for the union of all symspecs. |
| 166 |
|
| 167 |
Examples: |
| 168 |
|
| 169 |
-A Prints annotated source for all |
| 170 |
source files. |
| 171 |
-Agprof.c Prints annotated source for file |
| 172 |
gprof.c. |
| 173 |
-Afoobar Prints annotated source for files |
| 174 |
containing a function named "foobar". |
| 175 |
The entire file will be printed, but |
| 176 |
only the function itself will be |
| 177 |
annotated with profile data. |
| 178 |
|
| 179 |
-J[symspec] --no-annotated-source[=symspec] |
| 180 |
Suppress annotated source output. If specified |
| 181 |
without argument, annotated output is suppressed |
| 182 |
completely. With an argument, annotated output |
| 183 |
is suppressed only for the symbols selected by |
| 184 |
"symspec". If the option is specified multiple |
| 185 |
times, annotated output is suppressed for the |
| 186 |
union of all symspecs. This option has lower |
| 187 |
precedence than --annotated-source |
| 188 |
|
| 189 |
-p[symspec] --flat-profile[=symspec] |
| 190 |
Request output in the form of a flat profile |
| 191 |
(unless any other output-style option is specified, |
| 192 |
this option is turned on by default). If |
| 193 |
"symspec" is specified, include only symbols |
| 194 |
selected by "symspec" in flat profile. If the |
| 195 |
option is specified multiple times, the flat |
| 196 |
profile includes symbols selected by the union |
| 197 |
of all symspecs. |
| 198 |
|
| 199 |
-P[symspec] --no-flat-profile[=symspec] |
| 200 |
Suppress output in the flat profile. If given |
| 201 |
without an argument, the flat profile is suppressed |
| 202 |
completely. If "symspec" is specified, suppress |
| 203 |
the selected symbols in the flat profile. If the |
| 204 |
option is specified multiple times, the union of |
| 205 |
the selected symbols is suppressed. This option |
| 206 |
has lower precedence than --flat-profile. |
| 207 |
|
| 208 |
-q[symspec] --graph[=symspec] |
| 209 |
Request output in the form of a call-graph |
| 210 |
(unless any other output-style option is specified, |
| 211 |
this option is turned on by default). If "symspec" |
| 212 |
is specified, include only symbols selected by |
| 213 |
"symspec" in the call-graph. If the option is |
| 214 |
specified multiple times, the call-graph includes |
| 215 |
symbols selected by the union of all symspecs. |
| 216 |
|
| 217 |
-Q[symspec] --no-graph[=symspec] |
| 218 |
Suppress output in the call-graph. If given without |
| 219 |
an argument, the call-graph is suppressed completely. |
| 220 |
With a "symspec", suppress the selected symbols |
| 221 |
from the call-graph. If the option is specified |
| 222 |
multiple times, the union of the selected symbols |
| 223 |
is suppressed. This option has lower precedence |
| 224 |
than --graph. |
| 225 |
|
| 226 |
-C[symspec] --exec-counts[=symspec] |
| 227 |
Request output in the form of execution counts. |
| 228 |
If "symspec" is present, include only symbols |
| 229 |
selected by "symspec" in the execution count |
| 230 |
listing. If the option is specified multiple |
| 231 |
times, the execution count listing includes |
| 232 |
symbols selected by the union of all symspecs. |
| 233 |
|
| 234 |
-Z[symspec] --no-exec-counts[=symspec] |
| 235 |
Suppress output in the execution count listing. |
| 236 |
If given without an argument, the listing is |
| 237 |
suppressed completely. With a "symspec", suppress |
| 238 |
the selected symbols from the call-graph. If the |
| 239 |
option is specified multiple times, the union of |
| 240 |
the selected symbols is suppressed. This option |
| 241 |
has lower precedence than --exec-counts. |
| 242 |
|
| 243 |
-i --file-info |
| 244 |
Print information about the profile files that |
| 245 |
are read. The information consists of the |
| 246 |
number and types of records present in the |
| 247 |
profile file. Currently, a profile file can |
| 248 |
contain any number and any combination of histogram, |
| 249 |
call-graph, or basic-block count records. |
| 250 |
|
| 251 |
-s --sum |
| 252 |
|
| 253 |
-x --all-lines |
| 254 |
This option affects annotated source output only. |
| 255 |
By default, only the lines at the beginning of |
| 256 |
a basic-block are annotated. If this option is |
| 257 |
specified, every line in a basic-block is annotated |
| 258 |
by repeating the annotation for the first line. |
| 259 |
This option is identical to tcov's "-a". |
| 260 |
|
| 261 |
-I dirs --directory-path=dirs |
| 262 |
This option affects annotated source output only. |
| 263 |
Specifies the list of directories to be searched |
| 264 |
for source files. The argument "dirs" is a colon |
| 265 |
separated list of directories. By default, gprof |
| 266 |
searches for source files relative to the current |
| 267 |
working directory only. |
| 268 |
|
| 269 |
-z --display-unused-functions |
| 270 |
|
| 271 |
-m num --min-count=num |
| 272 |
This option affects annotated source and execution |
| 273 |
count output only. Symbols that are executed |
| 274 |
less than "num" times are suppressed. For annotated |
| 275 |
source output, suppressed symbols are marked |
| 276 |
by five hash-marks (#####). In an execution count |
| 277 |
output, suppressed symbols do not appear at all. |
| 278 |
|
| 279 |
-L --print-path |
| 280 |
Normally, source filenames are printed with the path |
| 281 |
component suppressed. With this option, gprof |
| 282 |
can be forced to print the full pathname of |
| 283 |
source filenames. The full pathname is determined |
| 284 |
from symbolic debugging information in the image file |
| 285 |
and is relative to the directory in which the compiler |
| 286 |
was invoked. |
| 287 |
|
| 288 |
-y --separate-files |
| 289 |
This option affects annotated source output only. |
| 290 |
Normally, gprof prints annotated source files |
| 291 |
to standard-output. If this option is specified, |
| 292 |
annotated source for a file named "path/filename" |
| 293 |
is generated in the file "filename-ann". That is, |
| 294 |
annotated output is {\em always\/} generated in |
| 295 |
gprof's current working directory. Care has to |
| 296 |
be taken if a program consists of files that have |
| 297 |
identical filenames, but distinct paths. |
| 298 |
|
| 299 |
-c --static-call-graph |
| 300 |
|
| 301 |
-t num --table-length=num |
| 302 |
This option affects annotated source output only. |
| 303 |
After annotating a source file, gprof generates |
| 304 |
an execution count summary consisting of a table |
| 305 |
of lines with the top execution counts. By |
| 306 |
default, this table is ten entries long. |
| 307 |
This option can be used to change the table length |
| 308 |
or, by specifying an argument value of 0, it can be |
| 309 |
suppressed completely. |
| 310 |
|
| 311 |
-n symspec --time=symspec |
| 312 |
Only symbols selected by "symspec" are considered |
| 313 |
in total and percentage time computations. |
| 314 |
However, this option does not affect percentage time |
| 315 |
computation for the flat profile. |
| 316 |
If the option is specified multiple times, the union |
| 317 |
of all selected symbols is used in time computations. |
| 318 |
|
| 319 |
-N --no-time=symspec |
| 320 |
Exclude the symbols selected by "symspec" from |
| 321 |
total and percentage time computations. |
| 322 |
However, this option does not affect percentage time |
| 323 |
computation for the flat profile. |
| 324 |
This option is ignored if any --time options are |
| 325 |
specified. |
| 326 |
|
| 327 |
-w num --width=num |
| 328 |
Sets the output line width. Currently, this option |
| 329 |
affects the printing of the call-graph function index |
| 330 |
only. |
| 331 |
|
| 332 |
-e <no long form---for backwards compatibility only> |
| 333 |
-E <no long form---for backwards compatibility only> |
| 334 |
-f <no long form---for backwards compatibility only> |
| 335 |
-F <no long form---for backwards compatibility only> |
| 336 |
-k <no long form---for backwards compatibility only> |
| 337 |
-b --brief |
| 338 |
-dnum --debug[=num] |
| 339 |
|
| 340 |
-h --help |
| 341 |
Prints a usage message. |
| 342 |
|
| 343 |
-O name --file-format=name |
| 344 |
Selects the format of the profile data files. |
| 345 |
Recognized formats are "auto", "bsd", "magic", |
| 346 |
and "prof". The last one is not yet supported. |
| 347 |
Format "auto" attempts to detect the file format |
| 348 |
automatically (this is the default behavior). |
| 349 |
It attempts to read the profile data files as |
| 350 |
"magic" files and if this fails, falls back to |
| 351 |
the "bsd" format. "bsd" forces gprof to read |
| 352 |
the data files in the BSD format. "magic" forces |
| 353 |
gprof to read the data files in the "magic" format. |
| 354 |
|
| 355 |
-T --traditional |
| 356 |
-v --version |
| 357 |
|
| 358 |
** File Format Changes |
| 359 |
|
| 360 |
The old BSD-derived format used for profile data does not contain a |
| 361 |
magic cookie that allows to check whether a data file really is a |
| 362 |
gprof file. Furthermore, it does not provide a version number, thus |
| 363 |
rendering changes to the file format almost impossible. GNU gprof |
| 364 |
uses a new file format that provides these features. For backward |
| 365 |
compatibility, GNU gprof continues to support the old BSD-derived |
| 366 |
format, but not all features are supported with it. For example, |
| 367 |
basic-block execution counts cannot be accommodated by the old file |
| 368 |
format. |
| 369 |
|
| 370 |
The new file format is defined in header file \file{gmon_out.h}. It |
| 371 |
consists of a header containing the magic cookie and a version number, |
| 372 |
as well as some spare bytes available for future extensions. All data |
| 373 |
in a profile data file is in the native format of the host on which |
| 374 |
the profile was collected. GNU gprof adapts automatically to the |
| 375 |
byte-order in use. |
| 376 |
|
| 377 |
In the new file format, the header is followed by a sequence of |
| 378 |
records. Currently, there are three different record types: histogram |
| 379 |
records, call-graph arc records, and basic-block execution count |
| 380 |
records. Each file can contain any number of each record type. When |
| 381 |
reading a file, GNU gprof will ensure records of the same type are |
| 382 |
compatible with each other and compute the union of all records. For |
| 383 |
example, for basic-block execution counts, the union is simply the sum |
| 384 |
of all execution counts for each basic-block. |
| 385 |
|
| 386 |
*** Histogram Records |
| 387 |
|
| 388 |
Histogram records consist of a header that is followed by an array of |
| 389 |
bins. The header contains the text-segment range that the histogram |
| 390 |
spans, the size of the histogram in bytes (unlike in the old BSD |
| 391 |
format, this does not include the size of the header), the rate of the |
| 392 |
profiling clock, and the physical dimension that the bin counts |
| 393 |
represent after being scaled by the profiling clock rate. The |
| 394 |
physical dimension is specified in two parts: a long name of up to 15 |
| 395 |
characters and a single character abbreviation. For example, a |
| 396 |
histogram representing real-time would specify the long name as |
| 397 |
"seconds" and the abbreviation as "s". This feature is useful for |
| 398 |
architectures that support performance monitor hardware (which, |
| 399 |
fortunately, is becoming increasingly common). For example, under DEC |
| 400 |
OSF/1, the "uprofile" command can be used to produce a histogram of, |
| 401 |
say, instruction cache misses. In this case, the dimension in the |
| 402 |
histogram header could be set to "i-cache misses" and the abbreviation |
| 403 |
could be set to "1" (because it is simply a count, not a physical |
| 404 |
dimension). Also, the profiling rate would have to be set to 1 in |
| 405 |
this case. |
| 406 |
|
| 407 |
Histogram bins are 16-bit numbers and each bin represent an equal |
| 408 |
amount of text-space. For example, if the text-segment is one |
| 409 |
thousand bytes long and if there are ten bins in the histogram, each |
| 410 |
bin represents one hundred bytes. |
| 411 |
|
| 412 |
|
| 413 |
*** Call-Graph Records |
| 414 |
|
| 415 |
Call-graph records have a format that is identical to the one used in |
| 416 |
the BSD-derived file format. It consists of an arc in the call graph |
| 417 |
and a count indicating the number of times the arc was traversed |
| 418 |
during program execution. Arcs are specified by a pair of addresses: |
| 419 |
the first must be within caller's function and the second must be |
| 420 |
within the callee's function. When performing profiling at the |
| 421 |
function level, these addresses can point anywhere within the |
| 422 |
respective function. However, when profiling at the line-level, it is |
| 423 |
better if the addresses are as close to the call-site/entry-point as |
| 424 |
possible. This will ensure that the line-level call-graph is able to |
| 425 |
identify exactly which line of source code performed calls to a |
| 426 |
function. |
| 427 |
|
| 428 |
*** Basic-Block Execution Count Records |
| 429 |
|
| 430 |
Basic-block execution count records consist of a header followed by a |
| 431 |
sequence of address/count pairs. The header simply specifies the |
| 432 |
length of the sequence. In an address/count pair, the address |
| 433 |
identifies a basic-block and the count specifies the number of times |
| 434 |
that basic-block was executed. Any address within the basic-address can |
| 435 |
be used. |
| 436 |
|
| 437 |
IMPLEMENTATION NOTE: gcc -a can be used to instrument a program to |
| 438 |
record basic-block execution counts. However, the __bb_exit_func() |
| 439 |
that is currently present in libgcc2.c does not generate a gmon.out |
| 440 |
file in a suitable format. This should be fixed for future releases |
| 441 |
of gcc. In the meantime, contact [email protected] for a version |
| 442 |
of __bb_exit_func() to is appropriate. |