home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / binutils-2.7-src.tgz / tar.out / fsf / binutils / gprof / NOTES < prev    next >
Text File  |  1996-09-28  |  17KB  |  439 lines
  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.
  439.