gprof/NOTES

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