summaryrefslogtreecommitdiff
path: root/gprof/NOTES
diff options
context:
space:
mode:
Diffstat (limited to 'gprof/NOTES')
-rw-r--r--gprof/NOTES438
1 files changed, 0 insertions, 438 deletions
diff --git a/gprof/NOTES b/gprof/NOTES
deleted file mode 100644
index 511af302781..00000000000
--- a/gprof/NOTES
+++ /dev/null
@@ -1,438 +0,0 @@
-Sun Feb 5 16:09:16 1995
-
-This file documents the changes and new features available with this
-version of GNU gprof.
-
-* New Features
-
- o Long options
-
- o Supports generalized file format, without breaking backward compatibility:
- new file format supports basic-block execution counts and non-realtime
- histograms (see below)
-
- o Supports profiling at the line level: flat profiles, call-graph profiles,
- and execution-counts can all be displayed at a level that identifies
- individual lines rather than just functions
-
- o Test-coverage support (similar to Sun tcov program): source files
- can be annotated with the number of times a function was invoked
- or with the number of times each basic-block in a function was
- executed
-
- o Generalized histograms: not just execution-time, but arbitrary
- histograms are support (for example, performance counter based
- profiles)
-
- o Powerful mechanism to select data to be included/excluded from
- analysis and/or output
-
- o Support for DEC OSF/1 v3.0
-
- o Full cross-platform profiling support: gprof uses BFD to support
- arbitrary, non-native object file formats and non-native byte-orders
- (this feature has not been tested yet)
-
- o In the call-graph function index, static function names are now
- printed together with the filename in which the function was defined
- (required bfd_find_nearest_line() support and symbolic debugging
- information to be present in the executable file)
-
- o Major overhaul of source code (compiles cleanly with -Wall, etc.)
-
-* Supported Platforms
-
-The current version is known to work on:
-
- o DEC OSF/1 v3.0
- All features supported.
-
- o SunOS 4.1.x
- All features supported.
-
- o Solaris 2.3
- Line-level profiling unsupported because bfd_find_nearest_line()
- is not fully implemented for Elf binaries.
-
- o HP-UX 9.01
- Line-level profiling unsupported because bfd_find_nearest_line()
- is not fully implemented for SOM binaries.
-
-* Detailed Description
-
-** User Interface Changes
-
-The command-line interface is backwards compatible with earlier
-versions of GNU gprof and Berkeley gprof. The only exception is
-the option to delete arcs from the call graph. The old syntax
-was:
-
- -k fromname toname
-
-while the new syntax is:
-
- -k fromname/toname
-
-This change was necessary to be compatible with long-option parsing.
-Also, "fromname" and "toname" can now be arbitrary symspecs rather
-than just function names (see below for an explanation of symspecs).
-For example, option "-k gprof.c/" suppresses all arcs due to calls out
-of file "gprof.c".
-
-*** Sym Specs
-
-It is often necessary to apply gprof only to specific parts of a
-program. GNU gprof has a simple but powerful mechanism to achieve
-this. So called {\em symspecs\/} provide the foundation for this
-mechanism. A symspec selects the parts of a profiled program to which
-an operation should be applied to. The syntax of a symspec is
-simple:
-
- filename_containing_a_dot
- | funcname_not_containing_a_dot
- | linenumber
- | ( [ any_filename ] `:' ( any_funcname | linenumber ) )
-
-Here are some examples:
-
- main.c Selects everything in file "main.c"---the
- dot in the string tells gprof to interpret
- the string as a filename, rather than as
- a function name. To select a file whose
- name does contain a dot, a trailing colon
- should be specified. For example, "odd:" is
- interpreted as the file named "odd".
-
- main Selects all functions named "main". Notice
- that there may be multiple instances of the
- same function name because some of the
- definitions may be local (i.e., static).
- Unless a function name is unique in a program,
- you must use the colon notation explained
- below to specify a function from a specific
- source file. Sometimes, functionnames contain
- dots. In such cases, it is necessar to
- add a leading colon to the name. For example,
- ":.mul" selects function ".mul".
-
- main.c:main Selects function "main" in file "main.c".
-
- main.c:134 Selects line 134 in file "main.c".
-
-IMPLEMENTATION NOTE: The source code uses the type sym_id for symspecs.
-At some point, this probably ought to be changed to "sym_spec" to make
-reading the code easier.
-
-*** Long options
-
-GNU gprof now supports long options. The following is a list of all
-supported options. Options that are listed without description
-operate in the same manner as the corresponding option in older
-versions of gprof.
-
-Short Form: Long Form:
------------ ----------
--l --line
- Request profiling at the line-level rather
- than just at the function level. Source
- lines are identified by symbols of the form:
-
- func (file:line)
-
- where "func" is the function name, "file" is the
- file name and "line" is the line-number that
- corresponds to the line.
-
- To work properly, the binary must contain symbolic
- debugging information. This means that the source
- have to be translated with option "-g" specified.
- Functions for which there is no symbolic debugging
- information available are treated as if "--line"
- had not been specified. However, the line number
- printed with such symbols is usually incorrect
- and should be ignored.
-
--a --no-static
--A[symspec] --annotated-source[=symspec]
- Request output in the form of annotated source
- files. If "symspec" is specified, print output only
- for symbols selected by "symspec". If the option
- is specified multiple times, annotated output is
- generated for the union of all symspecs.
-
- Examples:
-
- -A Prints annotated source for all
- source files.
- -Agprof.c Prints annotated source for file
- gprof.c.
- -Afoobar Prints annotated source for files
- containing a function named "foobar".
- The entire file will be printed, but
- only the function itself will be
- annotated with profile data.
-
--J[symspec] --no-annotated-source[=symspec]
- Suppress annotated source output. If specified
- without argument, annotated output is suppressed
- completely. With an argument, annotated output
- is suppressed only for the symbols selected by
- "symspec". If the option is specified multiple
- times, annotated output is suppressed for the
- union of all symspecs. This option has lower
- precedence than --annotated-source
-
--p[symspec] --flat-profile[=symspec]
- Request output in the form of a flat profile
- (unless any other output-style option is specified,
- this option is turned on by default). If
- "symspec" is specified, include only symbols
- selected by "symspec" in flat profile. If the
- option is specified multiple times, the flat
- profile includes symbols selected by the union
- of all symspecs.
-
--P[symspec] --no-flat-profile[=symspec]
- Suppress output in the flat profile. If given
- without an argument, the flat profile is suppressed
- completely. If "symspec" is specified, suppress
- the selected symbols in the flat profile. If the
- option is specified multiple times, the union of
- the selected symbols is suppressed. This option
- has lower precedence than --flat-profile.
-
--q[symspec] --graph[=symspec]
- Request output in the form of a call-graph
- (unless any other output-style option is specified,
- this option is turned on by default). If "symspec"
- is specified, include only symbols selected by
- "symspec" in the call-graph. If the option is
- specified multiple times, the call-graph includes
- symbols selected by the union of all symspecs.
-
--Q[symspec] --no-graph[=symspec]
- Suppress output in the call-graph. If given without
- an argument, the call-graph is suppressed completely.
- With a "symspec", suppress the selected symbols
- from the call-graph. If the option is specified
- multiple times, the union of the selected symbols
- is suppressed. This option has lower precedence
- than --graph.
-
--C[symspec] --exec-counts[=symspec]
- Request output in the form of execution counts.
- If "symspec" is present, include only symbols
- selected by "symspec" in the execution count
- listing. If the option is specified multiple
- times, the execution count listing includes
- symbols selected by the union of all symspecs.
-
--Z[symspec] --no-exec-counts[=symspec]
- Suppress output in the execution count listing.
- If given without an argument, the listing is
- suppressed completely. With a "symspec", suppress
- the selected symbols from the call-graph. If the
- option is specified multiple times, the union of
- the selected symbols is suppressed. This option
- has lower precedence than --exec-counts.
-
--i --file-info
- Print information about the profile files that
- are read. The information consists of the
- number and types of records present in the
- profile file. Currently, a profile file can
- contain any number and any combination of histogram,
- call-graph, or basic-block count records.
-
--s --sum
-
--x --all-lines
- This option affects annotated source output only.
- By default, only the lines at the beginning of
- a basic-block are annotated. If this option is
- specified, every line in a basic-block is annotated
- by repeating the annotation for the first line.
- This option is identical to tcov's "-a".
-
--I dirs --directory-path=dirs
- This option affects annotated source output only.
- Specifies the list of directories to be searched
- for source files. The argument "dirs" is a colon
- separated list of directories. By default, gprof
- searches for source files relative to the current
- working directory only.
-
--z --display-unused-functions
-
--m num --min-count=num
- This option affects annotated source and execution
- count output only. Symbols that are executed
- less than "num" times are suppressed. For annotated
- source output, suppressed symbols are marked
- by five hash-marks (#####). In an execution count
- output, suppressed symbols do not appear at all.
-
--L --print-path
- Normally, source filenames are printed with the path
- component suppressed. With this option, gprof
- can be forced to print the full pathname of
- source filenames. The full pathname is determined
- from symbolic debugging information in the image file
- and is relative to the directory in which the compiler
- was invoked.
-
--y --separate-files
- This option affects annotated source output only.
- Normally, gprof prints annotated source files
- to standard-output. If this option is specified,
- annotated source for a file named "path/filename"
- is generated in the file "filename-ann". That is,
- annotated output is {\em always\/} generated in
- gprof's current working directory. Care has to
- be taken if a program consists of files that have
- identical filenames, but distinct paths.
-
--c --static-call-graph
-
--t num --table-length=num
- This option affects annotated source output only.
- After annotating a source file, gprof generates
- an execution count summary consisting of a table
- of lines with the top execution counts. By
- default, this table is ten entries long.
- This option can be used to change the table length
- or, by specifying an argument value of 0, it can be
- suppressed completely.
-
--n symspec --time=symspec
- Only symbols selected by "symspec" are considered
- in total and percentage time computations.
- However, this option does not affect percentage time
- computation for the flat profile.
- If the option is specified multiple times, the union
- of all selected symbols is used in time computations.
-
--N --no-time=symspec
- Exclude the symbols selected by "symspec" from
- total and percentage time computations.
- However, this option does not affect percentage time
- computation for the flat profile.
- This option is ignored if any --time options are
- specified.
-
--w num --width=num
- Sets the output line width. Currently, this option
- affects the printing of the call-graph function index
- only.
-
--e <no long form---for backwards compatibility only>
--E <no long form---for backwards compatibility only>
--f <no long form---for backwards compatibility only>
--F <no long form---for backwards compatibility only>
--k <no long form---for backwards compatibility only>
--b --brief
--dnum --debug[=num]
-
--h --help
- Prints a usage message.
-
--O name --file-format=name
- Selects the format of the profile data files.
- Recognized formats are "auto", "bsd", "magic",
- and "prof". The last one is not yet supported.
- Format "auto" attempts to detect the file format
- automatically (this is the default behavior).
- It attempts to read the profile data files as
- "magic" files and if this fails, falls back to
- the "bsd" format. "bsd" forces gprof to read
- the data files in the BSD format. "magic" forces
- gprof to read the data files in the "magic" format.
-
--T --traditional
--v --version
-
-** File Format Changes
-
-The old BSD-derived format used for profile data does not contain a
-magic cookie that allows to check whether a data file really is a
-gprof file. Furthermore, it does not provide a version number, thus
-rendering changes to the file format almost impossible. GNU gprof
-uses a new file format that provides these features. For backward
-compatibility, GNU gprof continues to support the old BSD-derived
-format, but not all features are supported with it. For example,
-basic-block execution counts cannot be accommodated by the old file
-format.
-
-The new file format is defined in header file \file{gmon_out.h}. It
-consists of a header containing the magic cookie and a version number,
-as well as some spare bytes available for future extensions. All data
-in a profile data file is in the native format of the host on which
-the profile was collected. GNU gprof adapts automatically to the
-byte-order in use.
-
-In the new file format, the header is followed by a sequence of
-records. Currently, there are three different record types: histogram
-records, call-graph arc records, and basic-block execution count
-records. Each file can contain any number of each record type. When
-reading a file, GNU gprof will ensure records of the same type are
-compatible with each other and compute the union of all records. For
-example, for basic-block execution counts, the union is simply the sum
-of all execution counts for each basic-block.
-
-*** Histogram Records
-
-Histogram records consist of a header that is followed by an array of
-bins. The header contains the text-segment range that the histogram
-spans, the size of the histogram in bytes (unlike in the old BSD
-format, this does not include the size of the header), the rate of the
-profiling clock, and the physical dimension that the bin counts
-represent after being scaled by the profiling clock rate. The
-physical dimension is specified in two parts: a long name of up to 15
-characters and a single character abbreviation. For example, a
-histogram representing real-time would specify the long name as
-"seconds" and the abbreviation as "s". This feature is useful for
-architectures that support performance monitor hardware (which,
-fortunately, is becoming increasingly common). For example, under DEC
-OSF/1, the "uprofile" command can be used to produce a histogram of,
-say, instruction cache misses. In this case, the dimension in the
-histogram header could be set to "i-cache misses" and the abbreviation
-could be set to "1" (because it is simply a count, not a physical
-dimension). Also, the profiling rate would have to be set to 1 in
-this case.
-
-Histogram bins are 16-bit numbers and each bin represent an equal
-amount of text-space. For example, if the text-segment is one
-thousand bytes long and if there are ten bins in the histogram, each
-bin represents one hundred bytes.
-
-
-*** Call-Graph Records
-
-Call-graph records have a format that is identical to the one used in
-the BSD-derived file format. It consists of an arc in the call graph
-and a count indicating the number of times the arc was traversed
-during program execution. Arcs are specified by a pair of addresses:
-the first must be within caller's function and the second must be
-within the callee's function. When performing profiling at the
-function level, these addresses can point anywhere within the
-respective function. However, when profiling at the line-level, it is
-better if the addresses are as close to the call-site/entry-point as
-possible. This will ensure that the line-level call-graph is able to
-identify exactly which line of source code performed calls to a
-function.
-
-*** Basic-Block Execution Count Records
-
-Basic-block execution count records consist of a header followed by a
-sequence of address/count pairs. The header simply specifies the
-length of the sequence. In an address/count pair, the address
-identifies a basic-block and the count specifies the number of times
-that basic-block was executed. Any address within the basic-address can
-be used.
-
-IMPLEMENTATION NOTE: gcc -a can be used to instrument a program to
-record basic-block execution counts. However, the __bb_exit_func()
-that is currently present in libgcc2.c does not generate a gmon.out
-file in a suiteable format. This should be fixed for future releases
-of gcc. In the meantime, contact davidm@cs.arizona.edu for a version
-of __bb_exit_func() to is appropriate.