gprof.texi

基于4个mips核的noc设计

\input texinfo @c -*-texinfo-*-
@setfilename gprof.info
@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001
@c Free Software Foundation, Inc.
@settitle GNU gprof
@setchapternewpage odd

@ifinfo
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.  [e-mail] is developing this facility.
@format
START-INFO-DIR-ENTRY
* gprof: (gprof).                Profiling your program's execution
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file documents the gprof profiler of the GNU system.

Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.

      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, with no Front-Cover Texts, and with no
      Back-Cover Texts.  A copy of the license is included in the
      section entitled "GNU Free Documentation License".

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
@end ifinfo

@finalout
@smallbook

@titlepage
@title GNU gprof
@subtitle The @sc{gnu} Profiler 
@author Jay Fenlason and Richard Stallman

@page

This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
can use it to determine which parts of a program are taking most of the
execution time.  We assume that you know how to write, compile, and
execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.

@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.

      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, with no Front-Cover Texts, and with no
      Back-Cover Texts.  A copy of the license is included in the
      section entitled "GNU Free Documentation License".

@end titlepage

@ifinfo
@node Top
@top Profiling a Program: Where Does It Spend Its Time?

This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
can use it to determine which parts of a program are taking most of the
execution time.  We assume that you know how to write, compile, and
execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.

This document is distributed under the terms of the GNU Free
Documentation License.  A copy of the license is included in the
section entitled "GNU Free Documentation License".

@menu
* Introduction::        What profiling means, and why it is useful.

* Compiling::           How to compile your program for profiling.
* Executing::           Executing your program to generate profile data
* Invoking::            How to run @code{gprof}, and its options

* Output::		Interpreting @code{gprof}'s output

* Inaccuracy::          Potential problems you should be aware of
* How do I?::           Answers to common questions
* Incompatibilities::   (between @sc{gnu} @code{gprof} and Unix @code{gprof}.)
* Details::             Details of how profiling is done
* GNU Free Documentation License::  GNU Free Documentation License
@end menu
@end ifinfo

@node Introduction
@chapter Introduction to Profiling

Profiling allows you to learn where your program spent its time and which
functions called which other functions while it was executing.  This
information can show you which pieces of your program are slower than you
expected, and might be candidates for rewriting to make your program
execute faster.  It can also tell you which functions are being called more
or less often than you expected.  This may help you spot bugs that had
otherwise been unnoticed.

Since the profiler uses information collected during the actual execution
of your program, it can be used on programs that are too large or too
complex to analyze by reading the source.  However, how your program is run
will affect the information that shows up in the profile data.  If you
don't use some feature of your program while it is being profiled, no
profile information will be generated for that feature.

Profiling has several steps:

@itemize @bullet
@item
You must compile and link your program with profiling enabled.
@xref{Compiling}.

@item
You must execute your program to generate a profile data file.
@xref{Executing}.

@item
You must run @code{gprof} to analyze the profile data.
@xref{Invoking}.
@end itemize

The next three chapters explain these steps in greater detail.

Several forms of output are available from the analysis.

The @dfn{flat profile} shows how much time your program spent in each function,
and how many times that function was called.  If you simply want to know
which functions burn most of the cycles, it is stated concisely here.
@xref{Flat Profile}.

The @dfn{call graph} shows, for each function, which functions called it, which
other functions it called, and how many times.  There is also an estimate
of how much time was spent in the subroutines of each function.  This can
suggest places where you might try to eliminate function calls that use a
lot of time.  @xref{Call Graph}.

The @dfn{annotated source} listing is a copy of the program's
source code, labeled with the number of times each line of the
program was executed.  @xref{Annotated Source}.

To better understand how profiling works, you may wish to read
a description of its implementation.
@xref{Implementation}.

@node Compiling
@chapter Compiling a Program for Profiling

The first step in generating profile information for your program is
to compile and link it with profiling enabled.

To compile a source file for profiling, specify the @samp{-pg} option when
you run the compiler.  (This is in addition to the options you normally
use.)

To link the program for profiling, if you use a compiler such as @code{cc}
to do the linking, simply specify @samp{-pg} in addition to your usual
options.  The same option, @samp{-pg}, alters either compilation or linking
to do what is necessary for profiling.  Here are examples:

@example
cc -g -c myprog.c utils.c -pg
cc -o myprog myprog.o utils.o -pg
@end example

The @samp{-pg} option also works with a command that both compiles and links:

@example
cc -o myprog myprog.c utils.c -g -pg
@end example

If you run the linker @code{ld} directly instead of through a compiler
such as @code{cc}, you may have to specify a profiling startup file
@file{gcrt0.o} as the first input file instead of the usual startup
file @file{crt0.o}.  In addition, you would probably want to
specify the profiling C library, @file{libc_p.a}, by writing
@samp{-lc_p} instead of the usual @samp{-lc}.  This is not absolutely
necessary, but doing this gives you number-of-calls information for
standard library functions such as @code{read} and @code{open}.  For
example:

@example
ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p
@end example

If you compile only some of the modules of the program with @samp{-pg}, you
can still profile the program, but you won't get complete information about
the modules that were compiled without @samp{-pg}.  The only information
you get for the functions in those modules is the total time spent in them;
there is no record of how many times they were called, or from where.  This
will not affect the flat profile (except that the @code{calls} field for
the functions will be blank), but will greatly reduce the usefulness of the
call graph.

If you wish to perform line-by-line profiling,
you will also need to specify the @samp{-g} option,
instructing the compiler to insert debugging symbols into the program
that match program addresses to source code lines.
@xref{Line-by-line}.

In addition to the @samp{-pg} and @samp{-g} options,
you may also wish to specify the @samp{-a} option when compiling.
This will instrument
the program to perform basic-block counting.  As the program runs,
it will count how many times it executed each branch of each @samp{if}
statement, each iteration of each @samp{do} loop, etc.  This will
enable @code{gprof} to construct an annotated source code
listing showing how many times each line of code was executed.

@node Executing
@chapter Executing the Program

Once the program is compiled for profiling, you must run it in order to
generate the information that @code{gprof} needs.  Simply run the program
as usual, using the normal arguments, file names, etc.  The program should
run normally, producing the same output as usual.  It will, however, run
somewhat slower than normal because of the time spent collecting and the
writing the profile data.

The way you run the program---the arguments and input that you give
it---may have a dramatic effect on what the profile information shows.  The
profile data will describe the parts of the program that were activated for
the particular input you use.  For example, if the first command you give
to your program is to quit, the profile data will show the time used in
initialization and in cleanup, but not much else.

Your program will write the profile data into a file called @file{gmon.out}
just before exiting.  If there is already a file called @file{gmon.out},
its contents are overwritten.  There is currently no way to tell the
program to write the profile data under a different name, but you can rename
the file afterward if you are concerned that it may be overwritten.

In order to write the @file{gmon.out} file properly, your program must exit
normally: by returning from @code{main} or by calling @code{exit}.  Calling
the low-level function @code{_exit} does not write the profile data, and
neither does abnormal termination due to an unhandled signal.

The @file{gmon.out} file is written in the program's @emph{current working
directory} at the time it exits.  This means that if your program calls
@code{chdir}, the @file{gmon.out} file will be left in the last directory
your program @code{chdir}'d to.  If you don't have permission to write in
this directory, the file is not written, and you will get an error message.

Older versions of the @sc{gnu} profiling library may also write a file
called @file{bb.out}.  This file, if present, contains an human-readable
listing of the basic-block execution counts.  Unfortunately, the
appearance of a human-readable @file{bb.out} means the basic-block
counts didn't get written into @file{gmon.out}.
The Perl script @code{bbconv.pl}, included with the @code{gprof}
source distribution, will convert a @file{bb.out} file into
a format readable by @code{gprof}.

@node Invoking
@chapter @code{gprof} Command Summary

After you have a profile data file @file{gmon.out}, you can run @code{gprof}
to interpret the information in it.  The @code{gprof} program prints a
flat profile and a call graph on standard output.  Typically you would
redirect the output of @code{gprof} into a file with @samp{>}.

You run @code{gprof} like this:

@smallexample
gprof @var{options} [@var{executable-file} [@var{profile-data-files}@dots{}]] [> @var{outfile}]
@end smallexample

@noindent
Here square-brackets indicate optional arguments.

If you omit the executable file name, the file @file{a.out} is used.  If
you give no profile data file name, the file @file{gmon.out} is used.  If
any file is not in the proper format, or if the profile data file does not
appear to belong to the executable file, an error message is printed.

You can give more than one profile data file by entering all their names
after the executable file name; then the statistics in all the data files
are summed together.

The order of these options does not matter.

@menu
* Output Options::      Controlling @code{gprof}'s output style
* Analysis Options::    Controlling how @code{gprof} analyses its data
* Miscellaneous Options::
* Deprecated Options::  Options you no longer need to use, but which
                            have been retained for compatibility
* Symspecs::            Specifying functions to include or exclude
@end menu

@node Output Options,Analysis Options,,Invoking
@section Output Options

These options specify which of several output formats
@code{gprof} should produce.

Many of these options take an optional @dfn{symspec} to specify
functions to be included or excluded.  These options can be
specified multiple times, with different symspecs, to include
or exclude sets of symbols.  @xref{Symspecs}.

Specifying any of these options overrides the default (@samp{-p -q}),
which prints a flat profile and call graph analysis
for all functions.

@table @code

@item -A[@var{symspec}]
@itemx --annotated-source[=@var{symspec}]
The @samp{-A} option causes @code{gprof} to print annotated source code.
If @var{symspec} is specified, print output only for matching symbols.
@xref{Annotated Source}.

@item -b
@itemx --brief
If the @samp{-b} option is given, @code{gprof} doesn't print the
verbose blurbs that try to explain the meaning of all of the fields in
the tables.  This is useful if you intend to print out the output, or
are tired of seeing the blurbs.

@item -C[@var{symspec}]