Change bug reporting email address.

1 files changed, 442 insertions, 0 deletions

diff --git a/gprof/README b/gprof/README
new file mode 100644
index 0000000000..8fe2da8a5a
--- /dev/null
+++ b/gprof/README
@@ -0,0 +1,442 @@
+		README for GPROF
+
+This is the GNU profiler.  It is distributed with other "binary 
+utilities" which should be in ../binutils.  See ../binutils/README for 
+more general notes, including where to send bug reports.
+
+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 necessary 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 suitable 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.