+2001-07-19 Nick Clifton <nickc@cambridge.redhat.com>
+
+ * README: Update for 2.11. Change bug reporting email address.
+ * MAINTAINERS: Tidy up. Change bug reporting email address.
+
2001-07-16 DJ Delorie <dj@redhat.com>
* resres.c (write_res_header): Align header size.
========= Binutils Maintainers =========
This is the list of individuals responsible for maintenance and update
-of the "binutils" module, which includes the bfd, binutils, include,
-gas, gprof, ld, and opcodes subdirectories. The home page for binutils
-is http://sources.redhat.com/binutils/ and patches should be sent to
-binutils@sources.redhat.com with "[patch]" as part of the subject.
+of the GNU Binary Utilities project. This includes the linker (ld),
+the assembler (gas), the profiler (gprof), a whole suite of other
+programs (binutils) and the libraries that they use (bfd and
+opcodes). This project shares a common set of header files with the
+GCC and GDB projects (include), so maintainership of those files is
+shared amoungst the projects.
-Note - patches to the top level configure.in and config.sub scripts
-should be sent to config-patches@gnu.org and not to the binutils list.
+The home page for binutils is:
- --------- Blanket Write Privs ---------
+ http://www.gnu.org/software/binutils/binutils.html
+
+and patches should be sent to:
+
+ bug-gnu-utils@gnu.org
+
+with "[Patch]" as part of the subject line. Note - patches to the
+top level configure.in and config.sub scripts should be sent to:
-Nick Clifton <nickc@redhat.com> (head maintainer)
-Richard Henderson <rth@redhat.com>
-Ian Taylor <ian@zembu.com>
-Jeff Law <law@redhat.com>
-Jim Wilson <wilson@redhat.com>
-DJ Delorie <dj@redhat.com>
-Alan Modra <amodra@bigpond.net.au>
-Michael Meissner <meissner@redhat.com>
+ config-patches@gnu.org
- --------- Maintainers ---------
+and not to the binutils list.
+
+ --------- Blanket Write Privs ---------
-Maintainers are individuals who are responsible for, and have permission
-to check in changes in, certain subsets of the code. Note that
-maintainers still need approval to check in changes outside of the
-immediate domain that they maintain.
+The following people have permission to check patches into the
+repository without obtaining approval first:
+
+ Nick Clifton <nickc@redhat.com> (head maintainer)
+ Richard Henderson <rth@redhat.com>
+ Ian Taylor <ian@zembu.com>
+ Jeff Law <law@redhat.com>
+ Jim Wilson <wilson@redhat.com>
+ DJ Delorie <dj@redhat.com>
+ Alan Modra <amodra@bigpond.net.au>
+ Michael Meissner <meissner@redhat.com>
+
+ --------- Maintainers ---------
+
+Maintainers are individuals who are responsible for, and have
+permission to check in changes in, certain subsets of the code. Note
+that maintainers still need approval to check in changes outside of
+the immediate domain that they maintain.
If there is no maintainer for a given domain then the responsibility
-falls to the head maintainer (above). If there are several maintainers
-for a given domain then responsibility falls to the first maintainer.
-The first maintainer is free to devolve that responsibility among the
-other maintainers.
-
-ARM Nick Clifton <nickc@redhat.com>
-AVR Denis Chertykov <denisc@overta.ru>
-CRIS Hans-Peter Nilsson <hp@axis.com>
-HPPA elf32 Alan Modra <amodra@bigpond.net.au>
-IA64 Jim Wilson <wilson@redhat.com>
-i860 Jason Eckhardt <jle@redhat.com>
-ix86 Alan Modra <amodra@bigpond.net.au>
-ix86 COFF,PE DJ Delorie <dj@redhat.com>
-ix86 H.J.Lu <hjl@gnu.org>
-ix86 INTEL MODE Diego Novillo <dnovillo@redhat.com>
-MN10300 Eric Christopher <echristo@redhat.com>
-MIPS Eric Christopher <echristo@redhat.com>
-M88k Ben Elliston <bje@redhat.com>
-PPC Geoff Keating <geoffk@redhat.com>
-SH Jörn Rennecke <amylaar@redhat.com>
-SH Hans-Peter Nilsson <hp@bitrange.com>
-SPARC Jakub Jelinek <jakub@redhat.com>
-68HC11 68HC12 Stephane Carrez <Stephane.Carrez@worldnet.fr>
-DWARF2 Jason Merrill <jason@redhat.com>
-x86_64 Jan Hubicka <jh@suse.cz>
-x86_64 Andreas Jaeger <aj@suse.de>
-z8k Christian Groessler <cpg@aladdin.de>
-
- --------- CGEN Maintainers -------------
+falls to the head maintainer (above). If there are several
+maintainers for a given domain then responsibility falls to the first
+maintainer. The first maintainer is free to devolve that
+responsibility among the other maintainers.
+
+ ARM Nick Clifton <nickc@redhat.com>
+ AVR Denis Chertykov <denisc@overta.ru>
+ CRIS Hans-Peter Nilsson <hp@axis.com>
+ DWARF2 Jason Merrill <jason@redhat.com>
+ HPPA elf32 Alan Modra <amodra@bigpond.net.au>
+ IA64 Jim Wilson <wilson@redhat.com>
+ x86_64 Jan Hubicka <jh@suse.cz>
+ x86_64 Andreas Jaeger <aj@suse.de>
+ i860 Jason Eckhardt <jle@redhat.com>
+ ix86 Alan Modra <amodra@bigpond.net.au>
+ ix86 COFF,PE DJ Delorie <dj@redhat.com>
+ ix86 H.J.Lu <hjl@gnu.org>
+ ix86 INTEL MODE Diego Novillo <dnovillo@redhat.com>
+ M68HC11 M68HC12 Stephane Carrez <Stephane.Carrez@worldnet.fr>
+ MN10300 Eric Christopher <echristo@redhat.com>
+ MIPS Eric Christopher <echristo@redhat.com>
+ M88k Ben Elliston <bje@redhat.com>
+ PPC Geoff Keating <geoffk@redhat.com>
+ SH Jörn Rennecke <amylaar@redhat.com>
+ SH Hans-Peter Nilsson <hp@bitrange.com>
+ SPARC Jakub Jelinek <jakub@redhat.com>
+ z8k Christian Groessler <cpg@aladdin.de>
+
+ --------- CGEN Maintainers -------------
CGEN is a tool for building, amongst other things, assemblers,
-disassemblers and simulators from a single description of a CPU. It
-creates files in several of the binutils directories, but it is
-mentioned here since there is a single group that maintains CGEN and
-the files that it creates.
+disassemblers and simulators from a single description of a CPU.
+It creates files in several of the binutils directories, but it
+is mentioned here since there is a single group that maintains
+CGEN and the files that it creates.
If you have CGEN related problems you can send email to;
- cgen@sources.redhat.com
+ cgen@sources.redhat.com
The current CGEN maintainers are:
Doug Evans, Ben Elliston, Frank Eigler
- --------- Write After Approval ---------
+ --------- Write After Approval ---------
Individuals with "write after approval" have the ability to check in
changes, but they must get approval for each change from someone in
one of the above lists (blanket write or maintainers).
[It's a huge list, folks. You know who you are. If you have the
- *ability* to do binutils checkins, you're in this group. Just remember
- to get approval before checking anything in.]
+ *ability* to do binutils checkins, you're in this group. Just
+ remember to get approval before checking anything in.]
- ------------- Obvious Fixes -------------
+ ------------- Obvious Fixes -------------
Fixes for obvious mistakes do not need approval, and can be checked in
right away, but the patch should still be sent to the binutils list.
small, the larger they are, the more likely it is that they contain
some un-obvious side effect or consequence.
- --------- Branch Checkins ---------
+ --------- Branch Checkins ---------
If a patch is approved for check in to the mainline sources, it can
also be checked into the current release branch. Normally however
great). If you are uncertain as to whether a patch is appropriate for
the branch, ask the branch maintainer. This is:
- Philip Blundell <philb@gnu.org>
+
Philip Blundell <philb@gnu.org>
-These are the GNU binutils. These are utilities of use when dealing
-with object files.
+ README for BINUTILS
-The linker (ld) is in a separate directory, which should be ../ld.
-Linker-specific notes are in ../ld/README.
+These are the GNU binutils. These are utilities of use when dealing
+with binary files, either object files or executables. These tools
+consist of the linker (ld), the assembler (gas), and the profiler
+(gprof) each of which have their own sub-directory named after them.
+There is also a collection of other binary tools, including the
+disassembler (objdump) in this directory. These tools make use of a
+pair of libraries (bfd and opcodes) and a common set of header files
+(include).
-As of version 2.5, the assembler (as) is also included in this package, in
-../gas. Assembler-specific notes can be found in ../gas/README.
+There are README and NEWS files in most of the program sub-directories
+which give more information about those specific programs.
-Recent changes are in ./NEWS, ../ld/NEWS, and ../gas/NEWS.
Unpacking and Installation -- quick overview
============================================
-When you unpack the binutils-2.9.tar.gz file, you'll get a directory
-called something like `binutils-2.9', which contains various files and
-directories. Most of the files in the top directory are for
-information and for configuration. The actual source code is in
-subdirectories.
+When you unpack the binutils archive file, you will get a directory
+called something like `binutils-XXX', where XXX is the number of the
+release. (Probably 2.11.2 or higher). This directory contains
+various files and sub-directories. Most of the files in the top
+directory are for information and for configuration. The actual
+source code is in sub-directories.
To build binutils, you can just do:
- cd binutils-2.9
+ cd binutils-XXX
./configure [options]
make
make install # copies the programs files into /usr/local/bin
mkdir objdir
cd objdir
- ../binutils-2.9/configure [options]
+ ../binutils-XXX/configure [options]
make
make install
By default, the binutils will be configured to support the system on
which they are built. When doing cross development, use the --target
-configure option to specify a different target.
+configure option to specify a different target, eg:
+
+ ./configure --target=foo-elf
The --enable-targets option adds support for more binary file formats
besides the default. List them as the argument to --enable-targets,
./configure --enable-targets=sun3,rs6000-aix,decstation
-The name 'all' compiles in support for all valid BFD targets (this was
-the default in releases before 2.3):
+The name 'all' compiles in support for all valid BFD targets:
./configure --enable-targets=all
+On 32-bit hosts though, this support will be restricted to 32-bit
+target unless the --enable-64-bit-bfd option is also used:
+
+ ./configure --enable-64-bit-bfd --enable-targets=all
+
You can also specify the --enable-shared option when you run
configure. This will build the BFD and opcodes libraries as shared
libraries. You can use arguments with the --enable-shared option to
a binutils release are bfd and opcodes.
The binutils will be linked against the shared libraries. The build
-step will attempt to place the correct library in the runtime search
+step will attempt to place the correct library in the run-time search
path for the binaries. However, in some cases, after you install the
binaries, you may have to set an environment variable, normally
LD_LIBRARY_PATH, so that the system can find the installed libbfd
To build under openVMS/AXP, see the file makefile.vms in the top level
directory.
+
If you don't have ar
====================
-If your system does not already have an ar program, the normal
+If your system does not already have an 'ar' program, the normal
binutils build process will not work. In this case, run configure as
usual. Before running make, run this script:
Porting
=======
-Binutils-2.9 supports many different architectures, but there
+Binutils-2.11 supports many different architectures, but there
are many more not supported, including some that were supported
-by earlier versions. We are hoping for volunteers to
-improve this situation.
+by earlier versions. We are hoping for volunteers to improve this
+situation.
The major effort in porting binutils to a new host and/or target
architecture involves the BFD library. There is some documentation
Reporting bugs
==============
-Send bug reports and patches to bug-binutils@gnu.org. Always mention
-the version number you are running; this is printed by running any of
-the binutils with the --version option. We appreciate reports about
-bugs, but we do not promise to fix them.
+Send bug reports and patches to:
+
+ bug-gnu-utils@gnu.org.
+
+Always mention the version number you are running; this is printed by
+running any of the binutils with the --version option. We appreciate
+reports about bugs, but we do not promise to fix them.
VMS
===
Installing the release
Provided that your directory setup conforms to the GNU on openVMS
-standard, you already have a concealed deviced named 'GNU_ROOT'.
+standard, you already have a concealed device named 'GNU_ROOT'.
In this case, a simple
$ gmake install
and define all programs as foreign commands.
-If you're satiesfied with the compilation, you may want to remove
+If you're satisfied with the compilation, you may want to remove
unneeded objects and libraries:
$ gmake clean
README for GAS
-A number of things have changed since version 1 and the wonderful world of gas
-looks very different. There's still a lot of irrelevant garbage lying around
-that will be cleaned up in time. Documentation is scarce, as are logs of the
-changes made since the last gas release. My apologies, and I'll try to get
-something useful.
+A number of things have changed since version 1 and the wonderful
+world of gas looks very different. There's still a lot of irrelevant
+garbage lying around that will be cleaned up in time. Documentation
+is scarce, as are logs of the changes made since the last gas release.
+My apologies, and I'll try to get something useful.
Unpacking and Installation - Summary
====================================
make as.dvi
The Info form is viewable with the GNU Emacs `info' subsystem, or the
-standalone `info' program, available as part of the GNU Texinfo distribution.
+stand-alone `info' program, available as part of the GNU Texinfo distribution.
To build the info files, you will need the `makeinfo' program. Type:
cd gas/doc
Supported platforms
===================
-At this point I believe gas to be ansi only code for most target cpu's. That
+At this point I believe gas to be ANSI only code for most target cpu's. That
is, there should be relatively few, if any host system dependencies. So
porting (as a cross-assembler) to hosts not yet supported should be fairly
easy. Porting to a new target shouldn't be too tough if it's a variant of one
sparc solaris
ns32k (netbsd, lites)
-I believe that gas as a cross-assembler can currently be targetted for
+I believe that gas as a cross-assembler can currently be targeted for
most of the above hosts, plus
+ arm
decstation-bsd (a.out format, to be used in BSD 4.4)
ebmon29k
go32 (DOS on i386, with DJGPP -- old a.out version)
REPORTING BUGS IN GAS
=====================
-Bugs in gas should be reported to bug-binutils@gnu.org. They may be
-cross-posted to bug-gcc if they affect the use of gas with gcc. They
-should not be reported just to bug-gcc, since I don't read that list,
-and therefore wouldn't see them.
+Bugs in gas should be reported to:
+
+ bug-gnu-utils@gnu.org.
+
+They may be cross-posted to gcc-bugs@gnu.org if they affect the use of
+gas with gcc. They should not be reported just to gcc-bugs, since not
+all of the maintainers read that list.
If you report a bug in GAS, please remember to include:
in filing the bug report, don't bother.
If the input file is very large, and you are on the internet, you may want to
-make it avaliable for anonymous FTP instead of mailing it. If you do, include
+make it available for anonymous FTP instead of mailing it. If you do, include
instructions for FTP'ing it in your bug report.
If you expect to be contributing a large number of test cases, it would be
+2001-07-19 Nick Clifton <nickc@cambridge.redhat.com>
+
+ * NOTES: Rename to README for consistency with other binutils.
+
2001-06-18 H.J. Lu <hjl@gnu.org>
* Makefile.am (diststuff): Add $(MANS).
+++ /dev/null
-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.
--- /dev/null
+ 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.
+2001-07-19 Nick Clifton <nickc@cambridge.redhat.com>
+
+ * README: Add header for consistency with other README files.
+
2001-07-14 H.J. Lu <hjl@gnu.org>
* emultempl/elf32.em (output_prev_sec_find): Never return
+ README for LD
+
This is the GNU linker. 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.
projects / binutils-gdb.git / commitdiff